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: fix stale hive-metric temporality docs

Browse source 
Usage synopsis was missing --temporality, --type's description still
said cumulative-by-default, and the tasks_completed example comment
still called it a cumulative counter. Also name hive-metric as the
documented exception to the always-cumulative policy, and note the
query-idiom consequence: sum_over_time()/rate_over_sum() instead of
rate()/increase(), since the collector pipeline has no
deltatocumulative processor.
This commit is contained in:
damocles 2026-08-30 19:48:21 +02:00
commit 34b5fc72fe
1 changed files with 18 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

22
docs/observability.md
View file

@ -327,13 +327,18 @@ Agents can push arbitrary labeled metrics to the same OTEL collector via the
### Usage
```text
hive-metric <name> <value> [--type counter|gauge] [--labels key=value...]
hive-metric <name> <value> [--type counter|gauge] [--temporality delta|cumulative] [--labels key=value...]
```
- `<name>` — metric name (e.g. `tasks_completed`, `latency_ms`).
- `<value>` — numeric value (f64; integers and floats both accepted).
- `--type counter|gauge` — metric kind: `counter` (cumulative sum, default) or
- `--type counter|gauge` — metric kind: `counter` (increasing sum, default) or
`gauge` (instantaneous point-in-time value).
- `--temporality delta|cumulative` — counter reporting mode (`counter` only,
ignored for `gauge`): `delta` (this call's own contribution, default — send
`1` each time and the collector accumulates) or `cumulative` (this call
reports the running total, which a stateless one-shot CLI can't track
itself).
- `--labels key=value` — extra per-data-point labels. May be repeated.
The resource labels (agent, hive, swarm, service.name) are inherited
automatically from `OTEL_RESOURCE_ATTRIBUTES` — do not re-specify them.
@ -341,7 +346,7 @@ hive-metric <name> <value> [--type counter|gauge] [--labels key=value...]
### Examples
```text
# Counter: cumulative tasks finished (default type — no --type flag needed)
# Counter: one more task finished (delta is the default — no flag needed)
hive-metric tasks_completed 1 --labels phase=scan
# Gauge: current queue depth (absolute value — must use --type gauge)
@ -366,8 +371,17 @@ with an informative error message. No silently-dropped metrics.
## Metrics temporality
OTEL export is always configured with **cumulative** temporality
OTEL export is configured with **cumulative** temporality by default
(`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative`),
overriding Claude Code's default of DELTA. This avoids silent metric drops in
Prometheus-family backends (including Grafana LGTM / Mimir) that don't ship a
delta-to-cumulative processor.
**`hive-metric` counters are the one exception**, reporting delta by default
(see above) — programmatically set on the exporter, which overrides this
container-wide env var for that tool specifically. `--type gauge` is
unaffected either way; gauges have no temporality. The collector pipeline
here has no `deltatocumulative` processor, so a delta `hive-metric` counter's
raw values land in VictoriaMetrics as-is — query it with `sum_over_time()` /
`rate_over_sum()`, not the standard `rate()`/`increase()` (those re-diff an
already-delta series and produce wrong numbers).