diff --git a/docs/observability.md b/docs/observability.md index 139b6e08..922144db 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -219,6 +219,32 @@ Cadence follows `metricIntervalMs` (default 60s). Transport is OTLP/HTTP first hop is unauthenticated for every producer on this host, and the upstream credential stays on the swarm tier. +## Agent-emitted per-turn metrics (`hive-agent`) + +When OTEL is enabled, the harness itself (`hive-agent`) exports one small set +of metrics per claude turn, recorded the moment the turn ends (not polled). +These are deliberately the fields Claude Code's own built-in export (see +above) can't know about — the harness's own wall-clock timing, what woke the +turn, its own outcome classification, the loose-ends backlog, and session +boundaries. Token usage, cost, and tool-call counts are **not** duplicated +here; that's already covered by Claude's own export. + +| Metric | Unit | Kind | Attributes | +|--------|------|------|------------| +| `hyperhive.agent.turn.duration` | `ms` | histogram | `wake_from`, `result_kind`, `model` | +| `hyperhive.agent.turn.count` | — | counter | `wake_from`, `result_kind`, `model` | +| `hyperhive.agent.session.count` | — | counter | `model` (incremented once per fresh, non-`--continue`'d session) | +| `hyperhive.agent.loose_ends.threads` | — | gauge | none | +| `hyperhive.agent.loose_ends.reminders` | — | gauge | none | + +Resource attributes (`service.name`, `agent`, `hive`, `swarm`) come from the +same container-wide `OTEL_RESOURCE_ATTRIBUTES` as everything else in this +section — nothing extra to configure. Cadence follows +`HYPERHIVE_OTEL_METRIC_INTERVAL_MS` (default 60s, same variable + default as +`hive-c0re`'s container-resource export above) — that only controls how often +the batched points are flushed to the collector, not how often they're +recorded (every turn, always). + ## Agent-emitted custom metrics (`hive-metric`) Agents can push arbitrary labeled metrics to the same OTEL collector via the