> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Prise en charge de l’API HTTP Prometheus dans ClickHouse : écriture distante, lecture distante et requêtes PromQL sur une table TimeSeries.
# API HTTP Prometheus et PromQL
export const PrivatePreviewBadge = () => {
return ;
};
ClickHouse implémente l’API HTTP Prometheus sur une table [`TimeSeries`](/fr/reference/engines/table-engines/integrations/time-series). 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.
Pour exposer les métriques propres à ClickHouse afin qu’un serveur Prometheus puisse les collecter, consultez l’[endpoint de métriques Prometheus](/fr/concepts/features/interfaces/prometheus-metrics).
Prérequis
Les étapes de configuration diffèrent entre ClickHouse Cloud et ClickHouse self-managed. Suivez la section correspondant à votre déploiement.
ClickHouse Cloud
La prise en charge de PromQL dans ClickHouse Cloud est en private preview. Les services qui participent à la private preview disposent déjà du paramètre `enable_time_series_table` et des points de terminaison de l'API Prometheus configurés. Les autres services ClickHouse Cloud n'ont pas cette configuration, et vous ne pouvez pas activer cette fonctionnalité vous-même sur un tel service. L'instruction `SET enable_time_series_table` et la configuration `http_handlers` décrites dans les sections suivantes s'appliquent aux déploiements self-managed.
Sur un service participant à la private preview, passez directement à la section [Créer une table TimeSeries](#create-a-timeseries-table). Le service expose les chemins de points de terminaison répertoriés dans le [tableau des endpoints](#configure-prometheus-api).
Self-managed : activer le paramètre TimeSeries
Activez le paramètre `enable_time_series_table` pour l’utilisateur qui crée la table et y accède :
```sql theme={null}
SET enable_time_series_table = 1;
```
Pour les requêtes d’API HTTP, activez `enable_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 :
```xml theme={null}
/prometheus/api/v1
prometheus_api_v1
```
`` conserve les gestionnaires intégrés pour les points de terminaison de l’API tels que `/ping` et les requêtes SQL. Le préfixe ci-dessus expose ces points de terminaison de l’API 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 |
| `/prometheus/api/v1/format_query` | Formatage d'expression PromQL |
| `/prometheus/api/v1/series` | Métadonnées des séries |
| `/prometheus/api/v1/metadata` | Métadonnées de la famille de métriques |
L'exemple ne spécifie pas `database` ni `table` dans le gestionnaire. Chaque requête doit fournir le paramètre de requête `table` (sauf pour `/format_query`, qui se contente d'analyser l'expression PromQL fournie et n'a pas besoin de 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 :
```xml theme={null}
prometheus_api_v1
prometheus
```
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`. |
Créer une table TimeSeries
Créez une base de données et une table `TimeSeries` :
```sql theme={null}
CREATE DATABASE prometheus;
CREATE TABLE prometheus.metrics ENGINE = TimeSeries;
```
Ingérer des métriques via écriture distante
ClickHouse prend en charge le [protocole écriture distante de Prometheus](https://prometheus.io/docs/specs/remote_write_spec/). Configurez Prometheus pour écrire vers le gestionnaire :
```yaml theme={null}
remote_write:
- url: https://clickhouse.example.com:8443/prometheus/api/v1/write?database=prometheus&table=metrics
basic_auth:
username: default
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](/fr/reference/settings/session-settings/async-insert#async_insert) en ajoutant le paramètre `async_insert` à l’URL (ou en l’activant dans le profil utilisateur) :
```yaml theme={null}
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`](/fr/reference/settings/session-settings/wait-for#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.
Interroger avec PromQL
Utilisez l’endpoint de requête instantanée pour évaluer une expression PromQL à un instant donné :
```bash theme={null}
curl --user default: --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 :
```bash theme={null}
curl --user default: --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"
```
Les endpoints de requête acceptent également les paramètres dans un corps de formulaire. Sans `--get`, curl envoie les paramètres au format `application/x-www-form-urlencoded` via `POST` :
```bash theme={null}
curl --user default: \
"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"
```
Utilisez l’endpoint de formatage de requête pour analyser et formater une expression PromQL sans l’évaluer :
```bash theme={null}
curl --user default: --get \
"https://clickhouse.example.com:8443/prometheus/api/v1/format_query" \
--data-urlencode "query=sum by(job)(http_requests_total{code=\"200\"})/2"
```
L’expression est renvoyée sérialisée à partir de la requête analysée, avec les espaces normalisés, les commentaires supprimés, les parenthèses redondantes retirées et les durées converties en nombres de secondes : `sum by (job) (http_requests_total{code="200"}) / 2`. Cet endpoint n’évalue pas l’expression, il n’a donc pas besoin des paramètres `database` et `table`.
Consultez les [fonctionnalités PromQL prises en charge](/fr/reference/functions/table-functions/prometheusQueryRange#supported-promql-features) 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` :
```yaml theme={null}
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:
```
Grafana ajoute `/api/v1/query` ou `/api/v1/query_range` à cette URL de base et ajoute `customQueryParameters` à chaque requête.
Avec `httpMethod: POST`, Grafana envoie les paramètres de requête dans le corps de la requête. ClickHouse lit le corps de la requête ainsi que la chaîne de requête de l’URL, de sorte que `customQueryParameters` s’applique toujours. Utilisez `POST` pour les expressions PromQL longues, car une URL a une limite de longueur.
Seuls les endpoints de requête `/api/v1/query`, `/api/v1/query_range` et `/api/v1/format_query`, ainsi que les endpoints de métadonnées `/api/v1/series`, `/api/v1/labels`, `/api/v1/label//values` et `/api/v1/metadata`, sont implémentés. `/api/v1/series` nécessite au moins un sélecteur de séries `match[]`, prend en charge les paramètres facultatifs `start`, `end` et `limit`, et renvoie l’union des séries correspondant à chaque sélecteur. `/api/v1/labels` accepte les mêmes paramètres, `match[]` étant facultatif, et renvoie les noms de libellés triés des séries correspondantes (ou de toutes les séries lorsqu’aucun sélecteur n’est fourni). `/api/v1/label//values` accepte les mêmes paramètres que `/api/v1/labels` et renvoie les valeurs triées d’un libellé, `` pouvant utiliser l’échappement Prometheus `U__...` pour les noms de libellés contenant des caractères en dehors de `[a-zA-Z0-9_]`. Ces endpoints couvrent ce qu’une source de données Prometheus dans Grafana utilise pour parcourir les libellés, les variables de modèle et l’autocomplétion du 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`](/fr/reference/functions/table-functions/prometheusQuery) et [`prometheusQueryRange`](/fr/reference/functions/table-functions/prometheusQueryRange).
Exécutez directement des requêtes PromQL avec `clickhouse-client` :
```bash theme={null}
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 :
```sql theme={null}
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 :
| Paramètre | Description |
| - | - |
| `metric` | Renvoie les métadonnées uniquement pour cette famille de métriques. |
| `limit` | Limite le nombre de familles de métriques renvoyées. Une valeur négative signifie qu’il n’y a pas de limite ; zéro ne renvoie aucune famille de métriques. |
| `limit_per_metric` | Limite le nombre d’objets de métadonnées renvoyés pour chaque famille de métriques. Les valeurs nulles ou négatives signifient qu’il n’y a pas de limite. |
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.
```bash theme={null}
curl --user default: --get \
"https://clickhouse.example.com:8443/prometheus/api/v1/metadata" \
--data-urlencode "metric=http_requests_total" \
--data-urlencode "database=prometheus" \
--data-urlencode "table=metrics"
```
Lire les métriques via lecture distante
ClickHouse prend en charge le [protocole lecture distante de Prometheus](https://prometheus.io/docs/prometheus/latest/querying/remote_read_api/) sur `/prometheus/api/v1/read`.
Configurez un serveur Prometheus pour lire les données de la même table `TimeSeries` :
```yaml theme={null}
remote_read:
- url: https://clickhouse.example.com:8443/prometheus/api/v1/read?database=prometheus&table=metrics
basic_auth:
username: default
password:
```