observability-crusade

The Observability Crusade

"In the beginning, there was darkness upon the codebase. And the Observability Purists said: LET THERE BE LIGHT."

This command orchestrates a multi-squad crusade to eliminate observability sins and bring full instrumentation to your codebase.

Command Invocation

# Survey darkness only (report mode)
/observability-crusade

# Survey specific scope
/observability-crusade --scope api
/observability-crusade --scope web

# Survey and apply fixes
/observability-crusade --illuminate

# Target specific directory
/observability-crusade apps/api/src/domains/orders
/observability-crusade apps/api/src/domains/orders --illuminate

The Four Phases

Phase 1: The Darkness Survey

First, we scan the codebase to identify every sin against observability:

Sins to detect:

1. Empty Catch Blocks: catch (e) {}, catch {}, catch blocks with only comments
2. Bare Console Calls: console.log, console.error, console.warn in non-test files
3. Untraced Endpoints: API controllers/routes with no logging
4. Untraced External Calls: HTTP calls, database queries without timing/logging
5. Missing Correlation IDs: No middleware, no propagation
6. Unstructured Logs: String concatenation instead of structured objects
7. Missing Health Checks: No /health endpoint
8. Swallowed Errors: Catch and return null/undefined without logging
9. Missing Business Metrics: No counters or histograms for business operations
10. Error Responses Without Context: Throwing exceptions without logging details

Scan commands:

# Empty catch blocks
rg 'catch\s*\([^)]*\)\s*\{\s*\}' --type ts --type tsx

# Bare console calls (exclude test files)
rg 'console\.(log|error|warn|info|debug)' --type ts --type tsx -g '!*.spec.ts' -g '!*.test.ts' -g '!*.e2e.ts'

# Catch blocks with only comments
rg 'catch.*\{[^}]*//[^}]*\}' --type ts --type tsx

# Missing correlation ID usage in services
rg 'logger\.(info|error|warn)' -A 2 --type ts | rg -v 'correlationId'

# Unstructured string concat logs
rg "logger\.(info|error|warn)\(['\"].*\+.*\)" --type ts

# Missing health check endpoints
rg -L '@Get.*health' apps/api

# Promise without catch
rg 'await\s+\w+\(.*\)' --type ts -g '!*.spec.ts' | rg -v 'try|catch'