rcooler/docker_exporter repository overview

⁠docker-exporter

Lightweight Docker metrics exporter for Docker Compose style projects. It collects a small set of project and container metrics and exposes them to Prometheus and MQTT/Home Assistant without the overhead of cadvisor.

⁠Features

• Per-container CPU usage percent
• Per-container memory usage bytes
• Per-project CPU usage percent
• Per-project memory usage bytes
• Total containers per project
• Running containers per project
• Prometheus metrics endpoint
• MQTT JSON state publishing
• Home Assistant MQTT discovery

⁠Requirements

• Docker Engine API access
• Go 1.26+ for local builds
• MQTT broker only if you want MQTT/Home Assistant export

The exporter reads the Docker Engine API directly. By default it uses unix:///var/run/docker.sock.

⁠Metrics

• docker_exporter_container_cpu_usage_percent
• docker_exporter_container_memory_usage_bytes
• docker_exporter_container_memory_limit_bytes
• docker_exporter_container_running
• docker_exporter_container_stats_collected
• docker_exporter_project_cpu_usage_percent
• docker_exporter_project_memory_usage_bytes
• docker_exporter_project_total_containers
• docker_exporter_project_running_containers
• docker_exporter_up
• docker_exporter_last_collection_timestamp_seconds
• docker_exporter_container_stats_errors

⁠Build

Local binary:

go build -o docker-exporter .

Docker image:

docker build -t docker-exporter:latest .

Published Docker Hub image:

docker pull rcooler/docker_exporter:latest

Docker Compose example:

docker compose -f docker-compose.example.yml up -d --build

⁠Run

Local process:

./docker-exporter \
  --docker-host unix:///var/run/docker.sock \
  --listen-address :9877

Docker container:

docker run -d \
  --name docker-exporter \
  -p 9877:9877 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  rcooler/docker_exporter:latest

With MQTT and Home Assistant discovery:

docker run -d \
  --name docker-exporter \
  -p 9877:9877 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e DOCKER_EXPORTER_MQTT_ENABLED=true \
  -e DOCKER_EXPORTER_MQTT_BROKER=tcp://host.docker.internal:1883 \
  -e DOCKER_EXPORTER_MQTT_USER=ha \
  -e DOCKER_EXPORTER_MQTT_PASS=change_me \
  -e DOCKER_EXPORTER_MQTT_CLIENT_ID=docker_exporter \
  -e DOCKER_EXPORTER_MQTT_TOPIC_PREFIX=docker_exporter \
  -e DOCKER_EXPORTER_MQTT_DISCOVERY_PREFIX=homeassistant \
  -e DOCKER_EXPORTER_MQTT_INTERVAL=60 \
  -e DOCKER_EXPORTER_MQTT_RETAIN=true \
  -e DOCKER_EXPORTER_MQTT_EXPIRE_AFTER=360 \
  rcooler/docker_exporter:latest

Docker Compose:

services:
  docker-exporter:
    build: .
    restart: unless-stopped
    ports:
      - "9877:9877"
    environment:
      DOCKER_HOST: "unix:///var/run/docker.sock"
      DOCKER_EXPORTER_MQTT_ENABLED: "true"
      DOCKER_EXPORTER_MQTT_BROKER: "tcp://host.docker.internal:1883"
      DOCKER_EXPORTER_MQTT_USER: "ha"
      DOCKER_EXPORTER_MQTT_PASS: "change_me"
      DOCKER_EXPORTER_MQTT_CLIENT_ID: "docker_exporter"
      DOCKER_EXPORTER_MQTT_TOPIC_PREFIX: "docker_exporter"
      DOCKER_EXPORTER_MQTT_DISCOVERY_PREFIX: "homeassistant"
      DOCKER_EXPORTER_MQTT_INTERVAL: "60"
      DOCKER_EXPORTER_MQTT_RETAIN: "true"
      DOCKER_EXPORTER_MQTT_EXPIRE_AFTER: "360"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

Full example file: docker-compose.example.yml⁠

⁠Configuration

Flags and env vars:

• --listen-address, LISTEN_ADDRESS
• --metrics-path, METRICS_PATH
• --scrape-interval, SCRAPE_INTERVAL
• --docker-host, DOCKER_HOST
• --docker-timeout, DOCKER_TIMEOUT
• --project-label, DOCKER_PROJECT_LABEL
• --standalone-project-name, STANDALONE_PROJECT_NAME
• --container-concurrency, CONTAINER_CONCURRENCY
• --mqtt-broker, MQTT_BROKER
• --mqtt-client-id, MQTT_CLIENT_ID
• --mqtt-username, MQTT_USERNAME
• --mqtt-password, MQTT_PASSWORD
• --mqtt-topic-prefix, MQTT_TOPIC_PREFIX
• --homeassistant-discovery-prefix, HOMEASSISTANT_DISCOVERY_PREFIX
• --mqtt-qos, MQTT_QOS
• --mqtt-retain, MQTT_RETAIN
• --mqtt-connect-timeout, MQTT_CONNECT_TIMEOUT
• --homeassistant-expire-after, HOMEASSISTANT_EXPIRE_AFTER

Preferred MQTT env vars:

• DOCKER_EXPORTER_MQTT_ENABLED
• DOCKER_EXPORTER_MQTT_BROKER
• DOCKER_EXPORTER_MQTT_USER
• DOCKER_EXPORTER_MQTT_PASS
• DOCKER_EXPORTER_MQTT_CLIENT_ID
• DOCKER_EXPORTER_MQTT_TOPIC_PREFIX
• DOCKER_EXPORTER_MQTT_DISCOVERY_PREFIX
• DOCKER_EXPORTER_MQTT_INTERVAL
• DOCKER_EXPORTER_MQTT_RETAIN
• DOCKER_EXPORTER_MQTT_QOS
• DOCKER_EXPORTER_MQTT_CONNECT_TIMEOUT
• DOCKER_EXPORTER_MQTT_EXPIRE_AFTER

DOCKER_EXPORTER_MQTT_INTERVAL and DOCKER_EXPORTER_MQTT_EXPIRE_AFTER accept either plain seconds like 60 and 360, or Go duration strings like 60s and 6m.

⁠Project Detection

Projects are detected from the label com.docker.compose.project by default. Containers without that label are grouped under standalone, unless you override it with --standalone-project-name.

⁠Notes

• Supported Docker host schemes: unix://, tcp://, http://, https://
• npipe:// is not implemented in this version
• The Docker socket mount is enough for Linux deployments