Noções Básicas de Logging

8 exemplos para você começar com Logging para backends Node.js - 6 básicos e 2 intermediários.

Pré-requisitos

npm install pino
npm install -D pino-pretty typescript@5.6 tsx

Serviços de produção no Node 24.18.0 devem emitir JSON estruturado para stdout - agregadores (Datadog, Loki, CloudWatch) analisam um objeto por linha.

Exemplos Básicos

1. JSON Estruturado em Vez de Concatenação de Strings

Máquinas analisam campos; humanos buscam level e requestId.

import pino from "pino";
 
const logger = pino({ level: "info" });
 
logger.info({ userId: "u_123", action: "login_success" }, "usuário logado");
// {"level":30,"userId":"u_123","action":"login_success","msg":"usuário logado",...}

• O primeiro argumento é um objeto de contexto; o segundo é uma mensagem curta para humanos.
• Modelos de string como `Usuário ${id} logado` perdem campos pesquisáveis.
• O nível level 30 é info no mapeamento numérico do Pino.

Relacionado: pino - loggers filhos e redação

2. Níveis de Log Têm Significado

Escolha o nível que corresponde à resposta do operador, não ao humor do desenvolvedor.

logger.fatal({ err }, "banco de dados inacessível na inicialização");
logger.error({ err, orderId }, "falha na captura de pagamento");
logger.warn({ retryCount: 3 }, "timeout downstream, tentando novamente");
logger.info({ requestId }, "requisição concluída");
logger.debug({ query }, "sql executado");

• error - precisa de investigação ou impacto no usuário.
• warn - degradado, mas se recuperando (tentativas, fallbacks).
• info - eventos normais de negócios e ciclo de vida da requisição.
• debug - apenas para desenvolvimento ou amostrado em produção.

Relacionado: Melhores Práticas de Logging - política de nível de log de produção

3. Registre Erros com a Chave err

O serializador padrão do Pino captura rastros de pilha.

try {
  await chargeCard(orderId);
} catch (err) {
  logger.error({ err, orderId }, "falha no carregamento");
}

• { err } aciona pino.stdSerializers.err - pilha e tipo preservados.
• logger.error(err) sem o wrapper de objeto perde a estrutura do campo.
• Mapeie para HTTP 5xx após o logging - registre primeiro, depois responda genericamente.

Relacionado: Padrões de Resposta de Erro - detalhe do cliente vs log

4. Proíba console.log no Código da Aplicação

Linhas não estruturadas quebram pipelines de log apenas em JSON.

// eslint no-console: error
import pino from "pino";
const log = pino();
log.info({ event: "worker_started" });

• console.log ignora filtros de nível e redação.
• ESLint no-console em src/ com exceção para scripts CLI.
• Testes podem usar pino.destination({ sync: true }) para captura.

Relacionado: Logging com Pino no Fastify - integração com framework

5. Inclua Metadados da Requisição em Cada Log HTTP

Método, caminho, status e duração alimentam dashboards SLO.

logger.info({
  event: "request_complete",
  method: "GET",
  path: "/users",
  statusCode: 200,
  durationMs: 42,
  requestId: "req_abc",
});

• Nomes de campo consistentes entre serviços (requestId, não reqId em um app e rid em outro).
• Duração de reply.elapsedTime (Fastify) ou temporização de middleware (Express).
• Verificações de saúde podem ser amostradas ou excluídas para reduzir ruído.

Relacionado: IDs de Correlação de Requisição - x-request-id

6. Uma Instância de Logger Por Processo

Crie no escopo do módulo; evite pino() por requisição.

// src/logger.ts
import pino from "pino";
 
export const logger = pino({
  level: process.env.LOG_LEVEL ?? "info",
  base: { service: "orders-api", version: process.env.APP_VERSION },
});

• Campos base aparecem em todas as linhas - nome do serviço para índices de log multi-tenant.
• Loggers filhos adicionam campos por requisição sem reconfigurar a raiz.
• Passe logger para workers via importação, não mutação global.

Relacionado: pino - opções de configuração

Exemplos Intermediários

7. Logger Filho para Contexto da Requisição

Associe requestId uma vez; todos os logs downstream o herdam.

const child = logger.child({ requestId: "req_abc", tenantId: "t_1" });
child.info({ action: "fetch_order" });
child.info({ action: "send_receipt" });
// ambas as linhas incluem requestId e tenantId

• Crie o filho no middleware HTTP ou no hook onRequest do Fastify.
• Após a autenticação, req.log = req.log.child({ userId: user.id }).
• Loggers filhos são baratos - prefira-os em vez de espalhar manualmente em cada chamada.

Relacionado: AsyncLocalStorage para Contexto - workers não-HTTP

8. Redija Caminhos Sensíveis

Mantenha senhas e tokens fora do armazenamento de logs.

const logger = pino({
  redact: {
    paths: ["req.headers.authorization", "req.body.password", "email"],
    censor: "[REDACTED]",
  },
});

• A redação ocorre no momento da serialização - mais seguro do que esperar que os desenvolvedores se lembrem.
• Liste os caminhos em um checklist de revisão de segurança.
• GDPR e PCI frequentemente exigem redação ou hashing de e-mail/telefone em logs.

Relacionado: Redação de PII e Conformidade - políticas de retenção

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