Protocoles Prometheus et PromQL

Exposer les métriques du serveur ClickHouse

Si vous utilisez ClickHouse Cloud, vous pouvez exposer des métriques à Prometheus à l’aide de l’intégration Prometheus.

Configurez un port dédié lorsqu’un serveur Prometheus doit collecter les propres métriques 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>

La section <prometheus.handlers> peut être utilisée pour créer des gestionnaires plus étendus sur le même port. Cette section est similaire à <http_handlers>, mais fonctionne pour les 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>

Paramètres :

Nom	Par défaut	Description
`port`	none	Port qui expose les métriques ClickHouse.
`endpoint`	`/metrics`	Endpoint HTTP pour le scraping des métriques. Commence par `/`. Ne doit pas être utilisé avec la section `<handlers>`.
`url` / `headers` / `method`	none	Filtres utilisés pour trouver un gestionnaire correspondant à une requête. Similaires aux champs portant les mêmes noms dans la section `<http_handlers>`.
`info`	true	Expose la jauge `ClickHouse_Info` avec les libellés d’identité du serveur (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`).
`metrics`	true	Expose les métriques de `system.metrics`.
`asynchronous_metrics`	true	Expose les métriques de `system.asynchronous_metrics`.
`events`	true	Expose les métriques de `system.events`.
`errors`	true	Expose le nombre d’erreurs de `system.errors`.
`histograms`	true	Expose les métriques de `system.histogram_metrics`.
`dimensional_metrics`	true	Expose les métriques de `system.dimensional_metrics`.
`labels`	none	Libellés constants ajoutés à chaque métrique exposée. Chaque élément enfant définit un libellé : le nom de l’élément est le nom du libellé (qui doit correspondre à `[a-zA-Z_][a-zA-Z0-9_]*`) et la valeur de l’élément est la valeur du libellé. Les valeurs de libellé prennent en charge les substitutions de config standard telles que l’attribut `from_env`. Un nom de libellé est rejeté lorsqu’il commence par `__` (réservé par Prometheus), ou lorsqu’il entrerait en conflit avec un libellé que cet endpoint exporte déjà pour l’une de ses sections activées. L’ensemble réservé dépend donc des données activement exportées par l’endpoint : `le` lorsque `histograms` est activé ; les libellés `ClickHouse_Info` (`name`, `version`, `version_describe`, `version_major`, `version_minor`, `version_patch`) lorsque `info` est activé ; et tout libellé utilisé par une famille de métriques d’histogramme ou dimensionnelles exposée (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érifiez l’endpoint :

curl http://127.0.0.1:9363/metrics

API HTTP Prometheus et PromQL

ClickHouse implémente l’API HTTP Prometheus sur une table TimeSeries. Un gestionnaire prend en charge l’écriture distante, la lecture distante, les requêtes PromQL instantanées et les requêtes PromQL sur une plage.

Prérequis

Activez le paramètre allow_experimental_time_series_table pour l’utilisateur qui crée la table et y accède :

SET allow_experimental_time_series_table = 1;

Créez une base de données et une table TimeSeries :

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

Pour les requêtes d’API HTTP, activez allow_experimental_time_series_table dans le profil de l’utilisateur de l’API.

Configurer l’API Prometheus

Configurez un gestionnaire routé par préfixe sur le port 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/> conserve les gestionnaires intégrés pour les endpoints tels que /ping et les requêtes SQL. Le préfixe ci-dessus expose ces endpoints via un seul gestionnaire :

Endpoint	Rôle
`/prometheus/api/v1/write`	Écriture distante Prometheus
`/prometheus/api/v1/read`	Lecture distante Prometheus
`/prometheus/api/v1/query`	Requêtes PromQL instantanées
`/prometheus/api/v1/query_range`	Requêtes PromQL sur une plage

L’exemple ne spécifie pas database ni table dans le gestionnaire. Chaque requête doit fournir le paramètre de requête table. Elle peut également fournir database, utiliser un nom de table qualifié tel que prometheus.metrics ou omettre la base de données afin d’utiliser default. Un même gestionnaire peut ainsi desservir plusieurs tables TimeSeries. Pour utiliser une table fixe pour toutes les requêtes, configurez-la dans le gestionnaire :

<handler>
    <type>prometheus_api_v1</type>
    <database>prometheus</database>
    <table>metrics</table>
</handler>

Une table configurée dans le gestionnaire ne peut pas être remplacée par des paramètres de requête. Paramètres de routage et du gestionnaire :

Nom	Par défaut	Description
`url_prefix`	aucun	Filtre qui correspond à tous les chemins de requête commençant par le préfixe configuré.
`table`	aucun	Nom d’une table `TimeSeries`. Si ce paramètre est omis, la requête doit fournir le paramètre de requête `table`. Le nom configuré peut inclure une base de données.
`database`	aucun	Base de données contenant la table. Une requête peut la fournir sous forme de paramètre de requête. Si ce paramètre est omis, ClickHouse utilise la base de données spécifiée dans une valeur `table` qualifiée ou utilise `default`.

Ingérer des métriques via écriture distante

ClickHouse prend en charge le protocole écriture distante de Prometheus. Configurez Prometheus pour écrire vers le gestionnaire :

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>

Prometheus envoie des échantillons dans la table prometheus.metrics.

Interroger avec PromQL

Utilisez l’endpoint de requête instantanée pour évaluer une expression PromQL à un instant donné :

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"

Utilisez l’endpoint de requête par plage pour évaluer une expression sur un intervalle de temps :

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"

Consultez les fonctionnalités PromQL prises en charge pour obtenir la liste des fonctions et des opérateurs d’agrégation utilisés par l’API HTTP, le dialecte promql et les fonctions de table.

Grafana

Configurez une source de données Prometheus avec une URL de base ne contenant pas /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 ajoute /api/v1/query ou /api/v1/query_range à cette URL de base et ajoute customQueryParameters à chaque requête.

Seuls les endpoints de requête /api/v1/query et /api/v1/query_range sont implémentés. Les endpoints de métadonnées utilisés par une source de données Prometheus dans Grafana pour parcourir les libellés, les variables de modèle et l’autocomplétion du générateur de requêtes (/api/v1/series, /api/v1/labels, /api/v1/label/<name>/values) ne sont pas implémentés et renvoient une erreur. Écrivez les expressions PromQL en mode code plutôt que d’utiliser le générateur de requêtes.

Points d’entrée SQL

ClickHouse utilise le même convertisseur PromQL pour l’API HTTP, le dialecte promql ainsi que les fonctions de table prometheusQuery et prometheusQueryRange. Exécutez directement des requêtes PromQL avec clickhouse-client :

clickhouse-client \
  --dialect promql \
  --promql_database prometheus \
  --promql_table metrics \
  --query 'rate(http_requests_total[5m])'

Utilisez les fonctions de table pour intégrer du PromQL dans une requête SQL :

SELECT *
FROM prometheusQuery(
    prometheus.metrics,
    'rate(http_requests_total[5m])',
    now()
);

Lire les métriques via lecture distante

ClickHouse prend en charge le protocole lecture distante de Prometheus sur /prometheus/api/v1/read. Configurez un serveur Prometheus pour lire les données de la même table TimeSeries :

remote_read:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
    basic_auth:
      username: default
      password: <password>

Fondamentaux

Concepts ClickHouse

Bonnes pratiques

Exposer les métriques du serveur ClickHouse

API HTTP Prometheus et PromQL

Prérequis

Configurer l’API Prometheus

Ingérer des métriques via écriture distante

Interroger avec PromQL

Grafana

Points d’entrée SQL

Lire les métriques via lecture distante

​Exposer les métriques du serveur ClickHouse

​API HTTP Prometheus et PromQL

​Prérequis

​Configurer l’API Prometheus

​Ingérer des métriques via écriture distante

​Interroger avec PromQL

​Grafana

​Points d’entrée SQL

​Lire les métriques via lecture distante

Exposer les métriques du serveur ClickHouse

API HTTP Prometheus et PromQL

Prérequis

Configurer l’API Prometheus

Ingérer des métriques via écriture distante

Interroger avec PromQL

Grafana

Points d’entrée SQL

Lire les métriques via lecture distante