vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

Compare commits

base: vinzenz:06e8a9a09eca0b32d3b60f078d808dda008f02ab
Branches Tags
vinzenz:main
...
compare: vinzenz:5fcd2a93876d49c5cc1989f0acfe3f787796caf9
Branches Tags
vinzenz:main
Author SHA1 Message Date
atlas
5fcd2a9387 docs(observability): name both hops, not just "the hop" 
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".
 2026-08-30 14:39:27 +02:00
atlas
50dab90d38 docs(observability): the agent label is self-reported, and auth won't fix it 
The swarm runs one collector, so authenticating the agent-to-collector hop
establishes which hive a sample came through and nothing finer. 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 label is
reachable and a verified agent label is not.

That is a property of the topology, not an unfinished piece of work, and it
survives the ingest-auth change rather than being fixed by it. Said here
because the section already tells an operator what this hop does and does not
guarantee, and "we will authenticate it later" reads as though the agent label
becomes trustworthy later too.

Written as something a reader can act on: group dashboards by it, do not treat
it as evidence of origin, and take per-agent numbers from the agent's own
turn-stats instead.
 2026-08-30 14:39:27 +02:00
1 changed files with 23 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

23
docs/observability.md
View file

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