# Metrics Documentation Generator

This tool generates the Prometheus metrics documentation at [`docs/admin/integrations/prometheus.md`](https://coder.com/docs/admin/integrations/prometheus#available-metrics).

## 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_aibridged_*`: Metrics from external dependencies

> [!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:

```bash
make scripts/metricsdocgen/generated_metrics
```

## Updating Metrics Documentation

To regenerate the documentation after code changes:

```bash
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