Integração do ClickHouse Managed Postgres com Prometheus

O ClickHouse Managed Postgres expõe dois endpoints de métricas compatíveis com Prometheus na ClickHouse Cloud API:

O endpoint usa as mesmas [chaves de API] usadas no restante da OpenAPI; consulte o guia da OpenAPI para saber como criá-las e localizar os IDs da sua organização e do seu serviço.

KEY_ID=mykeyid
KEY_SECRET=mykeysecret
ORG_ID=myorgid
PG_ID=mypgid

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/prometheus"

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID/prometheus"

# HELP PostgresServiceInfo Informações sobre o serviço PostgreSQL, incluindo status e versão.
# TYPE PostgresServiceInfo gauge
PostgresServiceInfo{clickhouse_org="ca04a310-730d-4ce0-93dd-39f2cd2d5e6f",postgres_service="0c330583-6396-86d0-82cd-ed0f23b0d38c",postgres_service_name="my-postgres",postgres_status="running",postgres_version="18"} 1

# HELP PostgresServer_ActiveConnections Número de conexões ativas por estado.
# TYPE PostgresServer_ActiveConnections gauge
PostgresServer_ActiveConnections{clickhouse_org="ca04a310-730d-4ce0-93dd-39f2cd2d5e6f",postgres_service="0c330583-6396-86d0-82cd-ed0f23b0d38c",postgres_service_name="my-postgres",state="active"} 1
PostgresServer_ActiveConnections{clickhouse_org="ca04a310-730d-4ce0-93dd-39f2cd2d5e6f",postgres_service="0c330583-6396-86d0-82cd-ed0f23b0d38c",postgres_service_name="my-postgres",state="idle"} 4

# HELP PostgresServer_CacheHitRatio Taxa de acerto do cache de buffer: blocos servidos do cache vs. total de blocos acessados (%).
# TYPE PostgresServer_CacheHitRatio gauge
PostgresServer_CacheHitRatio{clickhouse_org="ca04a310-730d-4ce0-93dd-39f2cd2d5e6f",postgres_service="0c330583-6396-86d0-82cd-ed0f23b0d38c",postgres_service_name="my-postgres"} 100

Para ver a lista completa de métricas e seus significados, consulte a referência de métricas.

Esta configuração faz coleta do endpoint em nível de organização a cada 60 segundos:

scrape_configs:
  - job_name: "managed-postgres"
    scheme: https
    metrics_path: "/v1/organizations/<ORG_ID>/postgres/prometheus"
    static_configs:
      - targets: ["api.clickhouse.cloud"]
    basic_auth:
      username: <KEY_ID>
      password: <KEY_SECRET>
    honor_labels: true
    scrape_interval: 60s

O endpoint atualiza as métricas uma vez por minuto. Fazer coleta em um intervalo menor que 60s duplica as amostras e produz um padrão em degraus nos painéis de gauge.

Defina honor_labels: true para que os labels postgres_service e postgres_service_name do endpoint sejam preservados, em vez de serem sobrescritos pelo Prometheus.

Para fazer a coleta de um único serviço, acrescente /<PG_ID> a metrics_path.

Um dashboard pronto para uso do Grafana visualiza cada métrica que o endpoint expõe — uma tabela de serviços que pode ser ordenada, utilização de CPU e memória, uso de disco com alertas de limite, conexões por estado, transações e taxa de rollback, atividade de Tuple, E/S, armazenamento por banco de dados e deadlocks.

Para implantações provisionadas do Grafana, coloque o JSON no seu caminho de provisionamento de dashboards. O Grafana associa a referência ${DS_PROMETHEUS} a uma fonte de dados do Prometheus disponível na instância.

O dashboard disponibiliza três variáveis:

• Fonte de dados — a fonte de dados do Prometheus usada pelo dashboard.
• Serviço — filtro de múltipla seleção em postgres_service_name. O padrão é All; escolha um ou mais serviços para restringir todos os painéis.
• Intervalo de coleta — constante oculta; o padrão é 60s. Determina o cálculo de $__rate_interval do Grafana. Altere esse valor no JSON se o seu intervalo de coleta for diferente.

Vários painéis permitem uma análise mais detalhada quando você filtra para um único serviço por meio da variável Service. O painel de CPU por modo, por exemplo, empilha user, system, iowait, steal e outros modos de CPU para que você possa identificar se um pico vem do código da aplicação, de processamento do kernel, de espera por disco ou de contenção no hipervisor.

O endpoint segue o mesmo formato do endpoint Prometheus do ClickHouse, portanto as configurações do Grafana Cloud, Grafana Alloy e do agente OpenMetrics do Datadog descritas ali também se aplicam aqui. Aponte metrics_path para o caminho da organização ou da instância do ClickHouse Managed Postgres, em vez do caminho do ClickHouse.