oma-observability

可観測性エージェント - インテントベースのルーター

スケジューリング

目標

MELT+P シグナル、レイヤー、境界、ベンダーカテゴリ、トランスポートの選択肢、メタ可観測性、インシデントフォレンジックにわたる可観測性業務のルーティング、設計、調整、レビューを行います。

インテントシグネチャ

• 可観測性、テレメトリ、OTel、メトリクス、ログ、トレース、プロファイル、SLO、RUM、APM、インシデントフォレンジック、トレース伝搬、トランスポートの調整、または可観測性のコード化についてユーザーが尋ねている場合。
• 単一ベンダーの既存の設定ではなく、ベンダー／カテゴリのルーティングや可観測性アーキテクチャが必要な場合。

使用する場合

• 可観測性パイプライン（OTel SDK + Collector + ベンダーバックエンド）のセットアップ
• サービスやドメインの境界をまたぐトレーサビリティの設計（W3C プロパゲーター、バゲージ、マルチテナント、マルチクラウド）
• トランスポートレイヤーの調整（UDP/MTU、OTLP gRPC と HTTP の比較、Collector の DaemonSet とサイドカーのトポロジー）
• インシデントフォレンジックの実施（6 次元の特定：コード／サービス／レイヤー／ホスト／リージョン／インフラ）
• ベンダーカテゴリの選定（OSS フルスタック、商用 SaaS、高カーディナリティ特化型、プロファイリング特化型）
• 可観測性のコード化の実装（Grafana Jsonnet ダッシュボード、PrometheusRule CRD、OpenSLO YAML、SLO バーンレートアラート）
• メタ可観測性（パイプラインの自己健全性、クロックスキューの検出、カーディナリティのガードレール、保持期間マトリクス）
• MELT+P シグナルセットの網羅：メトリクス、ログ、トレース、プロファイル（OTEP 0239）、コスト（OpenCost）、監査（SOC2/ISO）、プライバシー（GDPR/PIPA）
• 現在の上流サポート状況とプロジェクト要件に照らしたログパイプライン移行の評価

使用しない場合

• LLM 運用（プロンプトのバージョン管理、評価、gen_ai スパンの詳細分析）：Langfuse、Arize Phoenix、LangSmith、または Braintrust を直接使用してください
• データパイプラインのリネージ：OpenLineage + Marquez、dbt test、または Airflow のリネージバックエンドを使用してください
• IoT／ハードウェア／データセンターの物理レイヤーのテレメトリ（IPMI、BMC、SNMP）：ベンダーの DCIM ツール（Nlyte、Sunbird、Device42）を使用してください
• カオスエンジニアリングのオーケストレーション：Chaos Mesh、Litmus、Gremlin、または ChaosToolkit を使用してください（このスキルはそれらのテレメトリを利用しますが、カオスをオーケストレーションするものではありません）
• GPU／TPU インフラの可観測性：NVIDIA DCGM Exporter + Prometheus を使用してください
• ソフトウェアサプライチェーン（SBOM、アテステーション）：sigstore（cosign / rekor）、in-toto フレームワーク、SLSA レベルのアテステーションを使用してください
• インシデント対応ワークフロー（オンコールローテーション、ページング、エスカレーション）：PagerDuty、OpsGenie、または Grafana OnCall を使用してください
• TLS パケットの完全な検査：パケット解析ツールまたはベンダーの TLS 検査ツールを使用してください
• 単一ベンダーのセットアップが、そのベンダー自身の公開済みスキルで完全に扱われている場合：ベンダーのスキルを直接呼び出してください

想定される入力

• 可観測性の目的、対象システム、アーキテクチャの境界、シグナル、ベンダーの状況、該当する場合はインシデントの症状
• 既存の OTel／collector／ベンダー設定、ダッシュボード、SLO、トレース／ログ／メトリクスの例、またはデプロイトポロジー

想定される出力

• ルーティングされた可観測性のガイダンス、セットアップ／移行／調整計画、インシデントフォレンジックの手順、アラート／SLO のガイダンス、または可観測性のコード化に関する推奨事項
• トランスポート、メタ可観測性、プライバシー、監査、保持期間の確認
• 適切な場合の委譲先ベンダー

依存関係

リソースは必要に応じて読み込みます。実行プロトコルとインテントガイドを 1 つ読み込むところから始めます。関連するマトリクスの行だけを読み、根拠が必要な場合に境界、シグナル、またはトランスポートのセクションを追加します。参照リストは索引であり、事前読み込みリストではありません。

• OTel/W3C/CNCF の参照情報と resources/ 配下のリソース
• ベンダーカテゴリ、マトリクス、標準、インシデントフォレンジック、メタ可観測性、トランスポート、レイヤー、境界、シグナルのガイド

制御フロー機能

• インテント、ベンダーカテゴリ、レイヤー／境界／シグナルのマトリクス、トランスポートトポロジー、プライバシー／監査リスク、インシデントの特定次元に基づいて分岐します
• 可観測性の設定やドキュメントを読み書きする場合があります。通常、ベンダー固有の実装は委譲します
• 重要な CNCF／ベンダー情報の最新性について、ライブステータスの検証が必要です

構造フロー

エントリー

1. 意図を分類します：セットアップ、移行、調査、アラート、トレース、チューニング、ルーティングのいずれかです。
2. レイヤー、境界、シグナル、ベンダーカテゴリを特定します。
3. 関連するリソースガイドのみを読み込みます。

シーン

1. PREPARE：意図とマトリックスの対象範囲を分類します。
2. ACQUIRE：設定、トポロジー、テレメトリーのサンプル、またはインシデントのシグナルを読み取ります。
3. REASON：ベンダー／カテゴリへのルーティング、トランスポートのチューニング、メタオブザーバビリティの評価、またはインシデントの局所化を行います。
4. ACT：セットアップ／移行／チューニング／アラート／トレース／フォレンジックのガイダンス、または設定変更を提示します。
5. VERIFY：パイプラインの健全性、クロックスキュー、カーディナリティ、保持期間、プライバシー、監査上の懸念事項を確認します。
6. FINALIZE：ルート、証拠、リスク、引き継ぎ先の参照情報を報告します。

遷移

• ベンダー提供のスキルでセットアップを十分にカバーできる場合は、ドキュメントを重複させずに委任します。
• 移行が依頼された場合は、置き換え先を選ぶ前に、上流のサポート状況と互換性を確認します。
• インシデント調査が依頼された場合は、6次元の局所化を使用します。
• トランスポートのチューニングが必要な場合は、トランスポート固有のリソースを読み込みます。

障害と復旧

• CNCF／ベンダーの現在の状況が判断に不可欠な場合は、最新の状況を確認します。
• テレメトリーのサンプルが不足している場合は、分析の前に計装／収集の手順を提示します。
• 範囲が対象外のドメインに属する場合は、権威ある外部ツールに案内します。

終了条件

• 成功：オブザーバビリティの経路が案内され、証拠に裏付けられ、確認項目が明示されています。
• 部分的な成功：不足しているテレメトリー、古いベンダー情報、または外部ドメインへの引き継ぎが明示されています。

論理操作

アクション

アクション	SSL プリミティブ	証拠
オブザーバビリティの意図を分類する	SELECT	意図のルール
テレメトリー／設定の証拠を読み取る	READ	OTel／ベンダーの設定、ダッシュボード、サンプル
ベンダー／カテゴリにルーティングする	SELECT	ベンダーカテゴリ
カバレッジのギャップを推定する	INFER	マトリックスとシグナル／境界のマッピング
メタオブザーバビリティを検証する	VALIDATE	クロック、カーディナリティ、保持期間、健全性
ガイダンス／設定を書き込む	WRITE	依頼された場合の OaC／設定／ドキュメント
結果を通知する	NOTIFY	ルーティングされた推奨事項

ツールと計測器

• OTel／CNCF／W3C の標準規格に関する参照資料
• ベンダーカテゴリ、マトリックス、インシデントフォレンジック、メタオブザーバビリティ、トランスポート、シグナルのガイド
• 対象スタックのオプションの CLI／設定ツール

標準ワークフローのパス

1. Classify intent: setup, migrate, investigate, alert, trace, tune, or route.
2. Select layer/boundary/signal coverage from `resources/matrix.md`.
3. Load the specific vendor, transport, incident, or signal guide before producing guidance.

CNCF／ベンダーの状況が判断に不可欠な場合は、https://landscape.cncf.io で最新の状況を確認します。

リソースの範囲

範囲	リソースの対象
CODEBASE	オブザーバビリティの設定、ダッシュボード、アラートルール、計装
LOCAL_FS	リソースガイドと生成されたドキュメント
NETWORK	確認対象のベンダー／CNCF の状況とテレメトリーバックエンド
USER_DATA	インシデントの症状、ログ、メトリクス、トレース、プロファイル

前提条件

• オブザーバビリティの意図とシステム境界を特定できること。
• 関連するテレメトリー／設定の証拠を利用できるか、不足している証拠が明示されていること。

影響と副作用

• オブザーバビリティの設定、ダッシュボード、アラート、計装ドキュメントを推奨または変更する場合があります。
• ベンダー提供のスキルや外部ツールに案内する場合があります。

ガードレール

1. 意図を分類し、カテゴリの選択またはベンダーへの引き継ぎが必要な場合に限り、resources/vendor-categories.md を使用します。
2. 確認された問題に合ったトランスポートガイドを読み込みます：UDP/MTU、OTLP プロトコル、Collector トポロジー、またはサンプリング。
3. セットアップの完了を宣言する前に、パイプラインの健全性、時刻同期、カーディナリティ制限、保持期間がプロジェクトの要件を満たしていることを確認します。実行できなかった確認項目を記録します。
4. 推奨に影響する場合は、現在の上流サポート、属性の安定性、移行ガイダンスを確認します。公式のプロジェクトドキュメントと CNCF のステータスを使用します。保存されているバージョン情報は前提であり、現在のステータスを証明するものではありません。
5. デフォルトでは W3C Trace Context を使用し、必要に応じて resources/boundaries/cross-application.md にあるクラウド向けの変換を使用します。
6. 収集時に PII の編集と、サンプリングを考慮したバゲージ制御を適用します。対象システムの保持、消去、監査要件を確認します。
7. 動作する設定を提供するか、提案であることを明示します。スキャフォールドや未検証の確認を、完了したセットアップとして扱うことはできません。

カバレッジマトリックスには、4 つのレイヤー（L3、L4、mesh、L7）、4 つの境界（マルチテナント、アプリケーション間、SLO、リリース）、7 つのシグナル（メトリクス、ログ、トレース、プロファイル、コスト、監査、プライバシー）があります。resources/matrix.md で該当する行を読みます。N/A のセルは実装不要です。

ルート（意図）

意図	主な対象	フォールバック
setup	resources/vendor-categories.md → ベンダー提供のスキル	resources/standards.md の汎用 OTel semconv
migrate	現在の上流移行ドキュメント + resources/vendor-categories.md のログパイプラインのセクション	OTel Collector のブリッジ設定
investigate	resources/incident-forensics.md（MRA + 6 次元の切り分け）	resources/signals/traces.md + resources/signals/logs.md
alert	resources/boundaries/slo.md（バーンレートのアラートルール）	resources/observability-as-code.md
trace	resources/boundaries/cross-application.md（プロパゲーターのマトリックス）	resources/layers/mesh.md（ゼロコードの自動計装）
tune	resources/transport/（4 ファイル：UDP/MTU、OTLP、トポロジー、サンプリング）	resources/meta-observability.md（カーディナリティのガードレール）
route	resources/boundaries/multi-tenant.md + resources/transport/collector-topology.md	resources/boundaries/cross-application.md（データレジデンシー）

呼び出しと読み込み

例：/oma-observability --investigate "5xx spike in checkout"。 ほかのスキルには、意図、システム境界、エビデンスを渡します。結果として、ガイダンス、確認項目、ベンダーへの引き継ぎがあればその内容が返されます。

最初に resources/execution-protocol.md を読みます。上記から選択したルートを使用し、提供前には関連するチェックリストのセクションだけを読みます。見慣れない出力形式の場合は resources/examples.md を読み込み、該当するカテゴリに限って resources/anti-patterns.md を読み込みます。トランスポート、レイヤー、境界、シグナルのガイドをすべてまとめて読み込まないでください。

OMA エコシステムとの統合

スキル	統合ポイント
oma-debug	障害発生時：request_id でトレースとログを取得 → resources/incident-forensics.md の6次元ローカライズ手順を起動
oma-qa	chrome-devtools MCP を使用したデプロイ後のカナリアループ：コンソールエラーと Core Web Vitals の傾向を確認；resources/layers/L7-application/web-rum.md から INP/LCP/CLS を取得
oma-tf-infra	OTel Collector、Grafana、Loki スタックをプロビジョニングする Terraform モジュール
oma-scm	デプロイ SHA → service.version OTel 属性とリリースマーカーイベント；resources/boundaries/release.md を参照
oma-backend	プロパゲーターとバゲージのルール；DB の N+1 と Kafka のパターンは resources/signals/traces.md を参照。相互参照：oma-backend/SKILL.md §References「Observability handoff」
oma-frontend	resources/layers/L7-application/web-rum.md の INP/LCP/CLS チェックリスト。相互参照：oma-frontend/SKILL.md §References「Observability handoff」
oma-mobile	resources/layers/L7-application/mobile-rum.md のオフラインキューイングパターン。相互参照：oma-mobile/SKILL.md §References「Observability handoff」
oma-db	resources/signals/traces.md の DB パターン（N+1、コネクションプール）。相互参照：oma-db/SKILL.md §References「Observability handoff」

バージョン管理と非推奨化

• 仕様バージョンの固定：各ファイルのフロントマターにある otel_spec / otel_semconv キーは、前提とするバージョンを示します。内容が特定の属性安定性ティアに依存する場合は、そのティアを本文中に記載します。
• 更新のトリガー（定期更新ではありません）：
  • このスキルで引用されている属性に影響する OTel semconv の昇格（Development → RC → Stable）→ resources/standards.md と該当ファイルを更新し、マイナーバージョンを上げます。
  • 属性の非推奨化 → 引用しているすべてのファイルで置き換えます。移行に関する注記を resources/standards.md に記載します。
  • vendor-categories.md に記載されたベンダー／プロジェクトの CNCF ステータス変更（Graduated／Archived／買収）→ ベンダーテーブルを更新します。
• 正式な最新情報：CNCF プロジェクトのステータスについては https://landscape.cncf.io を参照してください。このスキルは、定期的に追跡することを約束するものではありません。情報が重要な根拠となる場合は、利用時に確認してください。
• ファイルごとのレビュー日時は記録しません：以前のドラフトでは、フロントマターに last_reviewed / next_review が含まれていました。自動チェックの仕組みがなく、任意の手動レビューに頼ると、実情を誤って伝える古い日時が残るため、削除しました。ファイルが最後に変更された時期の正確な記録は、Git の履歴（git log path/to/file）です。

貢献プロトコル

• ユーザー向けドキュメントで、将来追加される OMA スキル名を事前に宣言しないでください。対象範囲外のドメインについて OMA ネイティブのカバレッジが必要になった場合は、その時点で評価し、名前を決めてください。
• ファイルの編集は、docs/plans/designs/005-oma-observability.md §Ownership のオーナーシップマトリクスに従います。standards.md、matrix.md、anti-patterns.md の変更には CTO の共同署名が必要です。
• マージ前に resources/checklist.md §1 Setup validation を実行してください。

References

• Execution steps: resources/execution-protocol.md
• Intent classification: resources/intent-rules.md
• Coverage matrix: resources/matrix.md
• Standards (OTel spec, W3C, ISO): resources/standards.md
• Vendor categories: resources/vendor-categories.md
• Incident forensics: resources/incident-forensics.md
• Meta-observability: resources/meta-observability.md
• Observability-as-code: resources/observability-as-code.md
• Anti-patterns catalog (72 entries): resources/anti-patterns.md
• Checklist: resources/checklist.md
• Examples: resources/examples.md
• Transport:
  • resources/transport/udp-statsd-mtu.md
  • resources/transport/otlp-grpc-vs-http.md
  • resources/transport/collector-topology.md
  • resources/transport/sampling-recipes.md
• Layers:
  • resources/layers/L3-network.md
  • resources/layers/L4-transport.md
  • resources/layers/mesh.md
  • resources/layers/L7-application/web-rum.md
  • resources/layers/L7-application/mobile-rum.md
  • resources/layers/L7-application/crash-analytics.md
  • resources/layers/L7-application/waf.md
• Boundaries:
  • resources/boundaries/multi-tenant.md
  • resources/boundaries/cross-application.md
  • resources/boundaries/slo.md
  • resources/boundaries/release.md
• Signals:
  • resources/signals/metrics.md
  • resources/signals/logs.md
  • resources/signals/traces.md
  • resources/signals/profiles.md
  • resources/signals/cost.md
  • resources/signals/audit.md
  • resources/signals/privacy.md