nordisk/holger

Prometheus /metrics — for idiots

Class: guide (beginner) · Function: metrics. The five-minute version. The real reference is metrics-guide.md.

The problem

Your Holger server is running. Is it busy? How many downloads? Any errors? How many artifacts are in each repo? You don't want to guess — you want a dashboard.

The fix

Holger speaks Prometheus, the standard "numbers about a server" format. Open one URL and you get all the numbers:

curl http://your-holger:PORT/metrics

You'll see lines like this:

holger_requests_total{verb="get"} 1284
holger_requests_total{verb="put"} 57
holger_requests_total{verb="promote"} 9
holger_bytes_served_total 90173441
holger_errors_total 0
holger_proxy_requests_total{result="primary_hit"} 903
holger_proxy_requests_total{result="miss"} 12
holger_repo_artifacts{repo="rust-dev"} 128

Read it as plain English:

• holger_requests_total{verb="get"} 1284 — 1284 downloads so far. (This counts requests to BOTH doors — the fast gRPC one apps use and the plain HTTP one.)
• holger_requests_total{verb="put"} 57 — 57 uploads.
• holger_requests_total{verb="promote"} 9 — 9 artifacts promoted DEV→PROD.
• holger_bytes_served_total 90173441 — ~90 MB sent to clients.
• holger_errors_total 0 — no server errors.
• holger_proxy_requests_total{result="primary_hit"} 903 — for a "proxy" repo (one that falls back to an upstream like crates.io when it doesn't have something), 903 requests were answered straight from Holger's own cache. The miss line (12) is how often it had to give up because neither Holger nor any upstream had it. More primary_hit/upstream_hit and fewer miss = a well-warmed cache.
• holger_request_duration_seconds_count 1341 (plus a stack of ..._bucket{le="…"} lines) — how long requests take. The _bucket lines say "this many finished within X seconds"; a dashboard turns them into a "95% of requests finished under N ms" graph. (This times the plain HTTP door for now.)
• holger_repo_artifacts{repo="rust-dev"} 128 — the rust-dev repo has 128 things in it right now.

Hook it to a dashboard

Prometheus (the monitoring tool) scrapes that URL every few seconds and draws graphs. Tell it where Holger is:

scrape_configs:
  - job_name: holger
    metrics_path: /metrics
    static_configs:
      - targets: ["your-holger:PORT"]

Then Grafana can graph requests-per-second, error rate, bytes served, and how each repo grows over time.

Three things to remember

1. It's read-only — looking at the numbers never changes anything.
2. The counters reset when Holger restarts (that's normal — Prometheus knows).
3. It's not behind a password (just like /healthz) — if you don't want the world seeing your numbers, keep the port private.