Files
coder/scripts/metricsdocgen
Jaayden HalkoandMathias Fredriksson 8bf271c503 feat: add Prometheus metrics for the usage publisher (#28368)
The Tallyman usage publisher (`enterprise/coderd/usage/publisher.go`)
had no metrics; failures were only visible in logs and the
`usage_events.failure_message` column.

This adds five metrics under `coderd_usage_events_*`:

| Metric | Type | Meaning |
|---|---|---|
| `publish_results_total{result, event_type}` | counter | Per-event
outcomes from real Tallyman responses (`accepted`,
`rejected_temporarily`, `rejected_permanently`; events missing from the
response count as temporary) |
| `publish_send_errors_total` | counter | Ingest requests that failed
entirely (HTTP error, non-200, decode error), one per request |
| `pending` | gauge | Unpublished events still inside the 30-day
publishing window |
| `pending_oldest_age_seconds` | gauge | Age of the oldest pending event
(0 when none) |
| `expired` | gauge | Unpublished events older than 30 days that will
never be published |

Send errors and per-event results never double-count: when a request
fails, the publisher fakes an all-temporarily-rejected response for the
DB update, but only `publish_send_errors_total` increments, so
`publish_results_total` reflects only real Tallyman verdicts.

The gauges are backed by a new read-only `GetUsageEventsStats` query
(authorized as `ActionRead` on `ResourceUsageEvent`) and refreshed from
the publish loop after each attempt, so they update roughly every 17
minutes.

Metrics are created with `promauto.With(reg)` where the registerer
defaults to nil, so existing callers and tests need no changes;
`enterprise/cli/server.go` wires in the deployment's
`PrometheusRegistry` via the new `PublisherWithPrometheusRegisterer`
option.

Closes
https://linear.app/codercom/issue/CODAGT-833/e3-prometheus-metrics-for-the-usage-publisher

---------

Co-authored-by: Mathias Fredriksson <mafredri@gmail.com>
2026-08-28 15:44:31 +07:00
..

Metrics Documentation Generator

This tool generates the Prometheus metrics documentation at docs/admin/integrations/prometheus.md.

How It Works

The documentation is generated from two metrics files:

  1. metrics (static, manually maintained)
  2. generated_metrics (auto-generated, do not edit)

These files are merged and used to produce the final documentation.

metrics (static)

Contains metrics that are not directly defined in the coder source code:

  • go_*: Go runtime metrics
  • process_*: Process metrics from prometheus/client_golang
  • promhttp_*: Prometheus HTTP handler metrics
  • coder_ai_gateway_*: AI Gateway metrics are registered through prefixed registerer that the scanner does not resolve.

Note

This file also contains edge cases where metric metadata cannot be accurately extracted by the scanner (e.g., labels determined by runtime logic). Static metrics take priority over generated metrics when both files contain the same metric name.

Edit this file to add metrics that should appear in the documentation but are not scanned from the coder codebase, or to manually override metrics where the scanner generates incorrect metadata (e.g., missing runtime-determined labels like in agent_scripts_executed_total).

generated_metrics (auto-generated)

Contains metrics extracted from the coder source code by the AST scanner (scanner/scanner.go).

Do not edit this file directly. It is regenerated by running:

make scripts/metricsdocgen/generated_metrics

Updating Metrics Documentation

To regenerate the documentation after code changes:

make docs/admin/integrations/prometheus.md

This will:

  • Run the scanner to update generated_metrics
  • Merge metrics and generated_metrics metric files
  • Update the documentation file