Docker Prometheus Exporter

Exports basic metrics from Docker for scraping by Prometheus

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

Changelog

The full changelog can be found at CHANGELOG.md

[2.0.0] - 2025-09-02

Added

• Support for cli args, try --help
• Integration tests for all supported deployment methods, see EXAMPLES.md

Changed

• BREAKING CHANGE: recoverable panics now instead exit with an error message

Security

• Updated tracing-subscriber to patch CVE-2025-58160 / GHSA-xwfj-jgwm-7wp5

Usage

For a full list of usage methods, view EXAMPLES.md and the corresponding Docker Compose files in the examples/ directory.

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: 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:
    image: calum4/docker-prometheus-exporter:latest
    container_name: docker-prometheus-exporter
    user: "0:0" # root, 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

Security Considerations

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.

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

Argument Name	Environment Variable	Description	Default
N/A	RUST_LOG	Sets logging verbosity, see documentation	error
N/A	DOCKER_HOST	URI for the Docker Daemon, should already be set by Docker	Unix - unix:///var/run/docker.sock Windows - npipe:////./pipe/docker_engine
--listen-addr	LISTEN_ADDR	Metrics endpoint listen address	127.0.0.1
--listen-port	LISTEN_PORT	Metrics endpoint listen port	9000
--client-ip-source	CLIENT_IP_SOURCE	Sets the Client IP source for logging, see documentation for valid values	ConnectInfo
--container_health.filter_label	CONTAINER_HEALTH_FILTER_LABEL	Filter the container_health metric to only report containers with 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.