logging-and-observability

name	logging-and-observability
description	Adds structured JSON logging, correlation/trace IDs, metrics, and health endpoints. Use when wiring observability for a new service, debugging cross-service requests, or removing console.log.
license	MIT

Logging and Observability

When to use

• Wiring observability for a new service
• Debugging cross-service requests
• Removing console.log from production code

Core rules

1. Structured JSON logs in production, pretty in development
2. Every log entry has timestamp, level, message, traceId
3. No console.log in production code
4. Correlation/trace ID passed through async context
5. Health endpoint (/health) and readiness endpoint (/ready)

Reference shape (TypeScript)

Logger Interface (Port)

export interface Logger {
  info(message: string, meta?: Record<string, unknown>): void;
  warn(message: string, meta?: Record<string, unknown>): void;
  error(message: string, meta?: Record<string, unknown>): void;
  debug(message: string, meta?: Record<string, unknown>): void;
}

JSON Logger Implementation

export class JsonLogger implements Logger {
  constructor(private traceId?: string) {}

  info(message: string, meta?: Record<string, unknown>): void {
    this.log('info', message, meta);
  }

  private log(level: string, message: string, meta?: Record<string, unknown>): void {
    const entry = {
      timestamp: new Date().toISOString(),
      level,
      message,
      traceId: this.traceId,
      ...meta,
    };
    console.log(JSON.stringify(entry));
  }
}

Examples — Do

this.logger.info('User created', { userId: user.id, email: user.email.value });

Examples — Don't

// ❌ Console.log in production code
console.log('User created:', user);
// ❌ No trace ID
logger.info('Request processed');

Checklist

• Structured JSON logger implemented
• Trace/correlation ID in every log entry
• Health and readiness endpoints created
• No console.log in production code

See reference/logging-patterns.md for full patterns.