Skip to main content
Skip to main content
Edit this page

Prometheus protocols

Exposing metrics​

Note

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

ClickHouse can expose its own metrics for scraping from Prometheus:

<prometheus>
    <port>9363</port>
    <endpoint>/metrics</endpoint>
    <metrics>true</metrics>
    <asynchronous_metrics>true</asynchronous_metrics>
    <events>true</events>
    <errors>true</errors>
</prometheus>

Section `<prometheus.handlers>` can be used to make more extended handlers.
This section is similar to [<http_handlers>](/en/interfaces/http) but works for prometheus protocols:

```xml
<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>
            </handler>
        </my_rule_1>
    </handlers>
</prometheus>

Settings:

| Name | Default | Description | |---|---|---|---| | port | none | Port for serving the exposing metrics protocol. | | endpoint | /metrics | HTTP endpoint for scraping metrics by prometheus server. 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. | | metrics | true | Expose metrics from the system.metrics table. | | asynchronous_metrics | true | Expose current metrics values from the system.asynchronous_metrics table. | | events | true | Expose metrics from the system.events table. | | errors | true | Expose the number of errors by error codes occurred since the last server restart. This information could be obtained from the system.errors as well. |

Check (replace 127.0.0.1 with the IP addr or hostname of your ClickHouse server):

curl 127.0.0.1:9363/metrics

Remote-write protocol​

ClickHouse supports the remote-write protocol. Data are received by this protocol and written to a TimeSeries table (which should be created beforehand).

<prometheus>
    <port>9363</port>
    <handlers>
        <my_rule_1>
            <url>/write</url>
            <handler>
                <type>remote_write</type>
                <database>db_name</database>
                <table>time_series_table</table>
            </handler>
        </my_rule_1>
    </handlers>
</prometheus>

Settings:

| Name | Default | Description | |---|---|---|---| | port | none | Port for serving the remote-write protocol. | | 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. | | table | none | The name of a TimeSeries table to write data received by the remote-write protocol. This name can optionally contain the name of a database too. | | database | none | The name of a database where the table specified in the table setting is located if it's not specified in the table setting. |

Remote-read protocol​

ClickHouse supports the remote-read protocol. Data are read from a TimeSeries table and sent via this protocol.

<prometheus>
    <port>9363</port>
    <handlers>
        <my_rule_1>
            <url>/read</url>
            <handler>
                <type>remote_read</type>
                <database>db_name</database>
                <table>time_series_table</table>
            </handler>
        </my_rule_1>
    </handlers>
</prometheus>

Settings:

| Name | Default | Description | |---|---|---|---| | port | none | Port for serving the remote-read protocol. | | 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. | | table | none | The name of a TimeSeries table to read data to send by the remote-read protocol. This name can optionally contain the name of a database too. | | database | none | The name of a database where the table specified in the table setting is located if it's not specified in the table setting. |

Configuration for multiple protocols​

Multiple protocols can be specified together in one place:

<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>
            </handler>
        </my_rule_1>
        <my_rule_2>
            <url>/write</url>
            <handler>
                <type>remote_write</type>
                <table>db_name.time_series_table</table>
            </handler>
        </my_rule_2>
        <my_rule_3>
            <url>/read</url>
            <handler>
                <type>remote_read</type>
                <table>db_name.time_series_table</table>
            </handler>
        </my_rule_3>
    </handlers>
</prometheus>