`](/fr/concepts/features/interfaces/http). |
| `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`](/fr/reference/system-tables/metrics). |
| `asynchronous_metrics` | true | Expose les métriques de [`system.asynchronous_metrics`](/fr/reference/system-tables/asynchronous_metrics). |
| `events` | true | Expose les métriques de [`system.events`](/fr/reference/system-tables/events). |
| `errors` | true | Expose le nombre d’erreurs de [`system.errors`](/fr/reference/system-tables/errors). |
| `histograms` | true | Expose les métriques de [`system.histogram_metrics`](/fr/reference/system-tables/histogram_metrics). |
| `dimensional_metrics` | true | Expose les métriques de [`system.dimensional_metrics`](/fr/reference/system-tables/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 :
```bash theme={null}
curl http://127.0.0.1:9363/metrics
```
## API HTTP Prometheus et PromQL
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.
### Prérequis
Activez le paramètre [`allow_experimental_time_series_table`](/fr/reference/settings/session-settings/allow-experimental#allow_experimental_time_series_table) pour l’utilisateur qui crée la table et y accède :
```sql theme={null}
SET allow_experimental_time_series_table = 1;
```
Créez une base de données et une table `TimeSeries` :
```sql theme={null}
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 :
```xml theme={null}
/prometheus/api/v1
prometheus_api_v1
```
`` 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 :
```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`. |
### 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`.
### 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"
```
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: GET
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.
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//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`](/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()
);
```
### 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:
```