Integración con Prometheus

Esta función admite la integración con Prometheus para supervisar los servicios de ClickHouse Cloud. El acceso a las métricas de Prometheus se ofrece a través del endpoint de la ClickHouse Cloud API, que le permite conectarse de forma segura y exportar métricas a su collector de métricas de Prometheus. Estas métricas pueden integrarse con dashboards como Grafana y Datadog para su visualización. Las métricas de los ClickPipes asociados a un servicio se incluyen junto con las métricas de ClickHouse de ese servicio. Para empezar, genere una API key. Si busca el endpoint equivalente para los servicios de ClickHouse Managed Postgres, consulte el endpoint de Prometheus de ClickHouse Managed Postgres.

API del endpoint de Prometheus para obtener métricas de ClickHouse Cloud

Referencia de la API

Método	Ruta	Descripción
GET	`https://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/prometheus?filtered_metrics=[true \| false]`	Devuelve las métricas de un servicio específico
GET	`https://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus?filtered_metrics=[true \| false]`	Obsoleto. Devuelve las métricas de todos los servicios de una organización
GET	`https://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus/discovery?filtered_metrics=[true \| false]`	Devuelve los destinos de scrape de Prometheus para todos los servicios de una organización, en el formato de detección de servicios HTTP

El endpoint de métricas de toda la organización (GET /v1/organizations/{organizationId}/prometheus) está obsoleto en favor de la detección automática de servicios. Las organizaciones existentes pueden seguir usándolo; las organizaciones recién creadas usan el endpoint de detección en su lugar. Contacte con el soporte de ClickHouse si necesita acceso a este endpoint.

Parámetros de la solicitud

Nombre	Ubicación	Tipo
ID de la organización	endpoint	uuid
ID del servicio	endpoint	uuid (opcional)
filtered_metrics	Parámetro de consulta	boolean (opcional)

Los esquemas completos de solicitud y respuesta para estos endpoints están disponibles en la referencia de Cloud API.

Autenticación

Utiliza tu API key de ClickHouse Cloud para la autenticación básica:

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

# Para todos los servicios en $ORG_ID
curl --silent --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations/$ORG_ID/prometheus?filtered_metrics=true

# Solo para un único servicio
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

Respuesta de ejemplo

# HELP ClickHouse_ServiceInfo Información sobre el servicio, incluido el estado del clúster y la versión de ClickHouse
# 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 Número de consultas que se interpretarán y potencialmente ejecutarán. No incluye consultas que no se pudieron analizar o que fueron rechazadas por límites de tamaño de AST, límites de cuota o límites en el número de consultas en ejecución simultánea. Puede incluir consultas internas iniciadas por el propio ClickHouse. No cuenta las subconsultas.
# 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 Cuenta las consultas con todas sus subconsultas
# 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 Cuenta las consultas SELECT con todas sus subconsultas
# 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 Número de archivos abiertos.
# 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 Número de veces que se llamó a la función 'lseek'.
# 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 Siempre igual a 1. La etiqueta "clickpipe_state" contiene el estado actual del 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 Número total de registros enviados a 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 de bytes comprimidos enviados a 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 de bytes sin comprimir obtenidos desde el origen.
# 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 de errores al ingestar datos.
# 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 de bytes sin comprimir enviados a 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 de bytes comprimidos obtenidos desde el origen. Si los datos no están comprimidos en el origen, este valor será igual a 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 Número total de registros obtenidos de la fuente.
# 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

Etiquetas de métricas

Todas las métricas tienen las siguientes etiquetas:

Etiqueta	Descripción
clickhouse_org	ID de la organización
clickhouse_service	ID del servicio
clickhouse_service_name	Nombre del servicio

En ClickPipes, las métricas también tendrán las siguientes etiquetas:

Etiqueta	Descripción
clickpipe_id	ID de ClickPipe
clickpipe_name	Nombre de ClickPipe
clickpipe_source	Tipo de origen de ClickPipe

Métricas de información

ClickHouse Cloud proporciona una métrica especial ClickHouse_ServiceInfo, que es un gauge y siempre tiene el valor 1. Esta métrica contiene todas las Etiquetas de métricas, así como las siguientes etiquetas:

Label	Description
clickhouse_cluster_status	Estado del servicio. Puede ser uno de los siguientes: [`awaking`	`running`	`degraded`	`idle`	`stopped`]
clickhouse_version	Versión del servidor de ClickHouse que ejecuta el servicio
scrape	Indica el estado del último scrape. Puede ser `full` o `partial`
full	Indica que no hubo errores durante el último scrape de métricas
partial	Indica que hubo algunos errores durante el último scrape de métricas y que solo se devolvió la métrica `ClickHouse_ServiceInfo`.

Las solicitudes para recuperar métricas no reactivarán un servicio inactivo. Si un servicio está en estado idle, solo se devolverá la métrica ClickHouse_ServiceInfo. Para ClickPipes, hay una métrica gauge similar, ClickPipes_Info, que además de las Etiquetas de métricas contiene las siguientes etiquetas:

Label	Description
clickpipe_state	El estado actual del pipe

Configuración de Prometheus

El servidor Prometheus recopila métricas de los destinos configurados en los intervalos especificados. A continuación, se muestra un ejemplo de configuración para que el servidor Prometheus use el endpoint de Prometheus de ClickHouse Cloud:

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

Ten en cuenta que el parámetro de configuración honor_labels debe establecerse en true para que la etiqueta de instancia se rellene correctamente. Además, en el ejemplo anterior filtered_metrics está establecido en true, pero debe configurarse según las preferencias del usuario.

Detección automática de servicios

El endpoint de descubrimiento devuelve un destino de scrape por cada servicio de su organización, en el formato de detección de servicios HTTP (http_sd) de Prometheus. Prometheus actualiza la lista de destinos en cada sondeo de descubrimiento y recopila métricas de cada destino detectado, por lo que los servicios recién creados se incluyen automáticamente y los servicios eliminados se quitan de la lista de destinos. Solo se incluyen los servicios que su API key tiene autorización para ver; se omiten los servicios que se están eliminando o que ya se han eliminado. Para usarlo, configure un job de http_sd_configs para que apunte al endpoint de descubrimiento:

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

Configure basic_auth en ambos lugares: el bloque de http_sd_configs autentica los sondeos de detección y el bloque del trabajo de scrape autentica la recopilación de métricas de cada servicio. Al igual que con la configuración estática, establezca honor_labels: true para que la etiqueta de instancia se rellene correctamente. Una respuesta de detección de ejemplo:

[
  {
    "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"
    }
  }
]

Los destinos detectados se recopilan con filtered_metrics=true. Para detectar destinos que recopilan el conjunto completo de métricas, añada ?filtered_metrics=false a la URL de discovery. La especificación completa del endpoint está disponible en la referencia de Cloud API.

Integración con Grafana

Los usuarios disponen de dos formas principales de integrarse con Grafana:

Endpoint de métricas – Este enfoque tiene la ventaja de no requerir componentes ni infraestructura adicionales. Esta opción está limitada a Grafana Cloud y solo requiere la URL del endpoint de Prometheus de ClickHouse Cloud y las credenciales.
Grafana Alloy - Grafana Alloy es una distribución agnóstica del proveedor del OpenTelemetry (OTel) Collector que sustituye a Grafana Agent. Puede usarse como scraper, implementarse en su propia infraestructura y es compatible con cualquier endpoint de Prometheus.

A continuación, proporcionamos instrucciones para usar estas opciones, centrándonos en los detalles específicos del endpoint de Prometheus de ClickHouse Cloud.

Grafana Cloud con endpoint de métricas

Inicia sesión en tu cuenta de Grafana Cloud
Añade una nueva conexión seleccionando el endpoint de métricas
Configura la URL de scrape para que apunte al endpoint de Prometheus y usa autenticación básica para configurar la conexión con la API key/secret
Prueba la conexión para asegurarte de que se establece correctamente

Una vez configurado, deberías ver las métricas en el menú desplegable, que puedes seleccionar para configurar dashboards:

Grafana Cloud con Alloy

Si usas Grafana Cloud, puedes instalar Alloy desde el menú Alloy en Grafana siguiendo las instrucciones en pantalla:
Esto debería configurar Alloy con un componente prometheus.remote_write para enviar datos a un endpoint de Grafana Cloud con un token de autenticación. Después, solo tendrás que modificar la configuración de Alloy (ubicada en /etc/alloy/config.alloy en Linux) para incluir un scraper para el endpoint de Prometheus de ClickHouse Cloud. A continuación se muestra una configuración de ejemplo de Alloy con un componente prometheus.scrape para recopilar métricas del ClickHouse Cloud Endpoint, junto con el componente prometheus.remote_write configurado automáticamente. Ten en cuenta que el componente de configuración basic_auth contiene el ID y el secreto de nuestra API key de Cloud como nombre de usuario y contraseña, respectivamente.

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>"
  }
  }
}

Tenga en cuenta que el parámetro de configuración honor_labels debe establecerse en true para que la etiqueta de la instancia se rellene correctamente.

Grafana autogestionado con Alloy

Los usuarios de Grafana autogestionado pueden encontrar las instrucciones para instalar el agente Alloy aquí. Suponemos que los usuarios han configurado Alloy para enviar métricas de Prometheus al destino deseado. El componente prometheus.scrape que aparece a continuación hace que Alloy recopile métricas del ClickHouse Cloud Endpoint. Suponemos que prometheus.remote_write recibe las métricas recopiladas. Ajuste la clave forward_to para que apunte al destino de destino si esta no existe.

// 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]
}

Una vez configurado, deberías ver las métricas relacionadas con ClickHouse en el explorador de métricas:
Ten en cuenta que el parámetro de configuración honor_labels debe establecerse en true para que la etiqueta instance se rellene correctamente.

Integración con Datadog

Puedes usar el Agent de Datadog y la integración de OpenMetrics para recopilar métricas desde el endpoint de ClickHouse Cloud. A continuación se muestra un ejemplo sencillo de configuración para este agente y esta integración. No obstante, ten en cuenta que quizá te convenga seleccionar solo las métricas que más te interesen. El ejemplo genérico que aparece a continuación exportará muchos miles de combinaciones de métricas e instancias que Datadog tratará como métricas personalizadas.

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

Resumen de monitorización — Compare todos los enfoques de monitorización para ClickHouse Cloud
Monitorización en Cloud Console — Dashboards integrados que no requieren herramientas externas
Integraciones de la comunidad y de socios — Integración con el agente de Datadog y soluciones de la comunidad
Consulta de tablas del sistema — Acceso directo por SQL a las métricas del sistema
endpoint de Prometheus de ClickHouse Managed Postgres — Extraiga métricas de sus servicios de 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 del endpoint de Prometheus para obtener métricas de ClickHouse Cloud

Referencia de la API

Autenticación

Respuesta de ejemplo

Etiquetas de métricas

Métricas de información

Configuración de Prometheus

Detección automática de servicios

Integración con Grafana

Grafana Cloud con endpoint de métricas

Grafana Cloud con Alloy

Grafana autogestionado con Alloy

Integración con Datadog

​API del endpoint de Prometheus para obtener métricas de ClickHouse Cloud

​Referencia de la API

​Autenticación

​Respuesta de ejemplo

​Etiquetas de métricas

​Métricas de información

​Configuración de Prometheus

​Detección automática de servicios

​Integración con Grafana

​Grafana Cloud con endpoint de métricas

​Grafana Cloud con Alloy

​Grafana autogestionado con Alloy

​Integración con Datadog

​Páginas relacionadas

API del endpoint de Prometheus para obtener métricas de ClickHouse Cloud

Referencia de la API

Autenticación

Respuesta de ejemplo

Etiquetas de métricas

Métricas de información

Configuración de Prometheus

Detección automática de servicios

Integración con Grafana

Grafana Cloud con endpoint de métricas

Grafana Cloud con Alloy

Grafana autogestionado con Alloy

Integración con Datadog

Páginas relacionadas