# Metrics

> Real-time and background-calculated server metrics, counters, and CPU profiling data.

| | |
|---|---|
| **Routes** | `/metrics`, `/asynchronous-metrics`, `/profiler` |
| **Feature id** | `metrics` |
| **Default access** | `public` |
| **Requires auth** | No (set `CHM_FEATURE_METRICS_ACCESS=authenticated` to gate) |
| **System tables** | `system.metrics`, `system.asynchronous_metrics`, `system.processors_profile_log` |
| **ClickHouse grants** | `SELECT` on the system tables above |

## What it does

The Metrics section exposes three views of server-level performance data.

**Metrics** queries `system.metrics` for live counters: active connections, threads, merges in flight, and hundreds of other real-time gauges. Values reset when the server restarts.

**Async Metrics** queries `system.asynchronous_metrics`, which are updated in the background on a schedule (not per-query). These include CPU load, memory usage, uptime, and OS-level stats. Useful for dashboards and alerting.

**Profiler** queries `system.processors_profile_log` to show CPU time broken down by query processor (pipeline step). Use it to find which stage of query execution is consuming the most CPU.

## Pages

| Page | Route | What it shows | System tables |
|---|---|---|---|
| Metrics | `/metrics` | Live server metrics and counters | `system.metrics` |
| Async Metrics | `/asynchronous-metrics` | Background-calculated resource metrics | `system.asynchronous_metrics` |
| Profiler | `/profiler` | CPU profiling data per query processor | `system.processors_profile_log` |

## Permissions & access

All three pages share the `metrics` feature id.

Disable:

```bash
CHM_FEATURE_METRICS_ENABLED=false
```

Require authentication:

```bash
CHM_FEATURE_METRICS_ACCESS=authenticated
```

Config file:

```toml
[features.metrics]
enabled = true
access = "authenticated"
```

## Configuration

No feature-specific configuration. The profiler page requires `system.processors_profile_log` to be populated, which depends on `<processors_profile_log>` being enabled in the ClickHouse server config.

## Notes & limitations

- `system.metrics` values are live (reset on restart); they do not persist history. For trending, use `system.asynchronous_metrics` or `system.metric_log` (not yet surfaced in chmonitor).
- `system.processors_profile_log` must be enabled explicitly in the ClickHouse server configuration. If it is absent, the Profiler page shows an empty state.
- Async metrics are recalculated on a server-defined interval (typically every few seconds); values may lag slightly behind real-time.

## Related

- [Health](/features/health)
- [Feature permissions](/advanced/feature-permissions)
- [ClickHouse system.metrics docs](https://clickhouse.com/docs/en/operations/system-tables/metrics)
- [ClickHouse system.asynchronous_metrics docs](https://clickhouse.com/docs/en/operations/system-tables/asynchronous_metrics)