Monitorización de métricas de PostgreSQL con ClickStack

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

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;

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]

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

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:

Vaya a Metrics Explorer
Busque métricas que empiecen por postgresql (por ejemplo, postgresql.backends, postgresql.commits)
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.

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

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.

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"

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.

Dashboards y visualización

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

Descargar la configuración del dashboard

Descargar el archivo de configuración del dashboard.

Importa el dashboard preconfigurado

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

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

Cuadro de diálogo para finalizar la importación

Ver el dashboard

El dashboard se creará con todas las visualizaciones preconfiguradas:

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

Pasar a producción

Esta guía se basa en el OpenTelemetry Collector integrado de ClickStack para facilitar una configuración rápida. Para implementaciones de producción, recomendamos ejecutar su propio OTel Collector y enviar los datos al endpoint OTLP de ClickStack. Consulte Enviar datos de OpenTelemetry para obtener una configuración de producción.