Piyush-Nagar/coding-agents-skills

On ne peut pas réparer ce que l'on ne voit pas. L'observabilité est conçue dès le départ, pas ajoutée après un incident. Si une question sur la production nécessite une modification de code pour être répondue, l'instrumentation est erronée.

Qu'est-ce que coding-agents-skills ?

Cette compétence établit les principes fondamentaux pour concevoir des systèmes véritablement observables. Elle part du principe qu'il est impossible de résoudre un problème qu'on ne voit pas. Au lieu d'ajouter des outils après un incident, elle intègre l'observabilité dès la conception. La compétence couvre les trois piliers – logs, métriques et traces – en expliquant comment chacun répond à une question différente. Elle détaille les règles concrètes : logs structurés en JSON, ID de corrélation dans chaque ligne, métriques RED (taux, erreurs, durée) pour chaque point de terminaison, métriques USE (utilisation, saturation, erreurs) pour chaque ressource, et traçage de chaque appel interservice avec OpenTelemetry. Des pratiques avancées sont incluses comme les alertes basées sur les SLOs (et non sur des métriques brutes), la distinction entre les endpoints /health et /ready, et l'interdiction de journaliser des PII ou des secrets. La compétence liste également des signaux d'alarme à éviter, comme le débogage via SSH sur un pod, les alertes ignorées par habitude, les logs sans contexte, les métriques sans percentiles, et les tableaux de bord par service sans aucune vue par parcours utilisateur.

Compatible avec~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/Piyush-Nagar/coding-agents-skills/tree/HEAD/backend/core/nfr/observability

Documentation

Observabilité

Règles

Trois piliers : logs, métriques, traces. Chacun répond à une question différente — ce qui s'est passé (logs), combien et à quelle fréquence (métriques), pourquoi c'était lent (traces). Vous avez besoin des trois.
Logs structurés uniquement. JSON (ou similaire). Grep n'est pas une stratégie à grande échelle.
ID de corrélation / trace dans chaque ligne de log. Propagez-le via les en-têtes à travers les limites de service. Un seul ID relie l'ensemble du parcours d'une requête.
Métriques RED sur chaque point de terminaison. Taux, Erreurs, Durée (avec P50/P95/P99). Le minimum nécessaire pour repérer les régressions.
Métriques USE sur chaque ressource. Utilisation, Saturation, Erreurs — pour le CPU, la mémoire, les pools, les files d'attente, le disque, le réseau.
Tracez chaque appel interservice. Utilisez OpenTelemetry. Capturez également les requêtes DB et les accès au cache en tant que spans.
Alertez sur les SLOs, pas sur les métriques brutes. « CPU > 80% » réveille des humains à 3h du matin pour rien. « La latence P99 dépasse le SLO pendant 5 minutes » capte la vraie douleur utilisateur.
Les endpoints de santé et de disponibilité sont différents. /health = « Je suis vivant, ne me redémarre pas. » /ready = « Je peux recevoir du trafic maintenant. » Traitez-les comme tels.
Loggez au bon niveau, loggez une fois par événement. INFO pour le cycle de vie des requêtes, WARN pour les problèmes récupérables, ERROR pour ce qui nécessite une intervention humaine. Les logs dupliqués font mentir les tableaux de bord.
Ne loggez jamais de PII ni de secrets. Masquez au niveau du appender ; ne faites pas confiance aux appelants pour s'en souvenir.
Chaque alerte pointe vers un runbook. Une alerte sans action documentée est une notification Slack qui se fait passer pour une page.

Signaux d'alarme

Déboguer la production en se connectant en SSH à un pod.
Des alertes qui se déclenchent régulièrement et sont ignorées. (La fatigue des alertes est un problème de fiabilité.)
Des logs qui disent « erreur survenue » sans contexte, sans ID, sans pile.
Des métriques qui montrent uniquement des moyennes, sans percentiles.
Un tableau de bord par service, zéro tableau de bord par parcours utilisateur.