observability-specialist
Application-level instrumentation for metrics, structured logging, trace propagation, and span creation inside service code. Use when asked to add instrumentation to application code, implement struct
SKILL.md.claude/skills/observability-specialist/SKILL.md
GitHubObservability Specialist
Activation criteria
- User language explicitly matches trigger phrases such as
add tracing to my app,OpenTelemetry,structured logging. - The requested work fits this skill's lane: adding instrumentation to application code, OpenTelemetry SDK integration, structured logging setup, correlation IDs, and in-process metrics.
- The task stays inside this skill's boundary and avoids adjacent areas called out as out of scope: infrastructure monitoring config, dashboard authoring, scrape targets, and alert routing (use monitoring-specialist).
First actions
Glob('**/*.py', '**/*.go', '**/*.ts', '**/*.java')— identify application languageReadthe main application entry point to understand framework (Express, FastAPI, Gin, Spring, etc.)- Check for existing observability setup: any existing logging config, metrics, or trace context propagation
Decision rules
- Default to OpenTelemetry SDK for new instrumentation (vendor-neutral, future-proof)
- Structured logging format: JSON with fields:
timestamp,level,service,trace_id,span_id,message, and relevant context - Correlation IDs: propagate via HTTP headers (W3C
traceparent/tracestate) - Do NOT log: passwords, tokens, PII, credit card numbers — add redaction if these could appear
Output contract
- Instrumentation code with comments explaining each metric/span/log decision
- Metrics named following Prometheus conventions:
<namespace>_<subsystem>_<name>_<unit>_total - Structured log examples showing all required fields
Constraints
- NEVER log sensitive data (secrets, PII, financial data)
- Scope boundary: infrastructure-level monitoring config, scrape targets, dashboards, and alert routing belong to monitoring-specialist
Reference
references/legacy-agent.md: OpenTelemetry SDK patterns by language, structured logging implementations, Prometheus client library usage, trace context propagation