Communitygithub.com

lguidolin/observability-and-slos

Verwenden Sie dieses Skill beim Hinzufügen von Logging, Metriken, Tracing, Health Checks, SLOs oder Alerting – oder beim Aufbau einer Service-Oberfläche, die betreibbar und debugbar sein muss. Schlüsselwörter: strukturierte Logs, OpenTelemetry, Korrelations-ID, RED-Metriken, Liveness, Readiness, SLI, SLO, Error Budget, Alerting.

Was ist observability-and-slos?

Dieser Skill stellt eine umfassende Anleitung für Observability und Service Level Objectives (SLOs) bereit, die auf der Überzeugung basiert, dass Observability von Anfang an im Design verankert sein muss, nicht erst nach einem Ausfall nachgerüstet wird. Er definiert universelle Prinzipien: die drei Signale (strukturierte Logs, Metriken und Traces), die Golden Signals (Rate, Errors, Duration – RED) für jeden Endpunkt, Health-Check-Endpoints (Liveness/Readiness) sowie SLOs mit SLIs und Error Budgets. Alerting soll symptom-, nicht ursachenbasiert sein, um handlungsrelevante Benachrichtigungen zu gewährleisten. Die konkrete Implementierung basiert auf strukturierten JSON-Logs über stdout, OpenTelemetry für Traces und Metriken, einer durchgängigen Korrelations-ID, RED-Metriken pro HTTP-Route und GraphQL-Operation sowie Liveness/Readiness-Endpoints, die an Kubernetes-Probes angebunden sind. Der Skill unterstützt zudem Frontend-Telemetrie (Web Vitals, Client-Fehler) und empfiehlt, SLOs und Alerting erst ab einer Produktionsphase mit echten Nutzern zu aktivieren – für lokale oder Pre-Launch-Projekte genügen zunächst strukturierte Logs und Health-Endpoints. Der Skill ist plattformunabhängig formuliert, geht aber auf konkrete Technologien wie AKS, Azure Monitor, Application Insights und Prometheus/Grafana ein.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/observability-and-slos
Original anzeigen→Alle Skills durchsuchen

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Dokumentation

Observability und SLOs

Überblick

Sie können nicht betreiben, debuggen oder verbessern, was Sie nicht sehen können. Observability wird entworfen, nicht nach dem ersten Ausfall nachgerüstet. Die erste Frage bei jedem Vorfall ist „Was hat sich geändert und wer ist betroffen“ – ein System, das das nicht beantworten kann, macht aus einer Fünf-Minuten-Reparatur eine archäologische Ausgrabung.

Die Prinzipien (universell)

  • Die drei Signale. Erzeugen Sie strukturierte Logs (maschinenlesbar, nicht Freitext), Metriken (Zählungen, Raten, Dauern) und Traces (den Pfad einer Anfrage über Dienste hinweg). Eine Anfrage trägt eine Korrelations-/Trace-ID Ende-zu-Ende.
  • Instrumentieren Sie die goldenen Signale für jede Oberfläche: Rate, Fehler, Dauer (RED) pro Endpunkt/Operation, plus Ressourcensättigung. Ein neuer Endpunkt ist nicht „fertig“, bis er observabel ist.
  • Health ist ein Endpunkt, keine Vermutung. Stellen Sie Liveness („Läuft mein Prozess?“) und Readiness („Kann ich Traffic bedienen?“) als separate Prüfungen bereit.
  • Definieren Sie SLOs für kritische Journeys, mit SLIs, die sie messen, und einem Error Budget, das die Abwägung zwischen Zuverlässigkeit und neuen Features explizit und datengesteuert macht.
  • Alertieren Sie auf Symptome, nicht auf Ursachen. Pagern Sie, wenn Nutzer leiden (SLO-Burn, Readiness schlägt fehl), nicht bei jedem internen Aussetzer. Jeder Alert muss handlungsrelevant sein – ein Alert, auf den niemand reagiert, trainiert Menschen, Alerts zu ignorieren.

Die Mechanismen (dieser Stack)

  • Strukturierte JSON-Logs nach stdout, von der Plattform gesammelt (z.B. AKS → Azure Monitor / Log Analytics). Kein Freitext-Logging in Diensten.
  • OpenTelemetry im App-Server und PostGraphile; Export von Traces/Metriken an Azure Monitor / Application Insights (oder Prometheus/Grafana).
  • Korrelations-ID propagiert über den Datenpfad – am Edge generiert, vom Browser über die App zu PostGraphile zusammen mit Kontext-Headern weitergegeben, an jede Log-Zeile und jeden Span angehängt.
  • RED-Metriken pro HTTP-Route und GraphQL-Operation; Postgres-Slow-Query-Log + pg_stat_statements.
  • Liveness/Readiness-Endpoints, an Kubernetes-Probes angebunden (siehe cloud-delivery-aks). Readiness spiegelt die tatsächliche Abhängigkeitsgesundheit wider (kann die Datenbank erreicht werden?), nicht nur, dass der Prozess läuft.
  • Frontend: Melden Sie Web Vitals und Client-Fehler an dasselbe Backend.
  • SLOs pro Journey mit Dashboards und Burn-Rate-Alerts.

Wann skalieren

Ein Pre-Launch-/Lokalprojekt implementiert jetzt strukturierte Logs + Health-Endpoints und verschiebt SLOs/Alerting, bis echte Nutzer zu schützen sind. Geben Sie den Modus im ersten Entscheidungsdokument an.

Vollständige Begründung: Artikel IX und XVI der Verfassung, gebündelt in 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.

Verwandte Skills

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