Monitoramento das métricas do PostgreSQL com o ClickStack

Monitoramento das métricas do PostgreSQL com o ClickStack

Em resumo

Monitore as métricas de desempenho do PostgreSQL no ClickStack usando o receiver PostgreSQL do OTel. Inclui um dataset de demonstração e um dashboard pré-configurado.

​

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

1. ​

   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;
   
2. ​

   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]
   

   A configuração tls: insecure: true desativa a verificação de SSL para desenvolvimento/testes. Para PostgreSQL de produção com SSL habilitado, remova essa linha ou configure os certificados adequados.

3. ​

   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
   
4. ​

   Verifique a coleta de métricas

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

   1. Acesse o Metrics Explorer
   2. Procure métricas que comecem com postgresql. (por exemplo, postgresql.backends, postgresql.commits)
   3. 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.

Somente métricas no nível do banco de dados

Este conjunto de dados de demonstração inclui somente métricas no nível do banco de dados para manter os dados de amostra leves. Métricas de tabela e índice são coletadas automaticamente ao monitorar um banco de dados PostgreSQL real.

1. ​

   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
2. ​

   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.

3. ​

   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"
   
4. ​

   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.

   Exibição do fuso horário

   O HyperDX exibe timestamps no fuso horário local do seu navegador. Os dados de demonstração cobrem 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC). Defina seu intervalo de tempo como 2025-11-09 00:00:00 - 2025-11-12 00:00:00 para garantir que você veja as métricas de demonstração independentemente da sua localização. Depois de ver as métricas, você pode restringir o intervalo para um período de 24 horas para visualizações mais claras.

​

Dashboards e visualizações

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

1. ​

   a configuração do dashboard

2. ​

   Importe o dashboard pré-configurado

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

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

   Visualize o dashboard

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

   Para o demo dataset, defina o intervalo de tempo como 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC) (ajuste conforme o seu timezone local). Por padrão, o dashboard importado não terá um intervalo de tempo definido.

​

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

​

Indo para produção

Este guia utiliza 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 para o endpoint OTLP do ClickStack. Consulte Enviando dados do OpenTelemetry para ver a configuração de produção.