better-logging

ログ記録の改善

重要な操作を、複数のログ行をたどるのではなく、1 回のクエリで「何が起きたか」を把握できる、永続的な構造化レコードにします。

計測の単位は、コードベース全体に散在する個々のログ文ではなく、ランタイムが管理する操作として扱います。

クイックスタート

• まず監査スクリプトを実行します。

python3 scripts/audit_queryable_outcomes.py \
  --root . \
  --format markdown

このスキルディレクトリから、同梱の scripts/audit_queryable_outcomes.py を実行します。必要に応じて、このスキルディレクトリ内の SKILL.md の場所を特定し、スクリプトのパスを明示して渡してください。

• コードを変更する前に、ランタイムのリファレンスを 1 つだけ読みます。
  • Electron、tRPC、IPC、デスクトップアプリのバックグラウンドジョブ：references/runtime-patterns-electron.md
  • Node の HTTP アプリとワーカー：references/runtime-patterns-node.md
• ミドルウェアやラッパーを作成する前に、references/event-schema.md を使って標準イベント形式を定義します。
• まず、ユーザーにとって重要な操作の上位 3 件を計測します。リポジトリ内のすべてのルートやコマンドから始めないでください。

ワークフロー

1. 操作の境界を洗い出します。 通常、トランスポートの境界が最も重要です。HTTP ハンドラー、tRPC プロシージャ、IPC コマンド、キューコンシューマー、cron ジョブ、起動フローなどです。 低レベルのヘルパー関数は、標準操作ではなく情報を補足する箇所として扱います。
2. 操作レコードの形式を決めます。 references/event-schema.md を読みます。 まず必須フィールドを確定します。操作名、種類、タイムスタンプ、所要時間、成功状態、安定したエラーコード、相関 ID、バージョンメタデータです。
3. 境界にラッパーを 1 つ追加します。 処理の開始時にレコードを作成します。 操作の実行中に情報を補足します。 finally で確定して永続化し、成功時と失敗時の両方で結果を出力します。
4. デバッグに役立つドメイン情報を追加します。 利用可能であれば、アクター、リソース、トリガー、ロールアウトフラグ、リトライ回数、バージョンデータを含めます。 ローカルでのデバッグにしか役立たないフィールドや、秘密情報を含むフィールドは省きます。
5. 結果を永続化するか、永続的な仕組みに出力します。 ローカルテーブル、運用イベントストア、クエリ可能な分析データのシンクを優先します。 重要な結果について、一時的なコンソールログやメモリ内バッファに依存しないでください。
6. 実際の質問を使って検証します。 references/rollout-and-queries.md を読みます。 新しい形式で障害、レイテンシ、リグレッションに関する質問へすばやく回答できない場合、計測はまだ不十分です。

ランタイムの選択

• Electron デスクトップアプリ： tRPC のミューテーション、ipcMain.handle、起動時のアクション、バックグラウンドジョブについては、references/runtime-patterns-electron.md を読みます。
• Node サーバーまたはワーカー： Express、Fastify、Hono スタイルのハンドラー、キュー、cron ジョブについては、references/runtime-patterns-node.md を読みます。

ガードレール

• 多数のログ行を散在させるより、重要な操作ごとに永続的な結果イベントを 1 つ記録することを優先します。
• error_code は安定していて、機械からクエリ可能な状態に保ちます。自由形式のメッセージは補助的な情報として扱います。
• すべての重要な操作について、所要時間とリトライ回数を記録します。
• 相関フィールドは早い段階で追加します。request_id、operation_id、session_id が欠けると、それ以降のすべてのクエリの有用性が低下します。
• 運用上の事実とプロダクト分析を分離します。両方への複製は問題ありませんが、置き換えはできません。
• 厳密に必要でない場合は、秘密情報、トークン、生のプロンプト、ユーザーコンテンツ、完全な URL をマスキングするか、ハッシュ化します。
• デフォルトで巨大なデータ塊を出力しないでください。代わりにポインターや要約したコンテキストを永続化します。

リソース

• scripts/audit_queryable_outcomes.py リポジトリをスキャンし、操作の境界、既存の計測、相関フィールド、永続的な結果のシグナルを見つけます。
• references/event-schema.md 必須フィールドと推奨フィールド、命名ガイダンス、マスキングルール。
• references/runtime-patterns-electron.md Electron、tRPC、IPC、起動フロー、バックグラウンドジョブにおける境界の選択とラッパーパターン。
• references/runtime-patterns-node.md HTTP アプリ、キューコンシューマー、cron ジョブにおける境界の選択とラッパーパターン。
• references/rollout-and-queries.md 段階的な導入計画、受け入れチェックリスト、新しい計測で回答できるようにする質問の例。