monitoring-observability

監視とオブザーバビリティ

このスキルは、主な問いが 「どのようなパケットがあり、このシステムは何に気づくべきで、何が起きたら人に通知すべきか」 である場合に使用します。

目的は、Prometheus / Grafana / Datadog のチュートリアルを並べることではありません。 目的は、パケットの形式を整え、主要なオブザーバビリティのモードを1つ選び、役に立つ最小限のシグナル計画を定義し、このスキルがデバッグ、パフォーマンスチューニング、ロールアウトの実行、分析レポートへと広がる前に、関連する作業を別の担当へ振り分けることです。

内容に不慣れなパケットを扱う前に、references/intake-packets-and-route-outs.md を読んでください。 テレメトリーの設定、インシデント診断、プロダクト分析が混在した依頼を扱う前に、references/modes-and-boundaries.md を読んでください。 ダッシュボード、アラート、担当の不明確な部分を確認する際は、references/alert-dashboard-checklist.md を読んでください。 ロールアウトの最小範囲を選ぶ際は、references/telemetry-rollout-matrix.md を読んでください。

このスキルを使用する場合

• 新しいサービス、ワーカー、API、または複数サービスで構成されるシステムについて、リリース前に健全性シグナル、アラート、ダッシュボード、SLO 形式のカバレッジが必要な場合
• 既存のスタックにダッシュボード、アラート、テレメトリーがあるものの、信頼性が低く、維持／修正／削除／追加の監査が必要な場合
• ベンダーやバックエンドの詳細を選ぶ前に、何を計装し、相関付けし、保持し、サンプリングするかをチームで決める必要がある場合
• データ、マーケティング、分析、パイプラインの作業で、手動の信頼性確認を増やすのではなく、鮮度／スキーマ／量／リネージの監視が必要な場合
• ゲームやライブ運用の作業で、エンジンプロファイラーの解釈に踏み込まず、クラッシュ、セッション、ビルド、ローンチイベントを可視化する必要がある場合
• バックエンド、プロダクト／運用、マーケティングパイプライン、ゲームのライブ運用にまたがる信頼性の依頼で、次の担当者がまだ不明な場合

このスキルを使用しない場合

• パケットの中心がログで、最初に対処すべき障害を見つける作業である場合 → log-analysis
• コードのバグやリグレッションについて、再現 → 切り分け → 検証を行う作業である場合 → debugging
• 測定値がすでにあり、主な作業がボトルネックの特定やチューニングである場合 → performance-optimization
• 主な作業がリリースの実行、プロモーション、ロールバック、デプロイ後の手順調整である場合 → deployment-automation
• LLM 固有のトレース、評価、プロンプトのオブザーバビリティに関する作業である場合 → langsmith
• Unity/Unreal/Godot のフレーム時間の取得データを解釈する作業である場合 → game-performance-profiler
• キュレーション済みの BigQuery データを使った、純粋なダッシュボード／レポートの表示作業である場合 → looker-studio-bigquery

手順

ステップ 1：パケットの概要を把握する

ツールを推奨する前に、必要最小限の受付情報を記録してください。

次の情報を収集します。

• 対象：サービス/API | ワーカー／キュー | データ／パイプライン | ダッシュボード／監査 | ゲーム／ライブ運用 | 混在 | 不明
• 依頼の種類：新規設定 | レビュー／監査 | インシデントのフォローアップ | 移行 | リリース準備 | 不明
• 現在のパケット：アーキテクチャに関するメモ | アラートルール | ダッシュボード一覧 | インシデントの概要 | テレメトリー設定 | 古いレポートへの不満 | クラッシュ／セッション概要 | なし
• ユーザー／ビジネスへの影響：レイテンシ | エラー | データの古さ | 可視性の欠如 | クラッシュ／セッションのリスク | 通知の多さ | 不明
• 担当：アプリチーム | プラットフォーム／SRE | データ／運用 | ライブ運用 | 共有 | 不明

概要の枠組み：

Surface: data/pipeline
Request type: review/audit
Current packet: stale dashboard complaint + job ownership notes
Impact: stale data and trust erosion
Ownership: data/ops + dashboard consumer owner

ステップ 2：受付パケットを起点にする

references/intake-packets-and-route-outs.md を使用してください。

ユーザーが現在実際に持っているパケットを選びます。

• サービス／信頼性パケット
• テレメトリー基盤パケット
• データ／パイプラインパケット
• レビュー／監査パケット
• ゲーム／ライブ運用パケット
• まだ使えるパケットがない

このステップの出力：

## Intake Packet
- Current packet:
- Why it is enough (or not enough):
- Missing context to collect next:

ルール：現在のパケットによって次の判断がすでに絞り込まれている場合は、ベンダー比較やテレメトリースタックの全面的な置き換えを無理に進めないでください。

ステップ 3：主要な可観測性モードを 1 つ選ぶ

references/modes-and-boundaries.md から主要モードを 1 つ選びます。

主要モード：

• service-reliability
• telemetry-foundation
• data-pipeline-observability
• game-liveops-visibility
• review-gap-audit
• unknown-needs-better-packet

ルール：主要モードは 1 つ、必要に応じて副次モードを追加します。 ローンチ時のテレメトリ、古くなったダッシュボードの監査、クラッシュの可視化、汎用的な計装を 1 つの回答に混在させないでください。

ステップ 4：中核となる監視上の問いを明確にする

ツールやメトリクスを列挙する前に、システムが何に答えなければならないかを述べます。

良い例：

• 「ユーザーが目にする API の不具合を、顧客から報告される前に検知して通知できますか？」
• 「月曜の成長ダッシュボードが古くなったとき、古くなった理由と修正担当者が分かりますか？」
• 「ローンチイベントのクラッシュをビルド／プラットフォーム別にグループ化し、SNS での報告が急増する前にエスカレーションできますか？」
• 「現在のアラートは、対応者を有用なダッシュボード／ランブック 1 つに誘導していますか。それとも、ノイズの多い症状 3 つに誘導していますか？」

「より良い監視を設定する」のような曖昧な表現は避けてください。

ステップ 5：最小限のシグナル計画を 1 つ作成する

references/telemetry-rollout-matrix.md を使用します。

選択したモードについて、次を定義します：

• ダッシュボード／アラート経路が答えるべき主な問い
• エビデンスの対象：メトリクス、ログ、トレース、ブラックボックスチェック、クラッシュツール、鮮度チェック、リネージュビュー
• 直ちに通知するしきい値、後でチケットにするしきい値、ダッシュボードのみで扱うしきい値
• 各アラートまたはダッシュボード群の担当者
• 最初に実装する 1～3 個のスライスのみ

ルール：

• 内部原因より先に症状をアラートします。
• 同じインシデントについて、スタックの各レイヤーから多数のページを送るより、明確なページを 1 つ送ることを優先します。
• ラベルの種類を制限し、高カーディナリティの詳細はログ／トレースに含めます。
• アラートで人の対応を求める場合は、ランブック／ダッシュボードへのリンクを含めます。
• アラートの配信が気付かれずに失敗する可能性がある場合、メタ監視を最優先事項として扱います。

ステップ 6：引き継ぎ先を明示する

作業の内容が変わったら、適切な担当へ引き継ぎます。

一般的な引き継ぎ先：

• 根本原因のログフォレンジック → log-analysis
• 正確性を優先した回帰調査 → debugging
• ボトルネックの診断またはチューニング → performance-optimization
• リリース実行／デプロイ後のロールバック手順 → deployment-automation
• LLM のトレース／評価／プロンプトの可観測性 → langsmith
• KPI の解釈／ステークホルダー向けエビデンスの要約 → data-analysis
• BigQuery を利用したダッシュボードのプレゼンテーション層 → looker-studio-bigquery
• エンジンプロファイラーの解釈 → game-performance-profiler

ステップ 7：可観測性ブリーフを返す

# Observability Brief

## Scope
- Surface:
- Request type:
- Intake packet:
- Primary mode:
- Confidence:

## Core Monitoring Question
- ...

## Signal Plan
- Metrics / checks:
- Logs / traces / crash context:
- Dashboards / views:
- Alert policy:

## Ownership
- Primary owner:
- Secondary owner(s):

## First Implementation Slice
1. ...
2. ...
3. ...

## Route-outs
- ...

例

例 1：ローンチ前の新しい API

入力：「来週、新しい API をローンチします。何を計装し、何を通知対象にすべきか教えてください。」

期待される形式： service-reliability に分類し、現在のローンチ／準備状況パケットを使用します。RED／ゴールデンシグナルに関する問いとブラックボックスのカバレッジ、通知しきい値、最小限のロールアウトスライスを 1 つ定義します。

例 2：成長ダッシュボードが頻繁に古くなる

入力：「月曜朝の成長ダッシュボードは半分くらいの頻度で古くなります。別のスプレッドシートチェックではなく、可観測性が必要です。」

期待される形式： data-pipeline-observability に分類し、鮮度／スキーマ／ボリューム／リネージュ／担当者を扱います。また、ダッシュボードの信頼性チェックと KPI の解釈作業を区別します。

例 3：レビュー／ギャップ監査

入力：「アラートやダッシュボードは大量にありますが、誰も信頼していません。何を残して、何を削除すべきですか？」

期待される形式： review-gap-audit に分類し、アラート／ダッシュボードのチェックリストを使用します。維持／修正／削除／追加の判断を示し、ノイズの多いページ、担当者のいないパネル、欠けているメタ監視を指摘します。

例 4：ロールアウト実行への引き継ぎ

入力：「デプロイしたばかりです。ヘルスチェックを含む、ロールバック／昇格の手順を段階的に示したチェックリストが必要です。」

期待される形式： 実行ワークフローを deployment-automation に引き継ぎ、必要に応じてデプロイ後に重要となる可観測性の問いをいくつか示します。

例 5：ログのフォレンジック分析への振り分け

入力：「こちらが障害のログです。根本原因を見つけてください。」

**期待される対応：**これをメインのワークフローとして使わず、log-analysis に振り分けます。最初に対応可能な障害が特定されてから、可観測性に関する追加対応のみを提案します。

ベストプラクティス

1. ベンダーではなく、パケットと中核となる監視上の問いから始めます。
2. 主なモードを1つに絞り、実装範囲は最小限の単位にします。
3. あらゆる原因ではなく、症状に対してアラートを設定します。
4. 担当者、ランブック、ダッシュボードへのリンクを明確にします。
5. データの陳腐化やパイプラインの信頼性を、可観測性の主要な取り組みとして扱います。
6. ゲームのライブ運用に関する可視性と、エンジンプロファイラーの解釈を分けます。
7. レビュー／監査では、実態に即した対応を徹底します。使用されていないダッシュボードやノイズの多いアラートは、記録するだけでなく削除します。
8. 最初にユーザーが接する境界が変わるたびに、簡潔なディスカバリー用サーフェスを同期します。

参考資料

• Google SRE — 分散システムの監視
• OpenTelemetry — 可観測性の入門
• Prometheus — アラート
• Grafana — ダッシュボードのベストプラクティス