docs: trim observability.md's duplicate option-reference sections
The hand-maintained per-option reference (services.hyperhive.otel.*) restated what nixosOptionsDoc already generates from the same nix module's mkOption descriptions into /options/ — two copies of the same fact, one of which the build keeps honest and the other doesn't. Trimmed to a pointer, keeping only the architecture/security prose a flat per-option listing can't express. The port-conflict cross- reference (hive tier 4318 vs swarm tier 4319) that isn't in either option's own description is already covered in swarm/services.md, which this doc already links to.
This commit is contained in:
iris
parent
36810ae598
commit
3b0180e7d6
1 changed files with 7 additions and 96 deletions
|
|
@ -64,89 +64,13 @@ closed by this design, and nothing here should be read as closing it.
|
||||||
|
|
||||||
## Options reference
|
## Options reference
|
||||||
|
|
||||||
### `services.hyperhive.otel.enable` — bool, default `false`
|
Every `services.hyperhive.otel.*` option's full type/default/description/
|
||||||
|
example is generated straight from the nix module (`nix/host-modules/
|
||||||
Master switch. When true, all other options below take effect.
|
otel.nix`) into [`/options/`](/options/) (host options — `nix build
|
||||||
|
.#docs-host` for a local render). That page is kept honest by the build in a
|
||||||
### `services.hyperhive.otel.endpoint` — string, default `""`
|
way a hand-copied version here cannot be, so it is the reference, not this
|
||||||
|
doc. What follows is what a flat per-option listing can't express: the
|
||||||
Upstream OTLP endpoint URL, read by the swarm's collector. Example:
|
two-tier architecture, the security model, and how the options interact.
|
||||||
`"https://collector.example.com/otel"`.
|
|
||||||
|
|
||||||
Leave it empty on a swarm running its own metrics store — that store is then
|
|
||||||
the destination. With neither, the swarm collector is refused at eval:
|
|
||||||
telemetry with nowhere to go is a misconfiguration, not a quiet no-op.
|
|
||||||
|
|
||||||
Not what agents are handed. Their endpoint is this hive's own collector,
|
|
||||||
derived from the bridge address, so setting this changes where telemetry
|
|
||||||
*ends up* and never what a container is told.
|
|
||||||
|
|
||||||
### `services.hyperhive.otel.protocol` — enum, default `"http/protobuf"`
|
|
||||||
|
|
||||||
Wire protocol for the **upstream** link, honoured by the swarm collector's
|
|
||||||
exporter. Accepted values:
|
|
||||||
- `"http/protobuf"` (default)
|
|
||||||
- `"http/json"`
|
|
||||||
- `"grpc"`
|
|
||||||
|
|
||||||
Agents are not affected: their first hop is this hive's collector, whose
|
|
||||||
OTLP/HTTP receiver takes protobuf whatever the upstream wants.
|
|
||||||
|
|
||||||
### `services.hyperhive.otel.headersCredential` — string or null, default `null`
|
|
||||||
|
|
||||||
Absolute path to a secret file on the host holding the upstream auth header as
|
|
||||||
`NAME=value` (e.g. `Authorization=Bearer <token>`).
|
|
||||||
|
|
||||||
**Only the swarm's collector reads it** — the one tier that talks to the
|
|
||||||
upstream. It arrives as an `EnvironmentFile` on that unit, so the value is
|
|
||||||
never read by nix, never copied into the store or the generated config, never
|
|
||||||
passed in argv — and reaches **neither an agent container nor a hive's own
|
|
||||||
collector**. An agent cannot read the upstream credential because it is never
|
|
||||||
given one.
|
|
||||||
|
|
||||||
Set it on the host running the swarm's services; a hive that only forwards has
|
|
||||||
no use for it.
|
|
||||||
|
|
||||||
Leave `null` if the upstream needs no auth header; the collector then sends
|
|
||||||
none rather than an empty one.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
services.hyperhive.otel = {
|
|
||||||
enable = true;
|
|
||||||
endpoint = "https://collector.example.com/otel";
|
|
||||||
headersCredential = "/run/secrets/otel-headers";
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### `services.hyperhive.otel.extraResourceAttributes` — string, default `""`
|
|
||||||
|
|
||||||
Extra comma-separated entries appended to `OTEL_RESOURCE_ATTRIBUTES` after the
|
|
||||||
built-in labels (`service.name`, `agent`, `hive`, `swarm`). Example:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
extraResourceAttributes = "deployment.environment=prod,team=platform";
|
|
||||||
```
|
|
||||||
|
|
||||||
### `services.hyperhive.otel.debug` — bool, default `false`
|
|
||||||
|
|
||||||
When `true`, sets `CLAUDE_CODE_OTEL_DIAG_STDERR=1` in every agent container,
|
|
||||||
causing the OTEL SDK to emit diagnostic messages to stderr. Useful when
|
|
||||||
troubleshooting collector connectivity or endpoint config errors. Leave `false`
|
|
||||||
in normal operation — SDK errors from a misconfigured endpoint would otherwise
|
|
||||||
appear in every agent's journal unconditionally.
|
|
||||||
|
|
||||||
Only meaningful when `enable` is true.
|
|
||||||
|
|
||||||
### `services.hyperhive.otel.metricIntervalMs` — positive int or null, default `null`
|
|
||||||
|
|
||||||
Metric export interval in milliseconds, set as `OTEL_METRIC_EXPORT_INTERVAL`
|
|
||||||
for every agent. Claude Code's default is 60000 (60 s). Leave `null` to keep
|
|
||||||
that default.
|
|
||||||
|
|
||||||
Each agent runs claude as a short-lived per-turn process; claude force-flushes
|
|
||||||
metrics on process exit, so interval tuning is not required for metrics to be
|
|
||||||
exported. A lower value gives more frequent intermediate flushes within
|
|
||||||
long-running turns — cosmetic, not a correctness knob.
|
|
||||||
|
|
||||||
## The two collectors
|
## The two collectors
|
||||||
|
|
||||||
|
|
@ -211,19 +135,6 @@ belongs to exactly one hive.
|
||||||
Getting the secret wrong shows up as the hive's collector logging 401s from the
|
Getting the secret wrong shows up as the hive's collector logging 401s from the
|
||||||
swarm tier and no metrics appearing for that hive.
|
swarm tier and no metrics appearing for that hive.
|
||||||
|
|
||||||
### `services.hyperhive.otel.collector.port` — port, default `4318`
|
|
||||||
|
|
||||||
The OTLP/HTTP port the hive tier listens on, bound to the bridge IP only. The
|
|
||||||
swarm tier has its own (`swarm.otel.port`, default `4319`) — they share a
|
|
||||||
network namespace when co-located, so the two must differ.
|
|
||||||
|
|
||||||
### `services.hyperhive.otel.collector.upstreamHeaderName` — string, default `"Authorization"`
|
|
||||||
|
|
||||||
Name of the header the swarm tier sends upstream. The **value** comes from the
|
|
||||||
credential file at runtime (`EnvironmentFile` → `${env:<name>}`), never from
|
|
||||||
nix — so header names are config and header values are secrets, which is the
|
|
||||||
only split a static header map can express.
|
|
||||||
|
|
||||||
⚠️ **`endpoint` must be valid for `protocol`.** The upstream exporter follows
|
⚠️ **`endpoint` must be valid for `protocol`.** The upstream exporter follows
|
||||||
`otel.protocol` (`grpc` → the gRPC exporter, otherwise OTLP/HTTP), and the gRPC
|
`otel.protocol` (`grpc` → the gRPC exporter, otherwise OTLP/HTTP), and the gRPC
|
||||||
exporter takes an *address*: `https://host/path` is a legal
|
exporter takes an *address*: `https://host/path` is a legal
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue