Piyush-Nagar/coding-agents-skills

Was du nicht sehen kannst, kannst du nicht reparieren. Observability wird von Anfang an mitentwickelt, nicht nach einem Vorfall aufgesetzt. Wenn eine Frage zur Produktion eine Codeänderung zur Beantwortung benötigt, ist die Instrumentierung falsch.

Was ist coding-agents-skills?

Dieser Skill vermittelt die Grundprinzipien echter Observability für verteilte Systeme, die über einfaches Monitoring hinausgehen. Er basiert auf den drei Säulen Logs, Metriken und Traces, die jeweils unterschiedliche Fragen beantworten – was passiert ist (Logs), wie viel und wie oft (Metriken) und warum etwas langsam war (Traces). Der Skill enthält klare Regeln wie strukturierte Logs im JSON-Format, Korrelations-IDs in jeder Logzeile, RED-Metriken für Endpunkte (Rate, Errors, Duration) und USE-Metriken für Ressourcen (Utilization, Saturation, Errors) sowie die Verwendung von OpenTelemetry für Traces über Service-Grenzen hinweg. Er betont die Alarmierung basierend auf Service Level Objectives (SLOs) statt auf Rohmetriken, getrennte Health- und Readiness-Endpunkte, richtige Log-Level und die strikte Vermeidung von PII oder Secrets in Logs. Der Skill unterstützt Entwickler und DevOps-Teams auf allen Plattformen, die OpenTelemetry und strukturierte Logging-Frameworks nutzen, und hilft, typische Anti-Patterns wie SSH-Debugging in der Produktion oder Alarmmüdigkeit zu vermeiden.

Funktioniert mit~Claude Code~Codex CLI~Cursor

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

Dokumentation

Observability

Regeln

Drei Säulen: Logs, Metriken, Traces. Jede beantwortet eine andere Frage – was passiert ist (Logs), wie viel und wie oft (Metriken), warum es langsam war (Traces). Du brauchst alle drei.
Nur strukturierte Logs. JSON (oder ähnlich). Grep ist in großem Maßstab keine Strategie.
Korrelations-/Trace-ID in jeder Logzeile. Leite sie über Header durch Service-Grenzen hinweg weiter. Eine ID verbindet die gesamte Anfrage-Reise.
RED-Metriken für jeden Endpunkt. Rate, Errors, Duration (mit P50/P95/P99). Das Minimum, um Regressionen zu erkennen.
USE-Metriken für jede Ressource. Utilization, Saturation, Errors – für CPU, Speicher, Pools, Warteschlangen, Festplatten, Netzwerk.
Trace jeden serviceübergreifenden Aufruf. Nutze OpenTelemetry. Erfasse auch DB-Abfragen und Cache-Treffer als Spans.
Alarmiere basierend auf SLOs, nicht auf Rohmetriken. „CPU > 80%“ weckt Menschen um 3 Uhr morgens grundlos. „P99-Latenz überschreitet SLO für 5 Minuten“ erfasst echten Benutzerschmerz.
Health und Readiness sind unterschiedliche Endpunkte. /health = „Ich lebe, starte mich nicht neu.“ /ready = „Ich kann jetzt Traffic aufnehmen.“ Behandle sie entsprechend.
Logge auf der richtigen Ebene, logge einmal pro Ereignis. INFO für den Anfrage-Lebenszyklus, WARN für behebbare Probleme, ERROR für Dinge, die einen Menschen brauchen. Doppelte Logs lassen Dashboards lügen.
Protokolliere niemals PII oder Secrets. Maskiere sie im Appender; vertraue nicht darauf, dass Aufrufer daran denken.
Jeder Alarm verweist auf ein Runbook. Ein Alarm ohne dokumentierte Aktion ist eine Slack-Benachrichtigung, die vorgibt, ein Page zu sein.

Warnsignale

Debuggen der Produktion durch SSH in einen Pod.
Alarme, die regelmäßig ausgelöst und ignoriert werden. (Alarmmüdigkeit ist ein Zuverlässigkeitsproblem.)
Logs, die „Fehler aufgetreten“ sagen, ohne Kontext, ohne ID, ohne Stacktrace.
Metriken, die nur Durchschnitte zeigen, keine Perzentile.
Ein Dashboard pro Service, null Dashboards pro Benutzerreise.