Monitorización de métricas de PostgreSQL con ClickStack

Monitorización de métricas de PostgreSQL con ClickStack

Resumen

Supervisa las métricas de rendimiento de PostgreSQL en ClickStack con el PostgreSQL receiver de OTel. Incluye un conjunto de datos de demostración y un dashboard preconfigurado.

​

Integración con PostgreSQL existente

En esta sección se explica cómo configurar su instalación existente de PostgreSQL para enviar métricas a ClickStack mediante la configuración del ClickStack OTel collector con el PostgreSQL receiver.

Si desea probar la integración de métricas de PostgreSQL antes de configurar su propia instalación, puede hacerlo con nuestro demo dataset preconfigurado en la siguiente sección.

Requisitos previos

• Instancia de ClickStack en ejecución
• Instalación existente de PostgreSQL (versión 9.6 o posterior)
• Acceso de red desde ClickStack a PostgreSQL (puerto predeterminado: 5432)
• Usuario de monitorización de PostgreSQL con los permisos adecuados

1. ​

   Asegúrese de que el usuario de monitorización tenga los permisos necesarios

   El PostgreSQL receiver requiere un usuario con acceso de lectura a las vistas de estadísticas. Otorgue el rol pg_monitor a su usuario de monitorización:

   GRANT pg_monitor TO your_monitoring_user;
   
2. ​

   Cree una configuración personalizada del OpenTelemetry Collector

   ClickStack le permite ampliar la configuración base del OpenTelemetry Collector montando un archivo de configuración personalizado y estableciendo una variable de entorno.

   Cree postgres-metrics.yaml:

   receivers:
     postgresql:
       endpoint: postgres-host:5432
       transport: tcp
       username: otel_monitor
       password: ${env:POSTGRES_PASSWORD}
       databases:
         - postgres
         - your_application_db # Reemplace por los nombres reales de sus bases de datos
       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]
   

   La configuración tls: insecure: true desactiva la verificación de SSL para entornos de desarrollo o pruebas. En PostgreSQL de producción con SSL habilitado, elimine esta línea o configure los certificados adecuados.

3. ​

   Despliegue ClickStack con una configuración personalizada

   Monte su configuración 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 la recopilación de métricas

   Una vez configurado, inicie sesión en HyperDX y verifique que las métricas se estén recibiendo:

   1. Vaya a Metrics Explorer
   2. Busque métricas que empiecen por postgresql (por ejemplo, postgresql.backends, postgresql.commits)
   3. Debería ver puntos de datos de métricas en el intervalo de recopilación configurado

   Una vez que las métricas se estén recibiendo, continúe con la sección Dashboards y visualización para importar el dashboard preconfigurado.

​

Conjunto de datos de demostración

Para los usuarios que quieran probar la integración de métricas de PostgreSQL antes de configurar sus sistemas en producción, proporcionamos un conjunto de datos pregenerado con patrones realistas de métricas de PostgreSQL.

Solo métricas a nivel de base de datos

Este conjunto de datos de demostración incluye únicamente métricas a nivel de base de datos para mantener la muestra de datos ligera. Las métricas de tablas e índices se recopilan automáticamente al supervisar una base de datos PostgreSQL real.

1. ​

   Descargar el conjunto de datos de muestra de métricas

   Descargue los archivos de métricas pregenerados (24 horas de métricas de PostgreSQL con patrones realistas):

   # Descargar métricas gauge (conexiones, tamaño de la base de datos)
   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-gauge.csv
   
   # Descargar métricas sum (commits, rollbacks, operaciones)
   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-sum.csv
   

   El conjunto de datos incluye patrones realistas:

   • Pico matutino de conexiones (08:00) - Hora punta de inicios de sesión
   • Problema de rendimiento de la caché (11:00) - Pico de Blocks_read
   • Error de la aplicación (14:00-14:30) - La tasa de rollback alcanza picos del 15 %
   • Incidentes de deadlock (14:15, 16:30) - Deadlocks poco frecuentes
2. ​

   Iniciar ClickStack

   Inicie una instancia de ClickStack:

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

   Espere aproximadamente 30 segundos hasta que ClickStack se inicie por completo.

3. ​

   Cargar métricas en ClickStack

   Cargue las métricas directamente en ClickHouse:

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

   Verificar métricas en HyperDX

   Una vez cargadas, la forma más rápida de ver sus métricas es mediante el dashboard preconfigurado.

   Continúe en la sección Dashboards y visualización para importar el dashboard y ver varias métricas de PostgreSQL a la vez.

   Visualización de la zona horaria

   HyperDX muestra los timestamps en la zona horaria local de su navegador. Los datos de demostración abarcan 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC). Establezca el intervalo de tiempo en 2025-11-09 00:00:00 - 2025-11-12 00:00:00 para asegurarse de ver las métricas de demostración independientemente de su ubicación. Una vez que vea las métricas, puede reducir el intervalo a un período de 24 horas para obtener visualizaciones más claras.

​

Dashboards y visualización

Para ayudarte a empezar a monitorear PostgreSQL con ClickStack, proporcionamos visualizaciones esenciales de las métricas de PostgreSQL.

1. ​

   la configuración del dashboard

2. ​

   Importa el dashboard preconfigurado

   1. Abre HyperDX y ve a la sección Dashboards
   2. Haz clic en Import Dashboard en la esquina superior derecha, en el menú de los tres puntos

   3. Sube el archivo postgres-metrics-dashboard.json y haz clic en Finish Import
3. ​

   Ver el dashboard

   El dashboard se creará con todas las visualizaciones preconfiguradas:

   Para el demo dataset, establece el intervalo de tiempo en 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC) (ajústalo según tu zona horaria local). El dashboard importado no tendrá ningún intervalo de tiempo especificado de forma predeterminada.

​

Solución de problemas

​

La configuración personalizada no se carga

Verifique 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:

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

​

No se muestran métricas en HyperDX

Verifica que PostgreSQL sea accesible:

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

Revise los logs del OTel collector:

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

​

Errores de autenticación

Verifique que la contraseña esté configurada correctamente:

docker exec <clickstack-container> printenv POSTGRES_PASSWORD

Probar las credenciales directamente:

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

​

Siguientes pasos

• Configura alertas para umbrales críticos (límites de conexión, tasas elevadas de rollback y tasas bajas de aciertos de caché)
• Habilita la monitorización a nivel de consulta con la extensión pg_stat_statements
• Supervisa varias instancias de PostgreSQL duplicando la configuración del receiver con distintos endpoints y nombres de servicio

​

Paso 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 de OTLP de ClickStack. Consulte Envío de datos de OpenTelemetry para la configuración de producción.