pino

Use o Pino para logging rápido de JSON estruturado em Node.js - child loggers para contexto de requisição, redação para segredos e impacto mínimo na event loop.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import pino from "pino";
 
export const logger = pino({
  level: process.env.LOG_LEVEL ?? "info",
  redact: ["req.headers.authorization", "password"],
});
 
logger.info({ orderId: "o_1" }, "pedido criado");

Quando usar isso:

• Todo serviço HTTP Node em produção (Express, Fastify, NestJS).
• Substituindo Winston ou console.log para pipelines JSON.
• Necessidade de campos por escopo de requisição sem passar req por todas as funções.
• Volume de logs excede 1k linhas/segundo e o desempenho é importante.

Exemplo de Trabalho

import pino from "pino";
import express from "express";
import { randomUUID } from "node:crypto";
 
const logger = pino({
  level: process.env.LOG_LEVEL ?? "info",
  base: { service: "billing-api" },
  redact: {
    paths: ["req.headers.authorization", "req.headers.cookie", "body.cardNumber"],
    censor: "[REDACTED]",
  },
  timestamp: pino.stdTimeFunctions.isoTime,
});
 
const app = express();
app.use(express.json());
 
app.use((req, res, next) => {
  const requestId = (req.headers["x-request-id"] as string) ?? randomUUID();
  const start = process.hrtime.bigint();
  (req as express.Request & { log: pino.Logger }).log = logger.child({ requestId });
 
  res.on("finish", () => {
    req.log.info({
      event: "request_complete",
      method: req.method,
      path: req.path,
      statusCode: res.statusCode,
      durationMs: Number(process.hrtime.bigint() - start) / 1e6,
    });
  });
  next();
});
 
app.post("/charges", async (req, res) => {
  req.log.info({ amount: req.body.amount }, "início da cobrança");
  try {
    const result = await processCharge(req.body);
    req.log.info({ chargeId: result.id }, "cobrança bem-sucedida");
    res.status(201).json(result);
  } catch (err) {
    req.log.error({ err }, "falha na cobrança");
    res.status(500).json({ error: "Internal Server Error" });
  }
});
 
async function processCharge(body: { amount: number }) {
  return { id: "ch_1", amount: body.amount };
}
 
app.listen(3000);

O que isso demonstra:

• Logger raiz com metadados de serviço base e timestamps ISO.
• Child logger por requisição vinculado no middleware com requestId.
• O evento finish registra a duração e o status sem bloquear a resposta.
• Erros registrados com { err } antes da resposta genérica 5xx.

Mergulho Profundo

Como Funciona

• O Pino serializa objetos de log em strings JSON de forma assíncrona (thread worker por padrão em muitas configurações).
• Níveis numéricos: trace 10, debug 20, info 30, warn 40, error 50, fatal 60.
• Child loggers herdam os bindings do pai e adicionam os seus - cadeia imutável.
• A saída é uma linha JSON por log - NDJSON para Loki/Datadog/CloudWatch.

Opções de Configuração

Impressão Bonita para Desenvolvimento

const logger = pino({
  transport: process.env.NODE_ENV === "development"
    ? { target: "pino-pretty", options: { colorize: true } }
    : undefined,
});

• Nunca use pino-pretty em produção - bloqueia a thread principal.

Integração com NestJS

npm install nestjs-pino

// app.module.ts
import { LoggerModule } from "nestjs-pino";
 
@Module({
  imports: [LoggerModule.forRoot({ pinoHttp: { level: "info" } })],
})
export class AppModule {}

Armadilhas

• Registrando req e res completos - linhas enormes, risco de PII. Correção: serializadores personalizados apenas com método, url, status.
• pino-pretty em produção - colapso de throughput. Correção: JSON para stdout; formatar apenas localmente.
• Destino síncrono sob carga - pino.destination({ sync: true }) bloqueia. Correção: destino assíncrono padrão.
• Serializador de err ausente - log.error("msg", err) assinatura incorreta. Correção: log.error({ err }, "msg").
• Logs de debug sempre ativos - custo e ruído. Correção: LOG_LEVEL=info em produção; amostrar debug.
• Child logger não passado para serviços - perde requestId em camadas profundas. Correção: AsyncLocalStorage ou parâmetro explícito.

Alternativas

FAQs

Relacionados

• Princípios Básicos de Logging - princípios de logging estruturado
• IDs de Correlação de Requisição - propagação de requestId
• Redação de PII e Conformidade - caminhos GDPR
• Logging com Pino no Fastify - hooks do Fastify

Versões de 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.