oodle-o11y-review

Oodle Telemetry Review — 左側オブザーバビリティ

コード変更に含まれるテレメトリーを、シニア SRE が PR をレビューする際の判断基準で確認します。このスキルは、インストルメンテーションの方法を教えるものではありません。最新のエージェントはすでに SDK を把握しています。見落としやすい判断を適用します。出力されるテレメトリーには、適切なカーディナリティで適切なビジネスコンテキストが含まれているか、重複していないか、重要な障害モードをカバーしているか、すでにこのコードを保護しているアラートのデバッグに十分かを確認します。

リポジトリ全体ではなく、差分をレビューします。指摘事項は O11y Change Context マニフェストに記録し、後続のトリアージで参照できるようにします。具体的な修正はここで説明し直すのではなく、既存の Oodle スキルに引き継ぎます。

使用する場面

• メトリクス、スパン、ログを追加または変更する変更をレビューまたは作成するとき。
• PR が、リクエストコンテキスト（テナント／アカウント／ユーザー）を引き継ぐ経路、または測定可能な処理（I/O、ループ、プール）を行う計測済みのコードやサービスコードに触れるとき。

ドキュメントのみ、または見た目だけの変更では、テレメトリーレビューを省略します。

バックエンドの検出（最初に実施）

ハードコードされたサーバー名ではなく、機能とツールの構成から、利用可能なオブザーバビリティバックエンドを特定します（名前は oodle-ai-us1、ap1、staging、dev、顧客固有の名前など、さまざまです）。

1. メトリクス／アラート／ログ／トレースのクエリツールを公開しているオブザーバビリティ MCP を探します。固定のプレフィックスではなく、ツールの機能（例：「モニターを検索する」「メトリクスをクエリする」「トレースを検索する」）からの検出を優先します。
2. ツール一式が Oodle の構成（モニター、PromQL クエリ、ログ、トレース、さらに load_skill__* ワークフロー）に一致する場合は、Oodle の短縮パスを使用します。対象サービスを管轄する環境を選び、適合するものがあれば load_skill__* を読み込みます。
3. 別のベンダーのオブザーバビリティ MCP がある場合は、その同等機能を使用します。
4. オブザーバビリティバックエンドを利用できない場合は、チェック 1～3 を実施します（差分から静的に確認できます）。チェック 4 は劣化していると明示して報告し、黙って省略しないでください。

チェック 1 — ビジネスコンテキストとカーディナリティの配置

リクエストコンテキストに ID（テナント、アカウント、ユーザー、組織）が含まれる場合、その ID はカーディナリティに応じた場所でテレメトリーに含める必要があります。

• 低カーディナリティ → メトリクスラベル。 ルート、メソッド、ステータスクラス、リージョン、ティア、キュー名など、値の集合が上限のあるものに限ります。これらは時系列の数を増やします。
• 高カーディナリティ → スパン属性とログフィールド。 tenant_id、account_id、user_id、order_id、request_id は、時系列を爆発的に増やすことなくデバッグ可能性を高める、これらの場所に含めます。
• ループとバッチでは、各反復の処理を追跡できるように、スパン／ログに反復またはバッチの識別子（item_index、sku、batch_id）を含める必要があります。

指摘事項：高カーディナリティの値がメトリクスラベルに含まれている場合（スパン属性またはログフィールドへの移動を推奨し、メトリクスがすでに配信済みなら oodle-drop-rules に引き継ぐ）；テナントスコープのコードで、テレメトリーにテナント／アカウントが含まれていない場合。

チェック 2 — テレメトリーの重複を避ける

追加するメトリクス、スパン、ログはそれぞれ異なる役割を果たす必要があります。新しいシグナルが既存のものと重複する場合（ヒストグラムと重複するタイマー、スパンの内容を言い換えるログ行、同じイベントを測定する 2 つのカウンターなど）は指摘します。削除を推奨してください。削除理由を添えた - 行として、マニフェストの telemetry フィールドに記録するか、そのシグナルを正当化する固有の目的を明示します。

シグナルの目的を 1 行で言い表せない場合は、追加すべきではありません。

チェック 3 — パフォーマンスカバレッジのパターン

変更したコードについて、パフォーマンスのリグレッションを検出するカバレッジを確認します。

• RED（リクエストハンドラー）— Rate（レート）、Errors（エラー）、Duration（継続時間）。ルート／メソッド別のレイテンシーヒストグラム、クラス別のエラーカウンターを確認します。
• USE（リソースプール）— Utilization（使用率）、Saturation（飽和度）、Errors（エラー）。DB／HTTP／スレッドプールについて、アクティブ数と最大数、待ち時間／キューの深さ、接続エラーを確認します。
• キューの飽和度（非同期処理）— 深さ、コンシューマーのラグ、処理時間を確認します。
• ファンアウト／N+1 — バッチ呼び出しもループを計測するスパンもないまま、反復ごとに I/O（DB、キャッシュ、RPC）を実行するループを確認します。該当する場合は指摘し、リスクをマニフェストの watch フィールドに記録します。

変更したコードでカバレッジが不足している場合は、ギャップとして報告します。変更していないコードのカバレッジは要求しません。

チェック 4 — アラートに基づく精査

ここが差別化要因です。本番環境で重視されているものに合わせて、レビューにかける労力を調整します。

1. バックエンドから、どのアラートと SLO が変更対象のコードを保護しているかを特定します（変更が影響するサービス／ルート／メトリクスに基づきます）。
2. 保護対象のコードについて、そのアラートをデバッグするために必要なテレメトリが存在することを求めます。どこで時間が費やされているかを特定するスパン／属性がない経路を保護するレイテンシーアラートは、対応不能なアラートであり、critical の指摘事項です。
3. 保護するアラートをマニフェストの guarded-by フィールドに記録し、変更のリスクを高く評価します（重大な SLO が関係する場合は、type を critical-path 寄りに引き上げます）。
4. 保護対象の障害モードに既知の盲点がある場合、トリアージで必要なデータがその問いに答えられないと分かるよう、マニフェストの gaps フィールドに追加します。

バックエンドに接続できない場合は、保護するアラートを特定できなかったことを明記し、作成者に手動での確認を勧めます。

出力に関する方針

• 確度の高い指摘事項だけを報告します。それぞれに critical／important／minor のタグを付けます。細かな指摘を大量に並べないでください。目標は、アラート疲れを避ける Oodle の理念に沿った、有用なシグナルを提供することです。
• 結果をマニフェストに記述します。O11y Change Context の仕様に従い、telemetry の目的、guarded-by、watch、gaps を記入または調整します。
• 具体的な修正方法を引き継ぎ、改めて説明しないでください。
  • 保護するモニターを追加または調整する → oodle-monitors
  • カーディナリティまたはボリュームの高いメトリクスを削除する → oodle-drop-rules
  • ログからメトリクスを導出する → oodle-log-metrics
• 何を変更するか、そしてそれがなぜ重要かを説明します。エージェントは、インストルメンテーションの記述方法をすでに理解しています。