Integración con Prometheus

Exportar métricas de ClickHouse a 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.

Para empezar, genere una API key.

Si busca el endpoint equivalente para los servicios de Managed Postgres, consulte el endpoint de Prometheus de 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]	Devuelve las métricas de todos los servicios de una organización

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)

​

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.

​

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 ClickHouse Cloud Prometheus Endpoint.

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.

// El componente prometheus.scrape hace que Alloy realice scraping del endpoint de Prometheus de ClickHouse Cloud.
  // Ajuste la clave forward_to para que coincida con su receiver de remote_write si difiere.
  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

​

Páginas relacionadas

• Resumen de monitorización — Compare todos los enfoques de monitorización de ClickHouse Cloud
• Monitorización en Cloud Console — dashboards integrados que no requieren herramientas externas
• Integraciones de la comunidad y de socios — Integración del agente de Datadog y soluciones de la comunidad
• Consulta de system tables — Acceso directo por SQL a las métricas del sistema
• endpoint de Prometheus de Managed Postgres — Extraiga métricas de sus servicios de Managed Postgres