Prise en main : installer PWR étape par étape

Prérequis : extensions PostgreSQL

Connectez-vous à la base PostgreSQL à surveiller avec un compte superutilisateur (par exemple postgres), puis installez les extensions ci-dessous.

pg_stat_statements fournit les statistiques d'exécution des requêtes et pg_buffercache les indicateurs de cache et de mémoire utilisés dans les rapports.

pg_stat_statements doit être ajouté à shared_preload_libraries. Vous pouvez modifier postgresql.conf directement (alternative 1) ou exécuter ALTER SYSTEM en tant que superutilisateur (alternative 2). Attention : ALTER SYSTEM SET remplace la valeur existante ; si d'autres bibliothèques sont déjà préchargées, conservez-les dans la nouvelle valeur.

Si pg_stat_statements n'a encore jamais été activé sur cette instance, effectuez ensuite un redémarrage complet du service PostgreSQL. Une troisième extension, pg_cron, est optionnelle : elle ne sert que si vous voulez que la planification des snapshots soit gérée nativement par PostgreSQL (Linux uniquement).

shared_preload_libraries = 'pg_stat_statements'
# puis redémarrer le service PostgreSQL

ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements';

sudo systemctl restart postgresql

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE EXTENSION IF NOT EXISTS pg_buffercache;
-- optionnel, planification native (Linux) :
CREATE EXTENSION IF NOT EXISTS pg_cron;

Installation assistée (recommandée)

Pour garantir une installation rapide et sans erreur, nous proposons un call d'installation gratuit de 15 minutes pendant votre période d'essai.

Ce call permet de :

• vérifier la configuration PostgreSQL (extensions, shared_preload_libraries)
• valider les permissions de l'utilisateur pwr
• installer le schéma perfhist
• choisir le mode de connexion (Direct ou Agent)
• tester la capture du premier snapshot
• s'assurer que le collector communique correctement avec le SaaS

L'installation manuelle reste possible

Vous pouvez suivre les étapes ci-dessous si vous préférez une mise en place autonome.

Étape 1 — Créer l'utilisateur de monitoring

Nous recommandons de créer un utilisateur distinct sur votre base PostgreSQL pour le monitoring PWR.

Connectez-vous à la base à surveiller en tant que superutilisateur PostgreSQL, puis exécutez le code ci-dessous. Remplacez CHANGE_ME_STRONG_PASSWORD par un mot de passe fort de votre choix et change_me_db_name par le nom de la base à surveiller.

Ce code crée l'utilisateur de monitoring dédié pwr, puis lui accorde uniquement les droits nécessaires : pg_monitor pour lire les statistiques d'activité et de requêtes, et CONNECT/CREATE limités à la base cible afin d'installer le schéma perfhist. Cet utilisateur n'a aucun accès en lecture ou en écriture sur vos données applicatives.

CREATE ROLE pwr WITH LOGIN PASSWORD 'CHANGE_ME_STRONG_PASSWORD';
ALTER ROLE pwr WITH CREATEROLE CREATEDB;
GRANT CONNECT, CREATE ON DATABASE change_me_db_name TO pwr;
GRANT pg_monitor TO pwr;

Vérifier la connexion

Vérifiez que vous pouvez vous connecter à la base avec le nouvel utilisateur de monitoring :

• Conservez le nom d'utilisateur et le mot de passe de l'utilisateur pwr : ils seront utilisés lors de la dernière étape de ce guide.

PGPASSWORD=CHANGE_ME_STRONG_PASSWORD psql -h localhost -d change_me_db_name -U pwr

Étape 1 bis — Alternative : installer le schéma via un script interactif (Install_schema.zip)

Si vous préférez ne pas enchaîner les scripts SQL un par un, l'archive Install_schema.zip (téléchargeable ci-dessous) regroupe tout le nécessaire pour installer perfhist en une seule commande interactive. Après extraction, le dossier racine Install_schema/ contient deux dossiers frères : scripts/ pour les installateurs Linux/macOS et Windows, et Install_schema/ pour tous les scripts SQL.

Le fichier Install_schema/Install_schema/create_perfhist.sql est le script SQL principal : les installateurs Install_schema/scripts/install.sh et Install_schema/scripts/install.bat l'exécutent automatiquement après avoir demandé vos informations de connexion.

Prérequis : une base PostgreSQL accessible, le client psql installé et disponible dans le PATH, ainsi qu'un utilisateur disposant des droits suffisants pour créer le schéma, les tables, vues, fonctions, procédures et grants (l'utilisateur pwr créé à l'étape précédente convient).

Sous Linux/macOS, rendez le script exécutable puis lancez-le ; sous Windows, lancez simplement Install_schema\scripts\install.bat. Dans les deux cas, le script demande PGHOST (défaut 127.0.0.1), PGPORT (défaut 5432), PGDATABASE, PGUSER, et PGPASSWORD (optionnel si vous utilisez déjà .pgpass ou un mécanisme équivalent côté client).

Une fois le script terminé, vérifiez l'installation avec les commandes psql ci-dessous, et assurez-vous qu'un premier snapshot a bien été créé si le script en prévoit un.

Install_schema/
  scripts/
    install.bat                 # Windows
    install.sh                  # Linux / macOS
  Install_schema/
    create_perfhist.sql         # SCRIPT PRINCIPAL
    autres scripts *.sql

Linux / macOSCopier

chmod +x Install_schema/scripts/install.sh
./Install_schema/scripts/install.sh

Voici le résultat attendu lorsque l'installation du schéma perfhist se termine correctement :

Install_schema\scripts\install.bat

Vérification post-installationCopier

\dn+ perfhist
\dt perfhist.*
\dv perfhist.*

SELECT DISTINCT date_extract
FROM perfhist.pg_stat_statements_hist
ORDER BY 1 DESC;

Voici le résultat attendu après la vérification post-installation :

Étape 2 — Prendre un snapshot

Une fois l'installation terminée, l'utilisation courante ne nécessite plus aucun script d'installation : il suffit de prendre des snapshots et de générer des rapports.

Cette commande peut être exécutée manuellement ou automatisée (cron, pg_cron, Planificateur de tâches Windows, Ansible, CI/CD). Plus les snapshots sont fréquents, plus il est facile de rejouer un incident passé et d'en identifier la cause racine.

Copier

CALL perfhist.new_snapshot();

Voici le résultat attendu après la création du snapshot :

Capture automatique intégrée (fréquence + rétention, sans cron externe)

En mode Direct, il n'est plus nécessaire de mettre en place un cron externe pour automatiser vos snapshots : depuis l'onglet "Connexions", le bouton "Configurer la capture" permet de choisir une fréquence (en minutes) et une durée de rétention (en jours), puis d'activer la planification automatique en un clic.

Côté serveur, un planificateur interne à PWR vérifie toutes les 30 secondes les planifications arrivées à échéance, et traite chacune d'elles selon un flux strict : création d'un journal d'exécution ("running"), connexion à votre base, exécution de CALL perfhist.new_snapshot(), calcul du nombre maximal de snapshots à conserver, puis purge des plus anciens via CALL perfhist.purge_snapshot(max_snapshot). Le journal et la planification sont ensuite mis à jour (succès ou échec).

Le nombre de snapshots conservés (max_snapshot) est calculé ainsi : snapshots_par_jour = floor(1440 / fréquence_minutes), puis max_snapshot = rétention_jours × snapshots_par_jour (avec un minimum de 1). Par exemple, une fréquence de 15 minutes et une rétention de 7 jours conservent au maximum 672 snapshots.

En cas d'erreur pendant la capture ou la purge (base injoignable, timeout, etc.), l'exécution est retentée une fois après un court délai ; si l'échec persiste, le journal d'exécution est marqué "failed" avec le message d'erreur, et la planification reste active pour retenter automatiquement au cycle suivant plutôt que de s'arrêter silencieusement.

1. Claim anti-doublon (FOR UPDATE SKIP LOCKED) des planifications dues
2. Pour chaque planification claimée :
   - créer un journal d'exécution "running"
   - se connecter à la base cliente
   - CALL perfhist.new_snapshot();
   - max_snapshot = retention_days * floor(1440 / interval_minutes)  -- min 1
   - CALL perfhist.purge_snapshot(max_snapshot);
   - marquer le journal "success"
   - mettre à jour la planification (last_run_at, next_run_at, last_status)
3. En cas d'erreur : journal "failed" + error_message, planification mise à
   jour (last_status='failed', last_error, next_run_at recalculé pour le
   prochain essai)

Deux modes de connexion à votre base

Une fois l'utilisateur pwr et le schéma perfhist installés (étapes ci-dessus), PWR peut se connecter à votre base de deux façons.

Mode Direct : votre base est accessible depuis Internet (ou via un tunnel/VPN déjà en place). Aucune installation supplémentaire n'est nécessaire — renseignez simplement l'hôte, le port, le nom de la base et les identifiants de l'utilisateur pwr directement dans l'onglet "Connexions" de votre compte.

Mode Agent : votre base n'est pas exposée publiquement (cas le plus courant en entreprise). Le Collector s'installe sur une machine ayant accès à PostgreSQL et établit lui-même des connexions sortantes sécurisées vers PWR et Cloudflare. Son téléchargement et sa configuration personnalisée sont disponibles uniquement dans l'espace compte.

Mode Agent — Qu'est-ce que le Collector ?

Le Collector est un agent mono-tenant installé dans l'infrastructure du client, sur une machine capable de joindre la base PostgreSQL à superviser. Il agit comme passerelle locale sécurisée entre PostgreSQL et PWR : la base reste privée et n'est jamais exposée directement au SaaS.

Il charge sa configuration locale depuis config/.env, maintient la connexion à PostgreSQL, collecte les métriques et les snapshots, expose les routes de diagnostic et de rapport, puis transmet au SaaS les heartbeats et données nécessaires au suivi de l'instance.

Le Collector et cloudflared sont deux processus distincts installés comme services natifs. Le Collector dialogue avec PostgreSQL et PWR ; cloudflared publie uniquement l'API HTTP locale du Collector au travers d'un tunnel sortant chiffré.

• collecte des métriques live, snapshots et données de rapport PostgreSQL
• authentification dédiée avec le Collector Token PWR
• configuration locale et isolée par client dans config/.env
• heartbeats, remontée d'état et suivi de la dernière activité
• API locale protégée pour les diagnostics et opérations à la demande
• accès distant sans ouverture de port entrant grâce au tunnel Cloudflare

Mode Agent — Responsabilités du projet Collector et du backend PWR

Tout ce qui s'exécute sur la machine du client appartient au projet Collector. Ce dépôt porte le cycle de vie complet de l'agent et produit les artefacts distribués aux différents systèmes d'exploitation.

Le backend PWR reste un service de provisionnement et de contrôle. Il ne doit ni installer cloudflared, ni créer les services système, ni construire les exécutables : il fournit au Collector les secrets et informations personnalisés nécessaires, puis suit son installation et son activité.

• Projet Collector : installateur multiplateforme et installation automatique de cloudflared
• Projet Collector : services Windows, Linux systemd et macOS launchd
• Projet Collector : installation et démarrage du Collector comme service natif
• Projet Collector : écriture et protection de la configuration locale
• Projet Collector : tests de /health en local puis via l'URL Cloudflare
• Projet Collector : génération des exécutables, archives et paquets par plateforme
• Backend PWR : création du tunnel Cloudflare et génération du Tunnel Token
• Backend PWR : attribution de l'URL publique du Collector
• Backend PWR : API authentifiée de téléchargement de la configuration personnalisée
• Backend PWR : suivi de l'installation, des heartbeats, de l'état et de la dernière activité du Collector

Mode Agent — Comment circule une requête entre PWR et votre base

Le Collector se connecte localement à PostgreSQL pour capturer les snapshots et calculer les métriques. Il envoie ensuite ses heartbeats et snapshots au backend PWR via HTTPS, avec son token propre.

Pour les opérations à la demande, cloudflared maintient un tunnel nommé vers le serveur HTTP local du Collector. Ce tunnel utilise uniquement une connexion sortante depuis la machine cliente : aucun port du routeur ou du pare-feu n'est ouvert vers Internet.

Le sous-domaine Cloudflare et le Tunnel Token sont créés par PWR pour cette connexion. Le Collector Token PWR et le Tunnel Token Cloudflare sont deux secrets distincts.

PostgreSQL reste isolé : seul le Collector installé dans le réseau client s'y connecte. Le SaaS et Cloudflare n'obtiennent jamais les identifiants PostgreSQL depuis une route publique.

Mode Agent — Pré-requis côté base de données du client

Avant de démarrer l'agent, la base PostgreSQL du client doit avoir l'utilisateur pwr créé à l'étape 1, avec au minimum SELECT sur pg_stat_* (pour le live) et sur le schéma perfhist (pour tous les rapports), plus le droit d'exécuter ses fonctions/procédures — déjà couvert par pg_monitor et les GRANT ci-dessus.

L'extension pg_stat_statements doit être activée (CREATE EXTENSION IF NOT EXISTS pg_stat_statements;, nécessite shared_preload_libraries incluant pg_stat_statements + redémarrage) : elle est requise pour le live et pour les rapports (top requêtes).

Mode Agent — Pré-requis sur la machine qui héberge l'agent

Aucune installation de Python n'est nécessaire avec l'installeur autonome fourni par PWR.

La machine doit pouvoir joindre PostgreSQL sur son port (5432 par défaut), PWR en HTTPS (443) et Cloudflare en sortie. Aucun port entrant public n'est requis.

L'installation des services Collector et cloudflared nécessite des droits administrateur sous Windows, root/sudo sous Linux, ou les droits correspondants sous macOS.

Mode Agent — Parcours guidé dans votre espace compte

Dans Connexions, créez une connexion en mode Agent. La progression affiche alors une quatrième étape, Collector installé, et un bouton Continuer l'installation.

La page Mon collector provisionne le tunnel Cloudflare, affiche son URL et son état, puis propose uniquement dans votre espace authentifié l'artefact correspondant à votre système d'exploitation.

Téléchargez l'archive de l'installeur, le fichier .env personnalisé et collector-install.json. Ce dernier contient temporairement les paramètres PostgreSQL et ne doit jamais être partagé.

Mode Agent — Installation automatique

Décompressez l'archive et placez collector-install.json dans le même dossier que l'installeur. La page Mon collector affiche une commande personnalisée prête à copier.

Ouvrez PowerShell en administrateur sous Windows, ou un terminal avec les privilèges requis sous Linux/macOS, dans ce dossier, puis exécutez la commande affichée dans votre compte.

L'installeur récupère la configuration complète auprès du backend, écrit config/.env avec des permissions restreintes, installe cloudflared et le Collector comme services natifs, démarre les services et vérifie /health en local puis via le tunnel.

collector-install.json est supprimé automatiquement après lecture par l'installeur.

.\collector-installer.exe install --api-base "<URL PWR>" --install-id "<ID>" --install-token "<TOKEN>" --params-file ".\collector-install.json"

Mode Agent — Démonstration Windows : du dossier au service natif

Une fois l'archive décompressée, le dossier contient collector.exe, collector-installer.exe, .env et config. Lancée dans ce dossier, la commande personnalisée affiche en direct chaque étape : récupération de la configuration, déploiement du binaire, écriture de config/.env, vérification/installation de cloudflared, puis installation du service Collector.

L'installeur détecte automatiquement le système d'exploitation de la machine au moment de l'exécution, sans aucun choix manuel à faire : sous Windows, il installe le Collector et cloudflared comme deux services Windows natifs (via NSSM, téléchargé et vérifié automatiquement au besoin) ; sous Linux, comme unités systemd ; sous macOS, comme agents launchd. La commande à lancer est la même, seul l'artefact téléchargé change selon l'OS choisi dans votre espace compte.

Une fois l'installation terminée, Collector et Cloudflared agent apparaissent dans les services Windows (services.msc), tous deux à l'état En cours avec un type de démarrage Automatique : ils redémarrent seuls avec la machine, sans intervention manuelle après un redémarrage ou une coupure.

Mode Agent — Démonstration Linux : du dossier au service natif

Sous Linux, rendez le binaire téléchargé exécutable puis lancez la commande personnalisée avec sudo : l'installeur doit tourner en tant que root pour écrire les unités systemd de Collector et de cloudflared. La commande affiche en direct chaque étape : récupération de la configuration, déploiement du binaire, écriture de config/.env, vérification/installation de cloudflared, installation des services, puis vérification de /health en local et via le tunnel.

L'installeur détecte automatiquement le système d'exploitation de la machine au moment de l'exécution, sans aucun choix manuel à faire : sous Linux, Collector et cloudflared sont installés comme deux unités systemd indépendantes (/etc/systemd/system/collector.service et cloudflared.service) ; sous Windows, comme deux services natifs ; sous macOS, comme agents launchd.

Une fois l'installation terminée, systemctl list-unit-files confirme que collector.service et cloudflared.service sont tous deux enabled : ils démarrent automatiquement avec la machine, sans intervention manuelle après un redémarrage ou une coupure.

chmod +x collector-installer

Mode Agent — Suivi de l'installation

Pendant l'installation, l'installeur remonte son état au backend : installation en cours, installée ou en échec avec le message associé.

Une fois le Collector démarré, ses heartbeats mettent à jour Collector connecté et la dernière activité dans votre espace compte. La progression de la page Connexions passe alors à 100 %.

En cas d'échec, vérifiez d'abord la connectivité PostgreSQL depuis la machine du Collector, puis relancez la commande personnalisée après correction.

Test-NetConnection -ComputerName <db_host> -Port 5432