review-observability_skill

Overview

This skill performs observability and debugging-focused code reviews. It inspects logging, metrics, tracing, alerting, and runtime diagnostics to surface visibility gaps that impede production troubleshooting. Use it to ensure teams can detect, diagnose, and respond to incidents quickly.

How this skill works

The skill evaluates source changes against an observability checklist: log presence and levels, structured logging, metric collection, trace propagation, alerting triggers, health endpoints, and diagnostic accessibility. It flags missing or risky practices and categorizes findings by priority (Critical, High, Medium, Low) to guide remediation. It provides concrete examples and remediation hints when possible.

When to use it

• When reviewing changes that touch logging, error handling, or instrumentation
• Before merging services with new network, async, or distributed behaviors
• When adding or changing metrics, alerts, or health checks
• When introducing feature flags, config changes, or sensitive data paths
• During incident postmortems to validate observability gaps are addressed

Best practices

• Log business-significant events at INFO, debug flow details at DEBUG, and failures at ERROR or WARN as appropriate
• Always emit structured logs (JSON or key=value) with correlation IDs and key context fields
• Avoid logging sensitive data; redact or transform PII, tokens, and passwords
• Export key business and system metrics (counts, latencies, error rates, resource usage) and attach thresholds for alerting
• Propagate trace/correlation IDs through service boundaries and include them in logs for combined trace-log analysis
• Provide meaningful health endpoints and attach actionable alerts that include runbook links or next steps

Example use cases

• Review a pull request that replaces sync calls with async background jobs to ensure trace context and error logging survive async boundaries
• Audit a service that recently added third-party auth to confirm tokens are not logged and authentication failures are observable
• Evaluate new metrics and alerts to verify thresholds, cardinality, and tagging are appropriate for dashboards and SLOs
• Assess a refactor of error handling to ensure stack traces and root-cause context are preserved
• Validate a rollout that introduces feature flags to confirm flag state and impact metrics are emitted