vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(observability): name both hops, not just "the hop"

Browse source 
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".
This commit is contained in:
atlas 2026-08-19 00:59:19 +02:00 • committed by mara
commit 5fcd2a9387
1 changed files with 20 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

32
docs/observability.md
View file

@ -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