What This Is (and Isn't)
Watchtower isn't a monitoring platform — it doesn't watch CPU, memory, or your application's health. What it can do is report on its own activity: how many containers it checked, how many it updated, and how many update attempts failed. If you already run Prometheus and Grafana for your infrastructure, scraping this gives you a small panel showing "is Watchtower actually doing anything" without logging into the host to read docker logs.
Enabling the Metrics Endpoint
services:
watchtower:
image: containrrr/watchtower
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- WATCHTOWER_HTTP_API_TOKEN=change-this-to-a-long-random-string
- WATCHTOWER_HTTP_API_METRICS=trueThe metrics endpoint shares the same token-based authentication as HTTP API mode — you need WATCHTOWER_HTTP_API_TOKEN set regardless of whether you're using the update-trigger endpoint, the metrics endpoint, or both.
What Gets Exposed
| Metric | Type | Meaning |
|---|---|---|
watchtower_containers_scanned | Gauge | Containers checked in the most recent scan |
watchtower_containers_updated | Gauge | Containers successfully updated in the most recent scan |
watchtower_containers_failed | Gauge | Update attempts that failed in the most recent scan |
watchtower_scans_total | Counter | Total scan cycles since the container started |
watchtower_scans_skipped | Counter | Total scans skipped since the container started |
Prometheus Scrape Config
Point a scrape job at the endpoint, passing the token as a bearer token:
scrape_configs:
- job_name: 'watchtower'
metrics_path: /v1/metrics
scheme: http
authorization:
type: Bearer
credentials: change-this-to-a-long-random-string
static_configs:
- targets: ['watchtower-host:8080']From there it's a normal Prometheus target — build a Grafana panel on watchtower_containers_failed if you want to be alerted the moment an update starts failing, rather than discovering it days later when you notice a container is stuck on an old image.
containrrr/watchtower is frozen at its last release; nickfedor/watchtower continues to receive updates) before depending on it for production alerting.Frequently Asked Questions
Set WATCHTOWER_HTTP_API_TOKEN and enable the metrics API, then expose port 8080. Metrics are served at /v1/metrics, authenticated the same way as the update endpoint.
watchtower_containers_scanned, watchtower_containers_updated, and watchtower_containers_failed as gauges reflecting the last scan, plus watchtower_scans_total and watchtower_scans_skipped as running counters since startup.
It's documented as experimental. Treat metric names and availability as subject to change between releases, and check your specific image's changelog before building critical alerting on it.