@ecdt/logger

Middleware de logging para Express (baseado em morgan) com saída em JSON ou string, com suporte a campos extras livres (extraFields), informações adicionais do request (extraLogInfos) e captura opcional de stack trace em respostas 5xx.

Instalação

npm i @ecdt/logger

Uso (Express)

Logger padrão (JSON)

const express = require('express');
const { createLogger, createErrorCapture } = require('@ecdt/logger');

const app = express();
app.use(express.json());

// 1) Logger (no começo)
app.use(createLogger());

app.get('/', (_req, res) => res.status(200).send('ok'));

// 2) Error handler (sempre por último)
app.use(createErrorCapture());

Logger com opções

app.use(
  createLogger({
    format: 'json', // 'json' | 'string'
    extraLogInfos: ['user-agent', 'remote-addr'],
    extraFields: {
      service: 'minha-api',
      env: process.env.NODE_ENV,
    },
    includeStackErrors5xx: true, // default: true
  })
);

Captura de stack em 5xx

• Para o logger incluir error.stack, é necessário que res.error esteja preenchido.
• A forma recomendada é usar o middleware createErrorCapture() por último, pois ele seta res.error e responde o erro.

Exemplo:

app.get('/throw-error', (_req, _res) => {
  // erro síncrono: o Express encaminha para o error handler
  throw new Error('boom');
});

app.use(createErrorCapture());

Se você apenas fizer res.status(500).send(...) em uma rota, o status será 500, mas não haverá stack (porque não existe erro capturado em res.error).

Status da resposta do createErrorCapture()

O status é resolvido a partir do próprio erro, na ordem err.statusCode → err.status, aceitando inteiro entre 400 e 599. Qualquer outro valor (ausente, fora da faixa, não numérico) responde 500.

// erro de negócio: o status do endpoint é preservado
class NotFoundError extends Error {
  constructor(message) {
    super(message);
    this.statusCode = 404;
  }
}

app.get('/lead', (_req, _res) => {
  throw new NotFoundError('Lead não encontrado'); // → 404 { error: 'Lead não encontrado' }
});

// erro inesperado: 500 com stack no access log
app.get('/boom', (_req, _res) => {
  throw new Error('boom'); // → 500 { error: 'boom' }
});

Isso cobre err.status de bibliotecas como http-errors e express-openapi-validator — sem isso, um 400 de validação de contrato chegava ao cliente como 500.

Erro de axios é a exceção: quando err.isAxiosError é true, o status da resposta do terceiro é ignorado e a resposta é 500. Um 404 do RD Station não é o 404 do seu endpoint — ele vazou de um catch, então é bug do serviço. Manter 500 garante que a stack (e o bloco axiosError com config/response) chegue ao access log, já que o logger só anexa res.error em status >= 500.

Consequência do ponto acima: erro 4xx não gera stack no log, apenas severity: WARNING. Isso é intencional — status de negócio não é falha. Só sinalize statusCode/status em erro que você quer que o cliente veja.

Severidade (severity)

Todo log inclui automaticamente o campo severity, seguindo o padrão LogSeverity do Google Cloud Logging, derivado do status HTTP da resposta:

• INFO (azul): status < 400
• WARNING (amarelo): status >= 400 e < 500
• ERROR (vermelho): status >= 500
• DEFAULT: quando não há status (ex.: requisição abortada)

Formatos de saída

• format: 'json' (default): log em JSON com method, url, status, severity, responseTime, payload, campos de extraLogInfos e extraFields.
• format: 'string': log em texto (campos extras são concatenados).

Opções (createLogger(options))

• format?: 'json' | 'string' | string: formato do log (default: 'json').
• extraLogInfos?: string[]: lista opcional de informações extras do request obtidas a partir de tokens suportados do Morgan.
• extraFields?: Record<string, unknown>: objeto livre com campos extras definidos manualmente e adicionados ao log.
• ignorePaths?: string[]: lista de paths que não geram log quando a resposta é sucesso (status < 400). Em caso de erro (status >= 400), o log acontece normalmente. A comparação é exata, pelo pathname sem query string (ex.: ['/health', '/metrics']).
• includeStackErrors5xx?: boolean: inclui stack de erro quando status >= 500 e res.error.stack existir (default: true).
• retainedLogPercentage?: number: fração de requisições bem-sucedidas (status < 400) que serão efetivamente logadas. Valor entre 0 e 1 — 1 loga 100% (default), 0.1 loga ~10%. Erros (status >= 400) são sempre logados independente desse valor.

Diferença entre extraLogInfos e extraFields

• extraLogInfos: adiciona ao log informações derivadas da requisição/resposta usando tokens já suportados internamente.
• extraFields: adiciona ao log qualquer dado fixo ou contextual informado manualmente pela aplicação.

Exemplo:

app.use(
  createLogger({
    format: 'json',
    extraLogInfos: ['user-agent', 'http-version'],
    extraFields: {
      service: 'billing-api',
      env: 'prod',
    },
  })
);

Saída esperada em JSON:

{
  "method": "GET",
  "url": "/health",
  "status": "200",
  "severity": "INFO",
  "responseTime": "2.315 ms",
  "payload": {},
  "user-agent": "curl/8.5.0",
  "http-version": "1.1",
  "service": "billing-api",
  "env": "prod"
}

Opções suportadas em extraLogInfos

Tokens do morgan:

• remote-addr: IP do peer da conexão. Atrás de nginx/LB isso é o proxy, não o cliente — para o IP real use os headers abaixo.
• referrer: valor do header Referrer/Referer.
• user-agent: valor do header User-Agent.
• http-version: versão HTTP da requisição.

Headers do request (allowlist):

• x-forwarded-for: cadeia de IPs do cliente até o último proxy — o IP real do usuário atrás de CDN/nginx.
• x-real-ip: IP que o proxy declarou como cliente.
• x-client-ip: convenção interna do ecossistema (o SSR do site propaga o IP do usuário nas chamadas internas).
• x-forwarded-proto: http/https na borda.
• x-request-id: id de correlação, quando o proxy gera um.
• x-cloud-trace-context: id de trace do Google Cloud — permite cruzar o log com o trace da requisição.
• host: host requisitado (separa ambientes e sondagem de bot).
• origin: origem do request (CORS).
• referer: header cru, alternativa ao token referrer do morgan.

Valor fora dessas duas listas é ignorado — a allowlist é deliberada, para um extraLogInfos solto não derrubar cookie ou authorization no log.

Observação sobre format: 'string'

No formato string, a implementação atual concatena apenas os campos base do log e os valores de extraFields. Os itens configurados em extraLogInfos são aplicados ao objeto de log JSON, mas não são interpolados no texto final do formato string.

Logs de Eventos de Processo (setupProcessHandlers)

O pacote exporta a função setupProcessHandlers() para registrar listeners globais de processo apenas para observabilidade. Ela cobre:

| Evento | Severidade | Comportamento | |---|---|---| | warning | WARNING | Loga warnings emitidos pelo Node.js | | uncaughtExceptionMonitor | ERROR | Loga exceções fatais sem interferir no comportamento padrão | | unhandledRejection | ERROR | Loga o motivo da rejeição e a stack | | beforeExit | INFO | Loga quando o event loop esvazia | | exit | WARNING / ERROR | WARNING quando o código é 0 (encerramento normal, ex.: SIGTERM de rollout no k8s); ERROR nos demais |

Cada linha sai como JSON com severity explícito: em GKE o agente de logs classifica pelo stream (stdout → INFO, stderr → ERROR), e só um payload estruturado muda essa classificação. Sem isso, até saída normal de pod chegaria ao Cloud Logging como erro.

Por que uma função separada? Bibliotecas não devem registrar listeners de processo automaticamente ao serem importadas — isso causaria efeitos colaterais inesperados na aplicação host. Com setupProcessHandlers, o desenvolvedor decide explicitamente quando e se quer usar esse comportamento.

Uso básico (sem servidor HTTP)

Útil para workers, scripts ou qualquer processo Node.js que não sobe um servidor:

const { setupProcessHandlers } = require('@ecdt/logger');

setupProcessHandlers(); // server é opcional

Uso com servidor Express

const express = require('express');
const { createLogger, createErrorCapture, setupProcessHandlers } = require('@ecdt/logger');

const app = express();
app.use(express.json());
app.use(createLogger());

app.get('/', (_req, res) => res.status(200).send('ok'));

app.use(createErrorCapture());

app.listen(3000, () => {
  console.log('Servidor rodando na porta 3000');
});

// Registra handlers de processo apenas para logs/observabilidade
setupProcessHandlers();

Logs gerados pelos eventos

[PROCESS] START: { pid: 123, node: 'v22.0.0', ... }
[PROCESS] WARNING: { name: 'MaxListenersExceededWarning', message: '...' }
[PROCESS] UNCAUGHT EXCEPTION MONITOR: { origin: 'uncaughtException', message: 'algo deu errado', stack: '...' }
[PROCESS] UNHANDLED REJECTION at: Promise { <rejected> } | reason: TypeError: ...
[PROCESS] BEFORE EXIT with code: 0 | uptime: 12.34
[PROCESS] EXIT with code: 0 | uptime: 12.34

TypeScript

O pacote expõe definições em index.d.ts. Exemplo:

import { createLogger, createErrorCapture, setupProcessHandlers } from '@ecdt/logger';
app.use(createLogger({ format: 'json' }));
app.use(createErrorCapture());
app.listen(3000);
setupProcessHandlers();