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): the agent label is self-reported, and auth won't fix it

Browse source 
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.
This commit is contained in:
atlas 2026-08-19 00:53:41 +02:00 • committed by mara
commit 50dab90d38
1 changed files with 15 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

15
docs/observability.md
View file

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