Endpoint de metrics Prometheus - ClickHouse Documentation

ClickHouse expose ses propres metrics sur un port dédié, au format texte Prometheus, afin qu’un serveur Prometheus puisse les scraper. Pour stocker des metrics Prometheus dans ClickHouse et les interroger avec PromQL, consultez plutôt API HTTP Prometheus et PromQL.

Si vous utilisez ClickHouse Cloud, vous pouvez exposer les metrics à Prometheus via l’intégration Prometheus.

Configurer le port des metrics

Configurez un port dédié lorsqu’un serveur Prometheus doit scraper les metrics propres à 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>

Configurer des handlers étendus

La section <prometheus.handlers> permet de définir des handlers plus étendus sur le même port. Cette section est similaire à <http_handlers>, mais s’applique aux protocoles 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

Pour le comportement détaillé de ces paramètres, consultez la section Prometheus de la référence des paramètres serveur.

Nom	Valeur par défaut	Description
`port`	aucun	Port qui expose les metrics ClickHouse.
`endpoint`	`/metrics`	Endpoint HTTP pour le scraping des metrics. Il commence par `/`. Ne doit pas être utilisé avec la section `<handlers>`.
`url` / `headers` / `method`	aucun	Filtres utilisés pour trouver le handler correspondant à une requête. Similaires aux champs de même nom de la section `<http_handlers>`.
`info`	true	Expose la gauge `ClickHouse_Info` avec les labels d’identité du serveur (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`).
`metrics`	true	Expose les metrics de `system.metrics`.
`asynchronous_metrics`	true	Expose les metrics de `system.asynchronous_metrics`.
`events`	true	Expose les metrics de `system.events`.
`errors`	true	Expose les comptages d’erreurs de `system.errors`.
`histograms`	true	Expose les metrics de `system.histogram_metrics`.
`dimensional_metrics`	true	Expose les metrics de `system.dimensional_metrics`.
`labels`	aucun	Labels constants ajoutés à chaque metric exposée. Chaque élément enfant définit un label : le nom de l’élément correspond au nom du label (qui doit respecter `[a-zA-Z_][a-zA-Z0-9_]*`) et la valeur de l’élément à la valeur du label. Les valeurs de label prennent en charge les substitutions de configuration standard, comme l’attribut `from_env`. Un nom de label est rejeté s’il commence par `__` (réservé par Prometheus), ou s’il entre en conflit avec un label que cet endpoint écrit déjà pour l’une de ses sections activées. L’ensemble réservé dépend donc de la surface d’export active de l’endpoint : `le` lorsque `histograms` est activé ; les labels `ClickHouse_Info` (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`) lorsque `info` est activé ; et tout label utilisé par un histogramme exposé ou une famille de metrics dimensionnelles (par exemple `group`, `direction` ou `operation_type`) lorsque `histograms` ou `dimensional_metrics` est activé. Comme cela dépend de ce que l’endpoint expose réellement, un nom peut être valide sur un endpoint mais rejeté sur un autre.

Vérifier l’endpoint

curl http://127.0.0.1:9363/metrics

Dernière modification le 26 septembre 2026