Communitygithub.com

lguidolin/observabilité-et-slos

À utiliser pour ajouter la journalisation, les métriques, le tracing, les health checks, les SLOs ou les alertes — ou lors de la construction d'une surface de service qui doit être exploitable et déboguable. Mots-clés — logs structurés, OpenTelemetry, ID de corrélation, métriques RED, liveness, readiness, SLI, SLO, budget d'erreur, alerting.

Qu'est-ce que observabilité-et-slos ?

Ce skill est conçu pour les développeurs et les équipes d'IA agent qui doivent intégrer une observabilité robuste et des objectifs de niveau de service (SLO) dans leurs systèmes. Il guide la mise en œuvre des trois piliers de l'observabilité : les logs structurés, les métriques et les traces, en suivant les signaux d'or (taux, erreurs, durée) pour chaque endpoint. Le skill détaille l'utilisation d'OpenTelemetry, la propagation d'ID de corrélation de bout en bout, et la création d'endpoints de santé (liveness/readiness) pour les clusters Kubernetes. Il fournit également un cadre pour définir des SLOs basés sur des indicateurs de niveau de service (SLIs) et des alertes de taux de combustion, permettant des décisions explicites entre fiabilité et fonctionnalités. Le contexte d'utilisation inclut des plateformes comme AKS avec Azure Monitor, mais les principes restent universels. Ce skill est essentiel pour tout projet où l'observabilité ne doit pas être une réflexion après coup, en particulier pour les services devant être opérables et déboguables dès la conception.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/observability-and-slos
Voir l'original→Voir toutes les compétences

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentation

Observabilité et SLOs

Aperçu

Vous ne pouvez pas opérer, déboguer ou améliorer ce que vous ne voyez pas. L'observabilité est conçue, pas ajoutée après la première panne. La première question lors de chaque incident est « qu'est-ce qui a changé et qui est affecté » — un système qui ne peut pas y répondre transforme une correction de cinq minutes en fouille archéologique.

Les Principes (universels)

  • Les trois signaux. Émettez des logs structurés (lisibles par machine, pas de texte libre), des métriques (compteurs, taux, durées), et des traces (le chemin d'une requête à travers les services). Une requête porte un ID de corrélation/trace de bout en bout.
  • Instrumentez les signaux d'or pour chaque surface : taux, erreurs, durée (RED) par endpoint/opération, plus la saturation des ressources. Un nouvel endpoint n'est pas « terminé » tant qu'il n'est pas observable.
  • La santé est un endpoint, pas une supposition. Exposez la vivacité (« suis-je en cours d'exécution ? ») et la disponibilité (« puis-je servir du trafic ? ») comme des vérifications distinctes.
  • Définissez des SLOs pour les parcours critiques, avec des SLIs qui les mesurent et un budget d'erreur qui rend la fiabilité par rapport aux fonctionnalités un compromis explicite et guidé par les données.
  • Alertez sur les symptômes, pas les causes. Soyez en alerte lorsque les utilisateurs souffrent (épuisement du SLO, échec de la disponibilité), pas sur chaque variation interne. Chaque alerte doit être actionnable — une alerte à laquelle personne ne réagit forme les gens à ignorer les alertes.

Les Mécanismes (cette pile)

  • Logs JSON structurés vers stdout, collectés par la plateforme (par exemple AKS → Azure Monitor / Log Analytics). Pas de journalisation en texte libre dans les services.
  • OpenTelemetry dans le serveur d'application et PostGraphile ; exportez les traces/métriques vers Azure Monitor / Application Insights (ou Prometheus/Grafana).
  • ID de corrélation propagé à travers le chemin des données — généré à la périphérie, transmis Browser → App → PostGraphile avec les en-têtes de contexte, attaché à chaque ligne de log et chaque span.
  • Métriques RED par route HTTP et opération GraphQL ; journal des requêtes lentes Postgres + pg_stat_statements.
  • Endpoints de vivacité/disponibilité connectés aux sondes Kubernetes (voir cloud-delivery-aks). La disponibilité reflète la santé réelle des dépendances (peut-il atteindre la base de données ?), pas seulement le processus actif.
  • Frontend : signalez les web-vitals et les erreurs client au même backend.
  • SLOs par parcours avec tableaux de bord et alertes de taux de combustion.

Quand adapter cela

Un projet en pré-lancement/local implémente maintenant des logs structurés + des endpoints de santé et reporte les SLOs/alertes jusqu'à ce qu'il y ait de vrais utilisateurs à protéger. Indiquez le mode dans le premier enregistrement de décision.

Raisonnement complet : Articles IX & XVI de la constitution, regroupés dans engineering-constitution/references/engineering-constitution.md.

Individual skills in this repo

This repo contains 18 individual skills — each has its own dedicated page.

lguidolin/change-hygiene-and-code-craft

Use when writing or refactoring code, structuring a commit or PR, or deciding whether to abstract duplication. Symptoms — mixing reorg with logic changes, a PR doing several things at once, a file growing large, the second copy of similar code, or unsure whether to DRY something up.

lguidolin/cloud-delivery-aks

Use when deploying to Kubernetes or Azure Kubernetes Service (AKS), configuring cloud secrets, setting up progressive rollout/canary, per-PR ephemeral environments, or k8s health probes. Keywords — Kubernetes, AKS, Key Vault, Argo Rollouts, Flagger, canary, blue-green, liveness, readiness, PodDisruptionBudget, HPA, rollback, GHCR.

lguidolin/commit-history-rewrite

Use when an existing repository has messy commit history that needs to conform to conventional commits before adopting release-please, or when intermediate WIP/fixup/merge commits need to be cleaned up.

lguidolin/conventional-commits-and-releases

Use when committing, writing a commit message, opening a PR that will be squash-merged, or configuring automated versioning/changelogs. Keywords — conventional commits, release-please, semver, feat/fix/chore, breaking change, changelog.

lguidolin/defense-in-depth-security

Use when handling untrusted input, secrets, authentication/authorization, or dependencies — or threat-modeling a new surface. Keywords — STRIDE, threat model, least privilege, secrets management, supply chain, dependency scanning, input validation, audit log, defense in depth.

lguidolin/designing-before-building

Use when starting a feature, fixing a non-trivial bug, or about to write implementation code — before any code exists. Symptoms you need this: "this is simple, I'll just code it", reaching for the editor before a design is approved, or an idea that hasn't been turned into a spec and plan.

lguidolin/engineering-constitution

Use when starting work in a project that follows the engineering constitution, orienting to its rules, or deciding which engineering practice applies to a task — spec writing, commits, testing, security, deploys, database, or UI work.

lguidolin/graphql-contract-testing

Use when writing a GraphQL query/mutation that the UI and a test will share, or building route/schema contract or smoke tests. Symptoms — copying a query into a test, a test asserting on query text, schema change that didn't break the UI build, or RLS/permission drift. Keywords — graphql-codegen, typed document, contract test, route smoke test.

lguidolin/init-repo-CI

Use when setting up a new repository with conventional commits, release-please, and CI automation, or when retrofitting an existing repository that lacks automated versioning and PR validation workflows.

lguidolin/interface-craft-and-accessibility

Use when building or styling UI — components, layouts, forms, design tokens — or making accessibility decisions. Keywords — a11y, WCAG, keyboard navigation, focus state, contrast, design system, minimalist UI, component reuse, ARIA, semantic HTML.

lguidolin/merge-gates-and-automation

Use when setting up or changing CI, pre-push hooks, or a task runner, or deciding what must pass before merge. Symptoms — tempted to put authoritative checks only in a local hook, skip CI, bypass with --no-verify, or unsure what gates a merge vs. runs locally.

lguidolin/performance-and-scale

Use when working on hot paths, list endpoints, pagination, data-access in loops, or public interfaces/schemas. Symptoms — unbounded queries, N+1 access, no latency budget, optimizing without measuring, or changing an interface many consumers depend on. Keywords — pagination, N+1, Hyrum's Law, performance budget, bundle size.

lguidolin/postgres-postgraphile-rls-and-sql

Use when writing PostgreSQL, PostGraphile config, Row-Level Security policies, SQL schema files, or working on the Browser→App→PostGraphile→Postgres data path. Keywords — RLS, SECURITY DEFINER, search_path, pgSettings, grants, roles, GraphQL depth limit, query cost, statement_timeout, SQL file organization.

lguidolin/recording-decisions

Use when a design or architecture decision has been made and needs to be captured — writing a decision record or ADR, updating a decision index, noting a deferred idea, or superseding a past decision. Keywords — ADR, decision record, rationale, rejected alternatives, dependency index.

lguidolin/resilience-and-deploy-safety

Use when planning a deploy, designing a rollback, or responding to an incident or writing a postmortem. Keywords — deploy safety, rollback, immutable artifact, progressive delivery, canary, blast radius, incident response, blameless postmortem, error budget.

lguidolin/ship-it

Use when the user wants to ship work — push, PR, archive decision records, merge, and clean up. Handles the full lifecycle from committing final changes through post-merge cleanup including converting specs/plans to compact decision records.

lguidolin/tests-as-a-control

Use when writing or modifying tests, when a test breaks during a refactor, or when testing permission/role rules. Symptoms — tempted to edit a test to make it pass, testing only the happy path, a deny-test that started passing, flaky tests, or unsure what to assert.

lguidolin/zero-downtime-migrations

Use when changing a database schema where data must survive the change — adding/removing/renaming columns, constraints, indexes, or backfilling. Symptoms — a destructive migration bundled with a code deploy, a NOT NULL column with a backfill, a table-locking UPDATE, or a rename. Keywords — expand/contract, parallel change, backfill, NOT VALID, CREATE INDEX CONCURRENTLY, graphile-migrate.

Skills associés

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community