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