Endpoint de métricas de Prometheus - ClickHouse Documentation

ClickHouse expone sus propias métricas en un puerto dedicado con el formato de texto de Prometheus, de modo que un servidor de Prometheus pueda recolectarlas. Para almacenar métricas de Prometheus en ClickHouse y consultarlas con PromQL, consulta Prometheus HTTP API y PromQL.

Si utilizas ClickHouse Cloud, puedes exponer las métricas a Prometheus mediante la integración con Prometheus.

Configurar el puerto de métricas

Configure un puerto dedicado cuando un servidor Prometheus necesite recolectar (scrape) las métricas propias 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>

Configurar handlers extendidos

La sección <prometheus.handlers> permite definir handlers más extendidos en el mismo puerto. Esta sección es similar a <http_handlers>, pero funciona con los 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>

Settings

Para conocer el comportamiento completo de estos settings, consulta la sección Prometheus de la referencia de server settings.

Nombre	Valor predeterminado	Descripción
`port`	ninguno	Puerto que sirve las métricas de ClickHouse.
`endpoint`	`/metrics`	Endpoint HTTP para el scraping de métricas. Comienza con `/`. No debe usarse junto con la sección `<handlers>`.
`url` / `headers` / `method`	ninguno	Filtros utilizados para encontrar un handler que coincida con una solicitud. Equivalentes a los campos con los mismos nombres de la sección `<http_handlers>`.
`info`	true	Expone el gauge `ClickHouse_Info` con labels 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 los 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	Labels constantes que se añaden a cada métrica expuesta. Cada elemento hijo define un label: el nombre del elemento es el nombre del label (que debe coincidir con `[a-zA-Z_][a-zA-Z0-9_]*`) y el valor del elemento es el valor del label. Los valores de los labels admiten las sustituciones de configuración estándar, como el atributo `from_env`. Un nombre de label se rechaza cuando empieza por `__` (reservado por Prometheus) o cuando entraría en conflicto con un label que este endpoint ya escribe para alguna de sus secciones habilitadas. Por tanto, el conjunto reservado depende de la superficie de exportación activa del endpoint: `le` cuando `histograms` está habilitado; los labels de `ClickHouse_Info` (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`) cuando `info` está habilitado; y cualquier label utilizado por un histograma expuesto o por una metric family dimensional (por ejemplo, `group`, `direction` u `operation_type`) cuando `histograms` o `dimensional_metrics` están habilitados. Como esto depende de lo que el endpoint expone realmente, un nombre puede ser válido en un endpoint y ser rechazado en otro.

Comprobar el endpoint

curl http://127.0.0.1:9363/metrics

Última modificación el 26 de septiembre de 2026