Prometheus metrics endpoint - ClickHouse Documentation

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 instead.

If you’re using ClickHouse Cloud, you can expose metrics to Prometheus using the Prometheus Integration.

Configure the metrics port

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

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

Configure extended handlers

Section <prometheus.handlers> can be used to make more extended handlers on the same port. This section is similar to <http_handlers> but works for prometheus protocols:

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

Settings

For the complete behavior of these settings, see the Prometheus section 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>` 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`.
`asynchronous_metrics`	true	Exposes metrics from `system.asynchronous_metrics`.
`events`	true	Exposes metrics from `system.events`.
`errors`	true	Exposes error counts from `system.errors`.
`histograms`	true	Exposes metrics from `system.histogram_metrics`.
`dimensional_metrics`	true	Exposes metrics from `system.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.

Check the endpoint

curl http://127.0.0.1:9363/metrics

Last modified on September 14, 2026