Protocoles Prometheus et PromQL

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 :

Vérifiez l’endpoint :

curl http://127.0.0.1:9363/metrics

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.

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.

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 :

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 :

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.

Pour regrouper les données issues de nombreuses requêtes d’écriture distante concurrentes en un nombre réduit de parties, activez les insertions asynchrones en ajoutant le paramètre async_insert à l’URL (ou en l’activant dans le profil utilisateur) :

remote_write:
  - url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics&async_insert=1

ClickHouse n’accuse réception d’une requête d’écriture distante asynchrone qu’une fois les données écrites dans toutes les tables internes de la table TimeSeries, indépendamment du paramètre wait_for_async_insert : le protocole d’écriture distante considère comme durable toute écriture dont réception a été accusée. Si l’écriture échoue, la requête renvoie une erreur et Prometheus la réessaie.

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.

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.

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()
);

L’endpoint /prometheus/api/v1/metadata renvoie les métadonnées des métriques stockées dans la table cible Metrics de la table TimeSeries : le type, le texte d’aide et l’unité de chaque famille de métriques. Il prend en charge les paramètres Prometheus suivants dans la chaîne de requête de l’URL :

La table cible Metrics par défaut est une ReplacingMergeTree ordonnée par nom de famille de métriques : elle conserve l’entrée de métadonnées écrite le plus récemment pour chaque famille de métriques. Plusieurs entrées par famille ne sont renvoyées que tant que la table cible les stocke — avant la fusion de ses parts, ou lorsque la table est définie avec un engine qui les conserve.

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"

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>