ロギングベストプラクティス

目次

• 概要
• 使用場面
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

アプリケーション全体で構造化された安全で高性能なロギングを実装するための包括的なガイド。ログレベル、構造化ログ形式、文脈情報、PII保護、および集中ロギングシステムについて説明しています。

使用場面

• アプリケーションログインフラストラクチャのセットアップ
• 構造化ロギングの実装
• 異なる環境用のログレベルの構成
• ログ内の機密データの管理
• 集中ロギングのセットアップ
• 分散トレーシングの実装
• 本番環境の問題のデバッグ
• ロギング規制への準拠

クイックスタート

最小限の動作例：

// logger.ts
enum LogLevel {
  DEBUG = 0, // Detailed information for debugging
  INFO = 1, // General informational messages
  WARN = 2, // Warning messages, potentially harmful
  ERROR = 3, // Error messages, application can continue
  FATAL = 4, // Critical errors, application must stop
}

class Logger {
  constructor(private minLevel: LogLevel = LogLevel.INFO) {}

  debug(message: string, context?: object) {
    if (this.minLevel <= LogLevel.DEBUG) {
      this.log(LogLevel.DEBUG, message, context);
    }
  }

  info(message: string, context?: object) {
    if (this.minLevel <= LogLevel.INFO) {
      this.log(LogLevel.INFO, message, context);
    }
  }

  warn(message: string, context?: object) {
// ... (see reference guides for full implementation)

リファレンスガイド

references/ ディレクトリの詳細な実装：

ガイド	内容
Log Levels	ログレベル
Structured Logging (JSON)	構造化ロギング (JSON)
Contextual Logging	文脈ロギング
PII and Sensitive Data Handling	PII および機密データの処理
Performance Logging	パフォーマンスロギング
Centralized Logging	集中ロギング
Distributed Tracing	分散トレーシング
Log Sampling (High-Volume Services)	ログサンプリング (高ボリュームサービス)

ベストプラクティス

✅ DO

• 本番環境では構造化ロギング (JSON) を使用する
• すべてのログに correlation/request ID を含める
• 適切なレベルでログを記録する (DEBUG を過度に使用しない)
• 機密データ (PII、パスワード、トークン) をマスクする
• 文脈情報 (userId、requestId など) を含める
• エラーは完全なスタックトレース付きでログする
• 分散システムでは集中ロギングを使用する
• ディスク容量を管理するためにログローテーションをセットアップする
• ログボリュームとコストを監視する
• パフォーマンスのために非同期ロギングを使用する
• ISO 8601 形式のタイムスタンプを含める
• ビジネスイベント (ユーザーアクション、トランザクション) をログする
• エラーパターンのアラートをセットアップする

❌ DON'T

• パスワード、トークン、または機密データをログしない
• 本番環境で console.log を使用しない
• デフォルトで本番環境で DEBUG レベルでログしない
• タイトループ内でログしない (サンプリングを使用する)
• 匿名化なしで PII を含めない
• ログローテーションを無視しない (ディスクが満杯になる)
• ホットパスで同期ロギングを使用しない
• 不要なままに複数のトランスポートにログしない
• エラースタックトレースを含め忘れない
• バイナリデータまたは大きなオブジェクトをログしない
• 文字列連結を使用しない (構造化フィールドを使用する)
• 高ボリュームAPI内のすべてのリクエストをログしない