qa-observability

QA オブザーバビリティ

テレメトリーをQAのシグナルおよびデバッグの基盤として活用します。ログ、メトリクス、トレース、プロファイルを、テスト結果、リリースの準備状況、本番環境のリグレッションを判断する証拠として扱います。

主要なリファレンスは data/sources.json にあります。Navigation からタスク固有のガイドを読み込んでください。

クイックスタート（デフォルト）

重要なコンテキストが不足している場合は、重要なユーザージャーニー、サービス／依存関係の一覧、環境（ローカル／ステージング／本番）、現在のテレメトリースタック、現在のSLO／SLAコミットメントを確認してください。

1. 最低限の基準を確立します。相関ID、構造化ログ、トレース、ゴールデンメトリクス（レイテンシー、トラフィック、エラー、飽和度）を用意します。
2. 既知のリクエストまたは障害を1つ使い、テレメトリーの伝送を検証します。アプリケーションからの出力、コンテキストの伝播、コレクターでの受け入れ、バックエンドでのクエリを確認します。主張は最後に観測できた段階までにとどめてください。静的なSDKまたはコレクターの設定で証明できるのは、設定のみです。
3. 障害の診断を可能にします。すべての統合テストまたはE2Eテストの失敗で、トレースへのリンクまたはトレースIDと、それに相関するログを取得できるようにします。また、重要な縮退経路では、レート制限コード、再試行のヒント、状態遷移マーカーなどの構造化エラーメタデータを公開します。
4. ダッシュボード、SLO、アラートが対象に含まれる場合は、関連するSLI／SLOとエラーバジェットポリシーを定義し、ダッシュボードが既知のテレメトリーを選択することを検証します。さらに、合成条件と管理された非本番の通知先を使って、アラートの評価とルーティングをテストします。明示的な許可なしに、実際の対応担当者へ通知しないでください。バックエンドクエリ、ダッシュボードでの選択、ルール評価、ルート、配信の結果を個別に記録します。基本的なインストルメンテーションでは、バックエンドクエリの証明までで終了してかまいません。
5. タスクに合った成果物を作成します。準備状況チェックリスト、SLO定義、またはアラートルールには、assets/checklists/template-observability-readiness-checklist.md、assets/monitoring/slo/slo-definition.yaml、assets/monitoring/slo/prometheus-alert-rules.yaml を使用します。環境、サービスのリビジョン、トレース／リクエストID、クエリ期間、サンプリングの判断、実施した各段階の結果を保持してください。

QAの基本方針

• テレメトリーを受け入れ基準として扱います。特に統合テストとE2Eフローでは必須です。
• 相関を必須とします。サービス境界を越えてリクエストIDとトレースIDを引き継ぎます。
• 重要なジャーニーでは、認証リダイレクト、レート制限、状態同期の遅延を、内容が不透明なテキストのみのエラーではなく、構造化コードまたは属性で診断できるようにします。
• 生のインフラストラクチャーしきい値よりも、SLOベースのリリースゲートとバーンレートアラートを優先します。
• サンプリング、カーディナリティ、保持期間、コストを品質上の制約として扱います。
• ログ、スパン、属性では、デフォルトでPIIとシークレットをマスキングします。
• カスタム属性名ではなく、OpenTelemetryのセマンティック規約を使用します。また、ビジネスワークフローの境界に手動でスパンを追加します。自動インストルメンテーションだけでは、これらの境界は示されません。
• OpenTelemetryでは、ログとプロファイルの対応状況はエコシステムに依存するものとして扱います。ベンダー中立な実装を約束する前に、言語とバックエンドの対応状況を確認してください。
• OTel Span Events API（Span.AddEvent、Span.RecordException）は、ログベースのイベントに置き換えるため非推奨になります（OTelブログ）。新しいイベントのインストルメンテーションにはLogs APIを使用してください。段階的な移行期間中も、既存のスパンイベントデータは引き続き機能します。

専門家の判断（チェックリストでは見落とすこと）

• テレメトリーの欠落： 重要なジャーニーを1つ選び、構造化リクエストログ、その入口でのゴールデンメトリクス、伝播されるトレースから始めます。ダッシュボードやアラートを証拠として使う前に、既知のリクエストをクエリします。
• ログかトレースか： リクエストの因果関係とレイテンシにはトレース、ビジネス状態の遷移にはログ、レートとパーセンタイルにはメトリクスを使用します。ログやトレースを永続的な記録として扱う前に、保持期間、サンプリング、監査要件を確認します。
• サンプリング： テールサンプリングで保持できるのは、サンプラーに到達したスパンのみです。ヘッドで破棄されたトレースは下流で復元できません。トレース内のすべてのスパンを同じテールサンプリングコレクターにルーティングし、バッファリングを考慮します。SLI にはサンプリングされていないリクエストメトリクスを使用します。設定上の制約については、OpenTelemetry のサンプリングと references/sampling-strategies.md を参照してください。
• ページング： 重複する症状を、実行可能な SLO アラートに集約します。ページの負荷と対応の品質を測定し、普遍的なアラート件数の上限ではなく、サービスの人員配置とエラーバジェットのポリシーに従います。references/alerting-strategies.md を参照してください。
• カーディナリティ： ユーザー ID や生のパスなどのメトリクスラベルに上限を設けます。バックエンドのコストはシグナルとストレージ設計によって異なります。保持期間と取り込み予算を明示したうえで、有用なログやトレースのディメンションを意図的に保持します。規模を見積もる前に、選択したバックエンドの課金対象ディメンションと制限を調べます。
• デバッグの境界： テレメトリーを使って、影響を受けたコンポーネントとリクエストのコンテキストを特定します。その後、コードレベルの実行証拠が必要な場合はデバッガーを使用します。

ワークフロー

1. ベースラインを確立します。ログ、メトリクス、トレース、相関関係、および少なくとも1つの診断可能な重要なジャーニーを用意します。
2. OpenTelemetry で計装します。まず自動計装を行い、その後、ビジネスワークフローの境界に手動のスパンを追加します。
3. HTTP、キュー、RPC の境界をまたいでコンテキストが伝播することを確認します。
4. 正規のバーンレート表に基づいて、SLI／SLO、エラーバジェット、バーンレートアラートを定義します。この表では、トラフィックの少ないサービスも扱っています。
5. 障害を診断可能にします。失敗したテストに、トレースへのリンク、主要なログ、関連するメトリクスを添付します。
6. テレメトリーの信頼性を確認してから、パフォーマンスの証拠を追加します。プロファイリング、負荷テスト、エグザンプラー、ベースラインなどです。

クイックリファレンス

タスク	推奨されるデフォルト	備考
トレーシング	OpenTelemetry + Collector + OTLP 互換バックエンド	Jaeger と Tempo はどちらも適したバックエンドです。デフォルトのルーティングレイヤーとして Collector を維持してください
メトリクス	Prometheus + Grafana	レイテンシのヒストグラムを使用してください。デプロイ済みバージョンのスクレイプとストレージの設定については、ネイティブヒストグラムのドキュメントを確認してください。ロールアウトはインフラストラクチャの変更として扱い、まずダッシュボードとアラートをテストしてください
ログ記録	stdout/stderr への構造化 JSON 出力 + Collector/filelog パイプライン	シークレットやカーディナリティの高い ID をラベルとして記録しないでください。OTel Logs SDK の成熟度は言語によって異なるため、SDK から直接利用する方法を採用する前にステータスページを確認してください
信頼性のゲート	SLI/SLO + エラーバジェット + バーンレートアラート	バーンが継続している場合や、重大なリグレッションがある場合はリリースをブロックしてください
パフォーマンス	継続的プロファイリング + 負荷テスト + バジェット	本番環境で安定したプロファイリングを行うには、Pyroscope または Parca を使用してください。本番環境で重要な用途に使用する前に、OTel Profiles のステータスを確認し、references/performance-profiling-guide.mdを参照してください
コード変更不要の可視性	実現可能な場合は eBPF ベースの計装	Beyla/OBI を選択する前に、Beyla のセットアップ要件と選択したリリースを確認し、カーネル、権限、ランタイム、バックエンドとの互換性を確認してください
LLM / AI エージェントの可視性	OTel GenAI semconv + コストメトリクス + 評価イベント	GenAI の規約はgithub.com/open-telemetry/semantic-conventions-genaiにあります。リリース前にリポジトリで安定性ステータスを確認し、semconv のバージョンを固定してください。また、名称変更が発生する可能性を考慮してください。エージェントのトレースと評価については、references/tools-ebpf-apm.mdとai-coding-agents-observability-evalsを参照してください

ナビゲーション

必要に応じて、以下のガイドを開いてください：

ユーザーが必要としているもの	読む資料	併せて使用するもの
本番環境向けの最小限のベースライン	references/core-observability-patterns.md	assets/checklists/template-observability-readiness-checklist.md
最新の Node または Python の計装	references/opentelemetry-best-practices.md	assets/opentelemetry/nodejs/opentelemetry-nodejs-setup.md、assets/opentelemetry/python/opentelemetry-python-setup.md
サービス間で機能するトレース伝播	references/distributed-tracing-patterns.md	assets/checklists/template-observability-readiness-checklist.md
SLO、バーンレートアラート、リリースゲート	references/slo-design-guide.md（標準のバーンレート表）	assets/monitoring/slo/slo-definition.yaml、assets/monitoring/slo/prometheus-alert-rules.yaml、ルールテスト（promtool test rules）、assets/monitoring/grafana/grafana-dashboard-slo.json
テレメトリーとしてのプロファイル（継続的プロファイリング、エグザンプラー、OTel Profiles）	references/performance-profiling-guide.md	診断：software-performance；負荷テスト：qa-testing-performance；スターターアセット：assets/performance/backend/template-nodejs-profiling-config.js、assets/performance/frontend/template-lighthouse-ci.json、assets/load-testing/load-testing-k6.js、assets/load-testing/template-load-test-artillery.yaml
成熟度モデルとロードマップ	references/observability-maturity-model.md	assets/checklists/template-observability-readiness-checklist.md
避けるべきこととその修正方法	references/anti-patterns-best-practices.md	assets/checklists/template-observability-readiness-checklist.md
アラート設計と疲弊の軽減	references/alerting-strategies.md	assets/monitoring/slo/prometheus-alert-rules.yaml
ダッシュボードの階層とレイアウト	references/dashboard-design-patterns.md	assets/monitoring/grafana/template-grafana-dashboard-observability.json
構造化ログとコスト管理	references/log-aggregation-patterns.md	assets/observability/template-logging-setup.md
RED、USE、Golden Signals の比較 — メトリクスフレームワークの選択	references/methods-red-use-golden.md	references/slo-design-guide.md
サンプリング戦略、テールサンプリング、エグザンプラー	references/sampling-strategies.md	references/opentelemetry-best-practices.md
eBPF と APM ツールのスタブ（Beyla、Pixie、Honeycomb、SigNoz、Coroot）、LLM／AI エージェントの可観測性	references/tools-ebpf-apm.md	data/sources.json
仮説も再現手順もない本番環境の異常のデバッグ	references/core-analysis-loop.md	../qa-debugging/references/production-debugging-patterns.md
テレメトリーに応用する信頼性理論、待ち行列理論、制御理論、情報理論	references/reliability-theory-applied.md、references/queueing-theory-applied.md、references/control-theory-applied.md、references/information-theory-applied.md	該当する foundations-* スキル
厳選した情報源：data/sources.json。

避けること

• シークレットやカーディナリティの高い ID をメトリクスのラベルとして記録する
• セマンティック規約が存在するのに、独自の属性名を考案する
• サンプリングとカーディナリティの方針を定めずに計装を追加する
• ビジネスワークフローの可視性を自動計装だけに頼ること。重複するルートスパンではなく、ビジネスワークフローの境界に手動でスパンを追加する
• 記憶だけを頼りにベンダーを選ぶこと。data/sources.json を起点に、最新のドキュメントやリリースを確認する

スクリプト

Python 3.9 以降で実行できる、標準ライブラリのみを使用する Python CLI ツールです。回帰テストには pytest が必要です。

スクリプト	用途
scripts/observability_scorer.py	成熟度のスコアリング、SLO エラーバジェット分析、レディネスレポートの生成

スコアラーが受け付けるのは、完全なウィンドウの SLO 測定値のみです。ステータスのしきい値はローカルのヒューリスティックであり、複数ウィンドウにわたるページングの判断には使用しません。target_pct には 0 より大きく 100 より小さい値、window_days には正の整数を指定してください。また、整数のイベント数（total_events は正の値、0 <= good_events <= total_events）を両方指定するか、0～100 の範囲内の明示的な有限値 current_availability_pct を指定してください。イベント数を指定した場合、入力された割合より優先されます。イベント数が 0 の場合、正常性を判断できません。割合のみを指定した入力では、残りのイベントバジェットは不明です。成熟度スコアは自己評価として入力するものであり、実行時の証明ではありません。指定した各ディメンションには、ドキュメントに記載された範囲内の整数スコアが必要です。必須入力が無効または不足している場合は、エラーになります。

回帰テスト：scripts/test_observability_scorer.py。python3 -m pytest scripts/test_observability_scorer.py を実行してください。保存済みの実装と比較する場合は、OBSERVABILITY_SCORER_SCRIPT に別のスクリプトパスを設定します。

クイックスタート：

# Score observability maturity (0–100) across 6 signal dimensions
python scripts/observability_scorer.py maturity \
  --input data/sample-observability-profile.json

# Calculate SLO error budget burn rates and status flags
python scripts/observability_scorer.py slo \
  --input data/sample-slo-data.json

# Full readiness report (maturity + SLO) written to a Markdown file
python scripts/observability_scorer.py report \
  --input data/sample-observability-profile.json \
  --slos  data/sample-slo-data.json \
  --output report.md

CLI の完全なリファレンスと入力スキーマについては、scripts/README.md を参照してください。

データ

スクリプト用のサンプル入力ファイルです。

ファイル	説明
data/sample-observability-profile.json	現実的な B2B SaaS サービスのオブザーバビリティ評価（checkout-service、Node.js）
data/sample-slo-data.json	現在の可用性とイベント数を含む 5 つの SLO 定義
data/sources.json	このスキル向けに厳選した参照情報源

関連スキル

スキル	用途
ops-devops-platform	インフラストラクチャの監視、Kubernetes、CI/CD
data-sql-optimization	データベースクエリの最適化とインデックス作成
qa-debugging	アプリケーションレベルのデバッグとスタックトレース
qa-testing-strategy	テスト戦略の設計とカバレッジ
qa-resilience	レジリエンスパターン、再試行、サーキットブレーカー
software-architecture-design	アーキテクチャ上の意思決定
software-performance	パフォーマンスの診断とプロファイリング
qa-testing-performance	負荷、ストレス、長時間稼働テスト、パフォーマンス CI ゲート
ai-coding-agents-observability-evals	エージェントのトレースと評価パイプライン

学びのループ

過去の判断や落とし穴が関連する場合は、存在すれば learnings.consolidated.md を参照してください。必要な履歴を確認する場合、または代わりに利用できるファイルとしてのみ learnings.md を使用します。それ以外の場合は、どちらも参照しないでください。

適用後、覚えておく価値のあるパターン、防止すべきミス、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付付きの箇条書きを 1 つ learnings.md に追記してください。SKILL.md 自体は変更しないでください。