registry-stats

Track how many times your container images are pulled — with a ready-made Grafana dashboard.

What it does

When you publish a container image to Docker Hub or GitHub Container Registry (GHCR), each registry tracks how many times that image has been downloaded — but there's no built-in way to see those numbers over time, compare trends, or get alerts. Registry Stats solves this by polling the registries on a schedule and exposing the download counts as Prometheus metrics for dashboards and alerting.

• Prometheus metrics (/metrics) — pull counts as gauges, scraped by any Prometheus-compatible collector for native Grafana dashboards
• Supports both explicit repos (myuser/myapp) and owner wildcards (myuser/*) to automatically discover and track all public repos for an owner. Wildcards are resolved on each poll cycle, so newly published images are picked up automatically.

Why this design

• Stateless — no on-disk persistence required. The app polls registries and exposes current counts as Prometheus metrics. Time-series history lives in your Prometheus/Mimir backend.
• Minimal dependencies — no non-cplieger runtime deps beyond golang.org/x/sync; the cplieger httpx / health / metrics libraries supply retry/backoff, the health probe, and Prometheus exposition. Small, auditable supply chain.
• Distroless, rootless container — runs as nonroot on gcr.io/distroless/static-debian13 with no shell or package manager, minimising attack surface.
• Public repos only — avoids credential management entirely.

Limitations

• Public repositories only. Docker Hub uses the unauthenticated API. GHCR download counts are scraped from public package pages. Private repositories and packages are not supported.
• GHCR scraping is fragile. Download counts and package listings are extracted from GitHub's HTML, not an official API. If GitHub changes their page structure, scraping will break. The container logs a clear error with a link to open an issue when this happens.
• No historical backfill. The registries only expose current totals. Time-series data is built by your Prometheus backend as scrapes accumulate.

Quick start

The image is published to both ghcr.io/cplieger/registry-stats and docker.io/cplieger/registry-stats — use whichever registry you prefer.

services:
  registry-stats:
    image: ghcr.io/cplieger/registry-stats:latest
    container_name: registry-stats
    restart: unless-stopped

    environment:
      # Set at least one repo; leaving both empty makes the container report unhealthy after the first collect.
      DOCKERHUB_REPOS: ""  # owner/repo or owner/* format, comma-separated
      GHCR_REPOS: ""  # owner/package or owner/* format, comma-separated
      POLL_INTERVAL_HOURS: "1"  # 0 = collect once then serve

    ports:
      - "9100:9100"

Configuration reference

Environment variables

Variable	Description	Default	Required
DOCKERHUB_REPOS	Comma-separated list of Docker Hub repositories to track. Use owner/repo for specific repos or owner/* to auto-discover all public repos for an owner (e.g. myuser/*,otheruser/specific-app)	``	No
GHCR_REPOS	Comma-separated list of public GHCR packages to track. Use owner/package for specific packages or owner/* to auto-discover all public packages for an owner (e.g. myuser/*,otheruser/specific-app)	``	No
LOG_LEVEL	Logging verbosity: debug, info, warn, or error. Unrecognized values fall back to info	info	No
POLL_INTERVAL_HOURS	Hours between collection cycles. Set to 0 to collect once and then only serve metrics (no recurring polls). Wildcards are re-expanded on each cycle, picking up newly published images	1	No
ENABLE_METRICS	Enable Prometheus metrics endpoint	true	No
LISTEN_ADDR	TCP listen address for the HTTP server in host:port form. The port must match the published container port	:9100	No

Ports

Port	Description
9100	HTTP server (Prometheus metrics + health endpoint)

API reference

The HTTP server listens on port 9100.

Endpoints

GET /api/health

Returns {"status":"ok"} when healthy, or {"status":"unready","reason":"..."} with HTTP 503 when the most recent collect cycle returned no data (every configured registry failed, or no repos are configured). The marker is set healthy as soon as the HTTP API is listening, so a slow first collect cannot trip the Docker healthcheck grace window; it flips to 503 only once a collect cycle completes with an empty result. Used as the Docker healthcheck endpoint.

GET /metrics

Prometheus text format metrics. Includes:

• registrystats_image_pulls_total{registry,owner,repo} — current pull count per image
• registrystats_image_tags{registry,owner,repo} — tag count per image
• registrystats_http_requests_total{method,path,status} — HTTP request counters
• registrystats_http_request_duration_seconds — request latency histogram
• registrystats_collects_total{source} — total collect runs per source (successful + failed; collect_errors_total is the failed subset, so collect_errors_total / collects_total is the per-source failure ratio)
• registrystats_collect_errors_total{source} — failed collects per source
• registrystats_collect_duration_seconds — collect cycle duration histogram
• process_goroutines, process_heap_bytes, process_uptime_seconds — runtime metrics

Disabled when ENABLE_METRICS=false.

Grafana integration

Registry Stats exposes Prometheus metrics at /metrics. The included grafana-dashboard.json uses PromQL and requires only a standard Prometheus datasource — no plugins needed.

Setup

1. Add a scrape target for registry-stats:9100 in your Prometheus/Alloy/Grafana Agent config
2. Import grafana-dashboard.json in Grafana
3. Select your Prometheus/Mimir datasource when prompted

Alloy example:

prometheus.scrape "registry_stats" {
  targets         = [{ __address__ = "registry-stats:9100" }]
  forward_to      = [prometheus.remote_write.default.receiver]
  scrape_interval = "60s"
  job_name        = "registry-stats"
  metrics_path    = "/metrics"
}

Prometheus example (prometheus.yml):

scrape_configs:
  - job_name: registry-stats
    scrape_interval: 60s
    static_configs:
      - targets: ["registry-stats:9100"]

The dashboard shows cumulative downloads, daily deltas, package overview, and tracked package count — all via standard PromQL.

Healthcheck

The container includes a built-in Docker healthcheck using a marker file at /tmp/.healthy. The marker is created as soon as the HTTP API is listening, then refreshed after every collection cycle: a cycle that collects at least one repo keeps the marker present, and a cycle in which every configured registry fails removes it. The health subcommand (/registry-stats health) checks for this file and exits 0 when healthy. The first collect runs in the background so a slow initial poll (GHCR paces each package by a few seconds) cannot exceed the Docker healthcheck grace window and trigger a restart loop: the container reports healthy on boot, then reflects the first cycle's real outcome once it finishes. If both registries are unreachable on first boot the marker flips to unhealthy after that cycle and recovers on the next successful poll. Partial failures are tolerated: one successful repo keeps the container healthy. Wildcard expansion failures alone do not cause unhealthy status if explicit repos still succeed.

Security

No vulnerabilities found. All scans clean across the full scanner battery.

Tool	Result
govulncheck	No vulnerabilities in call graph
golangci-lint (gosec)	0 issues
trivy	0 vulnerabilities (distroless base)
grype	0 vulnerabilities
gitleaks	No secrets detected
semgrep	1 info (false positive)
hadolint	Clean

Prometheus metrics endpoint designed for internal scraping. No authentication required (standard for internal metrics APIs). Runs as nonroot on a distroless base image with no shell. The HTTP client follows redirects only within a host allowlist (httpx.DockerGitHubRedirectPolicy: docker.com / github.com / githubusercontent.com, 5-hop cap) so a compromised or misconfigured upstream cannot bounce the polling request to an arbitrary third-party host (the registries legitimately redirect to their own CDNs/blob stores).

Details for advanced users: URL path segments validated via isSafeURLSegment (rejects /%\?#@:). Response bodies capped via io.LimitReader (10 MB JSON, 2 MB HTML). HTTP server sets all five timeouts. Retry-After response headers are honoured on 429/503 responses (capped at the configured retry backoff ceiling). A GHCR page that exceeds the HTML body cap is treated as a format-change signal, not silently truncated. Semgrep flags math/rand/v2 usage, which is correct for jitter timing (not crypto).

Hardened deployment

To lock the container down further, layer these directives onto the Quick start service:

    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - "/tmp:size=1m,mode=1777,noexec,nosuid,nodev"

read_only: true makes the root filesystem read-only, so the file-marker health probe needs a writable /tmp; the tmpfs supplies it. size=1m is ample for the bare /tmp/.healthy marker, the only thing registry-stats writes to disk.

Dependencies

All dependencies are updated automatically via Renovate and pinned by digest or version for reproducibility.

Dependency	Source
golang	Go
Distroless static	Distroless
golang.org/x/sync	Go stdlib
pgregory.net/rapid	pkg.go.dev

Credits

This is an original tool that builds upon Docker Hub API.

Contributing

Issues and pull requests are welcome. Please open an issue first for larger changes so the approach can be discussed before implementation.

Disclaimer

This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.

This project was built with AI-assisted tooling using Claude Opus and Kiro. The human maintainer defines architecture, supervises implementation, and makes all final decisions.

License

This project is licensed under the GNU General Public License v3.0.