Node.js Logging

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: nodejs for comprehensive documentation.

Library Comparison

Library Performance Features Best For

Pino Fastest (10x+ faster) JSON-native, low overhead High-performance APIs

Winston Good Flexible transports, formatting Enterprise apps, flexibility

Bunyan Good JSON-native, streams Legacy projects

console Basic Built-in, no deps Simple scripts, debugging

Pino (Recommended for Performance)

Installation

npm install pino pino-pretty # pino-pretty for dev

Basic Setup

import pino from 'pino';

const logger = pino({ level: process.env.LOG_LEVEL || 'info', transport: process.env.NODE_ENV !== 'production' ? { target: 'pino-pretty', options: { colorize: true } } : undefined, });

// Usage logger.info('Server started'); logger.info({ userId: 123, action: 'login' }, 'User logged in'); logger.error({ err }, 'Database connection failed');

Child Loggers (Request Context)

import { Request, Response, NextFunction } from 'express';

export function requestLogger(req: Request, res: Response, next: NextFunction) { req.log = logger.child({ requestId: crypto.randomUUID(), method: req.method, path: req.path, });

req.log.info('Request started');

res.on('finish', () => { req.log.info({ statusCode: res.statusCode }, 'Request completed'); });

next(); }

Express Integration

import express from 'express'; import pino from 'pino'; import pinoHttp from 'pino-http';

const app = express(); const logger = pino();

app.use(pinoHttp({ logger }));

app.get('/users/:id', (req, res) => { req.log.info({ userId: req.params.id }, 'Fetching user'); // ... });

NestJS Integration

// logger.module.ts import { Module, Global } from '@nestjs/common'; import { LoggerModule as PinoLoggerModule } from 'nestjs-pino';

@Global() @Module({ imports: [ PinoLoggerModule.forRoot({ pinoHttp: { level: process.env.LOG_LEVEL || 'info', transport: process.env.NODE_ENV !== 'production' ? { target: 'pino-pretty' } : undefined, }, }), ], }) export class LoggerModule {}

// usage in service import { Logger } from 'nestjs-pino';

@Injectable() export class UserService { constructor(private readonly logger: Logger) {}

findUser(id: string) { this.logger.log({ userId: id }, 'Finding user'); } }

Winston

Installation

npm install winston

Basic Setup

import winston from 'winston';

const logger = winston.createLogger({ level: process.env.LOG_LEVEL || 'info', format: winston.format.combine( winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json() ), defaultMeta: { service: 'my-service' }, transports: [ new winston.transports.File({ filename: 'logs/error.log', level: 'error' }), new winston.transports.File({ filename: 'logs/combined.log' }), ], });

// Pretty console in development if (process.env.NODE_ENV !== 'production') { logger.add(new winston.transports.Console({ format: winston.format.combine( winston.format.colorize(), winston.format.simple() ), })); }

export { logger };

Usage

import { logger } from './logger';

// Basic logging logger.info('Server started on port 3000'); logger.warn('Cache miss for key: user:123'); logger.error('Database connection failed', { error: err });

// With metadata logger.info('User action', { userId: user.id, action: 'purchase', amount: 99.99, });

Child Loggers

const orderLogger = logger.child({ module: 'orders' }); orderLogger.info('Order created', { orderId: '12345' }); // Output: { module: 'orders', orderId: '12345', message: 'Order created', ... }

Custom Transports

import winston from 'winston'; import DailyRotateFile from 'winston-daily-rotate-file';

const rotateTransport = new DailyRotateFile({ filename: 'logs/app-%DATE%.log', datePattern: 'YYYY-MM-DD', maxSize: '100m', maxFiles: '30d', zippedArchive: true, });

rotateTransport.on('rotate', (oldFilename, newFilename) => { logger.info('Log file rotated', { oldFilename, newFilename }); });

logger.add(rotateTransport);

Express Middleware

import expressWinston from 'express-winston';

app.use(expressWinston.logger({ winstonInstance: logger, meta: true, msg: 'HTTP {{req.method}} {{req.url}} {{res.statusCode}} {{res.responseTime}}ms', expressFormat: false, colorize: false, }));

app.use(expressWinston.errorLogger({ winstonInstance: logger, }));

Log Levels

Level Priority Usage

fatal

60 App crash imminent

error

50 Error conditions

warn

40 Warning conditions

info

30 Normal operations

debug

20 Debug information

trace

10 Very detailed tracing

// Pino logger.fatal('Uncaught exception'); logger.error('Failed to connect to database'); logger.warn('Deprecated API called'); logger.info('Server started'); logger.debug('Query executed'); logger.trace('Entering function');

// Winston (no fatal, uses error) logger.error('Critical error'); logger.warn('Warning'); logger.info('Info'); logger.verbose('Verbose'); // between info and debug logger.debug('Debug'); logger.silly('Trace-level'); // lowest

Structured Logging Best Practices

DO

// Include context logger.info({ userId, orderId, action: 'checkout' }, 'Order placed');

// Log errors properly logger.error({ err, userId }, 'Payment failed');

// Use child loggers for context const reqLogger = logger.child({ requestId, userId }); reqLogger.info('Processing request');

DON'T

// Don't log sensitive data logger.info({ password, creditCard }, 'User registered'); // BAD!

// Don't use string interpolation for objects logger.info(User ${JSON.stringify(user)} logged in); // BAD!

// Don't log PII without masking logger.info({ email: user.email }); // Consider masking

Sensitive Data Handling

import pino from 'pino';

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

// Logs: { password: '[REDACTED]', username: 'john' } logger.info({ password: 'secret123', username: 'john' });

Production Configuration

Environment Variables

LOG_LEVEL=info # Log level LOG_FORMAT=json # json or pretty LOG_FILE=logs/app.log # File output

Docker/Container Logging

// Log to stdout (Docker captures this) const logger = pino({ level: process.env.LOG_LEVEL || 'info', // No file transport - Docker handles log collection });

// Ensure logs are flushed process.on('SIGTERM', () => { logger.info('Received SIGTERM, shutting down'); logger.flush(); process.exit(0); });

Correlation IDs

import { AsyncLocalStorage } from 'async_hooks';

const asyncLocalStorage = new AsyncLocalStorage<{ requestId: string }>();

export function withRequestContext(req: Request, res: Response, next: NextFunction) { const requestId = req.headers['x-request-id'] || crypto.randomUUID(); asyncLocalStorage.run({ requestId }, () => next()); }

export function getRequestId(): string | undefined { return asyncLocalStorage.getStore()?.requestId; }

// In logger const logger = pino({ mixin() { return { requestId: getRequestId() }; }, });

When NOT to Use This Skill

• Python applications: Use python-logging skill instead

• Java/Spring Boot: Use slf4j and logback skills instead

• Browser/frontend logging: Different APIs and requirements

• Simple CLI tools: console.log may be sufficient

• Framework-specific details: Use winston or pino skills for deep dives

Anti-Patterns

Anti-Pattern Why It's Bad Solution

Using console.log in production No control, no persistence Use Winston or Pino

Synchronous file logging Blocks event loop Use async transports

Logging entire request/response objects Contains sensitive data, huge size Log only necessary fields

No request correlation IDs Can't trace requests across services Use AsyncLocalStorage or child loggers

String interpolation in logs Always evaluated Use template strings or parameterized logging

Missing error stack traces Loses debugging context Always include error object: logger.error({ err })

Quick Troubleshooting

Issue Cause Solution

Performance degradation Synchronous logging Switch to Pino or async Winston transports

Logs not appearing Wrong log level Check LOG_LEVEL environment variable

Unreadable JSON in console No pretty-printer Add pino-pretty or Winston simple format for dev

Memory leak Log files growing unbounded Configure log rotation (daily-rotate-file)

Missing request context No correlation ID Use child loggers or AsyncLocalStorage

Duplicate logs Multiple loggers/transports Consolidate to single logger instance

Reference

• Quick Reference: Cheatsheet

• Pino Documentation

• Winston Documentation