logger-design

Logger Design Skill

Esta skill define padrões rígidos para logging estruturado com distributed tracing, garantindo rastreabilidade completa e segurança de dados sensíveis.

Core Principle

Logs são a memória do sistema. Estruturados, rastreáveis e seguros.

┌─────────────────────────────────────────────────────────────┐
│  ESTRUTURADO: Schema rígido, campos obrigatórios            │
│  RASTREÁVEL: Distributed tracing com correlation IDs        │
│  SEGURO: PII sanitizado, dados sensíveis protegidos         │
└─────────────────────────────────────────────────────────────┘

---

Schema de Log Obrigatório

Interface Base

interface LogEntry {
  // === OBRIGATÓRIOS ===
  timestamp: string;        // ISO 8601: "2024-01-15T10:30:00.000Z"
  level: LogLevel;          // "debug" | "info" | "warn" | "error" | "fatal"
  message: string;          // Descrição legível
  service: string;          // Nome do serviço/app
  environment: string;      // "development" | "staging" | "production"

  // === TRACING (obrigatório em requests) ===
  traceId: string;          // ID único da requisição raiz
  spanId: string;           // ID do span atual
  parentSpanId?: string;    // ID do span pai (se existir)

  // === CONTEXTO (quando disponível) ===
  userId?: string;          // ID do usuário (nunca PII direto)
  sessionId?: string;       // ID da sessão
  requestId?: string;       // ID da requisição HTTP

  // === TÉCNICO ===
  caller?: string;          // "file.ts:123:functionName"
  duration?: number;        // Duração em ms (para operações)

  // === DADOS ADICIONAIS ===
  data?: Record<string, unknown>;  // Contexto específico
  error?: ErrorInfo;        // Detalhes do erro (se level = error/fatal)
}

interface ErrorInfo {
  name: string;
  message: string;
  stack?: string;
  code?: string;
  cause?: ErrorInfo;
}

type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';

Níveis de Log

Nível	Quando usar	Exemplo	Produção
debug	Desenvolvimento, troubleshooting	"Query params: {...}"	❌ Off
info	Eventos normais de negócio	"Order created"	✅ On
warn	Situação inesperada, não crítica	"Retry attempt 2/3"	✅ On
error	Erro que afeta operação	"Payment failed"	✅ On
fatal	Sistema comprometido	"Database connection lost"	✅ On