Skip to main content

Prometheus protocols

Exposing metrics​

Note

ClickHouse Cloud does not currently support connecting to Prometheus. To be notified when this feature is supported, please contact support@clickhouse.com.

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:

NameDefaultDescription
portnonePort for serving the exposing metrics protocol.
endpoint/metricsHTTP endpoint for scraping metrics by prometheus server. Starts with /. Should not be used with the <handlers> section.
url / headers / methodnoneFilters used to find a matching handler for a request. Similar to the fields with the same names in the <http_handlers> section.
metricstrueExpose metrics from the system.metrics table.
asynchronous_metricstrueExpose current metrics values from the system.asynchronous_metrics table.
eventstrueExpose metrics from the system.events table.
errorstrueExpose 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:

NameDefaultDescription
portnonePort for serving the remote-write protocol.
url / headers / methodnoneFilters used to find a matching handler for a request. Similar to the fields with the same names in the <http_handlers> section.
tablenoneThe 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.
databasenoneThe 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:

NameDefaultDescription
portnonePort for serving the remote-read protocol.
url / headers / methodnoneFilters used to find a matching handler for a request. Similar to the fields with the same names in the <http_handlers> section.
tablenoneThe 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.
databasenoneThe 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>