Integração com Prometheus

O recurso oferece suporte à integração com o Prometheus para monitorar serviços do ClickHouse Cloud. O acesso às métricas do Prometheus é disponibilizado por meio do endpoint da ClickHouse Cloud API, que permite conectar-se com segurança e exportar métricas para seu collector de métricas do Prometheus. Essas métricas podem ser integradas a dashboards, como Grafana e Datadog, para visualização. As métricas dos ClickPipes associados a um serviço são incluídas junto às métricas do ClickHouse desse serviço. Para começar, gere uma chave de API. Se você estiver procurando o endpoint equivalente para serviços de ClickHouse Managed Postgres, consulte o endpoint Prometheus do ClickHouse Managed Postgres.

API do endpoint Prometheus para obter métricas do ClickHouse Cloud

Referência da API

Método	Caminho	Descrição
GET	`https://api.clickhouse.cloud/v1/organizations/:organizationId/services/:serviceId/prometheus?filtered_metrics=[true \| false]`	Retorna métricas de um serviço específico
GET	`https://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus?filtered_metrics=[true \| false]`	Descontinuado. Retorna métricas de todos os serviços em uma organização
GET	`https://api.clickhouse.cloud/v1/organizations/:organizationId/prometheus/discovery?filtered_metrics=[true \| false]`	Retorna alvos de coleta do Prometheus para todos os serviços em uma organização, no formato descoberta de serviços HTTP

O endpoint de métricas de toda a organização (GET /v1/organizations/{organizationId}/prometheus) foi descontinuado em favor da descoberta automática de serviços. As organizações existentes podem continuar a usá-lo; as organizações recém-criadas usam o endpoint de descoberta. Entre em contato com o suporte do ClickHouse se precisar de acesso a este endpoint.

Parâmetros da requisição

Nome	Localização	Tipo
ID da organização	Endereço do endpoint	uuid
ID do serviço	Endereço do endpoint	uuid (opcional)
filtered_metrics	Parâmetro de consulta	booleano (opcional)

Os esquemas completos de requisição e resposta desses endpoints estão disponíveis na Referência da Cloud API.

Autenticação

Use a chave de API do ClickHouse Cloud para autenticação 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 os serviços em $ORG_ID
curl --silent --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations/$ORG_ID/prometheus?filtered_metrics=true

# Para um único serviço
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

Resposta de exemplo

# HELP ClickHouse_ServiceInfo Informações sobre o serviço, incluindo o status do cluster e a versão do 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 a serem interpretadas e potencialmente executadas. Não inclui consultas que falharam ao fazer parse ou foram rejeitadas devido a limites de tamanho de AST, limites de QUOTA ou limites no número de consultas em execução simultânea. Pode incluir consultas internas iniciadas pelo próprio ClickHouse. Não contabiliza 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 Contagem de consultas com todas as 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 Contagem de consultas SELECT com todas as 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 arquivos abertos.
# 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 vezes que a função 'lseek' foi chamada.
# 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 Sempre igual a 1. O label "clickpipe_state" contém o estado atual do 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 ao 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 ao 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 não comprimidos obtidos da fonte.
# 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 erros na ingestão de dados.
# 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 não comprimidos enviados ao 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 obtidos da fonte. Se os dados não estiverem comprimidos na fonte, 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 obtidos da fonte.
# 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

Rótulos de métricas

Todas as métricas têm os seguintes rótulos:

Rótulo	Descrição
clickhouse_org	ID da organização
clickhouse_service	ID do serviço
clickhouse_service_name	Nome do serviço

No ClickPipes, as métricas também terão os seguintes rótulos:

Rótulo	Descrição
clickpipe_id	ID do ClickPipe
clickpipe_name	Nome do ClickPipe
clickpipe_source	Tipo de origem do ClickPipe

Métricas informativas

O ClickHouse Cloud fornece uma métrica especial, ClickHouse_ServiceInfo, que é um gauge e sempre tem o valor 1. Essa métrica contém todos os rótulos de métricas, bem como os seguintes rótulos:

Rótulo	Descrição
clickhouse_cluster_status	Status do serviço. Pode ser um dos seguintes: [`awaking`	`running`	`degraded`	`idle`	`stopped`]
clickhouse_version	Versão do servidor ClickHouse em execução no serviço
scrape	Indica o status do último scrape. Pode ser `full` ou `partial`
full	Indica que não houve erros durante o último scrape de métricas
partial	Indica que houve alguns erros durante o último scrape de métricas e que apenas a métrica `ClickHouse_ServiceInfo` foi retornada.

As solicitações para obter métricas não reativam um serviço em inatividade. Caso um serviço esteja no estado idle, apenas a métrica ClickHouse_ServiceInfo será retornada. Para o ClickPipes, há uma métrica gauge semelhante, ClickPipes_Info, que, além dos rótulos de métricas, contém os seguintes rótulos:

Rótulo	Descrição
clickpipe_state	O estado atual do pipe

Configurando o Prometheus

O servidor Prometheus coleta métricas dos alvos configurados nos intervalos definidos. Abaixo está um exemplo de configuração para o servidor Prometheus usar o endpoint Prometheus do 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

Observe que o parâmetro de configuração honor_labels precisa ser definido como true para que o rótulo da instância seja preenchido corretamente. Além disso, no exemplo acima, filtered_metrics está definido como true, mas isso deve ser configurado de acordo com a preferência do usuário.

Descoberta automática de serviços

O endpoint de descoberta retorna um alvo de coleta para cada serviço da sua organização, no formato de descoberta de serviços HTTP (http_sd) do Prometheus. O Prometheus atualiza a lista de alvos a cada consulta de descoberta e coleta métricas de cada alvo descoberto. Assim, os serviços recém-criados são incluídos automaticamente, e os serviços excluídos são removidos da lista de alvos. São incluídos apenas os serviços que sua chave de API tem permissão para visualizar; serviços que estão sendo excluídos ou já foram excluídos são omitidos. Para usá-lo, configure um job http_sd_configs para apontar para o endpoint de descoberta:

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

Defina basic_auth nos dois locais: o bloco em http_sd_configs autentica as consultas de descoberta, e o bloco no job de scrape autentica a coleta de métricas de cada serviço. Assim como na configuração estática, defina honor_labels: true para que o rótulo de instância seja preenchido corretamente. Um exemplo de resposta de descoberta:

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

Os alvos descobertos são coletados com filtered_metrics=true. Para descobrir alvos que coletam o conjunto completo de métricas, adicione ?filtered_metrics=false à URL de discovery. A especificação completa do endpoint está disponível na referência da Cloud API.

Integrando-se ao Grafana

Os usuários têm duas maneiras principais de se integrar ao Grafana:

Endpoint de métricas – Essa abordagem tem a vantagem de não exigir componentes nem infraestrutura adicionais. Essa opção é limitada ao Grafana Cloud e requer apenas a URL do endpoint Prometheus do ClickHouse Cloud e as credenciais.
Grafana Alloy - O Grafana Alloy é uma distribuição independente de fornecedor do Collector do OpenTelemetry (OTel), substituindo o Grafana Agent. Ele pode ser usado como scraper, pode ser implantado na sua própria infraestrutura e é compatível com qualquer endpoint Prometheus.

Fornecemos abaixo instruções para usar essas opções, com foco nos detalhes específicos do endpoint Prometheus do ClickHouse Cloud.

Grafana Cloud com endpoint de métricas

Faça login na sua conta do Grafana Cloud
Adicione uma nova conexão selecionando o Endpoint de Métricas
Configure a URL de scrape para apontar para o endpoint Prometheus e use autenticação básica para configurar a conexão com a chave da API/o segredo
Teste a conexão para garantir que ela funcione

Depois de concluir a configuração, as métricas deverão aparecer no menu suspenso para que você possa selecioná-las e configurar dashboards:

Grafana Cloud com Alloy

Se você estiver usando o Grafana Cloud, o Alloy pode ser instalado acessando o menu Alloy no Grafana e seguindo as instruções na tela:
Isso deve configurar o Alloy com um componente prometheus.remote_write para enviar dados a um endpoint do Grafana Cloud com um token de autenticação. Depois, basta modificar a configuração do Alloy (localizada em /etc/alloy/config.alloy no Linux) para incluir um scraper para o Endpoint Prometheus do ClickHouse Cloud. A seguir, é mostrado um exemplo de configuração do Alloy com um componente prometheus.scrape para a coleta de métricas do endpoint do ClickHouse Cloud, bem como o componente prometheus.remote_write configurado automaticamente. Observe que o componente de configuração basic_auth contém o ID e o segredo da nossa chave de API do Cloud como nome de usuário e senha, 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>"
  }
  }
}

Observe que o parâmetro de configuração honor_labels precisa ser definido como true para que o rótulo da instância seja preenchido corretamente.

Grafana autogerenciado com Alloy

Usuários do Grafana autogerenciado podem encontrar as instruções para instalar o agente Alloy aqui. Presumimos que os usuários já tenham configurado o Alloy para enviar métricas do Prometheus ao destino desejado. O componente prometheus.scrape abaixo faz o Alloy coletar métricas do endpoint do ClickHouse Cloud. Presumimos que prometheus.remote_write receba as métricas coletadas. Ajuste a forward_to key para o destino de envio desejado, caso ela não exista.

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

Depois de configurar, você deverá ver as métricas relacionadas ao ClickHouse no explorador de métricas:
Observe que o parâmetro de configuração honor_labels precisa ser definido como true para que o rótulo da instância seja preenchido corretamente.

Integração com o Datadog

Você pode usar o Agent e a integração OpenMetrics do Datadog para coletar métricas do endpoint do ClickHouse Cloud. Abaixo está um exemplo simples de configuração desse agente e dessa integração. Observe, porém, que talvez você queira selecionar apenas as métricas mais importantes para você. O exemplo genérico abaixo exportará muitos milhares de combinações de métrica-instância, que o 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

Visão geral do monitoramento — Compare todas as abordagens de monitoramento do ClickHouse Cloud
Monitoramento no Cloud Console — Dashboards integrados que não exigem ferramentas externas
Integrações da comunidade e de parceiros — Integração com o agente Datadog e soluções da comunidade
Consultando tabelas do sistema — Acesso SQL direto às métricas do sistema
Endpoint Prometheus do ClickHouse Managed Postgres — Colete métricas dos seus serviços 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 do endpoint Prometheus para obter métricas do ClickHouse Cloud

Referência da API

Autenticação

Resposta de exemplo

Rótulos de métricas

Métricas informativas

Configurando o Prometheus

Descoberta automática de serviços

Integrando-se ao Grafana

Grafana Cloud com endpoint de métricas

Grafana Cloud com Alloy

Grafana autogerenciado com Alloy

Integração com o Datadog

​API do endpoint Prometheus para obter métricas do ClickHouse Cloud

​Referência da API

​Autenticação

​Resposta de exemplo

​Rótulos de métricas

​Métricas informativas

​Configurando o Prometheus

​Descoberta automática de serviços

​Integrando-se ao Grafana

​Grafana Cloud com endpoint de métricas

​Grafana Cloud com Alloy

​Grafana autogerenciado com Alloy

​Integração com o Datadog

​Páginas relacionadas

API do endpoint Prometheus para obter métricas do ClickHouse Cloud

Referência da API

Autenticação

Resposta de exemplo

Rótulos de métricas

Métricas informativas

Configurando o Prometheus

Descoberta automática de serviços

Integrando-se ao Grafana

Grafana Cloud com endpoint de métricas

Grafana Cloud com Alloy

Grafana autogerenciado com Alloy

Integração com o Datadog

Páginas relacionadas