Files
coder/scripts/metricsdocgen
Ehab Younes 1126533c31 feat: export workspace last used time to Prometheus (#31346)
Add an opt-in coderd_workspace_last_used_timestamp_seconds gauge that
reports workspaces.last_used_at, the value the dormancy threshold
measures inactivity from. To enable it, set
--prometheus-collect-workspace-stats or
CODER_PROMETHEUS_COLLECT_WORKSPACE_STATS.

A separate WorkspaceStats collector refreshes the gauge once a minute
in the background from a new GetWorkspaceLastUsedForMetrics query. Each
series has a workspace_id label, so a workspace that reuses a deleted
workspace's name starts a new series. Workspaces owned by deleted users
are excluded.

Closes CLIENT-1065
2026-11-11 15:02:18 +00: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 defined in Coder source code, such as:

  • go_*: Go runtime metrics
  • process_*: Process metrics from prometheus/client_golang
  • promhttp_*: Prometheus HTTP handler metrics

Note

This file also supplies label metadata for source-defined metrics that the scanner cannot observe. For example, coderd_agentstats_* labels are configured at runtime. When a metric appears in both files, its generated name, type, and description take priority, and the two label sets are unioned and deduplicated by name.

Edit this file to add metrics that should appear in the documentation but are not scanned from the Coder codebase, or to supply labels that only exist at runtime. Static labels are additive: an entry here can document a label the scanner cannot see, but it cannot remove or replace one the scanner found. To correct a label the scanner derives wrongly, fix the source declaration or the scanner, because a static entry will not override it. Do not add source-defined metrics solely because their registerer has a static prefix: the scanner resolves prefixes from prometheus.WrapRegistererWithPrefix and prometheusmetrics.NewMetricAliasRegisterer.

generated_metrics (auto-generated)

Contains metrics extracted from 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

Configuring the scanner

Configure these options in scanner/scanner.go:

  • Scan scope (scanDirs): Directories searched recursively for metric definitions. Add a directory when definitions live outside the existing scan scope. Test files are excluded.
  • Prefix scope (prefixScanDirs): Directories searched for registerer wrapping. The scanner resolves name prefixes from prometheus.WrapRegistererWithPrefix and prometheusmetrics.NewMetricAliasRegisterer, so prefixes do not need to be listed by hand. Add a directory when a registerer is wrapped outside the existing scope.
  • Exclusions (excludeDirs): Subtrees excluded from scanning, for metrics a deployment never exposes. Document a metric in the static file instead when the scanner cannot extract it correctly.

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