Protocolos de Prometheus y PromQL

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 de rango
`/prometheus/api/v1/series`	Metadatos de series
`/prometheus/api/v1/metadata`	Metadatos de la familia métrica

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

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 y los endpoints de metadatos /api/v1/series, /api/v1/labels y /api/v1/metadata. /api/v1/series requiere al menos un selector de series match[], admite los parámetros opcionales start, end y limit, y devuelve la unión de las series coincidentes con cada selector. /api/v1/labels acepta los mismos parámetros, con match[] como opcional, y devuelve los nombres de etiquetas ordenados de las series coincidentes (o de todas las series cuando no se proporcionan selectores). El endpoint de valores de etiquetas (/api/v1/label/<name>/values), que utiliza un origen de datos de Prometheus en Grafana para explorar etiquetas, variables de plantilla y el autocompletado del constructor de consultas, no está implementado y devuelve 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()
);

Consultar metadatos de métricas

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:

Parámetro	Descripción
`metric`	Devuelve metadatos solo para esta familia de métricas.
`limit`	Limita el número de familias de métricas devueltas. Un valor negativo indica que no hay límite; cero no devuelve ninguna familia de métricas.
`limit_per_metric`	Limita el número de objetos de metadatos devueltos para cada familia de métricas. Los valores cero y negativos indican que no hay límite.

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"

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>

Fundamentals

ClickHouse concepts

Best practices

Exponer métricas del servidor ClickHouse

API HTTP de Prometheus y PromQL

Requisitos previos

Configure la API de Prometheus

Ingeste métricas mediante escritura remota

Consultas con PromQL

Grafana

Puntos de entrada de SQL

Consultar metadatos de métricas

Leer métricas mediante lectura remota

​Exponer métricas del servidor ClickHouse

​API HTTP de Prometheus y PromQL

​Requisitos previos

​Configure la API de Prometheus

​Ingeste métricas mediante escritura remota

​Consultas con PromQL

​Grafana

​Puntos de entrada de SQL

​Consultar metadatos de métricas

​Leer métricas mediante lectura remota

Exponer métricas del servidor ClickHouse

API HTTP de Prometheus y PromQL

Requisitos previos

Configure la API de Prometheus

Ingeste métricas mediante escritura remota

Consultas con PromQL

Grafana

Puntos de entrada de SQL

Consultar metadatos de métricas

Leer métricas mediante lectura remota