Protocolos de Prometheus y PromQL

Compatibilidad de ClickHouse con la API HTTP de Prometheus: escritura y lectura remotas, consultas PromQL y métricas del servidor.

​

Exponer métricas del servidor ClickHouse

Si usas ClickHouse Cloud, puedes exponer métricas a Prometheus con la integración de Prometheus.

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:

Nombre	Predeterminado	Descripción
port	ninguno	Puerto que expone las métricas de ClickHouse.
endpoint	/metrics	Endpoint HTTP para recopilar métricas. Empieza por /. No debe usarse con la sección <handlers>.
url / headers / method	ninguno	Filtros utilizados para encontrar un handler que coincida con una solicitud. Son similares a los campos con los mismos nombres de la sección <http_handlers>.
info	true	Expone el gauge ClickHouse_Info con etiquetas de identidad del servidor (name, version, version_describe, version_major, version_minor, version_patch).
metrics	true	Expone métricas de system.metrics.
asynchronous_metrics	true	Expone métricas de system.asynchronous_metrics.
events	true	Expone métricas de system.events.
errors	true	Expone recuentos de errores de system.errors.
histograms	true	Expone métricas de system.histogram_metrics.
dimensional_metrics	true	Expone métricas de system.dimensional_metrics.
labels	ninguno	Etiquetas constantes añadidas a cada métrica expuesta. Cada elemento secundario define una etiqueta: el nombre del elemento es el nombre de la etiqueta (que debe coincidir con [a-zA-Z_][a-zA-Z0-9_]*) y el valor del elemento es el valor de la etiqueta. Los valores de las etiquetas admiten sustituciones de configuración estándar, como el atributo from_env. Se rechaza un nombre de etiqueta cuando empieza por __ (reservado por Prometheus) o cuando entraría en conflicto con una etiqueta que este endpoint ya escribe para una de sus secciones habilitadas. Por tanto, el conjunto reservado sigue la superficie de exportación activa del endpoint: le cuando histograms está habilitado; las etiquetas de ClickHouse_Info (name, version, version_describe, version_major, version_minor, version_patch) cuando info está habilitado; y cualquier etiqueta utilizada por una familia de métricas de histograma o dimensional expuesta (por ejemplo, group, direction u operation_type) cuando histograms o dimensional_metrics está habilitado. Como depende de lo que el endpoint expone realmente, un nombre puede ser válido en un endpoint, pero rechazarse en otro.

Compruebe el endpoint:

curl http://127.0.0.1:9363/metrics

​

API HTTP de Prometheus y PromQL

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.

​

Requisitos previos

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 la API de Prometheus

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:

Endpoint	Finalidad
/prometheus/api/v1/write	Escritura remota de Prometheus
/prometheus/api/v1/read	Lectura remota de Prometheus
/prometheus/api/v1/query	Consultas PromQL instantáneas
/prometheus/api/v1/query_range	Consultas PromQL por intervalo

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:

Nombre	Predeterminado	Descripción
url_prefix	ninguno	Regla de filtrado que coincide con todas las rutas de solicitud que comienzan con el prefijo configurado.
table	ninguno	El nombre de una tabla TimeSeries. Si se omite, la solicitud debe incluir el parámetro de consulta table. El nombre configurado puede incluir una base de datos.
database	ninguno	La base de datos que contiene la tabla. Una solicitud puede proporcionarla como parámetro de consulta. Si se omite, ClickHouse usa la base de datos de un valor table calificado o recurre a default.

​

Ingeste métricas mediante escritura remota

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

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.

​

Consultas con PromQL

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.

​

Grafana

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.

Solo están implementados los endpoints de consulta /api/v1/query y /api/v1/query_range. Los endpoints de metadatos que utiliza un origen de datos de Prometheus en Grafana para explorar etiquetas, variables de plantilla y el autocompletado del constructor de consultas (/api/v1/series, /api/v1/labels, /api/v1/label/<name>/values) no están implementados y devuelven un error. Escriba expresiones de PromQL en el modo de código en lugar de usar el constructor de consultas.

​

Puntos de entrada de SQL

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()
);

​

Leer métricas mediante lectura remota

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>