pino

Q: ¿Debo registrar errores con logger.error o lanzar una excepción?

Lanza una excepción para el flujo de control; registra en el límite que maneja el error (manejador de errores HTTP, catch del worker). Registra una vez con la clave err: log.error({ err, orderId }, "payment_failed").

Q: ¿Información de identificación personal (PII) en los registros?

Redacta en la configuración. Prefiere IDs opacos (userId) sobre correos electrónicos y nombres. Si se aplica el GDPR, define la retención y la limpieza en la plataforma de registro, no solo en el código de la aplicación.

Pino es el registrador de producción predeterminado para las API de Node.js: JSON estructurado rápido, baja sobrecarga y una integración de primera clase con Fastify.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

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

# Solo desarrollo - nunca en Dockerfile de producción
npm install -D pino-pretty
LOG_LEVEL=debug node app.js | npx pino-pretty

Cuándo usarlo:

Cada servicio Node de producción (Express, Fastify, Nest, workers)
Agregación centralizada de registros (Datadog, CloudWatch, Loki, ELK)
Correlacionar solicitudes con requestId entre servicios

Ejemplo de trabajo

// 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 de 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" });
});

Reglas de producción:

Registrar solo en stdout: el tiempo de ejecución del contenedor envía los registros
Nunca uses pino-pretty en imágenes de producción
Usa loggers hijos por solicitud, no concatenación de cadenas global
Registra eventos como objetos: { event: "order_created", orderId }

Integración con Fastify

Fastify usa Pino por defecto:

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

Consulta Registro con Pino para hooks, serializadores e IDs de solicitud.

Comparación

Registrador	Usar cuando	Omitir cuando
Pino	Servicios JSON, Fastify, alto rendimiento	Aplicaciones heredadas profundamente ligadas a los transportes de Winston
Winston	Código base existente solo de Winston	API nuevas
console.log	Solo para pruebas locales	Cualquier entorno desplegado
Bunyan	Mantenimiento de servicios heredados	Proyectos nuevos

Preguntas frecuentes

¿Debo registrar errores con logger.error o lanzar una excepción?

Lanza una excepción para el flujo de control; registra en el límite que maneja el error (manejador de errores HTTP, catch del worker). Registra una vez con la clave err: log.error({ err, orderId }, "payment_failed").

¿Cómo registro las promesas rechazadas no manejadas?

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

Documenta la política de salida por servicio: Kubernetes reiniciará el pod.

¿Información de identificación personal (PII) en los registros?

Redacta en la configuración. Prefiere IDs opacos (userId) sobre correos electrónicos y nombres. Si se aplica el GDPR, define la retención y la limpieza en la plataforma de registro, no solo en el código de la aplicación.

Relacionado

Registro con Pino - Patrones específicos de Fastify
Conceptos básicos de bibliotecas esenciales - por qué Pino es el predeterminado
Conceptos básicos de observabilidad - correlación de trazas + registros

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Revisado por Chris St. John·Última actualización: 16 jul 2026

Was this article helpful?

Nodejs Essential Libraries Pino

pino

Pino es el registrador de producción predeterminado para las API de Node.js: JSON estructurado rápido, baja sobrecarga y una integración de primera clase con Fastify.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

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

# Solo desarrollo - nunca en Dockerfile de producción
npm install -D pino-pretty
LOG_LEVEL=debug node app.js | npx pino-pretty

Cuándo usarlo:

Cada servicio Node de producción (Express, Fastify, Nest, workers)
Agregación centralizada de registros (Datadog, CloudWatch, Loki, ELK)
Correlacionar solicitudes con requestId entre servicios

Ejemplo de trabajo

// 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 de 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" });
});

Reglas de producción:

Registrar solo en stdout: el tiempo de ejecución del contenedor envía los registros
Nunca uses pino-pretty en imágenes de producción
Usa loggers hijos por solicitud, no concatenación de cadenas global
Registra eventos como objetos: { event: "order_created", orderId }

Integración con Fastify

Fastify usa Pino por defecto:

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

Consulta Registro con Pino para hooks, serializadores e IDs de solicitud.

Comparación

Registrador	Usar cuando	Omitir cuando
Pino	Servicios JSON, Fastify, alto rendimiento	Aplicaciones heredadas profundamente ligadas a los transportes de Winston
Winston	Código base existente solo de Winston	API nuevas
console.log	Solo para pruebas locales	Cualquier entorno desplegado
Bunyan	Mantenimiento de servicios heredados	Proyectos nuevos

Preguntas frecuentes

¿Debo registrar errores con logger.error o lanzar una excepción?

¿Cómo registro las promesas rechazadas no manejadas?

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

Documenta la política de salida por servicio: Kubernetes reiniciará el pod.

¿Información de identificación personal (PII) en los registros?

Relacionado

Registro con Pino - Patrones específicos de Fastify
Conceptos básicos de bibliotecas esenciales - por qué Pino es el predeterminado
Conceptos básicos de observabilidad - correlación de trazas + registros

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Revisado por Chris St. John·Última actualización: 16 jul 2026

Was this article helpful?

pino

Buscar en la documentación

pino