Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Integração com Prometheus

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

Recurso beta

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
Configurar o Endpoint de Métricas do Grafana

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

Menu suspenso do Explorador de Métricas do Grafana

Gráfico do Explorador de Métricas do Grafana

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:

Grafana Alloy

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:

Explorador de Métricas do Grafana

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

Integração do Prometheus com o Datadog
Navigation