logging-best-practices

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

目次

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

概要

アプリケーション全体で、構造化され、安全で、高いパフォーマンスを発揮するロギングを実装するための包括的なガイドです。ログレベル、構造化ログの形式、コンテキスト情報、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/ ディレクトリを参照してください。

ガイド	内容
ログレベル	ログレベル
構造化ログ（JSON）	構造化ログ（JSON）
コンテキストロギング	コンテキストロギング
PII と機密データの取り扱い	PII と機密データの取り扱い
パフォーマンスロギング	パフォーマンスロギング
集中ログ管理	集中ログ管理
分散トレーシング	分散トレーシング
ログサンプリング（大量トラフィックのサービス）	ログサンプリング（大量トラフィックのサービス）

ベストプラクティス

✅ 推奨事項

• 本番環境では構造化ログ（JSON）を使用します
• すべてのログに相関 ID／リクエスト ID を含めます
• 適切なレベルでログを記録します（DEBUG の多用は避けます）
• 機密データ（PII、パスワード、トークン）をマスキングします
• コンテキスト（userId、requestId など）を含めます
• エラーは完全なスタックトレースとともに記録します
• 分散システムでは集中ログ管理を使用します
• ディスク容量を管理するため、ログローテーションを設定します
• ログの量とコストを監視します
• パフォーマンス向上のため、非同期ロギングを使用します
• ISO 8601 形式のタイムスタンプを含めます
• ビジネスイベント（ユーザー操作、トランザクション）を記録します
• エラーパターンに対するアラートを設定します

❌ 禁止事項

• パスワード、トークン、その他の機密データを記録しないでください
• 本番環境で console.log を使用しないでください
• 本番環境では、デフォルトで DEBUG レベルのログを記録しないでください
• タイトなループ内でログを記録しないでください（サンプリングを使用します）
• 匿名化せずに PII を含めないでください
• ログローテーションを無視しないでください（ディスクがいっぱいになります）
• ホットパスで同期ロギングを使用しないでください
• 必要がないのに複数のトランスポートへログを出力しないでください
• エラーのスタックトレースを必ず含めてください
• バイナリデータや大きなオブジェクトを記録しないでください
• 文字列連結を使用せず、構造化フィールドを使用してください
• トラフィック量の多い API ですべてのリクエストを記録しないでください