Logging

Logging estruturado com Pino, request IDs e pretty-print.

Visao geral

O PlazerCLI configura Pino como logger estruturado. Em desenvolvimento, logs sao formatados com pino-pretty (coloridos e legíveis). Em producao, sao JSON puro, prontos para ELK Stack, Datadog ou CloudWatch.

Niveis de log

Nivel	Valor	Uso
`trace`	10	Detalhes internos (debug profundo)
`debug`	20	Informacoes de debug
`info`	30	Eventos normais (padrao)
`warn`	40	Situacoes inesperadas
`error`	50	Erros recuperaveis
`fatal`	60	Erros criticos (app vai crashar)

# Variavel de ambiente
LOG_LEVEL=info   # trace | debug | info | warn | error | fatal

Request ID

Cada request recebe um ID unico (UUID v4) para correlacao entre servicos. Se o header x-request-id ja existir no request (enviado por um load balancer ou API gateway), ele e reaproveitado.

// Log de exemplo em dev:
[14:30:45.123] INFO: GET /api/users completed with 200
  reqId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  responseTime: 42
  method: "GET"
  url: "/api/users"

// Log de exemplo em producao (JSON):
{"level":30,"time":1708000000,"reqId":"a1b2c3d4...","method":"GET","url":"/api/users","statusCode":200,"responseTime":42}

NestJS — nestjs-pino

Usa nestjs-pino com LoggerModule e um AppLoggerService injetavel:

// Configurado no main.ts:
const app = await NestFactory.create(AppModule, { bufferLogs: true });
app.useLogger(app.get(Logger));

// Uso em services:
@Injectable()
export class OrdersService {
  constructor(private readonly logger: AppLoggerService) {}

  async create(dto: CreateOrderDto) {
    this.logger.info({ orderId: '123' }, 'Pedido criado');
    // ...
  }
}

Headers sensiveis (authorization, cookie) sao automaticamente redatados nos logs.

Express — pino-http

Middleware pino-http com request ID e custom log levels:

import { httpLogger, logger, requestIdMiddleware } from './middlewares/logger.js';

// Registrar no app.ts:
app.use(requestIdMiddleware);  // Gera e propaga x-request-id
app.use(httpLogger);           // Log automatico de requests

// Uso manual do logger:
import { logger } from './middlewares/logger.js';
logger.info({ userId: '123' }, 'Usuario atualizado');
logger.error({ err }, 'Falha ao processar pagamento');

Niveis customizados por status code: 5xx = error, 4xx = warn, outros = info.

Fastify — Pino nativo

Fastify usa Pino nativamente. O PlazerCLI gera a configuracao em config/logger.ts:

import { loggerConfig } from './config/logger.js';

const app = Fastify({
  ...loggerConfig,
  // Pino ja esta integrado, basta usar request.log:
});

// Uso nas rotas:
app.get('/users', async (request) => {
  request.log.info({ count: users.length }, 'Listando usuarios');
  return users;
});

Pretty-print vs JSON

O comportamento muda automaticamente baseado em NODE_ENV:

development: pino-pretty com cores, timestamps legíveis, sem pid/hostname
production: JSON puro para stdout, consumido por ferramentas de observabilidade

Rate Limiting

Swagger/OpenAPI