Prometheus Metrics
Scrape allow/block decisions, cache efficiency, upstream health, and latency from the firewall's /metrics endpoint.
Prometheus Metrics
Socket Registry Firewall exposes a Prometheus endpoint reporting allow and block decisions, cache efficiency, fail-open events, upstream registry health, and latency. Use it to alert on enforcement gaps and to measure the latency the firewall adds to installs.
The endpoint is always on and needs no configuration.
📝 Available from firewall image
1.1.343and later. The exemption from the client auth gate described below requires2.0.7or later.
Endpoint
| Property | Value |
|---|---|
| Path | GET /metrics (exact match) |
| Port | 9145, a dedicated listener separate from your request ports |
| Protocol | Plain HTTP, no TLS |
| Content type | text/plain; version=0.0.4; charset=utf-8 |
| Authentication | None |
| Other paths | 404, including /metrics/ with a trailing slash |
The listener binds 0.0.0.0:9145 and behaves identically in every deployment topology, so the same scrape config works for downstream, upstream, Artifactory, Nexus, and CodeArtifact deployments.
Scraping
Publish the port on your container:
services:
socket-firewall:
image: socketdev/socket-registry-firewall:latest
ports:
- "8443:8443"
- "9145:9145" # Prometheus metricsAdd a scrape job:
scrape_configs:
- job_name: socket-firewall
static_configs:
- targets: ['socket-firewall:9145']On Kubernetes, name the port on the Service and select it from a ServiceMonitor:
# Service
ports:
- name: metrics
port: 9145
# ServiceMonitor
endpoints:
- port: metrics
interval: 30sWhat a scrape returns
Series appear lazily, so do not assume every metric is always present.
- A freshly started firewall returns gauges only. Counters and histograms appear after their first observation, so a metric that has never fired is absent, not zero. To confirm the endpoint is working, pull one package through the firewall and scrape again.
- Guard queries with
or vector(0)and preferincrease(...) > 0over== 0checks. - Labeled series appear once their label combination is observed.
- Counters are pod-wide, so repeated scrapes of a multi-worker container return consistent totals with no per-worker aggregation needed.
Security
The endpoint is unauthenticated, served over plain HTTP, and bound on all interfaces. It carries no application-layer access control, so restrict who can reach the port at the network layer with nginx allow/deny rules, a Kubernetes NetworkPolicy, or a load balancer allow-list.
The listener is deliberately exempt from the client auth gate (bearer_token, basic_auth_username/basic_auth_password). When the gate is enabled, your request ports return 401 without a credential while 9145 continues to return 200, so scrapers never need to hold a firewall credential.
The payload is aggregate counters, histograms, and gauges only. It contains no package names, request URLs, API tokens, or user identifiers. The ecosystem label on the upstream and firewall-overhead series holds your route name. That is usually the ecosystem, such as npm, but it can be a repository name or a registry hostname, depending on how your routes are set up.
Metric reference
All metric names are prefixed socket_.
Decision counters
| Metric | Meaning |
|---|---|
socket_allowed_total | Package downloads allowed after a live Socket API lookup. See Known limitations |
socket_blocked_total | Package downloads blocked after a live Socket API lookup, plus cooldown holds and PyPI index rejections. See Known limitations |
socket_passthrough_total | Requests proxied upstream with no verdict because the URL was not recognized as a package |
socket_passthrough_by_kind_total | Same, split by ecosystem and kind (download, metadata, other) |
socket_fail_open_allowed_total | Requests allowed without a Socket verdict: the Socket API failed and fail_open is true, or Socket has no record of the package and unscanned packages are allowed (fail_open_unscanned, default true) |
socket_fail_closed_blocked_total | Requests blocked without a Socket verdict: the Socket API failed and fail_open is false, or the package is unscanned and fail_open_unscanned is false |
socket_fail_open_unvalidated_total | Downloads allowed because the firewall could not validate its access to Socket, with fail_open: true |
socket_fail_closed_unvalidated_total | Downloads blocked because the firewall could not validate its access to Socket, with fail_open: false |
socket_cooldown_passed_total | Packages that passed the cooldown policy check |
⚠️ The
*_unvalidated_totalcounters are the ones to alert on. A non-zero value means the firewall could not validate its access to Socket, for example because the firewall entitlement is off for your organization or the Socket API was unreachable before the first successful check. While that lasts, downloads are allowed or blocked without a policy check.
Do not treat socket_fail_open_allowed_total as an API-failure signal. Unscanned packages increment it in normal traffic, and a metadata listing counts each unscanned version, so it can exceed your request volume. For Socket API trouble, use socket_api_error_total and socket_api_breaker_open.
A rising socket_passthrough_by_kind_total with kind="download" means an artifact URL the parser could not classify streamed through unscanned. kind="metadata" is benign.
Cache counters
| Metric | Meaning |
|---|---|
socket_cache_hits_total | Decisions served from local or Redis cache while fresh |
socket_cache_misses_total | Decisions that required a fresh Socket API call |
socket_cache_stale_served_total | Decisions served from stale cache: while another request refreshes the entry, while the /purl circuit breaker is open, or after a failed Socket API call |
socket_cache_stale_revalidations_total | Stale cache revalidations started |
socket_cache_stale_updated_total | Stale revalidations that changed the cached verdict |
socket_cache_revalidation_lock_contention_total | Stale hits served because a revalidation lock was already held |
The stale-cache counters work with or without Redis. Without Redis, the cache lives in memory that all workers in the pod share.
API health counters
| Metric | Meaning |
|---|---|
socket_api_error_total | Socket API call failures, any cause |
socket_api_error_connect_total | Connection-level failures: timeout, refused, DNS |
socket_api_rate_limited_total | Socket API 429 responses |
socket_cooldown_api_error_total | Cooldown API call failures |
socket_background_revalidation_failed_total | Background stale-cache revalidations that failed |
socket_api_key_missing_total | Worker startups with no API token configured |
socket_breaker_open_skipped_total | API calls skipped because the /purl circuit breaker was open |
Histograms and labeled counters
Histograms expose _bucket, _sum, and _count series. Use histogram_quantile() for percentiles.
| Metric | Labels | Measures |
|---|---|---|
socket_upstream_duration_ms | ecosystem, kind | Firewall to upstream registry round trip, including full body read |
socket_firewall_overhead_ms | ecosystem | Latency the firewall itself added: total request time minus upstream duration. Only requests that reach the upstream registry are recorded, so blocked downloads are not included |
socket_upstream_status_total | ecosystem, code_class | Upstream responses by 2xx, 3xx, 4xx, 5xx, other |
socket_api_breaker_transitions_total | upstream, transition | Circuit breaker transitions: open, close, reopen |
For any request, client-observed time is roughly socket_firewall_overhead_ms plus socket_upstream_duration_ms. Keeping kind="metadata" and kind="download" separate matters, since a blended percentile tracks artifact size rather than how fast the registry responds.
Gauges
| Metric | Labels | Meaning |
|---|---|---|
socket_api_key_configured | 1 if a Socket API key is configured, 0 if missing | |
socket_redis_available | role | 1 if that Redis endpoint is reachable. role="primary" at 0 means the pod fell back to its in-memory cache. Present only when Redis is enabled. Versions before 2.7.0 emit it without the role label |
socket_api_breaker_open | upstream | 0 serving, 1 fast-failing. upstream="purl" is the breaker on the Socket API lookups behind allow and block decisions |
socket_circuit_breaker_state | sink | Event delivery to Socket telemetry and Splunk: 0 ok, 1 failing since the last successful send. Both sinks share one breaker |
socket_telemetry_queue_depth | sink | Events waiting in the telemetry, splunk, and webhook send queues |
socket_circuit_breaker_state and socket_telemetry_queue_depth describe event delivery, not policy enforcement, and they show the worker that answered the scrape rather than a pod total. For enforcement health, watch socket_api_breaker_open{upstream="purl"} and socket_api_error_total.
From 2.7.0, socket_redis_command_error_total counts Redis error replies such as READONLY, LOADING, or OOM. It should stay at 0.
The firewall also emits internal counters for metadata-filter load shedding, cache warming, and Redis pipeline timing. Contact support if you need them for an investigation.
Known limitations
These apply to current images unless a version is named. Know them before building dashboards or alerts.
Decision counters do not show total traffic. socket_allowed_total counts only downloads that needed a live Socket API lookup. Decisions served from cache are not counted, so a repeated pull of the same blocked package does not move socket_blocked_total after the first attempt. socket_blocked_total also counts cooldown holds and PyPI index rejections. Do not derive total volume or an allow/block ratio from these counters. Adding socket_cache_hits_total does not fill the gap, because it counts one lookup per package version when the firewall filters a metadata listing.
The metrics port is fixed at 9145. Current images do not read a port override from socket.yml. Remap it at the container or Service layer instead, for example -p 19145:9145.
socket_purl_check_latency_ms does not measure API latency. It is recorded only when a decision is served from cache, including a stale result served after a failed Socket API call. A successful live lookup never records it. Use socket_firewall_overhead_ms, which includes the verdict call, for the latency the firewall adds.
Versions 2.6.1 and 2.7.0 break every scrape. They emit a non-numeric sample, and Prometheus rejects the entire response, so the target reports up == 0 and no metrics are stored. Upgrade to 2.7.1 or later.
Example queries
Blocked decisions over five minutes. Read this with the cache caveat above:
rate(socket_blocked_total[5m]) or vector(0)
Upstream registry server errors by ecosystem, which separates a registry problem from a firewall problem. 4xx is left out because package managers trigger routine 404 responses:
sum by (ecosystem) (rate(socket_upstream_status_total{code_class="5xx"}[5m]))
Cache hit ratio:
rate(socket_cache_hits_total[5m])
/ (rate(socket_cache_hits_total[5m]) + rate(socket_cache_misses_total[5m]))
p99 firewall-added latency:
histogram_quantile(0.99, sum by (le, ecosystem) (rate(socket_firewall_overhead_ms_bucket[5m])))
Alert when the firewall stops enforcing policy:
increase(socket_fail_open_unvalidated_total[15m]) > 0
Alert when the API key goes missing:
socket_api_key_configured == 0
Verifying the endpoint
From the host:
curl -s http://localhost:9145/metrics | grep '^socket_api_key_configured'From inside the container, which is useful when the port is not published:
docker exec <container> curl -s http://127.0.0.1:9145/metrics | grep '^socket_api_key_configured'A working endpoint prints socket_api_key_configured 1. A value of 0 means the firewall has no Socket API key. If you get a connection refused, confirm the port is published and that you are using plain HTTP rather than HTTPS. If nothing prints, run the command again without | grep and look for a 404, which means the path is not exactly /metrics with no trailing slash.
Updated 30 days ago