Monitoramento das métricas do PostgreSQL com o ClickStack

Integração com PostgreSQL existente

Esta seção aborda como configurar a sua instalação existente do PostgreSQL para enviar métricas ao ClickStack, configurando o ClickStack OTel collector com o PostgreSQL receiver.

Se quiser testar a integração de métricas do PostgreSQL antes de configurar seu próprio ambiente, você pode usar nosso demo dataset pré-configurado na seção a seguir.

Pré-requisitos

Instância do ClickStack em execução
Instalação existente do PostgreSQL (versão 9.6 ou superior)
Acesso de rede do ClickStack ao PostgreSQL (porta padrão 5432)
Usuário de monitoramento do PostgreSQL com as permissões adequadas

Garanta que o usuário de monitoramento tenha as permissões necessárias

O receiver do PostgreSQL requer um usuário com acesso de leitura às visões de estatísticas. Conceda a role pg_monitor ao seu usuário de monitoramento:

GRANT pg_monitor TO your_monitoring_user;

Crie uma configuração personalizada do OTel collector

O ClickStack permite estender a configuração base do OpenTelemetry collector montando um arquivo de configuração personalizado e definindo uma variável de ambiente.

Crie postgres-metrics.yaml:

receivers:
  postgresql:
    endpoint: postgres-host:5432
    transport: tcp
    username: otel_monitor
    password: ${env:POSTGRES_PASSWORD}
    databases:
      - postgres
      - your_application_db # Substitua pelos nomes reais dos seus bancos de dados
    collection_interval: 30s
    tls:
      insecure: true

processors:
  resourcedetection:
    detectors: [env, system, docker]
    timeout: 5s
  batch:
    timeout: 10s
    send_batch_size: 10000

exporters:
  clickhouse:
    endpoint: tcp://localhost:9000
    database: default
    ttl: 96h

service:
  pipelines:
    metrics/postgres:
      receivers: [postgresql]
      processors: [resourcedetection, batch]
      exporters: [clickhouse]

Implante o ClickStack com configuração personalizada

Monte sua configuração personalizada:

docker run -d \
  --name clickstack-postgres \
  -p 8123:8123 -p 9000:9000 -p 4317:4317 -p 4318:4318 \
  -e HYPERDX_API_KEY=your-api-key \
  -e CLICKHOUSE_PASSWORD=your-clickhouse-password \
  -e POSTGRES_PASSWORD=secure_password_here \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/postgres-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  clickhouse/clickstack:latest

Verifique a coleta de métricas

Depois de configurar, faça login no HyperDX e verifique se as métricas estão chegando:

Acesse o Metrics Explorer
Procure métricas que comecem com postgresql. (por exemplo, postgresql.backends, postgresql.commits)
Você deverá ver pontos de dados das métricas aparecendo no intervalo de coleta configurado

Quando as métricas estiverem chegando, prossiga para a seção Dashboards e visualização para importar o dashboard pré-configurado.

Conjunto de dados de demonstração

Para usuários que desejam testar a integração de métricas do PostgreSQL antes de configurar seus sistemas de produção, fornecemos um conjunto de dados pré-gerado com padrões realistas de métricas do PostgreSQL.

Baixe o conjunto de dados de amostra de métricas

Baixe os arquivos de métricas pré-gerados (24 horas de métricas do PostgreSQL com padrões realistas):

# Baixar métricas gauge (conexões, tamanho do banco de dados)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-gauge.csv

# Baixar métricas de soma (commits, rollbacks, operações)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-sum.csv

O conjunto de dados inclui padrões realistas:

Pico matinal de conexões (08:00) - Pico de logins
Problema de desempenho de cache (11:00) - Pico de Blocks_read
Bug na aplicação (14:00-14:30) - A taxa de rollback sobe para 15%
Incidentes de deadlock (14:15, 16:30) - Deadlocks raros

Inicie o ClickStack

Inicie uma instância do ClickStack:

docker run -d --name clickstack-postgres-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

Aguarde aproximadamente 30 segundos para que o ClickStack seja totalmente iniciado.

Carregue as métricas no ClickStack

Carregue as métricas diretamente no ClickHouse:

# Carregar métricas gauge
cat postgres-metrics-gauge.csv | docker exec -i clickstack-postgres-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# Carregar métricas de soma
cat postgres-metrics-sum.csv | docker exec -i clickstack-postgres-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"

Verifique as métricas no HyperDX

Depois de carregadas, a maneira mais rápida de ver suas métricas é pelo dashboard pré-configurado.

Prossiga para a seção Dashboards e visualização para importar o dashboard e visualizar várias métricas do PostgreSQL de uma só vez.

Dashboards e visualização

Para ajudar você a começar a monitorar o PostgreSQL com o ClickStack, fornecemos visualizações essenciais para as métricas do PostgreSQL.

Baixe a configuração do dashboard

Baixe a configuração do dashboard.

Importe o dashboard pré-configurado

Abra o HyperDX e navegue até a seção Dashboards
Clique em Import Dashboard no canto superior direito, no menu de reticências

Envie o arquivo postgres-metrics-dashboard.json e clique em Finish Import

Visualize o dashboard

O dashboard será criado com todas as visualizações pré-configuradas:

Solução de problemas

Config personalizada não carrega

Verifique se a variável de ambiente está definida:

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Verifique se o arquivo de configuração personalizado está montado:

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml

Nenhuma métrica aparece no HyperDX

Verifique se o PostgreSQL está acessível:

docker exec <clickstack-container> psql -h postgres-host -U otel_monitor -d postgres -c "SELECT 1"

Verifique os logs do OTel collector:

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i postgres

Erros de autenticação

Verifique se a senha está definida corretamente:

docker exec <clickstack-container> printenv POSTGRES_PASSWORD

Teste as credenciais diretamente:

psql -h postgres-host -U otel_monitor -d postgres -c "SELECT version();"

Próximos passos

Configure alertas para limites críticos (limites de conexão, altas taxas de rollback, baixas taxas de acerto no cache)
Habilite o monitoramento no nível de consulta com a extensão pg_stat_statements
Monitore várias instâncias do PostgreSQL duplicando a configuração do receiver com endpoints e nomes de serviço diferentes

Em produção

Este guia aproveita o OpenTelemetry Collector integrado do ClickStack para uma configuração rápida. Para implantações em produção, recomendamos executar seu próprio OTel Collector e enviar os dados ao endpoint OTLP do ClickStack. Consulte Enviando dados do OpenTelemetry para a configuração de produção.