logging

Logging — Structured Logging

Activate When

• User invokes /godmode:logging
• User says "structured logging", "JSON logs"
• User says "log levels", "correlation ID", "trace ID"
• User says "log aggregation", "ELK", "Loki"
• User needs PII redaction or compliance-aware logging

Workflow

Step 1: Logging Assessment

# Detect current logging state
grep -rn "console\.log\|console\.error" src/ \
  --include="*.ts" 2>/dev/null | wc -l
grep -rn "log\.Println\|fmt\.Println" . \
  --include="*.go" 2>/dev/null | wc -l
grep -rn "print(\|logging\." . \
  --include="*.py" 2>/dev/null | wc -l

# Check for structured loggers
grep -r "pino\|winston\|structlog\|zerolog\|slog" \
  package.json go.mod pyproject.toml 2>/dev/null

LOGGING ASSESSMENT:
| Aspect      | Status                    |
|-------------|---------------------------|
| Format      | Unstructured / JSON       |
| Levels      | info/error only / full    |
| Context     | requestId, userId present?|
| Correlation | traceId propagated?       |
| PII         | Redacted / exposed        |
| Aggregation | stdout / ELK / Loki       |
| Retention   | Configured / none         |

IF unstructured: migrate to JSON logger
IF no correlation IDs: add middleware
IF PII in logs: add redaction layer
IF no retention policy: configure rotation

Step 2: Log Level Strategy

| Level | When to Use                  |
|-------|------------------------------|
| FATAL | Process cannot continue      |
| ERROR | Operation failed, process OK |
| WARN  | Degraded but functional      |
| INFO  | Business events, milestones  |
| DEBUG | Diagnostic detail            |

THRESHOLDS:
  Production default: INFO
  DEBUG in prod: only when explicitly enabled
  IF 404/validation fail logged as ERROR: fix to WARN
  IF > 100 ERROR/min sustained: investigate
  IF DEBUG enabled in prod > 1 hour: auto-disable

Step 3: Structured Logging Implementation

STRUCTURED LOG FORMAT (JSON):
{
  "timestamp": "ISO 8601 with timezone",
  "level": "info",
  "service": "<name>",
  "environment": "<env>",
  "version": "<semver>",
  "requestId": "<uuid>",
  "traceId": "<uuid>",
  "message": "<event description>",
  "data": { <structured fields> }
}

LIBRARIES:
  Node.js: pino (async, fast, JSON native)
  Go: slog (stdlib) or zerolog (zero-alloc)
  Python: structlog (processor pipeline)

RULES:
  Always structured fields, never string interpolation
  Always ISO 8601 timestamps with timezone
  Always include service, environment, version
  IF log line > 10KB: truncate request/response