Metrics
Reference for the traffic and enforcement counters, per namespace and per firewall.
Metrics are time-bucketed counters of what the firewall processed and enforced. The dashboard charts them on the namespace overview and on each firewall's page; the API endpoints below return the raw numbers for your own monitoring. The CLI has no metrics command. For which record answers which question, see Observability.
Endpoints
GET /v1/<namespace-id>/metrics
GET /v1/<namespace-id>/metrics/firewall/<firewall-id>| Parameter | Description |
|---|---|
periodMinutes | Window to return, ending now. Default 1440 (24 hours), maximum 43200 (30 days) |
bucketMinutes | Size of each returned bucket, maximum 1440 (24 hours). Metrics are recorded per minute and rolled up server-side. Defaults by period: 1 up to 1 hour, 5 up to 6 hours, 10 up to 24 hours, 60 up to 7 days, 180 beyond |
Reading metrics requires only namespace access.
Response shape
{
"periodMinutes": 1440,
"bucketMinutes": 10,
"buckets": [
{
"timestamp": "2026-07-03T09:00:00Z",
"requests": 412,
"downloads": 268,
"published": 2,
"processedVersions": 3801,
"blockedFilteredVersions": 121,
"blockedDownloads": 4,
"blockedUploads": 0,
"allowedByException": 1,
"rules": 6,
"exceptions": 3
}
],
"totals": { "requests": 9822, "downloads": 6120, "published": 14, "processedVersions": 88213, "blockedFilteredVersions": 2901, "blockedDownloads": 37, "blockedUploads": 1, "allowedByException": 12 },
"previousTotals": { "requests": 8514, "downloads": 5390, "published": 9, "processedVersions": 79102, "blockedFilteredVersions": 2544, "blockedDownloads": 29, "blockedUploads": 0, "allowedByException": 10 },
"inventoryCurrent": { "rules": 6, "exceptions": 3 }
}totals sums the buckets over the period. previousTotals sums the window of equal length immediately before it, for period-over-period comparison; those buckets are not returned. inventoryCurrent is the rule and exception count from the most recent bucket. Within a bucket, counters sum the underlying minutes; the rules and exceptions gauges take the highest value observed.
Counters
| Counter | Counts |
|---|---|
requests | Package requests handled |
downloads | Artifacts served |
published | Publishes forwarded to the publish target |
processedVersions | Versions the firewall read from upstream metadata responses |
blockedFilteredVersions | Versions filtered out of a metadata response by rules |
blockedDownloads | Downloads blocked by rules, on either the versions or the download phase |
blockedUploads | Publishes blocked by rules |
allowedByException | Package accesses a rule would have blocked but an exception allowed through, counted in every phase |
rules | Rules configured (gauge per bucket) |
exceptions | Exceptions configured (gauge per bucket) |
The enforcement counters describe different outcomes:
blockedFilteredVersionscounts versions the firewall removed from package metadata before the client picked one. The client usually does not notice: a version range resolves to an older version that passed the rules. This counter runs high compared to the other two: it counts filtered versions in metadata responses, not failed installs. See rule evaluation for how filtering plays out per request shape.blockedDownloadsandblockedUploadsare hard stops: a client asked for a specific artifact, or tried to publish one, and a rule refused. Artifact requests run the versions-phase rules too, so a client that skips resolution and fetches a filtered version directly is counted here, not underblockedFilteredVersions. These are the failures users experience, and the firewall log shows which rule and which package.allowedByExceptioncounts requests a rule would have blocked but an exception let through. If it rises steadily, those exceptions carry real traffic every day and are worth a review.
Related
- Concept: Observability
- Reference: Logs, API
- Per-webhook delivery metrics are separate: Webhooks