Observability AIops

Observability AIops

免責事項：コミュニティがメンテナンスしているオープンソースプロジェクトです。Prometheus または Grafana の各プロジェクト、Grafana Labs、Cloud Native Computing Foundation とは提携、推奨、後援関係にありません。 Prometheus、Alertmanager、Grafana は、それぞれの所有者の商標です。MIT ライセンスで公開されています。

1 台のサーバーでセルフホスト型の可観測性スタック向けに、ガバナンスを備えた AI 運用を実現します。対象は Prometheus（HTTP API、PromQL、ターゲット、ルール、アラート）、Alertmanager（アラートとサイレンス）、Grafana（ダッシュボード、データソース、フォルダー）、Grafana Loki（範囲を制限した LogQL ログ読み取りとログの根本原因分析）です。ガバナンス機能を組み込んだ仕組みとして、統合監査ログ、トークン／暴走予算ガード、取り消しトークンの記録、リスク階層を示すラベルを備えています。1 つの設定でスタック全体を対象にできます。各ターゲットにはそれぞれの platform を指定します。 モックテストスイートに加え、Prometheus／Alertmanager／Grafana の読み取り、根本原因分析、ガバナンス付きサイレンスおよびダッシュボードの書き込み（取り消し機能付き）は、稼働中の Prometheus 3.x + Alertmanager + Grafana 13 スタックで検証済みです。詳しくはdocs/VERIFICATION.mdをご覧ください。

これは、エンタープライズ向け監視スイートを補完するセルフホスト型可観測性ソリューションです。SRE が実際に運用するオープンな Prometheus／Grafana API を扱い、ベンダーの NMS は使用しません。

できること

Prometheus／Grafana スタックを運用する SRE が繰り返し確認する質問に答え、後続の書き込み操作を保護します。

• PromQL + メタデータ — 即時クエリと範囲クエリ、ラベル値の列挙、時系列メタデータを取得します。すべて読み取り専用で、結果数に上限を設けています。
• スクレイプターゲットとルールの健全性 — 稼働中／停止中のターゲット（lastError からその理由も確認できます）、再ラベリングで除外されたターゲット、エラーが発生している記録ルール／アラートルールを確認できます。
• アラートとサイレンス — 発火中／保留中の Prometheus ルールアラート、ルーティング後の Alertmanager の表示、およびサイレンスを確認できます。
• Grafana — ダッシュボード、データソース（健全性も含む）、フォルダーを扱います。
• Loki ログ — 範囲を制限した LogQL 読み取り（ラベルとラベル値の列挙、検証を通過した query_range、定型のエラー末尾取得）を行います。すべて読み取り専用で、参照期間と行数に厳格な上限があり、オプションでマルチテナントの X-Scope-OrgID と、ターゲットごとの basic／bearer 認証を利用できます。
• 主要な分析機能 — 数値を明示する透明性の高いヒューリスティックです。firing_alert_rca（各発火中アラートをルール式に結び付け、原因と対処を提示）、target_scrape_health_analysis（停止中／エラーのスクレイプを順位付けし、考えられる原因を提示）、alert_noise_and_flap_analysis（頻繁に繰り返される／重複するアラートを検出し、重複排除／集約を推奨）に加え、ログ分析が 2 つあります。log_error_burst_rca（ストリームごとのエラーバーストをベースラインと比較し、新しいシグネチャ／急増したボリューム／単一インスタンス／ベースラインなしに分類）と log_volume_analysis（上位ストリーム、高カーディナリティラベルの警告、保持期間のヒント）です。さらに、発火中の Prometheus アラートを対応する Loki ストリームと関連付ける alert_log_context もあります。
• ガバナンス付き書き込み — Alertmanager のサイレンスの作成／期限切れ設定（時間制限付き）、Grafana アノテーションの作成、ダッシュボードの更新／削除、Prometheus 設定のホットリロードが可能です。各操作は監査され、リスク階層が設定され、dry_run に対応しています。取り消し可能な操作では、実際に取得した変更前の状態を取り消し用に記録します。

このツールが行うこと、行わないこと

Prometheus と Grafana の操作（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。書き込みを実行してよいかどうかは判断しません。それはエージェントの判断、または接続するアカウントの権限によります。たとえば、Viewer スコープのみの Grafana トークンを指定し、管理者用／書き込み用 API にアクセスできない Prometheus／Alertmanager に接続した場合、書き込みは権限を実際に管理するサーバー側で失敗します。

そのため、読み取り専用スイッチも、ポリシーファイルも、設定が必要な承認ゲートもありません。このツールが保証するのは、何も黙って実行されないことです。MCP 経由でも CLI 経由でも、すべての呼び出しが ~/.observability-aiops/audit.db に監査行として記録されます。また、破壊的な書き込みでは、変更前の状態を取得し、可能な場合は元に戻す操作も記録します。

各ツールは risk_level を宣言し、監査行に説明用の階層（none/confirm/review）として記録します。これにより、レビュー担当者は高リスクの削除であることをすぐに確認できます。これはラベルであり、ゲートではありません。

機能一覧（39 個の MCP ツール）

グループ	プラットフォーム	ツール	数	読み取り／書き込み
メトリクス	Prometheus	instant_query, range_query, label_values, series_metadata	4	読み取り
ターゲット	Prometheus	list_targets, target_scrape_health, dropped_targets	3	読み取り
ステータス	Prometheus	prometheus_config_status, prometheus_tsdb_status	2	読み取り
ルール	Prometheus	list_rules, rule_health	2	読み取り
アラート	Prometheus/Alertmanager	firing_alerts, pending_alerts, alertmanager_alerts, list_silences	4	読み取り
Grafana	Grafana	list_dashboards, get_dashboard, list_datasources, datasource_health, list_folders	5	読み取り
Loki	Loki	loki_labels, loki_label_values, loki_query, loki_tail_errors	4	読み取り
概要	すべて	observability_overview	1	読み取り
分析	Prometheus	firing_alert_rca, target_scrape_health_analysis, alert_noise_and_flap_analysis	3	読み取り
ログ分析	Loki	log_error_burst_rca, log_volume_analysis	2	読み取り
シグナル横断	Prometheus + Loki	alert_log_context	1	読み取り
書き込み	Alertmanager	create_silence, expire_silence	2	書き込み（中）
	Grafana	create_annotation	1	書き込み（中）
	Grafana	update_dashboard	1	書き込み（中）
	Grafana	delete_dashboard	1	書き込み（高）
	Prometheus	reload_prometheus_config	1	書き込み（中）
取り消し	すべて	undo_list	1	読み取り
	すべて	undo_apply	1	書き込み（中）

Loki は読み取り専用です。Loki には安全な運用上の書き込み手段（サイレンスやアノテーションに相当する機能）がないため、このツールには意図的に Loki の書き込み機能を含めていません。

CLI では便利な機能の一部（query、logs、alert、overview など）を利用できます。39 個すべてのツールを利用するには MCP サーバーを使用してください。

クイックスタート

Claude Code プラグインとして

1 回のインストールで、エージェントにスキルと MCP サーバーの両方を提供します。

/plugin marketplace add AIops-tools/marketplace
/plugin install observability-aiops@aiops-tools

MCP サーバーは uv を使用して取得され、このプラグインが宣言するパッケージバージョンに固定されます。そのため、監査行から、その行を書き込んだコードを追跡できます。認証情報は引き続き observability-aiops init で設定します。以下を参照してください。

OpenClaw プラグインとして

同じバンドルが ClawHub で公開されており、1 回のインストールでスキルと MCP サーバーをまとめて導入できます。

openclaw plugins install clawhub:@zw008/observability-aiops
openclaw skills info observability-aiops          # expect: Visible to model: yes

その後、プラグインを読み込ませるために OpenClaw ゲートウェイを再起動してください。MCP サーバーは uv を使用して取得され、このリリースのバージョンに固定されています。そのため、uvx が PATH 上にある必要があります。ない場合、スキルはインストールされますが、Visible to model: no と表示されます。認証情報は以下の手順と同じ方法で設定します。

CLI またはスタンドアロン MCP サーバーとして

uv tool install observability-aiops          # or: pipx install observability-aiops
observability-aiops init                     # wizard: pick platform (prometheus/grafana) + store the token (encrypted)
observability-aiops doctor                   # verify config, secrets, connectivity
observability-aiops overview                 # snapshot: firing alerts + targets up/down + rules erroring
observability-aiops query instant 'up'       # run a PromQL instant query
observability-aiops logs errors '{app="api"}' # tail error-level Loki logs (bounded)
observability-aiops alert rca                # root-cause the firing alerts

MCP サーバーとして実行します（stdio）：

export OBSERVABILITY_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
observability-aiops mcp

そのパスワードが保存される場所：エクスポートされた変数は、このシェルが起動するすべてのプロセスから読み取り可能で、シェルの履歴にも記録されます。共有ホストや長期間稼働するホストでは、対話型プロンプトを使用するか、必要なコマンドの実行中のみシークレットマネージャーから渡すことをおすすめします。

ガバナンス

すべての MCP ツールは、バンドルされた @governed_tool ハーネスを経由します。

• 監査 — すべての呼び出し（パラメーター、結果、ステータス、所要時間、リスクティア、オペレーターが指定した承認者や理由）は ~/.observability-aiops/audit.db に記録されます（OBSERVABILITY_AIOPS_HOME で保存先を変更できます）。CLI は MCP 経由の場合と同じ行を書き込みます。監査されない実行経路はありません。
• 暴走防止ガード — 認可ゲートではなく、安全性を確保するための最後の防護策です。同じ呼び出しを短い間隔で繰り返すと、サーキットブレーカーが作動します。OBSERVABILITY_RUNAWAY_MAX=0 で無効化できます。オプションで OBSERVABILITY_MAX_TOOL_CALLS / OBSERVABILITY_MAX_TOOL_SECONDS による上限も設定できます。
• 取り消しの記録 — 元に戻せる書き込みでは、取得した変更前の状態から逆操作の記述子を作成します（create_silence→期限切れにする、update_dashboard/delete_dashboard→取得済みの以前のモデルを復元する）。
• リスクティア — risk_level から導出され、監査行に記録される説明用ラベルです。何かを制限することはありません。

サポート範囲と制限事項

• プラットフォーム：Prometheus HTTP API（および連携する Alertmanager）、Grafana HTTP API、Grafana Loki HTTP API（読み取り専用）に対応しています。ホスト型／SaaS 型の監視スイート（Datadog、New Relic、エンタープライズ向け NMS）は、このツールの対象外です。
• 検証。 モックテストスイートでは 4 つすべてのプラットフォームをカバーしています。さらに、Prometheus、Alertmanager、Grafana の各機能は、Prometheus 3.x + Alertmanager + Grafana 13 の実環境でテスト済みです（RCA、サイレンスとダッシュボードのガバナンス対象の書き込み、取り消しの再実行）。Loki の機能は、まだ実環境ではテストされていません。4 つとも無料のオープンソースで、ラボ環境に簡単にセットアップできます（docker run prom/prometheus、grafana/grafana、grafana/loki）。そのため、実環境での確認には observability-aiops doctor が最も手早い方法です（Prometheus /api/v1/status/buildinfo、Grafana /api/health、Loki /ready + /loki/api/v1/status/buildinfo）。docs/VERIFICATION.md を参照してください。

必要な機能がありませんか？

別の読み取り機能、より目的に合わせた分析、または未対応のプラットフォーム機能をご希望ですか？ イシューまたは PR を作成してください。フィードバックやコントリビューションを歓迎します。