pino

Q: Devo registrar erros com logger.error ou lançar uma exceção?

Lance para controle de fluxo; registre no limite que lida com o erro (manipulador de erro HTTP, catch do worker). Registre uma vez com a chave err: log.error({ err, orderId }, "payment_failed").

Q: PII em logs?

Redija na configuração. Prefira IDs opacos (userId) em vez de e-mails e nomes. Se o GDPR se aplicar, defina a retenção e a limpeza na plataforma de logs, não apenas no código do aplicativo.

Pino é o logger de produção padrão para APIs Node.js: JSON estruturado rápido, baixo overhead e integração de primeira classe com Fastify.

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", "cookie"],
  base: { service: "orders-api", env: process.env.NODE_ENV },
});
 
logger.info({ event: "server_start", port: 3000 });

# Apenas para desenvolvimento - nunca no Dockerfile de produção
npm install -D pino-pretty
LOG_LEVEL=debug node app.js | npx pino-pretty

Quando usar isso:

Todo serviço Node em produção (Express, Fastify, Nest, workers)
Agregação centralizada de logs (Datadog, CloudWatch, Loki, ELK)
Correlação de requisições com requestId entre serviços

Exemplo de Trabalho

// src/logger.ts
import pino from "pino";
 
export function createLogger() {
  return pino({
    level: process.env.LOG_LEVEL ?? "info",
    timestamp: pino.stdTimeFunctions.isoTime,
    redact: {
      paths: [
        "req.headers.authorization",
        "req.headers.cookie",
        "body.password",
        "body.token",
      ],
      censor: "[REDACTED]",
    },
    formatters: {
      level(label) {
        return { level: label };
      },
    },
  });
}
 
// src/middleware/request-context.ts
import type { Request, Response, NextFunction } from "express";
import { randomUUID } from "node:crypto";
import type { Logger } from "pino";
 
export function requestContext(log: Logger) {
  return (req: Request, res: Response, next: NextFunction) => {
    const requestId = (req.headers["x-request-id"] as string) ?? randomUUID();
    req.log = log.child({ requestId });
    res.setHeader("x-request-id", requestId);
    const start = Date.now();
    res.on("finish", () => {
      req.log.info({
        event: "request_complete",
        method: req.method,
        path: req.path,
        statusCode: res.statusCode,
        durationMs: Date.now() - start,
      });
    });
    next();
  };
}

// Uso com Express
import express from "express";
import { createLogger } from "./logger.js";
import { requestContext } from "./middleware/request-context.js";
 
const log = createLogger();
const app = express();
 
declare global {
  namespace Express {
    interface Request {
      log: import("pino").Logger;
    }
  }
}
 
app.use(requestContext(log));
app.get("/health", (req, res) => {
  req.log.debug({ event: "health_check" });
  res.json({ status: "ok" });
});

Regras de produção:

Faça log apenas para stdout - o runtime do contêiner envia os logs
Nunca use pino-pretty em imagens de produção
Use loggers filhos por requisição, não concatenação de strings global
Registre eventos como objetos: { event: "order_created", orderId }

Integração com Fastify

Fastify usa Pino por padrão:

import Fastify from "fastify";
 
const app = Fastify({
  logger: {
    level: "info",
    redact: ["req.headers.authorization"],
  },
});

Veja Logging with Pino para hooks, serializadores e IDs de requisição.

Comparação

Logger	Use quando	Evite quando
Pino	Serviços JSON, Fastify, alto throughput	Aplicações legadas profundamente ligadas a transports do Winston
Winston	Código-base existente apenas com Winston	APIs novas
console.log	Apenas para testes locais rápidos	Qualquer ambiente implantado
Bunyan	Manutenção de serviços legados	Novos projetos

FAQs

Devo registrar erros com logger.error ou lançar uma exceção?

Lance para controle de fluxo; registre no limite que lida com o erro (manipulador de erro HTTP, catch do worker). Registre uma vez com a chave err: log.error({ err, orderId }, "payment_failed").

Como registrar rejeições não tratadas?

process.on("unhandledRejection", (reason) => {
  logger.fatal({ err: reason }, "unhandled_rejection");
  process.exit(1);
});

Documente a política de saída por serviço - o Kubernetes reiniciará o pod.

PII em logs?

Redija na configuração. Prefira IDs opacos (userId) em vez de e-mails e nomes. Se o GDPR se aplicar, defina a retenção e a limpeza na plataforma de logs, não apenas no código do aplicativo.

Relacionados

Logging with Pino - Padrões específicos do Fastify
Essential Libraries Basics - por que Pino é o padrão
Observability Basics - correlação de traces + logs

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.

Revisado por Chris St. John·Última atualização: 16 de jul. de 2026

Was this article helpful?

Nodejs Essential Libraries Pino

pino

Pino é o logger de produção padrão para APIs Node.js: JSON estruturado rápido, baixo overhead e integração de primeira classe com Fastify.

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", "cookie"],
  base: { service: "orders-api", env: process.env.NODE_ENV },
});
 
logger.info({ event: "server_start", port: 3000 });

# Apenas para desenvolvimento - nunca no Dockerfile de produção
npm install -D pino-pretty
LOG_LEVEL=debug node app.js | npx pino-pretty

Quando usar isso:

Todo serviço Node em produção (Express, Fastify, Nest, workers)
Agregação centralizada de logs (Datadog, CloudWatch, Loki, ELK)
Correlação de requisições com requestId entre serviços

Exemplo de Trabalho

// src/logger.ts
import pino from "pino";
 
export function createLogger() {
  return pino({
    level: process.env.LOG_LEVEL ?? "info",
    timestamp: pino.stdTimeFunctions.isoTime,
    redact: {
      paths: [
        "req.headers.authorization",
        "req.headers.cookie",
        "body.password",
        "body.token",
      ],
      censor: "[REDACTED]",
    },
    formatters: {
      level(label) {
        return { level: label };
      },
    },
  });
}
 
// src/middleware/request-context.ts
import type { Request, Response, NextFunction } from "express";
import { randomUUID } from "node:crypto";
import type { Logger } from "pino";
 
export function requestContext(log: Logger) {
  return (req: Request, res: Response, next: NextFunction) => {
    const requestId = (req.headers["x-request-id"] as string) ?? randomUUID();
    req.log = log.child({ requestId });
    res.setHeader("x-request-id", requestId);
    const start = Date.now();
    res.on("finish", () => {
      req.log.info({
        event: "request_complete",
        method: req.method,
        path: req.path,
        statusCode: res.statusCode,
        durationMs: Date.now() - start,
      });
    });
    next();
  };
}

// Uso com Express
import express from "express";
import { createLogger } from "./logger.js";
import { requestContext } from "./middleware/request-context.js";
 
const log = createLogger();
const app = express();
 
declare global {
  namespace Express {
    interface Request {
      log: import("pino").Logger;
    }
  }
}
 
app.use(requestContext(log));
app.get("/health", (req, res) => {
  req.log.debug({ event: "health_check" });
  res.json({ status: "ok" });
});

Regras de produção:

Faça log apenas para stdout - o runtime do contêiner envia os logs
Nunca use pino-pretty em imagens de produção
Use loggers filhos por requisição, não concatenação de strings global
Registre eventos como objetos: { event: "order_created", orderId }

Integração com Fastify

Fastify usa Pino por padrão:

import Fastify from "fastify";
 
const app = Fastify({
  logger: {
    level: "info",
    redact: ["req.headers.authorization"],
  },
});

Veja Logging with Pino para hooks, serializadores e IDs de requisição.

Comparação

Logger	Use quando	Evite quando
Pino	Serviços JSON, Fastify, alto throughput	Aplicações legadas profundamente ligadas a transports do Winston
Winston	Código-base existente apenas com Winston	APIs novas
console.log	Apenas para testes locais rápidos	Qualquer ambiente implantado
Bunyan	Manutenção de serviços legados	Novos projetos

FAQs

Devo registrar erros com logger.error ou lançar uma exceção?

Como registrar rejeições não tratadas?

process.on("unhandledRejection", (reason) => {
  logger.fatal({ err: reason }, "unhandled_rejection");
  process.exit(1);
});

Documente a política de saída por serviço - o Kubernetes reiniciará o pod.

PII em logs?

Redija na configuração. Prefira IDs opacos (userId) em vez de e-mails e nomes. Se o GDPR se aplicar, defina a retenção e a limpeza na plataforma de logs, não apenas no código do aplicativo.

Relacionados

Logging with Pino - Padrões específicos do Fastify
Essential Libraries Basics - por que Pino é o padrão
Observability Basics - correlação de traces + logs

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.

Revisado por Chris St. John·Última atualização: 16 de jul. de 2026

Was this article helpful?

pino

Buscar na documentação

pino