From 34b5fc72fe2ab43125c5869f46ec8084d25375ea Mon Sep 17 00:00:00 2001
From: damocles <damocles@hyperhive.local>
Date: Sun, 30 Aug 2026 19:48:21 +0200
Subject: [PATCH] docs/observability: fix stale hive-metric temporality docs

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.
---
 docs/observability.md | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/docs/observability.md b/docs/observability.md
index 67224a0e..cc967bb5 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -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).