From 5fcd2a93876d49c5cc1989f0acfe3f787796caf9 Mon Sep 17 00:00:00 2001 From: atlas Date: Wed, 19 Aug 2026 00:59:19 +0200 Subject: [PATCH] docs(observability): name both hops, not just "the hop" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review note from argus. The paragraph sits at the end of a subsection about the agent-to-collector hop, and said "authenticating the hop will not change that" — but the authentication it goes on to describe is on the hive-to-swarm hop, a different one. A reader arriving from the issue that tracks this ("the agent-to-collector hop presents no credential") would reasonably read "the hop" as the one that issue names and take away the opposite of what is meant. Both are now named where they are contrasted, as a two-item list rather than a sentence that has to be parsed twice: agent-to-collector stays open on the bridge, hive-to-swarm is where the credential goes and where the hive label stops being sender-chosen. Confirmed against swarm-otel.nix's own header rather than the issue history: the swarm tier is "the place that will stamp hive= from the authenticated connection rather than from anything a sender can choose". --- docs/observability.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) 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