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

バージョン: 1.0.0

目的

このスキルは、アプリケーションで効果的なロギングを実装するためのガイドラインを提供します。ワイドイベント(正規ログラインとも呼ばれる)に焦点を当てています。これはリクエストごとサービスごとに単一の文脈豊富なイベントを発行するパターンで、強力なデバッグと分析を実現します。

適用時期

以下の場合にこれらのガイドラインを適用してください：

• ロギングコードを書いたり、レビューしたりする場合
• console.log、logger.info またはそれ以外を追加する場合
• 新しいサービスのロギング戦略を設計する場合
• ロギングインフラストラクチャをセットアップする場合

コアプリンシプル

1. ワイドイベント（最重要）

リクエストごとサービスごとに1つの文脈豊富なイベントを発行します。ハンドラー全体にログ行を散らすのではなく、リクエスト完了時に発行される単一の構造化イベントにすべてを統合してください。

const wideEvent: Record<string, unknown> = {
  method: 'POST',
  path: '/checkout',
  requestId: c.get('requestId'),
  timestamp: new Date().toISOString(),
};

try {
  const user = await getUser(c.get('userId'));
  wideEvent.user = { id: user.id, subscription: user.subscription };

  const cart = await getCart(user.id);
  wideEvent.cart = { total_cents: cart.total, item_count: cart.items.length };

  wideEvent.status_code = 200;
  wideEvent.outcome = 'success';
  return c.json({ success: true });
} catch (error) {
  wideEvent.status_code = 500;
  wideEvent.outcome = 'error';
  wideEvent.error = { message: error.message, type: error.name };
  throw error;
} finally {
  wideEvent.duration_ms = Date.now() - startTime;
  logger.info(wideEvent);
}

2. 高カーディナリティ & 高次元性（最重要）

高カーディナリティ(ユーザーID、リクエストID - 数百万の一意な値)と高次元性(イベントごとの多くのフィールド)を持つフィールドを含めてください。これにより、特定のユーザーで照会し、まだ予想していない質問に答えることができます。

3. ビジネスコンテキスト（最重要）

常にビジネスコンテキストを含めてください：ユーザーのサブスクリプション層、カート値、フィーチャーフラグ、アカウント年齢。目標は「プレミアム顧客が$2,499の購入を完了できなかった」を知ることであり、単に「チェックアウトが失敗した」ではなく。

4. 環境特性（最重要）

すべてのイベントに環境とデプロイメント情報を含めてください：コミットハッシュ、サービスバージョン、リージョン、インスタンスID。これにより、問題をデプロイメントと相関させ、リージョン固有の問題を特定できます。

5. 単一のロガー（高）

スタートアップで設定された1つのロガーインスタンスを使用し、どこにでもインポートしてください。これにより、一貫したフォーマットと自動的な環境コンテキストが確保されます。

6. ミドルウェアパターン（高）

ミドルウェアを使用してワイドイベントインフラストラクチャ(タイミング、ステータス、環境、発行)を処理してください。ハンドラーはビジネスコンテキストのみを追加する必要があります。

7. 構造と一貫性（高）

• JSON フォーマットを一貫して使用する
• サービス間でフィールド名の一貫性を保つ
• ログレベルを info と error の2つに簡潔にする
• 非構造化文字列をログに記録しない

回避すべきアンチパターン

1. 散らばったログ：リクエストごとに複数の console.log() 呼び出し
2. 複数のロガー：異なるファイルに異なるロガーインスタンス
3. 環境コンテキストの欠落：コミットハッシュやデプロイメント情報がない
4. ビジネスコンテキストの欠落：ユーザー/ビジネスデータなしで技術的詳細をログに記録
5. 非構造化文字列：構造化データの代わりに console.log('something happened')
6. スキーマの不一貫性：サービス間で異なるフィールド名

ガイドライン

ワイドイベント (rules/wide-events.md)

• サービスホップごとに1つのワイドイベントを発行する
• すべての関連コンテキストを含める
• リクエストIDでイベントを接続する
• リクエスト完了時にfinally ブロックで発行する

コンテキスト (rules/context.md)

• 高カーディナリティフィールド(user_id、request_id)をサポートする
• 高次元性(多くのフィールド)を含める
• 常にビジネスコンテキストを含める
• 常に環境特性(commit_hash、version、region)を含める

構造 (rules/structure.md)

• コードベース全体で単一のロガーを使用する
• 一貫したワイドイベントにミドルウェアを使用する
• JSON フォーマットを使用する
• スキーマの一貫性を保つ
• ログレベルを info と error に簡潔にする
• 非構造化文字列をログに記録しない

一般的な落とし穴 (rules/pitfalls.md)

• リクエストごとに複数のログ行を回避する
• 未知の未知に対応する設計をする
• サービス間でリクエストIDを常に伝播させる

参考資料：

• Logging Sucks
• Observability Wide Events 101
• Stripe - Canonical Log Lines