Observability
The four records a firewall keeps, firewall log, audit log, metrics, and observations, and which question each one answers.
A firewall produces four kinds of records. They overlap, so it is easy to look in the wrong one:
| Record | Answers | Granularity | Where |
|---|---|---|---|
| Firewall log | What happened to this package request, and which rule decided | One entry per logged rule decision | View logs, reference |
| Audit log | Who changed configuration, policy, tokens, teams | One event per control-plane action | Review the audit log, reference |
| Metrics | How much traffic, how much blocked, over time | Time-bucketed counters | Dashboard, reference |
| Observations | Which packages and versions are actually in use | One row per package version seen | Dashboard, reference |
Firewall log
A rule match writes an entry when the rule has logging enabled. Each one records:
- who requested which package version, through which firewall and upstream,
- which rule and execution phase decided, and whether it blocked,
- rule-specific output, such as vulnerability IDs or a malware finding with its scanner and confidence.
Exceptions that allowed a request through are recorded the same way.
Requests that match no rule, and rules configured without log, leave nothing behind. This is a decision trail, not a request trail. See What is logged when.
This is the log you use day to day: a developer's blocked install, a dry-run rule under evaluation, an exception being exercised. It can be queried or streamed live, and it defaults to your own entries, so looking at someone else's request takes an explicit flag. See View logs.
Audit log
Where the firewall log records what the firewall did to traffic, the audit log records what people did to the firewall: config imports, rule and exception changes, credential updates, token creation, team changes, permission denials, and OIDC exchanges.
Events carry the actor, the outcome, and action detail. Failures are recorded as deliberately as successes, so an attempt that was denied leaves the same kind of trail as a change that went through.
Metrics
Counters per time bucket, for the namespace or for one firewall: how much traffic came through, how much was blocked, how much an exception let through, and how many rules and exceptions are configured. The metrics reference lists every counter.
Metrics tell you that blocking spiked on Tuesday. The firewall log tells you which rule and which packages.
Versions hidden from a metadata response count as filtered versions. A blocked artifact request counts as a blocked download instead, whichever phase the rule that stopped it runs in.
Observations
An observation is a package version the firewall has actually served: first seen, last seen, request count, internal or external, enriched with a vulnerability severity summary.
Where the other three records are about events, observations are about state: what your organization currently depends on, as evidenced by real traffic rather than manifest files. It is the closest thing to an SBOM the firewall derives on its own.
Webhooks
The four records are pull surfaces: you query them. Webhooks push instead, delivering to HTTPS endpoints you run, signed and batched, as events happen:
- firewall log entries, download and upload decisions only,
- audit events,
- configuration changes,
- successful publishes.
The records stay the source of truth: a delivery that never arrives is a gap in your system, not in the log. See Receive webhook events.
Request and interaction IDs
Request IDs and interaction IDs stitch the records together. A blocked install error carries a request ID that finds the firewall log entry. An interaction ID appended to a CI token groups that pipeline's package requests and its audit events.
That is how you get from "the build failed" to the rule, the package, and the change behind it without guessing. See Investigate a blocked install.
Related
- How-to: View logs, Review the audit log
- Reference: Logs, Audit log, Metrics, Observations