> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Prometheus metrics endpoint in ClickHouse: expose server metrics on a dedicated port for scraping.

# Prometheus metrics endpoint

ClickHouse exposes its own metrics on a dedicated port in the Prometheus text format, so that a Prometheus server can scrape them.

To store Prometheus metrics in ClickHouse and query them with PromQL, see [Prometheus HTTP API and PromQL](/docs/interfaces/prometheus) instead.

<Note>
  If you're using ClickHouse Cloud, you can expose metrics to Prometheus using the [Prometheus Integration](/docs/products/cloud/features/monitoring/prometheus).
</Note>

<h2 id="configure-the-metrics-port">
  Configure the metrics port
</h2>

Configure a dedicated port when a Prometheus server needs to scrape ClickHouse's own metrics:

```xml theme={null}
<prometheus>
    <port>9363</port>
    <endpoint>/metrics</endpoint>
    <metrics>true</metrics>
    <asynchronous_metrics>true</asynchronous_metrics>
    <events>true</events>
    <errors>true</errors>
    <histograms>true</histograms>
    <dimensional_metrics>true</dimensional_metrics>
</prometheus>
```

<h2 id="configure-extended-handlers">
  Configure extended handlers
</h2>

Section `<prometheus.handlers>` can be used to make more extended handlers on the same port.
This section is similar to [`<http_handlers>`](/docs/concepts/features/interfaces/http) but works for prometheus protocols:

```xml theme={null}
<prometheus>
    <port>9363</port>
    <handlers>
        <my_rule_1>
            <url>/metrics</url>
            <handler>
                <type>expose_metrics</type>
                <metrics>true</metrics>
                <asynchronous_metrics>true</asynchronous_metrics>
                <events>true</events>
                <errors>true</errors>
                <histograms>true</histograms>
                <dimensional_metrics>true</dimensional_metrics>
                <labels>
                    <environment>production</environment>
                    <shard from_env="SHARD_NAME"></shard>
                </labels>
            </handler>
        </my_rule_1>
    </handlers>
</prometheus>
```

<h2 id="settings">
  Settings
</h2>

For the complete behavior of these settings, see the [Prometheus section](/docs/reference/settings/server-settings/settings/other#prometheus) of the server settings reference.

| Name                         | Default    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`                       | none       | Port that serves ClickHouse metrics.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `endpoint`                   | `/metrics` | HTTP endpoint for scraping metrics. It starts with `/`. Should not be used with the `<handlers>` section.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `url` / `headers` / `method` | none       | Filters used to find a matching handler for a request. Similar to the fields with the same names in the [`<http_handlers>`](/docs/concepts/features/interfaces/http) section.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `info`                       | true       | Exposes the `ClickHouse_Info` gauge with server identity labels (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `metrics`                    | true       | Exposes metrics from [`system.metrics`](/docs/reference/system-tables/metrics).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `asynchronous_metrics`       | true       | Exposes metrics from [`system.asynchronous_metrics`](/docs/reference/system-tables/asynchronous_metrics).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `events`                     | true       | Exposes metrics from [`system.events`](/docs/reference/system-tables/events).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `errors`                     | true       | Exposes error counts from [`system.errors`](/docs/reference/system-tables/errors).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `histograms`                 | true       | Exposes metrics from [`system.histogram_metrics`](/docs/reference/system-tables/histogram_metrics).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `dimensional_metrics`        | true       | Exposes metrics from [`system.dimensional_metrics`](/docs/reference/system-tables/dimensional_metrics).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `labels`                     | none       | Constant labels added to every exposed metric. Each child element defines one label: the element name is the label name (which must match `[a-zA-Z_][a-zA-Z0-9_]*`) and the element value is the label value. Label values support standard config substitutions such as the `from_env` attribute. A label name is rejected when it starts with `__` (reserved by Prometheus), or when it would collide with a label this endpoint already writes for one of its enabled sections. The reserved set therefore follows the endpoint's active export surface: `le` when `histograms` is enabled; the `ClickHouse_Info` labels (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`) when `info` is enabled; and any label used by an exposed histogram or dimensional metric family (for example, `group`, `direction`, or `operation_type`) when `histograms` or `dimensional_metrics` is enabled. Because it depends on what the endpoint actually exposes, a name can be valid on one endpoint but rejected on another. |

<h2 id="check-the-endpoint">
  Check the endpoint
</h2>

```bash theme={null}
curl http://127.0.0.1:9363/metrics
```