Protocolos de Prometheus y PromQL

Configure un puerto dedicado cuando un servidor Prometheus necesite recopilar las propias métricas de ClickHouse:

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

Section <prometheus.handlers> can be used to make more extended handlers en el mismo puerto. Esta sección es similar a <http_handlers> pero funciona para Protocolos de Prometheus:

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

Configuración:

Compruebe el endpoint:

curl http://127.0.0.1:9363/metrics

ClickHouse implementa la API HTTP de Prometheus sobre una tabla TimeSeries. Un handler gestiona la escritura remota, la lectura remota, las consultas PromQL instantáneas y las consultas PromQL de rango.

Habilite la opción allow_experimental_time_series_table para el usuario que crea la tabla y accede a ella:

SET allow_experimental_time_series_table = 1;

Cree una base de datos y una tabla TimeSeries:

CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;

Para las solicitudes a la API HTTP, habilite allow_experimental_time_series_table en el perfil del usuario de la API.

Configure un handler enrutado por prefijo en el puerto HTTP principal de ClickHouse:

<http_handlers>
    <defaults/>
    <rule>
        <url_prefix>/prometheus/api/v1</url_prefix>
        <handler>
            <type>prometheus_api_v1</type>
        </handler>
    </rule>
</http_handlers>

<defaults/> conserva los handler integrados para endpoints como /ping y para solicitudes SQL. El prefijo anterior expone estos endpoints mediante un único handler:

El ejemplo omite database y table del handler. Cada solicitud debe incluir el parámetro de consulta table. También puede incluir database, usar un nombre de tabla completo como prometheus.metrics u omitir la base de datos para usar default. Esto permite que un único handler atienda varias tablas TimeSeries.

Para usar una tabla fija en todas las solicitudes, configúrela en el handler:

<handler>
    <type>prometheus_api_v1</type>
    <database>prometheus</database>
    <table>metrics</table>
</handler>

Una tabla configurada en el handler no puede sobrescribirse mediante parámetros de la solicitud.

Configuración de enrutamiento y del handler:

ClickHouse admite el protocolo remote-write de Prometheus. Configure Prometheus para que escriba en el handler:

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>

Prometheus envía muestras a la tabla prometheus.metrics.

Para agrupar los datos de muchas solicitudes simultáneas de remote-write en menos partes, habilite las inserciones asíncronas añadiendo la configuración async_insert a la URL (o habilitándola en el perfil de usuario):

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics&async_insert=1

ClickHouse confirma una solicitud de escritura remota asíncrona solo después de que los datos se hayan vaciado en todas las tablas internas de la tabla TimeSeries, independientemente de la configuración de wait_for_async_insert: el protocolo remote-write considera duradera una escritura confirmada. Si el vaciado falla, la solicitud devuelve un error y Prometheus la reintenta.

Utilice el endpoint de consulta instantánea para evaluar una expresión de PromQL en un momento dado:

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

Use el endpoint de consulta de rango para evaluar una expresión en un intervalo de tiempo:

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/query_range" \
  --data-urlencode "query=rate(http_requests_total[5m])" \
  --data-urlencode "start=2026-08-15T12:00:00Z" \
  --data-urlencode "end=2026-08-15T13:00:00Z" \
  --data-urlencode "step=60s" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

Consulte las funcionalidades de PromQL compatibles para obtener la lista de funciones y operadores de agregación que utilizan la API HTTP, el dialecto promql y las funciones de tabla.

Configure una fuente de datos de Prometheus con una URL base que termine antes de /api/v1:

apiVersion: 1
datasources:
  - name: ClickHouse Prometheus
    type: prometheus
    access: proxy
    url: https://clickhouse.example.com:8443/prometheus
    basicAuth: true
    basicAuthUser: default
    jsonData:
      httpMethod: GET
      customQueryParameters: database=prometheus&table=metrics
    secureJsonData:
      basicAuthPassword: <password>

Grafana agrega /api/v1/query o /api/v1/query_range a esta URL base y añade customQueryParameters a cada solicitud.

ClickHouse utiliza el mismo convertidor de PromQL para la API HTTP, el dialecto promql y las funciones de tabla prometheusQuery y prometheusQueryRange.

Ejecute PromQL directamente con clickhouse-client:

clickhouse-client \
  --dialect promql \
  --promql_database prometheus \
  --promql_table metrics \
  --query 'rate(http_requests_total[5m])'

Utilice las funciones de tabla para integrar PromQL en una consulta SQL:

SELECT *
FROM prometheusQuery(
    prometheus.metrics,
    'rate(http_requests_total[5m])',
    now()
);

El endpoint /prometheus/api/v1/metadata devuelve los metadatos de las métricas almacenados en la tabla de destino Metrics de la tabla TimeSeries: el tipo, el texto de ayuda y la unidad de cada familia de métricas. Admite los siguientes parámetros de Prometheus en la cadena de consulta de la URL:

La tabla de destino Metrics predeterminada es una ReplacingMergeTree ordenada por el nombre de la familia de métricas: conserva la entrada de metadatos escrita más recientemente para cada familia de métricas. Solo se devuelven varias entradas por familia mientras la tabla de destino las almacene: antes de que se fusionen sus partes o cuando la tabla se define con un motor que las conserva.

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/metadata" \
  --data-urlencode "metric=http_requests_total" \
  --data-urlencode "database=prometheus" \
  --data-urlencode "table=metrics"

ClickHouse admite el protocolo de lectura remota de Prometheus en /prometheus/api/v1/read.

Configure un servidor Prometheus para que lea de la misma tabla TimeSeries:

remote_read:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>