winston

Winston Logger - クイックリファレンス

このスキルを使用する場面

• 複数のトランスポート（ファイル、コンソール、HTTP）を使ったロギング
• カスタムレベルを使った構造化ロギング
• ログファイルの自動ローテーション

詳細情報：包括的なドキュメントを参照するには、technology: winston を指定して mcp__documentation__fetch_docs を使用してください。

基本設定

npm install winston

重要なパターン

ロガーの基本

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

カスタムフォーマット

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()],
});

子ロガー

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

日次ローテーションファイル

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

このスキルを使用しない場面

• 高パフォーマンスの API：代わりに Pino を使用してください。Winston より 10 倍高速です
• JSON のみのロギング：構造化 JSON 出力には Pino のほうが最適化されています
• サーバーレス／Lambda：オーバーヘッドを抑えるには、よりシンプルなコンソールロギングまたは Pino を推奨します
• Python／Java プロジェクト：言語固有のロギングフレームワークを使用してください
• シンプルなスクリプト：基本的なデバッグには組み込みの console で十分です

アンチパターン

アンチパターン	問題点	解決策
同期的なファイルロギング	イベントループをブロックし、パフォーマンスを低下させます	{ stream: ... } を使った非同期トランスポートを使用してください
オブジェクトをシリアライズせずにロギングする	データの代わりに [Object] が記録されることがあります	JSON.stringify() または Winston の JSON フォーマットを使用してください
ログローテーションをしない	本番環境でディスクがいっぱいになります	winston-daily-rotate-file を使用してください
頻繁なループ内でロギングする	I/O に過剰な負荷がかかり、ディスクがいっぱいになります	条件分岐を追加するか、ログをサンプリングしてください
文字列連結	無効になっている場合でも常に評価されます	フォーマット文字列を使用してください：logger.info('User %s', userId)
エラースタックトレースがない	デバッグに必要な情報が失われます	{ error: err } または Winston のエラーフォーマットを使用してください

トラブルシューティングのクイックガイド

問題	原因	解決策
ログが表示されない	ログレベルの設定が誤っています	logger.level とトランスポートのレベルを確認してください
パフォーマンスの低下	同期的なファイル書き込み	非同期トランスポートを使用するか、ログの詳細度を下げてください
ディスクがいっぱい	ログローテーションがありません	maxFiles を指定して winston-daily-rotate-file を設定してください
ログに [Object] が表示される	オブジェクトのフォーマットが不適切です	winston.format.json() または winston.format.prettyPrint() を使用してください
ログが重複する	同じ出力先を指すトランスポートが複数あります	トランスポートの設定を確認してください
色が表示されない	コンソールトランスポートに colorize がありません	コンソールトランスポートに winston.format.colorize() を追加してください