Winston Logger - Quick Reference

When to Use This Skill

Logging with multiple transports (file, console, HTTP)
Structured logging with custom levels
Automatic log file rotation

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

Basic Setup

npm install winston

Essential Patterns

Logger Base

import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' }),
  ],
});

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

Custom Format

const customFormat = winston.format.printf(({ level, message, timestamp, ...meta }) => {
  return `${timestamp} [${level.toUpperCase()}]: ${message} ${Object.keys(meta).length ? JSON.stringify(meta) : ''}`;
});

const logger = winston.createLogger({
  format: winston.format.combine(
    winston.format.timestamp(),
    customFormat
  ),
  transports: [new winston.transports.Console()],
});

Child Logger

const childLogger = logger.child({ requestId: req.id, module: 'auth' });
childLogger.info('User authenticated', { userId: user.id });

Daily Rotate File

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

const transport = new DailyRotateFile({
  filename: 'logs/app-%DATE%.log',
  datePattern: 'YYYY-MM-DD',
  maxSize: '20m',
  maxFiles: '14d',
});

logger.add(transport);

When NOT to Use This Skill

High-performance APIs: Use Pino instead - 10x faster than Winston
JSON-only logging: Pino is more optimized for structured JSON output
Serverless/Lambda: Prefer simpler console logging or Pino for lower overhead
Python/Java projects: Use language-specific logging frameworks
Simple scripts: Built-in console is sufficient for basic debugging

Anti-Patterns

Anti-Pattern	Why It's Bad	Solution
Synchronous file logging	Blocks event loop, degrades performance	Use async transports with `{ stream: ... }`
Logging objects without serialization	Can log `[Object]` instead of data	Use `JSON.stringify()` or Winston JSON format
No log rotation	Disk fills up in production	Use `winston-daily-rotate-file`
Logging in tight loops	Overwhelms I/O, fills disks	Add conditional logic or sample logs
String concatenation	Always evaluated, even when disabled	Use format strings: `logger.info('User %s', userId)`
Missing error stack traces	Loses debugging context	Use `{ error: err }` or Winston error format

Quick Troubleshooting

Issue	Cause	Solution
Logs not appearing	Wrong log level configured	Check `logger.level` and transport levels
Performance degradation	Synchronous file writes	Use async transports or reduce log verbosity
Disk full	No log rotation	Configure `winston-daily-rotate-file` with `maxFiles`
`[Object]` in logs	Improper object formatting	Use `winston.format.json()` or `winston.format.prettyPrint()`
Duplicate logs	Multiple transports to same destination	Review transport configuration
Colors not showing	Console transport missing colorize	Add `winston.format.colorize()` to console transport