Boas Práticas de Logging

Registre campos acionáveis; amostre o debug em produção com moderação. Estas regras mantêm os logs do Node.js pesquisáveis, em conformidade e baratos em escala.

Como Usar Esta Lista

• Revise em cada novo middleware, cliente de saída e processador de worker.
• Combine com Redação de PII e Conformidade antes do SOC2.
• Adicione um teste de snapshot de CI para caminhos de redação em payloads de amostra.
• Alinhe os nomes dos campos (requestId, tenantId) entre microsserviços em um documento compartilhado.

A - Estrutura e Níveis

• Um objeto JSON por linha para stdout. Sem concatenação de strings ou dumps de stack de várias linhas como texto puro.
• Campo event ou action estável para logs de negócios. order_created, não um done vago.
• info para ciclo de vida de requisição e eventos de negócios. error para falhas que necessitam de ação.
• debug desativado ou amostrado em produção. LOG_LEVEL=info como padrão; amostragem de cauda para investigações.
• Proibir console.log em src/ via ESLint. Exceção apenas para pontos de entrada de CLI.

B - Contexto da Requisição

• Aceite ou gere x-request-id na borda. Retorne o mesmo ID no cabeçalho de resposta.
• Logger filho ou ALS para requestId em cada linha. Sem passagem manual em camadas profundas sem ALS.
• Encaminhe x-request-id em requisições HTTP de saída e jobs de fila. Correlação de ponta a ponta.
• Registre método, caminho, status, duração ao concluir. Exclua /health ou registre em debug.
• Vincule userId/tenantId após a autenticação em um logger filho. Não antes que a autenticação seja bem-sucedida.

C - Segurança e Conformidade

• redact do Pino para autorização, cookies, senhas, PAN. Veja pino.
• Serializadores personalizados removem PII dos objetos req e user. Registre IDs, não e-mails.
• Documente o TTL de retenção de logs por ambiente. 30-90 dias típicos para produção, alinhados com GDPR.
• Índices de log separados por ambiente. Sem tráfego de produção em agregadores de desenvolvimento.
• Nunca registre req.body completo ou error.response.data do Axios por padrão.

D - Desempenho e Operações

• Não use pino-pretty em produção. Apenas JSON; o transporte "pretty" bloqueia o event loop.
• Evite registrar dentro de loops apertados. Agregue contagens ou amostre 1/N.
• Um único logger raiz por processo com base: { service, version }. Metadados de frota pesquisáveis.
• Envie logs via stdout + agente sidecar. Não rotação de arquivos no nível do aplicativo em contêineres.
• Alerta sobre picos de volume de logs. Frequentemente indica tempestades de erros ou debug deixado ativado.

E - Integração de Observabilidade

• Compartilhe trace_id com OpenTelemetry quando ativado. Correlacione logs e traces no APM.
• Use mapeamento de severidade consistente para PagerDuty. fatal para chamadas de página; error para tickets; warn para dashboard.
• Links de runbook nas descrições de alerta, não em cada linha de log. Mantenha os payloads de log pequenos.
• Teste a saída de log no CI para regressões de redação. Snapshot de fixture sensível.
• Documente os campos necessários em LOGGING.md para novos serviços.

FAQs

Relacionados

• Noções Básicas de Logging - exemplos introdutórios
• pino - referência de configuração
• IDs de Correlação de Requisição - propagação de cabeçalho
• Boas Práticas de Observabilidade - métricas e traces

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.