Monitoramento de logs do PostgreSQL com ClickStack

Em resumoColete e visualize logs do servidor PostgreSQL (formato CSV) no ClickStack usando o receiver filelog do OTel. Inclui um dataset de demonstração e um dashboard pré-configurado.

Integração com um PostgreSQL existente

Esta seção aborda como configurar sua instalação existente do PostgreSQL para enviar logs ao ClickStack, modificando a configuração do OTel collector do ClickStack. Se quiser testar a integração de logs do PostgreSQL antes de configurar seu próprio ambiente, você pode usar nossa configuração pré-configurada e os dados de amostra na seção “Dataset de demonstração”.

Pré-requisitos

Instância do ClickStack em execução
Instalação existente do PostgreSQL (versão 9.6 ou superior)
Acesso para modificar os arquivos de configuração do PostgreSQL
Espaço em disco suficiente para os arquivos de log

Configure o logging do PostgreSQL

O PostgreSQL oferece suporte a vários formatos de log. Para o parsing estruturado com OpenTelemetry, recomendamos o formato CSV, que fornece uma saída consistente e fácil de analisar.O arquivo postgresql.conf normalmente fica em:

Linux (apt/yum): /etc/postgresql/{version}/main/postgresql.conf
macOS (Homebrew): /usr/local/var/postgres/postgresql.conf ou /opt/homebrew/var/postgres/postgresql.conf
Docker: a configuração geralmente é definida por variáveis de ambiente ou por um arquivo de configuração montado

Adicione ou modifique estas configurações em postgresql.conf:

# Necessário para logging em CSV
logging_collector = on
log_destination = 'csvlog'

# Recomendado: logging de conexão
log_connections = on
log_disconnections = on

# Opcional: ajuste conforme suas necessidades de monitoramento
#log_min_duration_statement = 1000  # Registra queries que levam mais de 1 segundo
#log_statement = 'ddl'               # Registra instruções DDL (CREATE, ALTER, DROP)
#log_checkpoints = on                # Registra atividade de checkpoint
#log_lock_waits = on                 # Registra contenção de lock

Este guia usa o formato csvlog do PostgreSQL para um processamento estruturado confiável. Se você estiver usando os formatos stderr ou jsonlog, precisará ajustar a configuração do coletor OpenTelemetry conforme necessário.

Após fazer essas alterações, reinicie o PostgreSQL:

# Para systemd
sudo systemctl restart postgresql

# Para Docker
docker restart 

Verifique se os logs estão sendo gravados:

# Localização padrão dos logs no Linux
tail -f /var/lib/postgresql/{version}/main/log/postgresql-*.log

# macOS Homebrew
tail -f /usr/local/var/postgres/log/postgresql-*.log

Crie uma configuração personalizada do OTel collector

O ClickStack permite estender a configuração padrão do OpenTelemetry Collector montando um arquivo de configuração personalizado e definindo uma variável de ambiente. A configuração personalizada é mesclada à configuração padrão gerenciada pelo HyperDX via OpAMP.Crie um arquivo chamado postgres-logs-monitoring.yaml com a configuração a seguir:

receivers:
  filelog/postgres:
    include:
      - /var/lib/postgresql/*/main/log/postgresql-*.csv # Ajuste conforme a sua instalação do PostgreSQL
    start_at: end
    multiline:
      line_start_pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'
    operators:
      - type: csv_parser
        parse_from: body
        parse_to: attributes
        header: 'log_time,user_name,database_name,process_id,connection_from,session_id,session_line_num,command_tag,session_start_time,virtual_transaction_id,transaction_id,error_severity,sql_state_code,message,detail,hint,internal_query,internal_query_pos,context,query,query_pos,location,application_name,backend_type,leader_pid,query_id'
        lazy_quotes: true
        
      - type: time_parser
        parse_from: attributes.log_time
        layout: '%Y-%m-%d %H:%M:%S.%L %Z'
      
      - type: add
        field: attributes.source
        value: "postgresql"
      
      - type: add
        field: resource["service.name"]
        value: "postgresql-production"

service:
  pipelines:
    logs/postgres:
      receivers: [filelog/postgres]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

Esta configuração:

Lê os logs CSV do PostgreSQL em seu local padrão
Processa entradas de log com várias linhas (os erros geralmente se estendem por várias linhas)
Analisa o formato CSV com todos os campos padrão de log do PostgreSQL
Extrai os timestamps para preservar o horário original dos logs
Adiciona o atributo source: postgresql para filtragem no HyperDX
Encaminha os logs para o exporter do ClickHouse por meio de um pipeline dedicado

Na configuração personalizada, você define apenas novos receivers e pipelines
Os processors (memory_limiter, transform, batch) e exporters (clickhouse) já estão definidos na configuração base do ClickStack - você só faz referência a eles pelo nome
O operator csv_parser extrai todos os campos padrão do log CSV do PostgreSQL como atributos estruturados
Esta configuração usa start_at: end para evitar reiniciar a ingestão dos logs quando o coletor é reiniciado. Para testes, altere para start_at: beginning para ver os logs históricos imediatamente.
Ajuste o caminho include para corresponder ao local do diretório de logs do PostgreSQL

Configure o ClickStack para carregar uma configuração personalizada

Para habilitar uma configuração personalizada do collector na implantação existente do ClickStack, você deve:

Montar o arquivo de configuração personalizado em /etc/otelcol-contrib/custom.config.yaml
Definir a variável de ambiente CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Montar o diretório de logs do PostgreSQL para que o collector possa lê-los

Opção 1: Docker Compose

Atualize a configuração da implantação do ClickStack:

services:
  clickstack:
    # ... configuração existente ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... outras variáveis de ambiente ...
    volumes:
      - ./postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/lib/postgresql:/var/lib/postgresql:ro
      # ... outros volumes ...

Opção 2: Docker Run (Imagem all-in-one)

Se você estiver usando a imagem all-in-one com docker run:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/lib/postgresql:/var/lib/postgresql:ro \
  clickhouse/clickstack-all-in-one:latest

Garanta que o collector do ClickStack tenha as permissões adequadas para ler os arquivos de log do PostgreSQL. Em produção, use montagens somente para leitura (:ro) e siga o princípio do menor privilégio.

Verificando logs no HyperDX

Depois de configurar, entre no HyperDX e verifique se os logs estão chegando:

Acesse a Search view
Defina source como Logs
Filtre por source:postgresql para ver logs específicos do PostgreSQL
Você deverá ver entradas de log estruturadas com campos como user_name, database_name, error_severity, message, query etc.

Dataset de demonstração

Para usuários que querem testar a integração de logs do PostgreSQL antes de configurar seus sistemas de produção, fornecemos um conjunto de dados de exemplo com logs do PostgreSQL pré-gerados e padrões realistas.

Baixe o conjunto de dados de exemplo

Baixe o arquivo de log de exemplo:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgresql.log

Crie a configuração do coletor de teste

Crie um arquivo chamado postgres-logs-demo.yaml com a configuração a seguir:

cat > postgres-logs-demo.yaml << 'EOF'
receivers:
  filelog/postgres:
    include:
      - /tmp/postgres-demo/postgresql.log
    start_at: beginning  # Ler desde o início para os dados de demonstração
    multiline:
      line_start_pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'
    operators:
      - type: csv_parser
        parse_from: body
        parse_to: attributes
        header: 'log_time,user_name,database_name,process_id,connection_from,session_id,session_line_num,command_tag,session_start_time,virtual_transaction_id,transaction_id,error_severity,sql_state_code,message,detail,hint,internal_query,internal_query_pos,context,query,query_pos,location,application_name,backend_type,leader_pid,query_id'
        lazy_quotes: true
        
      - type: time_parser
        parse_from: attributes.log_time
        layout: '%Y-%m-%d %H:%M:%S.%L %Z'
      
      - type: add
        field: attributes.source
        value: "postgresql-demo"
      
      - type: add
        field: resource["service.name"]
        value: "postgresql-demo"

service:
  pipelines:
    logs/postgres-demo:
      receivers: [filelog/postgres]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

Execute o ClickStack com a configuração de demonstração

Execute o ClickStack com os logs e a configuração de demonstração:

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/postgres-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/postgresql.log:/tmp/postgres-demo/postgresql.log:ro" \
  clickhouse/clickstack-all-in-one:latest

Verifique os logs no HyperDX

Quando o ClickStack estiver em execução:

Abra o HyperDX e faça login na sua conta (talvez seja necessário criar uma conta primeiro)
Navegue até a Search view e defina a source como Logs
Defina o intervalo de tempo como 2025-11-09 00:00:00 - 2025-11-12 00:00:00

Exibição de fuso horárioO HyperDX exibe os timestamps no fuso horário local do navegador. Os dados de demonstração cobrem 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC). O intervalo amplo garante que você verá os logs de demonstração independentemente da sua localização. Depois que os logs aparecerem, você pode restringir o intervalo para um período de 24 horas e obter 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 dos logs do PostgreSQL.

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

Faça upload do arquivo postgresql-logs-dashboard.json e clique em Finish Import

Visualize o dashboard

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

Para o dataset de demonstração, defina o intervalo de tempo como 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC) (ajuste com base no seu fuso horário local). Por padrão, o dashboard importado não terá um intervalo de tempo especificado.

Solução de problemas

Configuração personalizada não está sendo carregada

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 e acessível para leitura:

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

Logs não aparecem no HyperDX

Verifique se a configuração efetiva inclui o receiver filelog:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

Verifique se há erros nos logs do collector:

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

Se estiver usando o dataset de demonstração, verifique se o arquivo de log está acessível:

docker exec <container> cat /tmp/postgres-demo/postgresql.log | wc -l

Próximas etapas

Configure alertas para eventos críticos (falhas de conexão, consultas lentas, picos de erro)
Correlacione logs com métricas do PostgreSQL para um monitoramento completo do banco de dados
Crie dashboards personalizados para padrões de consulta específicos da aplicação
Configure log_min_duration_statement para identificar consultas lentas de acordo com seus requisitos de desempenho

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

Recursos

Guias

Monitoramento de logs do PostgreSQL com ClickStack

Integração com um PostgreSQL existente

Pré-requisitos

Configure o logging do PostgreSQL

Crie uma configuração personalizada do OTel collector

Configure o ClickStack para carregar uma configuração personalizada

Opção 1: Docker Compose

Opção 2: Docker Run (Imagem all-in-one)

Verificando logs no HyperDX

Dataset de demonstração

Baixe o conjunto de dados de exemplo

Crie a configuração do coletor de teste

Execute o ClickStack com a configuração de demonstração

Verifique os logs no HyperDX

Dashboards e visualizações

a configuração do dashboard

Importe o dashboard pré-configurado

Visualize o dashboard

Solução de problemas

Configuração personalizada não está sendo carregada

Logs não aparecem no HyperDX

Próximas etapas

Colocando em produção

​Integração com um PostgreSQL existente

Pré-requisitos

​Configure o logging do PostgreSQL

​Crie uma configuração personalizada do OTel collector

​Configure o ClickStack para carregar uma configuração personalizada

Opção 1: Docker Compose

Opção 2: Docker Run (Imagem all-in-one)

​Verificando logs no HyperDX

​Dataset de demonstração

​Baixe o conjunto de dados de exemplo

​Crie a configuração do coletor de teste

​Execute o ClickStack com a configuração de demonstração

​Verifique os logs no HyperDX

​Dashboards e visualizações

​ a configuração do dashboard

​Importe o dashboard pré-configurado

​Visualize o dashboard

​Solução de problemas

​Configuração personalizada não está sendo carregada

​Logs não aparecem no HyperDX

​Próximas etapas

​Colocando em produção

Integração com um PostgreSQL existente

Configure o logging do PostgreSQL

Crie uma configuração personalizada do OTel collector

Configure o ClickStack para carregar uma configuração personalizada

Verificando logs no HyperDX

Dataset de demonstração

Baixe o conjunto de dados de exemplo

Crie a configuração do coletor de teste

Execute o ClickStack com a configuração de demonstração

Verifique os logs no HyperDX

Dashboards e visualizações

a configuração do dashboard

Importe o dashboard pré-configurado

Visualize o dashboard

Solução de problemas

Configuração personalizada não está sendo carregada

Logs não aparecem no HyperDX

Próximas etapas

Colocando em produção