I built a Prometheus exporter for Docker Compose health monitoring

Source: Dev.to

The problem

I run multiple Docker Compose stacks on my homelab server (Jellyfin, Sonarr, Radarr, etc.). I needed a simple way to monitor the health of each service—whether it’s running, restart count, CPU and memory usage—and expose those metrics to Prometheus for alerting and Grafana dashboards.

Existing solutions were either too heavy or didn’t understand Docker Compose service naming. I wanted something lightweight that auto‑discovers docker-compose.yml and just works.

docker‑health‑monitor

A small Python CLI that:

• Parses docker-compose.yml to discover services
• Queries the Docker daemon for container status, restart count, CPU %, memory
• Exposes metrics in Prometheus text format on /metrics
• Provides a nice console status command with Rich tables
• Auto‑discovers docker-compose.yml (searches current directory and parents)

Prometheus metrics

Additional features

• Health‑check endpoint (/healthz) for the exporter itself
• Include / exclude service filters
• Configuration via YAML file or environment variables
• Threaded HTTP server (concurrent scrapes)
• Graceful shutdown on SIGTERM/SIGINT

Installation

pipx install docker-health-monitor

Or install from source:

git clone https://github.com/kernelghost557/docker-health-monitor.git
cd docker-health-monitor
poetry install

Usage

Show status in the terminal

docker-health-monitor status --compose-path ./docker-compose.yml

Start the Prometheus exporter

docker-health-monitor serve --port 8000 --compose-path ./docker-compose.yml

Prometheus can then scrape http://localhost:8000/metrics.

Configuration file (.docker-health-monitor.yaml)

compose_path: "/opt/media/docker-compose.yml"
interval: 30
include_services: ["jellyfin", "sonarr", "radarr", "qbittorrent"]
exclude_services: ["watchtower"]

Implementation details

The DockerComposeCollector reads the Compose file, resolves service names to container names (using the project name), then uses docker ps and docker stats to gather metrics.

Metrics are exposed via the prometheus_client library:

from prometheus_client import Gauge

SERVICE_UP = Gauge(
    "docker_compose_service_up",
    "Service availability (1=up, 0=down)",
    ["service"]
)
RESTART_COUNT = Gauge(
    "docker_compose_restart_count",
    "Number of container restarts",
    ["service"]
)
CPU_PERCENT = Gauge(
    "docker_compose_cpu_percent",
    "CPU usage percentage",
    ["service"]
)
MEMORY_BYTES = Gauge(
    "docker_compose_memory_bytes",
    "Memory usage in bytes",
    ["service"]
)

On each /metrics request:

metrics = collector.get_metrics()
exporter.update(metrics)
data = exporter.generate()
self.wfile.write(data)

Example terminal output

┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┓
┃ Service           ┃ State  ┃ CPU %    ┃ RAM   ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━┩
│ jellyfin          │ healthy│ 2.3      │ 450M  │
│ sonarr            │ healthy│ 0.4      │ 180M  │
│ radarr            │ healthy│ 0.6      │ 220M  │
│ qbittorrent       │ running│ 8.1      │ 1.2G  │
└───────────────────┴────────┴──────────┴───────┘

Example Prometheus metrics

# HELP docker_compose_service_up Service availability (1=up, 0=down)
# TYPE docker_compose_service_up gauge
docker_compose_service_up{service="jellyfin"} 1
docker_compose_service_up{service="sonarr"} 1

# HELP docker_compose_restart_count Number of container restarts
# TYPE docker_compose_restart_count gauge
docker_compose_restart_count{service="jellyfin"} 0

Future work

• Add alerting via webhook on state change
• Support multiple Compose files
• CSV/JSON export for offline analysis
• Docker image with a non‑root user

Repository

GitHub - kernelghost557/docker-health-monitor