diff --git a/docs/observability.md b/docs/observability.md index cb2f2b21..67224a0e 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -62,6 +62,29 @@ 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 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. + +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 Every `services.hyperhive.otel.*` option's full type/default/description/