Analyse Causale ClickHouse Managed Postgres

Quand l'utiliser

Déclenchez cette analyse chaque fois qu'un utilisateur signale une lenteur, un CPU élevé, un débit faible, une saturation du cache ou tout problème inexpliqué sur une instance Postgres gérée par ClickHouse.

Accès disponible

Deux APIs sur https://api.clickhouse.cloud (authentification HTTP Basic avec une paire clé/secret ClickHouse Cloud API) :

• Métriques Prometheus — opération postgresInstancePrometheusGet sous le tag Prometheus. Retourne le format exposition Prometheus. Métriques système et charge de travail pour un service Postgres.
• Patterns de Requêtes Lentes — opération slowQueryPatternsGetList sous le tag Postgres. Retourne les statistiques de latence, d'IO et d'appels par digest de pattern de requête normalisé. Bêta.

Les deux endpoints nécessitent un organizationId et un serviceId en paramètres de chemin. L'utilisateur doit fournir les deux, plus la paire clé/secret de l'API.

Ce que vous n'avez PAS

• Plans de requête / sortie EXPLAIN.
• Compteurs de type de scan par table (seq_scan / idx_scan).
• Timestamps d'autovacuum ou de dernière ANALYZE.

Raisonnez à partir de signaux d'IO et de timing, pas d'un arbre de plan.

Flux de travail

Six étapes, dans l'ordre. Ne passez pas directement à une étape ultérieure.

Les étapes 2 et 3 partagent uniquement l'authentification — pas de dépendance de données entre elles. Lancez-les en parallèle (curls en arrière-plan, & + wait) pour réduire le temps d'exécution d'environ ~2s à ~1s en séquentiel.

1. Découvrir la forme d'API en direct

Ces endpoints sont en Bêta — les chemins, paramètres et noms de champs JSON peuvent changer. Suivez rules/openapi-discovery.md pour :

1. Récupérer la spéc OpenAPI depuis https://api.clickhouse.cloud/v1.
2. Localiser les deux opérations par operationId :
   • postgresInstancePrometheusGet (tag Prometheus)
   • slowQueryPatternsGetList (tag Postgres)
3. Résoudre leurs templates de chemin, paramètres de requête obligatoires et (pour l'endpoint de requête lente) le schéma de réponse.
4. Construire une map de rôle à portée de session à partir des descriptions de propriétés du schéma : { rôle sémantique → nom de champ réel }.

Utilisez les noms résolus dans chaque demande et citation ultérieures. Ne codifiez jamais en dur les noms de champs de mémoire.

2. Scraper Prom une fois pour les gauges système

Suivez rules/prometheus-scrape.md. Un scrape, pas d'attente. Vous cherchez des gauges (valeurs courantes) qui n'ont pas besoin de delta : CacheHitRatio, ActiveConnections, MemoryUsedPercent, FilesystemUsedPercent.

Un CacheHitRatio bien en dessous de ~95% sur une charge de travail qui devrait tenir en cache est un signal en soi. Une ActiveConnections grimpant vers le plafond du pool est un signal en soi. Ces valeurs n'ont pas besoin de taux de changement.

Un deuxième scrape pour les deltas de compteurs est facultatif, utilisé uniquement quand le triage de l'étape 4 pointe vers une congestion d'écriture (où les taux de deadlock et de rollback comptent et l'API Slow Query Patterns ne peut pas les remplacer). Pour le cas du chemin de lecture (la forme d'RCA la plus courante), le scrape unique suffit.

3. Récupérer les top patterns de requêtes lentes

Demandez les patterns de requêtes lentes. Suivez rules/slow-query-patterns-fields.md pour les champs qui comptent et comment les lire. C'est le diagnostic principal — il retourne les totaux cumulés par pattern (nombre d'appels, durée, blocs, lignes) sur la fenêtre que vous demandez, c'est-à-dire les données de « taux de changement » que vous dériveriez autrement de deux scrapes Prom — mais par requête et sans attente.

Si aucun pattern ne retourne un totalDurationUs significatif, le rapport peut être exagéré ou le problème n'a pas la forme d'une requête. Arrêtez et dites à l'utilisateur ce que vous avez examiné.

4. Triage : choisir la bonne heuristique

Suivez rules/triage.md. Correspondez le signal Prom + requête lente combiné à l'une des formes heuristiques. Chaque forme pointe vers un fichier heuristique spécifique :

• rules/heuristic-full-scan.md — full scan sur le chemin de lecture.
• rules/heuristic-hot-loop.md — N+1 / hot loop depuis l'app.
• rules/heuristic-write-congestion.md — deadlocks, écritures lentes, taux de rollback élevé.

Si le signal ne correspond pas clairement à une forme, n'inventez pas d'hypothèse. Présentez les top patterns et demandez à l'utilisateur quelle charge de travail il reconnaît. Les nouvelles heuristiques sont bienvenues en tant que PRs.

5. Raisonner, puis recommander

Utilisez le format dans rules/output-template.md. Toujours inclure : symptôme, preuves, hypothèse (en notant toute cause alternative que vous ne pouvez pas écarter de cette surface seule), correctif court terme et suivis long terme.

6. Ne pas appliquer le correctif

Suivez rules/recommend-only.md. Ne jamais exécuter de DDL. Ne jamais appeler pg_cancel_backend ou pg_terminate_backend. Écrivez la recommandation, expliquez pourquoi, et laissez l'humain l'appliquer.

Document Compilé Complet

Pour le guide complet avec chaque règle développée en un seul chargement de contexte : AGENTS.md.