Skip to content
Menu

Metrics#

This page explains how to turn on and protect the Prometheus /metrics endpoint, and the counters it serves about signing requests and assertions.

Turn it on#

Drawbridge can expose a Prometheus /metrics endpoint, off by default. It is on when DRAWBRIDGE_METRICS_TOKEN (a bearer token) or DRAWBRIDGE_METRICS_ALLOW (a comma list of client IPs/CIDRs) is set, and a request is served when it presents the token or comes from an allowed address. A disabled or misconfigured endpoint answers 404 and an unauthorized request answers 403, so the route is never advertised and never served to a stranger. The client address is REMOTE_ADDR (the real client), never a client-supplied header, so a spoofed X-Forwarded-For cannot grant access, and the token is compared in constant time.

Serve it#

When you wire it up yourself, point a web server at bin/metrics for the path. In Apache, a location such as:

<Location "/metrics">
    SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
    ScriptAlias /metrics /opt/drawbridge/bin/metrics
</Location>

serves it (the SetEnvIf passes the bearer token through; without it only the allow list works). In the gateway image the endpoint is a php-cgi child: render maps ^/metrics$ to bin/metrics with a virtual-host-level ScriptAliasMatch beside the Location block that stands outside sign-in and signing, and a fixup hook hands the child the access rules (DRAWBRIDGE_METRICS_TOKEN, DRAWBRIDGE_METRICS_ALLOW, DRAWBRIDGE_METRICS_DIR) and the client secret's expiry date (DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES) from the request, where the environment is still whole, because Apache passes no server environment to a CGI child.

The end-to-end tests run the gateway with a throwaway metrics token and check every app host answers /metrics to the bearer token (200, text/plain, Cache-Control: no-store) and refuses it otherwise (403).

What it serves#

The endpoint serves only what it can see truthfully:

Metric Type Meaning
drawbridge_build_info{version} gauge the gateway is up, and which release (Version::CURRENT in src/Version.php, the same value drawbridge --version prints)
drawbridge_signing_requests_total counter signing requests the assertion signer received
drawbridge_assertions_signed_total counter assertions the signer signed successfully
drawbridge_assertion_errors_total{reason} counter signing requests the signer refused or failed, by reason
drawbridge_oidc_client_secret_days_left gauge whole days until the Entra client secret expires, negative once it has; only when DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES is set (the expiry date)

The days-left gauge is worked out from the date on every scrape and never kept in the shared store, so it disappears with the setting instead of counting down a secret that was already replaced. Alert when it drops to 30 and again at 7.

The shared file-backed store#

The signing counters cross from the long-running signer to the per-request endpoint through a shared file-backed store: one JSON file per metric family in a directory (default /tmp/drawbridge-metrics, moved by DRAWBRIDGE_METRICS_DIR), written atomically while a per-family lock is held, so a reader always sees a whole file and two writers never lose an increment. Every process in the gateway container runs as the same UID, so plain file permissions are enough. Without a shared store the endpoint registers no counters at all, because a counter that is always zero is not shown. When the store cannot be created or written, the signer counts in memory and the endpoint serves build info only.

What it does not serve#

Apache, not PHP, serves the requests, so request counts by path class are not exposed here either, and public requests and sign-in failures never reach the PHP side; mod_auth_openidc would need its own status or log scraping to expose those. Labels carry no identity, claim, or token, and the reason label is folded to a fixed set (refused, failed, other), so it stays low-cardinality.