@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 500.

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).

Formatos de saída

• format: 'json' (default): log em JSON com method, url, status, 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.
• includeStackErrors5xx?: boolean: inclui stack de erro quando status >= 500 e res.error.stack existir (default: true).

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",
  "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

Atualmente, os valores aceitos são:

• remote-addr: endereço IP remoto da requisição.
• referrer: valor do header Referrer/Referer.
• user-agent: valor do header User-Agent.
• http-version: versão HTTP da requisição.

Se um valor fora dessa lista for informado em extraLogInfos, ele será ignorado.

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 | Comportamento | |---|---| | START | Loga metadados de inicialização do processo | | warning | Loga warnings emitidos pelo Node.js | | uncaughtExceptionMonitor | Loga exceções fatais sem interferir no comportamento padrão | | unhandledRejection | Loga a promise e o motivo da rejeição | | beforeExit | Loga quando o event loop esvazia | | exit | Loga o código de saída do processo |

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();