Monitorización de logs de PostgreSQL con ClickStack

Integración con PostgreSQL existente

Esta sección explica cómo configurar su instalación actual de PostgreSQL para enviar logs a ClickStack modificando la configuración del OTel collector de ClickStack.

Si desea probar la integración de logs de PostgreSQL antes de configurar su propio entorno, puede hacerlo con nuestra configuración predefinida y datos de muestra en la sección "Conjunto de datos de demostración".

Requisitos previos

Instancia de ClickStack en ejecución
Una instalación existente de PostgreSQL (versión 9.6 o posterior)
Acceso para modificar los archivos de configuración de PostgreSQL
Espacio suficiente en disco para los archivos de registro

Configurar el registro de PostgreSQL

PostgreSQL admite varios formatos de registro. Para el análisis estructurado con OpenTelemetry, recomendamos el formato CSV, que proporciona una salida uniforme y fácil de procesar.

El archivo postgresql.conf normalmente se encuentra en:

Linux (apt/yum): /etc/postgresql/{version}/main/postgresql.conf
macOS (Homebrew): /usr/local/var/postgres/postgresql.conf o /opt/homebrew/var/postgres/postgresql.conf
Docker: La configuración suele establecerse mediante variables de entorno o un archivo de configuración montado

Agregue o modifique esta configuración en postgresql.conf:

# Required for CSV logging
logging_collector = on
log_destination = 'csvlog'

# Recommended: Connection logging
log_connections = on
log_disconnections = on

# Optional: Tune based on your monitoring needs
#log_min_duration_statement = 1000  # Log queries taking more than 1 second
#log_statement = 'ddl'               # Log DDL statements (CREATE, ALTER, DROP)
#log_checkpoints = on                # Log checkpoint activity
#log_lock_waits = on                 # Log lock contention

Después de realizar estos cambios, reinicia PostgreSQL:

# For systemd
sudo systemctl restart postgresql

# For Docker
docker restart

Verifique que se estén escribiendo los logs:

# Default log location on Linux
tail -f /var/lib/postgresql/{version}/main/log/postgresql-*.log

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

Crear una configuración personalizada del OTel collector

ClickStack permite ampliar la configuración base de OpenTelemetry Collector montando un archivo de configuración personalizado y estableciendo una variable de entorno. La configuración personalizada se fusiona con la configuración base administrada por HyperDX mediante OpAMP.

Cree un archivo llamado postgres-logs-monitoring.yaml con la siguiente configuración:

receivers:
  filelog/postgres:
    include:
      - /var/lib/postgresql/*/main/log/postgresql-*.csv # Adjust to match your PostgreSQL installation
    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 configuración:

Lee los logs CSV de PostgreSQL desde su ubicación predeterminada
Gestiona entradas de log multilínea (los errores suelen abarcar varias líneas)
Analiza el formato CSV con todos los campos estándar del log de PostgreSQL
Extrae las marcas de tiempo para conservar la hora original de los logs
Añade el atributo source: postgresql para filtrar en HyperDX
Envía los logs al exporter de ClickHouse mediante un pipeline dedicado

Configurar ClickStack para cargar una configuración personalizada

Para habilitar una configuración personalizada del collector en su despliegue actual de ClickStack, debe:

Montar el archivo de configuración personalizado en /etc/otelcol-contrib/custom.config.yaml
Establecer la variable de entorno CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Montar el directorio de logs de PostgreSQL para que el collector pueda leerlos

Opción 1: Docker Compose

Actualice la configuración del despliegue de ClickStack:

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/lib/postgresql:/var/lib/postgresql:ro
      # ... other volumes ...

Opción 2: Docker Run (imagen todo en uno)

Si usas la imagen todo en uno con 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

Verificación de logs en HyperDX

Una vez configurado, inicie sesión en HyperDX y compruebe que los logs estén fluyendo:

Vaya a la vista de búsqueda
Configure source como Logs
Filtre por source:postgresql para ver los logs específicos de PostgreSQL
Debería ver entradas de log estructuradas con campos como user_name, database_name, error_severity, message, query, etc.

Conjunto de datos de demostración

Para los usuarios que quieran probar la integración de logs de PostgreSQL antes de configurar sus sistemas de producción, proporcionamos un conjunto de datos de ejemplo con logs de PostgreSQL pregenerados y patrones realistas.

Descarga el conjunto de datos de ejemplo

Descarga el archivo de log de ejemplo:

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

Crea una configuración de collector de prueba

Crea un archivo llamado postgres-logs-demo.yaml con la siguiente configuración:

cat > postgres-logs-demo.yaml << 'EOF'
receivers:
  filelog/postgres:
    include:
      - /tmp/postgres-demo/postgresql.log
    start_at: beginning  # Leer desde el inicio para los datos de demostración
    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

Ejecuta ClickStack con la configuración de demostración

Ejecuta ClickStack con los logs de demostración y esta configuración:

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

Verifica los logs en HyperDX

Una vez que ClickStack esté en ejecución:

Abre HyperDX e inicia sesión en tu cuenta (puede que primero tengas que crear una cuenta)
Ve a la Search view y establece Logs como source
Configura el intervalo de tiempo en 2025-11-09 00:00:00 - 2025-11-12 00:00:00

Dashboards y visualización

Para ayudarte a empezar a monitorizar PostgreSQL con ClickStack, ofrecemos visualizaciones esenciales para los logs de PostgreSQL.

Descargar la configuración del dashboard

Descargar el archivo de configuración del dashboard.

Importar el dashboard preconfigurado

Abre HyperDX y ve a la sección Dashboards
Haz clic en Import Dashboard en la esquina superior derecha, dentro del menú de puntos suspensivos

Sube el archivo postgresql-logs-dashboard.json y haz clic en Finish Import

Ver el dashboard

El dashboard se creará con todas las visualizaciones preconfiguradas:

Solución de problemas

La configuración personalizada no se carga

Verifica que la variable de entorno esté configurada:

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Comprueba que el archivo de configuración personalizado esté montado y sea legible:

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

No aparecen logs en HyperDX

Comprueba que la configuración efectiva incluya tu receiver filelog:

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

Revise si hay errores en los logs del collector:

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

Si utiliza el conjunto de datos de demostración, verifique que se pueda acceder al archivo de registro:

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

Próximos pasos

Configure alertas para eventos críticos (fallos de conexión, consultas lentas, picos de errores)
Correlacione los logs con las métricas de PostgreSQL para supervisar la base de datos de forma integral
Cree dashboards personalizados para patrones de consultas específicos de la aplicación
Configure log_min_duration_statement para identificar consultas lentas según sus requisitos de rendimiento

Llevar a producción

Esta guía amplía el OpenTelemetry Collector integrado de ClickStack para ofrecer una configuración rápida. Para implementaciones en producción, recomendamos ejecutar su propio OTel Collector y enviar los datos al endpoint OTLP de ClickStack. Consulte Envío de datos de OpenTelemetry para la configuración de producción.