3 stable releases

Uses new Rust 2024

1.1.1	Apr 20, 2025
1.1.0	Apr 19, 2025
1.0.0	Apr 14, 2025

#132 in Command line utilities

401 downloads per month

MIT/Apache

35KB
390 lines

Docker Prometheus Exporter

Exports basic metrics from Docker for scraping by Prometheus

Changelog • Usage • Security • Metrics • Configuration • License • Contributing

Changelog

The full changelog can be found at CHANGELOG.md

[1.1.1] - 2025-04-20

Fixed

Misc documentation fixes

[1.1.0] - 2025-04-19

Added

Returned support for the DOCKER_HOST environment variable
Bundled compose file now utilises docker-socket-proxy for enhanced security
Automatically negotiate API version with the connected docker daemon
Blacklist container health reporting for a container by applying the docker-prometheus-exporter.metric.container_health.enabled=false label

Usage

Follow one of the installation methods detailed below

Proxy Docker Socket (Recommended)

This method is HIGHLY recommended over directly mounting the Docker socket to the container, see the security section.

services:
  docker-socket-proxy:
    image: ghcr.io/calum4/docker-socket-proxy:latest
    container_name: docker-socket-proxy
    environment:
      - PING=1
      - VERSION=1
      - EVENTS=0 # enabled by default
      - CONTAINER_LIST=1
      - CONTAINER_INSPECT=1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    expose:
      - "2357:2357/tcp"
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges=true
    cap_drop:
      - ALL
    tmpfs:
      - /run
    networks:
      - docker-socket-proxy
    labels:
      "docker-prometheus-exporter.metric.container_health.enabled": true

  docker-prometheus-exporter:
    image: calum4/docker-prometheus-exporter:latest
    container_name: docker-prometheus-exporter
    environment:
      - RUST_LOG=info,docker_prometheus_exporter=info
      - LISTEN_ADDR=0.0.0.0
      - DOCKER_HOST=tcp://docker-socket-proxy:2375
    ports:
      - "127.0.0.1:9000:9000"
    labels:
      "docker-prometheus-exporter.metric.container_health.enabled": true
    depends_on:
      - docker-socket-proxy
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges=true
    cap_drop:
      - ALL
    networks:
      - docker-socket-proxy
      - docker-prometheus-exporter
    user: "65534:65534"

networks:
  docker-socket-proxy:
    driver: bridge
    internal: true
  docker-prometheus-exporter:

Mount Docker Socket

services:
  docker-prometheus-exporter:
    container_name: docker-prometheus-exporter
    image: calum4/docker-prometheus-exporter:1
    user: "0:0" # can instead be run as an unprivileged user with the docker group
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - RUST_LOG=info,docker_prometheus_exporter=info
      - LISTEN_ADDR=0.0.0.0
    ports:
      - "127.0.0.1:9000:9000"
    labels:
      "docker-prometheus-exporter.metric.container_health.enabled": true
    restart: unless-stopped
    read_only: true

Other Methods

Security

Docker Prometheus Exporter requires access to the Docker Engine API, more specifically the following endpoints:

Endpoint	Usage	Why is it needed?	Risks
/version	main	API version negotiation	None known
/_ping	metric/up	Check whether the docker daemon is alive	None known
/containers/json	metric/container_health	Fetch the names and ids of containers	Provides basic information about a container
/containers/{id}/json	metric/container_health	Fetch the health status of the container	Provides extensive information on a container, including environment variables

Providing unrestricted access to the Docker socket is highly discouraged.

Docker socket /var/run/docker.sock is the UNIX socket that Docker is listening to. This is the primary entry point for the Docker API. The owner of this socket is root. Giving someone access to it is equivalent to giving unrestricted root access to your host.

- OWASP - Docker Security Cheat Sheet via The Internet Archive, accessed 2025-04-17

Therefore, it is recommended that access to the Docker socket is proxied, and endpoints whitelisted.

calum4/docker-socket-proxy

Fork of linuxserver/docker-socket-proxy utilising HAProxy, modified to enable fine-grained endpoint restriction for docker-prometheus-exporter. View the changes here.

View docker-compose.yml

services:
  docker-socket-proxy:
    image: ghcr.io/calum4/docker-socket-proxy:latest
    container_name: docker-socket-proxy
    environment:
      - PING=1
      - VERSION=1
      - EVENTS=0 # enabled by default
      - CONTAINER_LIST=1
      - CONTAINER_INSPECT=1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    expose:
      - "2357:2357/tcp"
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges=true
    cap_drop:
      - ALL
    tmpfs:
      - /run
    networks:
      - docker-socket-proxy
    labels:
      "docker-prometheus-exporter.metric.container_health.enabled": true

  docker-prometheus-exporter:
    image: calum4/docker-prometheus-exporter:latest
    container_name: docker-prometheus-exporter
    environment:
      - RUST_LOG=info,docker_prometheus_exporter=info
      - LISTEN_ADDR=0.0.0.0
      - DOCKER_HOST=tcp://docker-socket-proxy:2375
    ports:
      - "127.0.0.1:9000:9000"
    labels:
      "docker-prometheus-exporter.metric.container_health.enabled": true
    depends_on:
      - docker-socket-proxy
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges=true
    cap_drop:
      - ALL
    networks:
      - docker-socket-proxy
      - docker-prometheus-exporter
    user: "65534:65534"

networks:
  docker-socket-proxy:
    driver: bridge
    internal: true
  docker-prometheus-exporter:

wollomatic/socket-proxy

Highly configurable general purpose unix socket proxy written in Go with zero external dependencies.

View docker-compose.yml

services:
  docker-socket-proxy:
    image: wollomatic/socket-proxy:1
    container_name: docker-socket-proxy
    restart: unless-stopped
    user: "0:0" # can instead be run as an unprivileged user with the docker group
    mem_limit: 64M
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges
    command:
      - '-loglevel=info'
      - '-listenip=0.0.0.0'
      - '-allowfrom=docker-prometheus-exporter'
      - '-allowGET=^(/v[\d\.]+)?/((version)|(_ping)|(containers/json)|(containers/[a-zA-Z0-9_.-]+/json))$'
      - '-watchdoginterval=3600' # check once per hour for socket availability
      - '-stoponwatchdog' # halt program on error and let compose restart it
      - '-shutdowngracetime=5' # wait 5 seconds before shutting down
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - docker-socket-proxy
    labels:
      "docker-prometheus-exporter.metric.container_health.enabled": true

  docker-prometheus-exporter:
    image: calum4/docker-prometheus-exporter:latest
    container_name: docker-prometheus-exporter
    environment:
      - RUST_LOG=info,docker_prometheus_exporter=info
      - LISTEN_ADDR=0.0.0.0
      - DOCKER_HOST=tcp://docker-socket-proxy:2375
    ports:
      - "127.0.0.1:9000:9000"
    labels:
      "docker-prometheus-exporter.metric.container_health.enabled": true
    depends_on:
      - docker-socket-proxy
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges=true
    cap_drop:
      - ALL
    networks:
      - docker-socket-proxy
      - docker-prometheus-exporter
    user: "65534:65534"

networks:
  docker-socket-proxy:
    driver: bridge
    internal: true
  docker-prometheus-exporter:

linuxserver/docker-socket-proxy

Unlike the previous 2 options, this does not provide fine-grained restriction to only the endpoints that docker-prometheus-exporter requires. Due to this, the /containers endpoint must be enabled, consequently opening other GET endpoints such as:

View docker-compose.yml

services:
  docker-socket-proxy:
    image: lscr.io/linuxserver/socket-proxy:latest
    container_name: docker-socket-proxy
    environment:
      - PING=1
      - VERSION=1
      - EVENTS=0 # enabled by default
      - CONTAINERS=1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    expose:
      - "2357:2357/tcp"
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges=true
    cap_drop:
      - ALL
    tmpfs:
      - /run
    networks:
      - docker-socket-proxy
    labels:
      "docker-prometheus-exporter.metric.container_health.enabled": true

  docker-prometheus-exporter:
    image: calum4/docker-prometheus-exporter:latest
    container_name: docker-prometheus-exporter
    environment:
      - RUST_LOG=info,docker_prometheus_exporter=info
      - LISTEN_ADDR=0.0.0.0
      - DOCKER_HOST=tcp://docker-socket-proxy:2375
    ports:
      - "127.0.0.1:9000:9000"
    labels:
      "docker-prometheus-exporter.metric.container_health.enabled": true
    depends_on:
      - docker-socket-proxy
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges=true
    cap_drop:
      - ALL
    networks:
      - docker-socket-proxy
      - docker-prometheus-exporter
    user: "65534:65534"

networks:
  docker-socket-proxy:
    driver: bridge
    internal: true
  docker-prometheus-exporter:

Metrics

Metric Name	Description	Units/Values	Labels
`docker_up`	Reports the state of Docker	0 - Offline 1 - Online	N/A
`container_health`	Reports the health state of a Docker container	0 - Unknown 1 - Stopped 2 - Alive, no healthcheck 3 - Unhealthy 4 - Healthy	`id` - Container ID `name` - Container Name

Configuration

Environment Variables

Name	Description	Default
`RUST_LOG`	Sets logging verbosity, see documentation	`error`
`DOCKER_HOST`	URI for the Docker Daemon	Unix - `unix:///var/run/docker.sock` Windows - `npipe:////./pipe/docker_engine`
`LISTEN_ADDR`	Metrics endpoint listen address	`127.0.0.1`
`LISTEN_PORT`	Metrics endpoint listen port	`9000`
`CLIENT_IP_SOURCE`	Sets the Client IP source for logging, see documentation for valid values	`ConnectInfo`
`CONTAINER_HEALTH_FILTER_LABEL`	Whether the `container_health` metric should only report containers which have the `docker-prometheus-exporter.metric.container_health.enabled=true` label	`true`

Container Labels

Label	Description
`docker-prometheus-exporter.metric.container_health.enabled=true`	When used in conjunction with the `CONTAINER_HEALTH_FILTER_LABEL=true` environment variable, enables the `container_health` metric for the corresponding container
`docker-prometheus-exporter.metric.container_health.enabled=false`	Disables the `container_health` metric for the corresponding container, regardless of the `CONTAINER_HEALTH_FILTER_LABEL` environment variable

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See CONTRIBUTING.md.

Dependencies

~20–32MB
~459K SLoC