Supervision des métriques PostgreSQL avec ClickStack

Intégration avec une instance PostgreSQL existante

Cette section explique comment configurer votre instance PostgreSQL existante pour envoyer des métriques à ClickStack en configurant le ClickStack OTel collector avec le PostgreSQL receiver.

Si vous souhaitez tester l’intégration des métriques PostgreSQL avant de configurer votre propre environnement, vous pouvez utiliser notre jeu de données de démonstration préconfiguré dans la section suivante.

Prérequis

Instance ClickStack opérationnelle
Installation PostgreSQL existante (version 9.6 ou ultérieure)
Accès réseau de ClickStack à PostgreSQL (port par défaut : 5432)
Utilisateur de monitoring PostgreSQL disposant des autorisations appropriées

Assurez-vous que l’utilisateur de monitoring dispose des autorisations requises

Le PostgreSQL receiver nécessite un utilisateur ayant un accès en lecture aux vues de statistiques. Accordez le rôle pg_monitor à votre utilisateur de monitoring :

GRANT pg_monitor TO your_monitoring_user;

Créez une configuration personnalisée pour l’OTel collector

ClickStack vous permet d’étendre la configuration de base de l’OpenTelemetry Collector en montant un fichier de configuration personnalisé et en définissant une variable d’environnement.

Créez postgres-metrics.yaml :

receivers:
  postgresql:
    endpoint: postgres-host:5432
    transport: tcp
    username: otel_monitor
    password: ${env:POSTGRES_PASSWORD}
    databases:
      - postgres
      - your_application_db # Remplacez par les noms réels de vos bases de données
    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]

Déployez ClickStack avec une configuration personnalisée

Montez votre configuration personnalisée :

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

Vérifiez la collecte des métriques

Une fois la configuration en place, connectez-vous à HyperDX et vérifiez que les métriques remontent correctement :

Accédez à Metrics Explorer
Recherchez les métriques commençant par postgresql (par ex. : postgresql.backends, postgresql.commits)
Vous devriez voir apparaître des points de données à l’intervalle de collecte configuré

Une fois les métriques disponibles, passez à la section Tableaux de bord et visualisation pour importer le tableau de bord préconfiguré.

Jeu de données de démonstration

Pour les utilisateurs qui souhaitent tester l’intégration des métriques PostgreSQL avant de configurer leurs systèmes de production, nous fournissons un jeu de données pré-généré avec des schémas réalistes de métriques PostgreSQL.

Télécharger l’échantillon de métriques

Téléchargez les fichiers de métriques pré-générés (24 heures de métriques PostgreSQL avec des schémas réalistes) :

# Télécharger les métriques gauge (connexions, taille de la base de données)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-gauge.csv

# Télécharger les métriques de somme (commits, rollbacks, opérations)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-sum.csv

Le jeu de données inclut des schémas réalistes :

Pic de connexions le matin (08:00) - Afflux de connexions
Problème de performances du cache (11:00) - Pic de Blocks_read
Bug applicatif (14:00-14:30) - Le taux de rollback grimpe à 15 %
Incidents de deadlock (14:15, 16:30) - Deadlocks rares

Démarrer ClickStack

Démarrez une instance ClickStack :

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

Attendez environ 30 secondes pour que ClickStack démarre complètement.

Charger les métriques dans ClickStack

Chargez les métriques directement dans ClickHouse :

# Charger les métriques gauge
cat postgres-metrics-gauge.csv | docker exec -i clickstack-postgres-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# Charger les métriques de somme
cat postgres-metrics-sum.csv | docker exec -i clickstack-postgres-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"

Vérifier les métriques dans HyperDX

Une fois chargées, le moyen le plus rapide de voir vos métriques est d’utiliser le tableau de bord préconfiguré.

Passez à la section Tableaux de bord et visualisation pour importer le tableau de bord et afficher de nombreuses métriques PostgreSQL à la fois.

Tableaux de bord et visualisation

Pour vous aider à démarrer la surveillance de PostgreSQL avec ClickStack, nous fournissons les visualisations essentielles des métriques PostgreSQL.

Télécharger la configuration du tableau de bord

Télécharger le fichier de configuration du tableau de bord.

Importer le tableau de bord préconfiguré

Ouvrez HyperDX et accédez à la section Dashboards
Cliquez sur Import Dashboard dans le coin supérieur droit, sous les points de suspension

Téléversez le fichier postgres-metrics-dashboard.json, puis cliquez sur Finish Import

Boîte de dialogue de finalisation de l’importation

Afficher le tableau de bord

Le tableau de bord sera créé avec toutes les visualisations déjà configurées :

Tableau de bord des métriques PostgreSQL

Dépannage

La config personnalisée ne se charge pas

Vérifiez que la variable d'environnement est définie :

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Vérifiez que le fichier de configuration personnalisé est monté :

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

Aucune métrique n’apparaît dans HyperDX

Vérifiez que PostgreSQL est accessible :

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

Consultez les logs de l’OTel collector :

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

Erreurs d’authentification

Vérifiez que le mot de passe est correctement configuré :

docker exec <clickstack-container> printenv POSTGRES_PASSWORD

Testez directement les identifiants :

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

Étapes suivantes

Configurez des alertes pour les seuils critiques (limites de connexion, taux élevés de rollback, faibles taux de réussite du cache)
Activez la surveillance des requêtes avec l’extension pg_stat_statements
Surveillez plusieurs instances PostgreSQL en dupliquant la configuration du receiver avec différents endpoints et noms de service

Passage en production

Ce guide s’appuie sur l’OpenTelemetry Collector intégré de ClickStack pour une configuration rapide. Pour les déploiements en production, nous vous recommandons d’exécuter votre propre OTel Collector et d’envoyer les données vers l’endpoint OTLP de ClickStack. Consultez Envoi de données OpenTelemetry pour la configuration de production.