Intégration Prometheus

La fonctionnalité prend en charge l’intégration de Prometheus pour surveiller les services ClickHouse Cloud. L’accès aux métriques Prometheus est disponible via l’endpoint de la ClickHouse Cloud API, qui vous permet de vous connecter de manière sécurisée et d’exporter les métriques vers votre collector Prometheus. Ces métriques peuvent être intégrées à des tableaux de bord, par exemple dans Grafana ou Datadog, à des fins de visualisation. Les métriques des ClickPipes rattachés à un service sont incluses avec les métriques ClickHouse de ce service. Pour commencer, générez une clé API. Si vous recherchez l’endpoint équivalent pour les services ClickHouse Managed Postgres, consultez le ClickHouse Managed Postgres Prometheus endpoint.

API de l’endpoint Prometheus pour récupérer les métriques ClickHouse Cloud

Référence de l’API

Méthode	Chemin	Description
GET	`https://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/prometheus?filtered_metrics=[true \| false]`	Renvoie les métriques d’un service spécifique
GET	`https://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus?filtered_metrics=[true \| false]`	Obsolète. Renvoie les métriques de tous les services d’une organisation
GET	`https://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus/discovery?filtered_metrics=[true \| false]`	Renvoie les cibles de scraping Prometheus pour tous les services d’une organisation, au format de découverte de services HTTP

L’endpoint de métriques à l’échelle de l’organisation (GET /v1/organizations/{organizationId}/prometheus) est obsolète au profit de la découverte automatique des services. Les organisations existantes peuvent continuer à l’utiliser ; les organisations nouvellement créées utilisent à la place l’endpoint de découverte. Contactez le support ClickHouse si vous avez besoin d’accéder à cet endpoint.

Paramètres de la requête

Nom	Emplacement	Type
Organization ID	Adresse de l’endpoint	uuid
Service ID	Adresse de l’endpoint	uuid (facultatif)
filtered_metrics	Paramètre de requête	booléen (facultatif)

Les schémas complets des requêtes et réponses pour ces endpoints sont disponibles dans la référence de l’API Cloud.

Authentification

Utilisez votre clé API ClickHouse Cloud pour l’authentification de base :

Username: <KEY_ID>
Password: <KEY_SECRET>
Example request
export KEY_SECRET=<key_secret>
export KEY_ID=<key_id>
export ORG_ID=<org_id>

# For all services in $ORG_ID
curl --silent --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations/$ORG_ID/prometheus?filtered_metrics=true

# For a single service only
export SERVICE_ID=<service_id>
curl --silent --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations/$ORG_ID/services/$SERVICE_ID/prometheus?filtered_metrics=true

Exemple de réponse

# HELP ClickHouse_ServiceInfo Information about service, including cluster status and ClickHouse version
# TYPE ClickHouse_ServiceInfo untyped
ClickHouse_ServiceInfo{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",clickhouse_cluster_status="running",clickhouse_version="24.5",scrape="full"} 1

# HELP ClickHouseProfileEvents_Query Number of queries to be interpreted and potentially executed. Does not include queries that failed to parse or were rejected due to AST size limits, quota limits or limits on the number of simultaneously running queries. May include internal queries initiated by ClickHouse itself. Does not count subqueries.
# TYPE ClickHouseProfileEvents_Query counter
ClickHouseProfileEvents_Query{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 6

# HELP ClickHouseProfileEvents_QueriesWithSubqueries Count queries with all subqueries
# TYPE ClickHouseProfileEvents_QueriesWithSubqueries counter
ClickHouseProfileEvents_QueriesWithSubqueries{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 230

# HELP ClickHouseProfileEvents_SelectQueriesWithSubqueries Count SELECT queries with all subqueries
# TYPE ClickHouseProfileEvents_SelectQueriesWithSubqueries counter
ClickHouseProfileEvents_SelectQueriesWithSubqueries{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 224

# HELP ClickHouseProfileEvents_FileOpen Number of files opened.
# TYPE ClickHouseProfileEvents_FileOpen counter
ClickHouseProfileEvents_FileOpen{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 4157

# HELP ClickHouseProfileEvents_Seek Number of times the 'lseek' function was called.
# TYPE ClickHouseProfileEvents_Seek counter
ClickHouseProfileEvents_Seek{clickhouse_org="c2ba4799-a76e-456f-a71a-b021b1fafe60",clickhouse_service="12f4a114-9746-4a75-9ce5-161ec3a73c4c",clickhouse_service_name="test service",hostname="c-cream-ma-20-server-3vd2ehh-0",instance="c-cream-ma-20-server-3vd2ehh-0",table="system.events"} 1840

# HELP ClickPipes_Info Always equal to 1. Label "clickpipe_state" contains the current state of the pipe: Stopped/Provisioning/Running/Paused/Failed
# TYPE ClickPipes_Info gauge
ClickPipes_Info{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent",clickpipe_status="Running"} 1

# HELP ClickPipes_SentEvents_Total Total number of records sent to ClickHouse
# TYPE ClickPipes_SentEvents_Total counter
ClickPipes_SentEvents_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 5534250

# HELP ClickPipes_SentBytesCompressed_Total Total compressed bytes sent to ClickHouse.
# TYPE ClickPipes_SentBytesCompressed_Total counter
ClickPipes_SentBytesCompressed_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name
="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 380837520
ClickPipes_SentBytesCompressed_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name

# HELP ClickPipes_FetchedBytes_Total Total uncompressed bytes fetched from the source.
# TYPE ClickPipes_FetchedBytes_Total counter
ClickPipes_FetchedBytes_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 873286202

# HELP ClickPipes_Errors_Total Total errors ingesting data.
# TYPE ClickPipes_Errors_Total counter
ClickPipes_Errors_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 0

# HELP ClickPipes_SentBytes_Total Total uncompressed bytes sent to ClickHouse.
# TYPE ClickPipes_SentBytes_Total counter
ClickPipes_SentBytes_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 477187967

# HELP ClickPipes_FetchedBytesCompressed_Total Total compressed bytes fetched from the source. If data is uncompressed at the source, this will equal ClickPipes_FetchedBytes_Total
# TYPE ClickPipes_FetchedBytesCompressed_Total counter
ClickPipes_FetchedBytesCompressed_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 873286202

# HELP ClickPipes_FetchedEvents_Total Total number of records fetched from the source.
# TYPE ClickPipes_FetchedEvents_Total counter
ClickPipes_FetchedEvents_Total{clickhouse_org="11dfa1ec-767d-43cb-bfad-618ce2aaf959",clickhouse_service="82b83b6a-5568-4a82-aa78-fed9239db83f",clickhouse_service_name="ClickPipes demo instace",clickpipe_id="642bb967-940b-459e-9f63-a2833f62ec44",clickpipe_name="Confluent demo pipe",clickpipe_source="confluent"} 5535376

Libellés des métriques

Toutes les métriques comportent les libellés suivants :

Libellé	Description
clickhouse_org	ID de l’organisation
clickhouse_service	ID du service
clickhouse_service_name	Nom du service

Pour ClickPipes, les métriques comportent également les libellés suivants :

Libellé	Description
clickpipe_id	ID du ClickPipe
clickpipe_name	Nom du ClickPipe
clickpipe_source	Type de source du ClickPipe

Métriques d’information

ClickHouse Cloud fournit une métrique spéciale ClickHouse_ServiceInfo, qui est une gauge ayant toujours la valeur 1. Cette métrique contient tous les libellés de métrique ainsi que les libellés suivants :

Libellé	Description
clickhouse_cluster_status	État du service. Peut être l’un des suivants : [`awaking`	`running`	`degraded`	`idle`	`stopped`]
clickhouse_version	Version du serveur ClickHouse utilisée par le service
scrape	Indique l’état du dernier scrape. Peut être `full` ou `partial`
full	Indique qu’aucune erreur ne s’est produite lors du dernier scrape des métriques
partial	Indique que des erreurs se sont produites lors du dernier scrape des métriques et que seule la métrique `ClickHouse_ServiceInfo` a été renvoyée.

Les requêtes visant à récupérer des métriques ne réactiveront pas un service mis en veille. Si un service est dans l’état idle, seule la métrique ClickHouse_ServiceInfo sera renvoyée. Pour ClickPipes, il existe une métrique gauge similaire, ClickPipes_Info, qui contient, en plus des libellés de métrique, les libellés suivants :

Libellé	Description
clickpipe_state	L’état actuel du pipe

Configuration de Prometheus

Le serveur Prometheus collecte les métriques à partir des cibles configurées aux intervalles définis. Vous trouverez ci-dessous un exemple de configuration permettant au serveur Prometheus d’utiliser le ClickHouse Cloud Prometheus Endpoint :

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "prometheus"
    static_configs:
    - targets: ["localhost:9090"]
  - job_name: "clickhouse"
    static_configs:
      - targets: ["api.clickhouse.cloud"]
    scheme: https
    params:
      filtered_metrics: ["true"]
    metrics_path: "/v1/organizations/<ORG_ID>/prometheus"
    basic_auth:
      username: <KEY_ID>
      password: <KEY_SECRET>
    honor_labels: true

Notez que le paramètre de configuration honor_labels doit être défini sur true pour que le label d’instance soit correctement renseigné. De plus, filtered_metrics est défini sur true dans l’exemple ci-dessus, mais doit être configuré selon les préférences de l’utilisateur.

Découverte automatique des services

L’endpoint de découverte renvoie une cible de scraping par service de votre organisation, au format découverte de services HTTP (http_sd) de Prometheus. Prometheus actualise la liste des cibles à chaque interrogation de découverte et scrape chaque cible découverte. Les services nouvellement créés sont donc automatiquement pris en compte, tandis que les services supprimés sont retirés de la liste des cibles. Seuls les services que votre clé API est autorisée à consulter sont inclus ; les services en cours de suppression ou déjà supprimés sont omis. Pour l’utiliser, configurez un job http_sd_configs pour qu’il pointe vers l’endpoint de découverte :

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "clickhouse"
    http_sd_configs:
      - url: https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/prometheus/discovery
        refresh_interval: 60s
        basic_auth:
          username: <KEY_ID>
          password: <KEY_SECRET>
    basic_auth:
      username: <KEY_ID>
      password: <KEY_SECRET>
    honor_labels: true

Définissez basic_auth aux deux emplacements : le bloc sous http_sd_configs authentifie les requêtes de découverte, et le bloc du job de scraping authentifie la récupération des métriques pour chaque service. Comme pour la configuration statique, définissez honor_labels: true afin que le libellé d’instance soit correctement renseigné. Exemple de réponse de découverte :

[
  {
    "targets": ["api.clickhouse.cloud"],
    "labels": {
      "__scheme__": "https",
      "__metrics_path__": "/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/prometheus",
      "__param_filtered_metrics": "true",
      "clickhouse_org_id": "<ORG_ID>",
      "clickhouse_service_id": "<SERVICE_ID>",
      "clickhouse_discovery_service_name": "my service"
    }
  }
]

Les cibles découvertes récupèrent les métriques avec filtered_metrics=true. Pour découvrir les cibles qui récupèrent l’ensemble complet des métriques, ajoutez ?filtered_metrics=false à l’URL de découverte. La spécification complète de l’endpoint est disponible dans la référence de l’API Cloud.

Intégration à Grafana

Les utilisateurs ont deux principales façons d’intégrer Grafana :

Endpoint de métriques – Cette approche a l’avantage de ne nécessiter aucun composant ni infrastructure supplémentaire. Cette offre est limitée à Grafana Cloud et requiert uniquement l’URL du ClickHouse Cloud Prometheus Endpoint ainsi que des informations d’authentification.
Grafana Alloy - Grafana Alloy est une distribution d’OpenTelemetry (OTel) Collector indépendante des fournisseurs, qui remplace Grafana Agent. Il peut être utilisé comme scraper, être déployé dans votre propre infrastructure et est compatible avec n’importe quel endpoint Prometheus.

Nous fournissons ci-dessous des instructions sur l’utilisation de ces options, en nous concentrant sur les détails propres au ClickHouse Cloud Prometheus Endpoint.

Grafana Cloud avec endpoint de métriques

Connectez-vous à votre compte Grafana Cloud
Ajoutez une nouvelle connexion en sélectionnant endpoint de métriques
Configurez l’URL de scraping pour qu’elle pointe vers l’endpoint Prometheus et utilisez l’authentification de base pour configurer votre connexion avec la clé API/le secret
Testez la connexion pour vous assurer qu’elle fonctionne

Une fois la configuration terminée, vous devriez voir les métriques dans le menu déroulant, que vous pourrez sélectionner pour configurer des tableaux de bord :

Grafana Cloud avec Alloy

Si vous utilisez Grafana Cloud, vous pouvez installer Alloy en accédant au menu Alloy dans Grafana et en suivant les instructions affichées à l’écran :
Cela devrait configurer Alloy avec un composant prometheus.remote_write pour envoyer des données vers un endpoint Grafana Cloud à l’aide d’un jeton d’authentification. Il vous suffit ensuite de modifier la configuration d’Alloy (située dans /etc/alloy/config.alloy sous Linux) pour y inclure un scraper pour le ClickHouse Cloud Prometheus Endpoint. L’exemple suivant montre une configuration Alloy avec un composant prometheus.scrape pour scraper les métriques depuis le ClickHouse Cloud Endpoint, ainsi que le composant prometheus.remote_write configuré automatiquement. Notez que le composant de configuration basic_auth contient l’ID et le secret de notre clé Cloud API comme nom d’utilisateur et mot de passe, respectivement.

prometheus.scrape "clickhouse_cloud" {
  targets = [{
  __address__ = "api.clickhouse.cloud",
  }]

  scheme       = "https"
  metrics_path = "/v1/organizations/<clickhouse_org_id>/prometheus"

  params = {
  "filtered_metrics" = ["true"],
  }

  honor_labels    = true
  scrape_interval = "30s"
  scrape_timeout  = "25s"

  basic_auth {
  username = "<clickhouse_api_key_id>"
  password = "<clickhouse_api_key_secret>"
  }

  forward_to = [prometheus.remote_write.grafana_cloud.receiver]
}

  prometheus.remote_write "grafana_cloud" {
  endpoint {
  url = "https://<grafana_prometheus_url>/api/prom/push"

  basic_auth {
  username = "<grafana_username>"
  password = "<grafana_api_token>"
  }
  }
}

Notez que le paramètre de configuration honor_labels doit être défini sur true pour que le label d’instance soit correctement renseigné.

Grafana autogéré avec Alloy

Les utilisateurs de Grafana autogéré peuvent consulter les instructions d’installation de l’agent Alloy ici. Nous partons du principe qu’Alloy est configuré pour envoyer les métriques Prometheus vers la destination souhaitée. Le composant prometheus.scrape ci-dessous permet à Alloy de scraper le ClickHouse Cloud Endpoint. Nous supposons que prometheus.remote_write reçoit les métriques scrapées. Ajustez la clé forward_to vers la destination cible si elle n’existe pas.

// prometheus.scrape component causes Alloy to scrape the ClickHouse Cloud Prometheus endpoint.
  // Adjust the forward_to key to match your remote_write receiver if it differs.
  prometheus.scrape "clickhouse_cloud" {
  targets = [{
  __address__ = "api.clickhouse.cloud",
  }]

  scheme       = "https"
  metrics_path = "/v1/organizations/<organizationId>/prometheus"

  params = {
  "filtered_metrics" = ["true"],
  }

  honor_labels = true

  basic_auth {
  username = "<KEY_ID>"
  password = "<KEY_SECRET>"
  }

  forward_to = [prometheus.remote_write.metrics_service.receiver]
}

Une fois la configuration effectuée, vous devriez voir les métriques liées à ClickHouse dans votre explorateur de métriques :
Notez que le paramètre de configuration honor_labels doit être défini sur true pour que l’label d’instance soit correctement renseigné.

Intégration avec Datadog

Vous pouvez utiliser l’Agent Datadog et l’intégration OpenMetrics pour collecter des métriques à partir de l’endpoint ClickHouse Cloud. Vous trouverez ci-dessous un exemple simple de configuration pour cet agent et cette intégration. Notez toutefois qu’il peut être préférable de ne sélectionner que les métriques les plus pertinentes pour vous. L’exemple passe-partout ci-dessous exportera plusieurs milliers de combinaisons métrique-instance, que Datadog considérera comme des métriques personnalisées.

init_config:

instances:
   - openmetrics_endpoint: 'https://api.clickhouse.cloud/v1/organizations/97a33bdb-4db3-4067-b14f-ce40f621aae1/prometheus?filtered_metrics=true'
     namespace: 'clickhouse'
     metrics:
         - '^ClickHouse.*'
     username: username
     password: password

Vue d’ensemble de Monitoring — Comparez toutes les approches de monitoring pour ClickHouse Cloud
Monitoring dans Cloud Console — Tableaux de bord intégrés ne nécessitant aucun outil externe
Intégrations de la communauté et des partenaires — Intégration de l’agent Datadog et solutions de la communauté
Interrogation des tables système — Accès SQL direct aux métriques système
ClickHouse Managed Postgres Prometheus endpoint — Récupérez les métriques de vos services ClickHouse Managed Postgres

Get started

Services and infrastructure

Bring Your Own Cloud

Data and integrations

Connect and query

Access management

Security and compliance

Monitoring and backups

AI tools and agents

Cloud API

Billing

Support

ClickHouse Private

API de l’endpoint Prometheus pour récupérer les métriques ClickHouse Cloud

Référence de l’API

Authentification

Exemple de réponse

Libellés des métriques

Métriques d’information

Configuration de Prometheus

Découverte automatique des services

Intégration à Grafana

Grafana Cloud avec endpoint de métriques

Grafana Cloud avec Alloy

Grafana autogéré avec Alloy

Intégration avec Datadog

​API de l’endpoint Prometheus pour récupérer les métriques ClickHouse Cloud

​Référence de l’API

​Authentification

​Exemple de réponse

​Libellés des métriques

​Métriques d’information

​Configuration de Prometheus

​Découverte automatique des services

​Intégration à Grafana

​Grafana Cloud avec endpoint de métriques

​Grafana Cloud avec Alloy

​Grafana autogéré avec Alloy

​Intégration avec Datadog

​Pages associées

API de l’endpoint Prometheus pour récupérer les métriques ClickHouse Cloud

Référence de l’API

Authentification

Exemple de réponse

Libellés des métriques

Métriques d’information

Configuration de Prometheus

Découverte automatique des services

Intégration à Grafana

Grafana Cloud avec endpoint de métriques

Grafana Cloud avec Alloy

Grafana autogéré avec Alloy

Intégration avec Datadog

Pages associées