wire-observability

Wire Observability

HARD GATE — HARD GATE — Observability is not optional. Before shipping, verify: structured logging is in place, key metrics are instrumented, error cases emit signals. 'We'll add metrics later' becomes 'never.'

Add structured logging, observability commands, and idempotent setup scripts. Can be invoked at any phase — recommended at the end of the first working slice, before the first deploy.

What this sets up

1. Structured JSON logging — machine-readable logs for debugging and observability
2. Observability commands — how to check the system's health documented in CLAUDE.md
3. Idempotent setup scripts — scripts that can be run repeatedly without side effects

Process

1. Assess current state

Check what's already in place:

• Is there a logging library? (pino, winston, structlog, zap, slog, etc.)
• Is logging JSON or plain text?
• Is there a health check endpoint or command?
• Are there setup scripts? Are they idempotent?

2. Add structured JSON logging

For user-facing CLI output: plain text is fine. For everything else: structured JSON.

Structured log entry format:

{
  "level": "info",
  "timestamp": "2025-01-15T10:23:45.123Z",
  "message": "User created",
  "userId": "usr_abc123",
  "requestId": "req_xyz789"
}

Guidelines:

• Include level, timestamp, message in every entry
• Add context fields relevant to the operation (userId, requestId, traceId)
• Log at boundaries: HTTP requests in/out, DB queries, external API calls, background job start/end
• Log errors with stack traces: logger.error({ err, context }, "Operation failed")
• Never log secrets, passwords, tokens, or PII

3. Document observability commands in CLAUDE.md

Add an "Observability" section to the project's CLAUDE.md:

## Observability

| What | Command |
|------|---------|
| View logs | `<log tail command>` |
| Health check | `<health check command>` |
| Check DB connection | `<db ping command>` |
| View metrics | `<metrics command>` |