observability-audit

Observability Audit

Code that works locally but is impossible to debug in production. This skill finds and fixes observability gaps using whatever tools the app already has.

Step 0: Research existing observability tooling

Before anything else, explore the codebase to understand what's already in use:

• Error tracking: Sentry, Bugsnag, Rollbar, or similar?
• Logging: structured logger (Pino, Winston, Bunyan), cloud provider SDK, custom wrapper?
• APM / metrics: Datadog, New Relic, OpenTelemetry?
• Analytics: PostHog, Segment, Amplitude?
• Any custom logger or telemetry utilities?

Read how they're configured and how they're used in existing code. All fixes must use these — never introduce a new observability dependency or pattern.

What to look for

Debug artifacts left in production code:

• console.log, console.debug, console.info that aren't part of the established logging pattern
• Temporary logging added during debugging and never removed
• Commented-out log statements

Errors that disappear:

• catch(e) that propagates or re-throws without logging first — the error reaches the user but leaves no trace for debugging
• Errors logged with no context: logger.error(e) alone, with no info about what operation failed, what inputs were involved, or what the user was doing
• Errors tracked to the error tracker but without relevant metadata (user ID, request ID, relevant state)

Missing context on log entries:

• Logs that say what happened but not enough to reproduce it (no entity IDs, no relevant parameters)
• No correlation/request ID on logs in request-handling code
• Log entries that can't be connected to a specific user or session when that would be needed for debugging

Untracked slow or critical operations:

• External API calls with no timing logged on failure or when slow
• Database queries with no observability when they're critical path
• Background jobs or queues with no start/complete/fail tracking

Process

1. Research existing tooling (Step 0) — do not skip this
2. Identify the scope from the user's request
3. Find every instance of the anti-patterns above
4. Fix using the existing tooling and patterns
5. Remove debug artifacts, add context to thin logs, add tracking where missing
6. Report changes

Fix principles

• Every caught error should be logged with enough context to reproduce the problem
• Use the existing logger/tracker — never introduce a second one
• Debug console.log goes away entirely — no conversion to structured log, just deleted
• Log context should include: what operation, what failed, relevant IDs (user, entity, request)
• Don't add logging to every function — focus on boundaries (external calls, queue handlers, critical paths)

Reference files

• references/observability-patterns.md — Detection patterns, bad/fix examples for debug artifacts, missing logging, missing context, untracked operations. Read before starting the audit.

Report

Summarize by file: what was removed, what was added or improved, what context was missing and is now included.