fviolence/docker-health-exporter

By fviolence

•Updated 10 months ago

Tiny Prometheus exporter that turns Docker container health and runtime state into clean metrics.

Image

Monitoring & observability

10K+

Overview Tags

fviolence/docker-health-exporter repository overview

⁠Docker Health Exporter

Tiny Prometheus exporter that turns Docker container health and runtime state into clean, scrape-friendly metrics. Works with Docker healthchecks or without them, and exposes sensible gauges you can alert on immediately.

⁠Why?

See which containers are healthy / starting / unhealthy at a glance.
Alert when a container restarts too often or stops running.
Works even if containers don’t define a healthcheck (they’ll be treated as healthy=1.0 by default).

⁠What it exports

⁠All metrics are labeled with: container, image, id, hostname (and status for the one-hot series).

Metric	Extra Labels	Description	Values / Notes
`docker_container_health`	—	Numeric container health (uses Docker healthchecks if present; otherwise treated as healthy).	`1.0` = healthy, `0.5` = starting, `0.0` = unhealthy. No healthcheck → `1.0`.
`docker_container_health_status`	`status`	One-hot health status series.	`status ∈ {healthy, starting, unhealthy, none}`; value is `1` for the current status else `0`. (`none` = no healthcheck defined.)
`docker_container_running`	—	Container running state (from `State.Running`).	`1` = running, `0` = not running.
`docker_container_restart_count`	—	Docker `RestartCount` exposed as a gauge.	Monotonic per container instance (increments on restarts).
`docker_container_started_at_seconds`	—	Start time in Unix seconds (`State.StartedAt`).	`0` if unknown.

⁠Old/container-gone series are removed automatically to avoid stale label sets.

⁠Quick start

⁠Docker (CLI)

docker run -d \
  --name docker-health-exporter \
  -p 9066:9066 \
  -e PORT=9066 \
  -e SCRAPE_INTERVAL=10 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  fviolence/docker-health-exporter:latest

⁠Docker Compose

services:
  docker-health-exporter:
    image: fviolence/docker-health-exporter:latest
    container_name: docker-health-exporter
    restart: unless-stopped
    environment:
      - PORT=9066
      - SCRAPE_INTERVAL=10
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "9066:9066"

⁠Now visit: http://:9066/metrics

⁠Prometheus scrape config

scrape_configs:
  - job_name: 'docker-health-exporter'
    static_configs:
      - targets: ['<host-or-ip>:9066']
        labels:
          instance: '<host-descriptive-name>'

⁠If Prometheus runs in Docker on the same host, you can use the host’s LAN IP or publish this exporter into the same Docker network and target it by container name + port.

⁠Grafana: a couple of instant queries

Overall health counts (per host):

sum by (hostname, status) (docker_container_health_status)

Unhealthy containers (list):

docker_container_health_status{status="unhealthy"} == 1

Running vs stopped:

sum by (hostname) (docker_container_running)

Restart spikes (top N):

topk(5, increase(docker_container_restart_count[1h]))

⁠Environment variables

Variable	Default	Description
`PORT`	`9066`	HTTP port to serve `/metrics`.
`BIND_ADDR`	`0.0.0.0`	Address to bind the HTTP server.
`SCRAPE_INTERVAL`	`10`	How often (seconds) to poll the Docker Engine.
`DOCKER_HOST`	(empty)	Optional override for Docker endpoint (e.g. `unix:///var/run/docker.sock`, `tcp://host:2375`). If unset, the exporter auto-probes common sockets and finally `docker.from_env()`.

⁠Security / permissions

Mount Docker socket read-only: -v /var/run/docker.sock:/var/run/docker.sock:ro.
The container does not require Docker write actions; it only reads metadata.
If you use a TCP Docker daemon, TLS-protect it. The exporter supports DOCKER_HOST, but assumes your daemon security.

⁠Example alerts

Container unhealthy:

- alert: ContainerUnhealthy
  expr: docker_container_health_status{status="unhealthy"} == 1
  for: 2m
  labels:
    severity: critical
  annotations:
    summary: "Container unhealthy ({{ $labels.container }})"
    description: "Container {{ $labels.container }} on {{ $labels.hostname }} is unhealthy"

Container not running:

- alert: ContainerNotRunning
  expr: docker_container_running == 0
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Container not running ({{ $labels.container }})"
    description: "Container {{ $labels.container }} on {{ $labels.hostname }} is not running"

Excessive restarts (last 30m):

- alert: ContainerRestartSpike
  expr: increase(docker_container_restart_count[30m]) > 3
  for: 1m
  labels:
    severity: warning
  annotations:
    summary: "Container restart spike ({{ $labels.container }})"
    description: "Container {{ $labels.container }} on {{ $labels.hostname }} restarted more than 3 times in 30m"

All sources available on GitHub: https://github.com/fviolence/docker-health-exporter⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:14116e61c…

Size

46.1 MB

Last updated

10 months ago

docker pull fviolence/docker-health-exporter