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.343 and later. The exemption from the client auth gate described below requires 2.0.7 or later.

Endpoint

PropertyValue
PathGET /metrics (exact match)
Port9145, a dedicated listener separate from your request ports
ProtocolPlain HTTP, no TLS
Content typetext/plain; version=0.0.4; charset=utf-8
AuthenticationNone
Other paths404, 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 metrics

Add 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: 30s

What 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 prefer increase(...) > 0 over == 0 checks.
  • 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

MetricMeaning
socket_allowed_totalPackage downloads allowed after a live Socket API lookup. See Known limitations
socket_blocked_totalPackage downloads blocked after a live Socket API lookup, plus cooldown holds and PyPI index rejections. See Known limitations
socket_passthrough_totalRequests proxied upstream with no verdict because the URL was not recognized as a package
socket_passthrough_by_kind_totalSame, split by ecosystem and kind (download, metadata, other)
socket_fail_open_allowed_totalRequests 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_totalRequests 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_totalDownloads allowed because the firewall could not validate its access to Socket, with fail_open: true
socket_fail_closed_unvalidated_totalDownloads blocked because the firewall could not validate its access to Socket, with fail_open: false
socket_cooldown_passed_totalPackages that passed the cooldown policy check

⚠️ The *_unvalidated_total counters 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

MetricMeaning
socket_cache_hits_totalDecisions served from local or Redis cache while fresh
socket_cache_misses_totalDecisions that required a fresh Socket API call
socket_cache_stale_served_totalDecisions 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_totalStale cache revalidations started
socket_cache_stale_updated_totalStale revalidations that changed the cached verdict
socket_cache_revalidation_lock_contention_totalStale 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

MetricMeaning
socket_api_error_totalSocket API call failures, any cause
socket_api_error_connect_totalConnection-level failures: timeout, refused, DNS
socket_api_rate_limited_totalSocket API 429 responses
socket_cooldown_api_error_totalCooldown API call failures
socket_background_revalidation_failed_totalBackground stale-cache revalidations that failed
socket_api_key_missing_totalWorker startups with no API token configured
socket_breaker_open_skipped_totalAPI 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.

MetricLabelsMeasures
socket_upstream_duration_msecosystem, kindFirewall to upstream registry round trip, including full body read
socket_firewall_overhead_msecosystemLatency 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_totalecosystem, code_classUpstream responses by 2xx, 3xx, 4xx, 5xx, other
socket_api_breaker_transitions_totalupstream, transitionCircuit 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

MetricLabelsMeaning
socket_api_key_configured1 if a Socket API key is configured, 0 if missing
socket_redis_availablerole1 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_openupstream0 serving, 1 fast-failing. upstream="purl" is the breaker on the Socket API lookups behind allow and block decisions
socket_circuit_breaker_statesinkEvent delivery to Socket telemetry and Splunk: 0 ok, 1 failing since the last successful send. Both sinks share one breaker
socket_telemetry_queue_depthsinkEvents 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.


Did this page help you?