From 682dd81af2f502796de15208f19ad7ac8ba29ba5 Mon Sep 17 00:00:00 2001 From: damocles Date: Mon, 24 Aug 2026 20:00:14 +0200 Subject: [PATCH] docs(observability): document swarm-controller's vcs commit/push metrics --- docs/observability.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/observability.md b/docs/observability.md index 72e79f4f..c86a9013 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -270,6 +270,30 @@ detail behind it — `warn`-level entries mean "an operator should look" and do Same cadence, transport and resource labels as the container metrics above. +## VCS activity metrics (`swarm-controller`) + +`swarm-controller` registers a single instance-wide Forgejo webhook (a +"global/system" hook, not scoped to any one org or repo) and counts commit +and push activity as deliveries arrive — occurrence-driven, not polled. +Forgejo's own native `/metrics` endpoint has no equivalent: it exposes +counts of durable rows (issues, comments, repos), and neither a commit nor a +push is stored anywhere as a row to count. + +| Metric | Unit | Kind | Attributes | +|--------|------|------|------------| +| `hyperhive.vcs.commit.count` | — | counter | `repo` (`org/repo`) | +| `hyperhive.vcs.push.count` | — | counter | `repo` (`org/repo`) | + +A push with zero commits (a branch delete, or a force-push that doesn't add +new commits) still increments `push.count`; `commit.count` only advances +when the delivery actually carries commits. Same enable signal (`OTEL_EXPORTER_OTLP_ENDPOINT`), cadence variable +(`HYPERHIVE_OTEL_METRIC_INTERVAL_MS`) and `HYPERHIVE_OTEL_EXTRA_RESOURCE_ATTRIBUTES` +resource-attribute channel as `swarm-controller`'s other OTEL exporter (its +`hive-jobq-metrics`-backed job-graph rollup, undocumented here — see that +crate's own doc comment) — `service.name = swarm-controller` is set +directly rather than read from the container environment, since +`swarm-controller` is a standalone daemon, not a per-agent harness process. + ## Agent-emitted custom metrics (`hive-metric`) Agents can push arbitrary labeled metrics to the same OTEL collector via the