diff --git a/docs/observability.md b/docs/observability.md index 4ed8ffa2..67224a0e 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -62,20 +62,28 @@ boundary (`docs/security.md`: capability = accepted risk), so an agent being able to *send* is an accepted extension of that boundary — but it is not closed by this design, and nothing here should be read as closing it. -**The `agent` label is self-reported, and authenticating the hop will not -change that.** Treat it as a convenience for grouping dashboards, never as -evidence of which container produced a sample: any agent that can reach the +**The `agent` label is self-reported, and no planned authentication changes +that.** Treat it as a convenience for grouping dashboards, never as evidence of +which container produced a sample: any agent that can reach this hive's collector can label its data as any other agent. -This is worth stating because the obvious fix does not exist. Authentication -happens once per *hive* — the swarm runs one collector, so the strongest -identity it can establish is which hive's door a sample arrived through, and -the mechanism gives it no more: a bearer-token check never reveals *which* -token matched, and a receiver reads request metadata rather than the claims it -authenticated with. So a verified `hive` is reachable and a verified `agent` is -not; that falls out of the topology rather than being a gap someone forgot to -close. If you need per-agent numbers you can act on, take them from the agent's -own turn-stats rather than from a metric label. +Worth spelling out, because two different hops are in play and only one of them +is getting a credential: + +- **agent→collector** (this section's hop) stays open on the bridge. Nothing + downstream can tell one agent's export from another's. +- **hive→swarm** is where the planned ingest auth goes. The swarm tier stamps + `hive=` from the connection it authenticated, so *that* label becomes + unforgeable. + +So a verified `hive` is reachable and a verified `agent` is not — and that falls +out of the topology rather than being a gap someone forgot to close. The swarm +runs one collector, and the mechanism gives it no finer grain: a bearer-token +check never reveals *which* token matched, and a receiver reads request metadata +rather than the claims it authenticated with. + +If you need per-agent numbers you can act on, take them from the agent's own +turn-stats rather than from a metric label. ## Options reference