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. Para exponer las propias métricas de ClickHouse y que un servidor de Prometheus las recopile, consulta el endpoint de métricas de Prometheus.

Requisitos previos

Los pasos de configuración difieren entre ClickHouse Cloud y ClickHouse autogestionado. Siga la sección correspondiente a su Implementación.

ClickHouse Cloud

La compatibilidad con PromQL en ClickHouse Cloud está en private preview. Los servicios que participan en la private preview ya tienen configurado el SETTING enable_time_series_table y los API endpoints de Prometheus. El resto de los servicios de ClickHouse Cloud no cuentan con esta configuración, y no es posible habilitar la feature por cuenta propia en dichos servicios. La sentencia SET enable_time_series_table y la configuración http_handlers de las secciones siguientes se aplican a Implementaciones autogestionadas.

Si su servicio participa en la private preview, continúe en Crear una tabla TimeSeries. El servicio expone las rutas de endpoint que se enumeran en la tabla de endpoints.

Autogestionado: habilite el SETTING TimeSeries

Habilite el SETTING enable_time_series_table para el usuario que crea la tabla y accede a ella:

SET enable_time_series_table = 1;

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

Autogestionado: configure los endpoints de 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/format_query`	Formato de expresiones PromQL
`/prometheus/api/v1/series`	Metadatos de series
`/prometheus/api/v1/metadata`	Metadatos de la familia de métricas

El ejemplo omite database y table del handler. Cada solicitud debe incluir el parámetro de consulta table (excepto /format_query, que solo analiza la expresión PromQL indicada y no necesita una tabla). 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`.

Cree una tabla TimeSeries

Cree una base de datos y una tabla TimeSeries:

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

Ingeste métricas mediante escritura remota

ClickHouse admite el protocolo de escritura remota 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 escritura remota 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 de escritura remota 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"

Los endpoints de consulta también aceptan los parámetros en el cuerpo de un formulario. Sin --get, curl envía los parámetros como application/x-www-form-urlencoded mediante POST:

curl --user default:<password> \
  "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"

Utilice el endpoint de formato de consulta para analizar y formatear una expresión de PromQL sin evaluarla:

curl --user default:<password> --get \
  "https://clickhouse.example.com:8443/prometheus/api/v1/format_query" \
  --data-urlencode "query=sum by(job)(http_requests_total{code=\"200\"})/2"

La expresión se devuelve serializada a partir de la consulta analizada, con los espacios en blanco normalizados, los comentarios eliminados, los paréntesis redundantes suprimidos y las duraciones convertidas a número de segundos: sum by (job) (http_requests_total{code="200"}) / 2. Este endpoint no evalúa la expresión, por lo que no necesita los parámetros database ni table. 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: POST
      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. Con httpMethod: POST, Grafana envía los parámetros de consulta en el cuerpo de la solicitud. ClickHouse lee el cuerpo de la solicitud y la cadena de consulta de la URL, por lo que customQueryParameters sigue aplicándose. Use POST para expresiones PromQL largas, ya que una URL tiene un límite de longitud.

Solo están implementados los endpoints de consulta /api/v1/query, /api/v1/query_range y /api/v1/format_query y los endpoints de metadatos /api/v1/series, /api/v1/labels, /api/v1/label/<name>/values 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). /api/v1/label/<name>/values acepta los mismos parámetros que /api/v1/labels y devuelve los valores ordenados de una etiqueta, donde <name> puede usar opcionalmente el escapado U__... de Prometheus para nombres de etiquetas que contienen caracteres fuera de [a-zA-Z0-9_]. Estos endpoints cubren lo que utiliza un origen de datos de Prometheus en Grafana para explorar etiquetas, variables de plantilla y el autocompletado del 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>

Fundamentos

Conceptos de ClickHouse

Buenas prácticas

Requisitos previos

ClickHouse Cloud

Autogestionado: habilite el SETTING TimeSeries

Autogestionado: configure los endpoints de la API de Prometheus

Cree una tabla TimeSeries

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

​Requisitos previos

​ClickHouse Cloud

​Autogestionado: habilite el SETTING TimeSeries

​Autogestionado: configure los endpoints de la API de Prometheus

​Cree una tabla TimeSeries

​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

Requisitos previos

ClickHouse Cloud

Autogestionado: habilite el SETTING TimeSeries

Autogestionado: configure los endpoints de la API de Prometheus

Cree una tabla TimeSeries

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