kubesense-slo

KubeSense SLO

ここでの SLO は、保存された定義とバックグラウンド評価器で構成されます。評価器は evaluation_interval_seconds ごとに 1 つのバケットを評価し、結果を ClickHouse に書き込み、Prometheus の系列（kubesense_slo_*）を出力します。コンプライアンスは、 evaluation_window_days にわたるローリング集計です。

重要

SLO 用の MCP ツールはありません。 ログ、トレース、メトリクス、アラートにはありますが、SLO にはありません。ここで扱うのはすべて /api/slo の REST API で、 MCP サーバーと同じ方法（x-api-key、または Authorization: Bearer <token>）で認証します。MCP のクエリツールを使ってメトリクス名とフィールド名を 特定 してから、SLO の本文を作成してください。

つまり、このスキルには MCP 接続だけでは得られない次の 2 つが必要です。HTTP 呼び出しを行う手段 （curl を使えるシェル、または HTTP ツール）と、ヘッダーに設定できる値としての API 認証情報です。MCP サーバー自体の認証情報は、 ツール呼び出しの内部から読み取れません。MCP だけを使うエージェントでもペイロードの作成と説明はできますが、 ユーザー自身が送信する必要があることを明確に伝えてください。

ライフサイクル

順番どおりに進めてください。手順 5 と 6 は省略されがちですが、保存は正常にできても評価されない SLO を見つけるための手順です。

1. 特定します。 実際のメトリクス名（get-available-metrics、get-metric-labels）と 実際のフィールド名（get-trace-or-log-fields）を確認します。バーンレートアラートのチャネル ID（list-notification-channels）も確認します。アラート SLO の場合は、アラートルールの UUID も確認します。
2. 本文を作成します。 種別、2 つのクエリ、ウィンドウ、alert_types を設定します。
3. POST /api/slo/preview でプレビューします。 プレビューで確認できることと、できないことを把握しておいてください。数値が大幅にずれている場合、たいていはフィルターの不具合です。no_data は、その証拠になりません。実際に静かなサービスでも空のウィンドウが発生します。変更する前に、両者を見分けてください（手順 6）。アラート SLO の場合は、from_time／to_time を明示的に渡してください。デフォルトのウィンドウでは、ルールが存在するより前までさかのぼるため、発火した行がないと稼働率が完全であるかのように表示されます。
4. POST /api/slo で作成し、返された ID を保持します。 ID がなければ、SLO もありません。
5. GET /api/slo/{id}?current_time=… で読み戻し、保存された設定が送信した内容と一致することを確認します。 特に slo_type、operation、両方の groupBy リストを確認してください。
6. 評価間隔が 1～2 回経過したら、実際のバケットを確認します。 GET /api/slo/{id}/metrics?from_time=…&to_time=… に加えて、SLO も読み戻します。
   • 2 回の読み取りの間に last_evaluated が進んでいること が、評価器が SLO を処理した証拠です。Null、または値が変わらない場合、評価器は処理していません。status、間隔、グループ数の上限を確認してください。
   • ゼロ以外の total_events（または total のスライス／秒）は、クエリが解決され、一致する結果があることも証明します。
   • ゼロだからといって、必ずしも不具合ではありません。 静かなサービスでは正当に空のバケットが生成されます。by_count では no_data、time_slice では稼働時間になります。SLO に手を加える前に、同じ範囲とウィンドウを analyze-traces／ analyze-logs／analyze-metrics で直接クエリしてください。そこにも行がなければ、テレメトリが存在しないということであり、別の場所で対処すべき問題です。
   • 数値を表示させるために、ユーザーのフィルターを広げてはいけません。 何を測定するかを変えることになり、ユーザーが求めていないものを測定してしまいます。結果が空であることと、確認した内容を報告してください。
7. alert_types を設定した場合は、生成されたアラートを確認します。チャネル ID を指定したルールが "<SLO name> Fast Burn Rate" などの名前で作成されているはずです。
8. PUT（本文全体を指定し、ID を含める）で更新するか、DELETE /api/slo/{id} で削除し、その後、手順 5～7 を繰り返します。 更新すると、生成されたルールが再構築されます。

3 種類の SLI

slo_type	分子／分母	設定する内容	カウント単位
by_count	良好なイベント数／全イベント数	クエリを2 つ：good_events_filter と total_events_filter	events
time_slice	良好なスライス数／全スライス数	クエリを1 つ（total_events_filter）＋operation＋threshold_value	slices
alert	アラートが発火していない秒数／全秒数	total_events_filter.alert_ids にアラートルール ID を指定	seconds

省略した場合、slo_type のデフォルトは by_count です。UI では「By Count」「By Time Slices」「By Uptime」と呼ばれます。

ルーティング

ユーザーの依頼…	対応方法
「X の SLO を作成して」	POST /api/slo のリクエストボディを作成します — references/api-payloads.md
「この SLO は合格する？」／「コンプライアンスはどうなっていた？」	作成前に POST /api/slo/preview を実行します — 無料で、何も保存されません。ただし、リプレイではなく推定値です（制限事項）
「どんな SLO がある？／どれが違反している？」	POST /api/slo/list?status=active&current_time=…、または POST /api/slo/stats
「この SLO はなぜ予算を消費している？」	GET /api/slo/{id}/burn-rate/timeseries を実行し、同じフィルターを使って kubesense-traces／kubesense-logs を確認します
「予算を消費したら通知して」	SLO の alert_types を使います。バーンレートのアラートルールを手動で作成しないでください
「Datadog の SLO を移行して」	references/datadog-migration.md
「ダッシュボードに SLO を表示して」	kubesense-dashboards — panelType: "slo"

エンドポイント

すべて /api/slo 配下にあり、RBAC モジュールは slo です。作成／更新／削除には、このモジュールへの書き込みアクセスも必要です。

メソッド	パス	用途
POST	/api/slo	作成 — 新しい SLO ID を data で返します
PUT	/api/slo	更新 — ID はパスではなく、id としてリクエストボディに指定します
DELETE	/api/slo/{id}	論理削除（removed を設定）し、関連するバーンレートのアラートルールを削除します
GET	/api/slo/{id}?current_time=<RFC3339>	ロールアップを含む単一の SLO
POST	/api/slo/list?status=active&current_time=<RFC3339>	一覧。フィルターは JSON ボディで指定します
GET	/api/slo/search?search=<substr>&limit=50	{id, name} のみ — 選択用
POST	/api/slo/stats	ステータス別の件数：normal / warning / breached / no_data
POST	/api/slo/preview	指定期間のコンプライアンスをドライランで確認し、何も保存しません（ステータスは normal／breached／no_data のいずれかで、warning にはなりません）
GET	/api/slo/{id}/metrics?from_time=&to_time=	指定期間の良好／不良／合計件数と予算
GET	/api/slo/{id}/groups?windows=last_24_hour,last_7_days	グループごとの数値。1 回のスキャンで複数の期間を指定できます
GET	/api/slo/{id}/timeseries	時系列でのコンプライアンス
GET	/api/slo/{id}/burn-rate/timeseries	時系列でのバーンレート
POST	/api/slo/filters、/api/slo/filter/search	一覧ページ用のフィルター値

警告

/list と GET /{id} では current_time が必須で、/list では status も必須です。 どちらもクエリパラメーターであり、ボディフィールドではありません。current_time を省略すると呼び出しは 500 エラーになります（「currentTime must not be zero」）。status を省略すると、WHERE status = ? が何にも一致せず、空の一覧が返るため「SLO が存在しない」ように見えます。status=active を指定してください。

Create Payload

トレースに対する最小限の by_count SLO：

{
  "name": "Checkout availability",
  "description": "Successful checkout spans / all checkout spans",
  "slo_type": "by_count",
  "metric": "requests",
  "slo_target_percentage": 99.9,
  "evaluation_window_days": 30,
  "evaluation_time_interval_seconds": 60,
  "evaluate_from": "2026-09-01T00:00:00Z",
  "evaluation_start_time": "2026-09-01T00:00:00Z",
  "status": "active",
  "cluster": "", "namespace": "", "workload": "", "customer_identifier": "",
  "operation": "", "threshold_value": 0, "value": 0,
  "good_events_filter":  { "selectedMode": "traces", "value_operation": "row_count", "groupBy": [], "unified_filter": { "type": "common", "common_filter": [ {"field": "app_service", "operation": "IN", "values": ["checkout"]}, {"field": "status", "operation": "IN", "values": ["ok"]} ], "adv_filters": {} } },
  "total_events_filter": { "selectedMode": "traces", "value_operation": "row_count", "groupBy": [], "unified_filter": { "type": "common", "common_filter": [ {"field": "app_service", "operation": "IN", "values": ["checkout"]} ], "adv_filters": {} } },
  "alert_types": ["burn_rate_fast", "error_budget_low"],
  "notification_channels": [1]
}

タイプごとのすべての形式、メトリクスとログのバリエーション、レスポンスボディについては、 references/api-payloads.md をご覧ください。

ボディのルール：

• evaluation_time_interval_seconds は 0 より大きくなければなりません。サーバーは 0 を即座に拒否し、評価器も、無限ループを避けるため、インターバルが 0 の SLO をスキップします。
• status: "active" にしないと、評価器はその SLO を処理しません。
• slo_target_percentage は割合（99.9）であり、小数ではありません。
• warning_target_percentage を設定する場合は、目標値より 高く してください。これは、違反する 前に 警告を受けたい値です。UI では >= target + 0.1 が適用されますが、API では一切検証されません。目標値未満の値も保存されますが、違反チェックが先に実行されるため、その値に達することはありません。
• metric はクエリではなく ラベル です。トレースの SLI では "requests"、メトリクスの SLI では PromQL のメトリクス名、アラート SLI では "alert_uptime" を指定します。これを使った評価は行われず、一覧ページやフィルターに表示されるだけです。
• operation と threshold_value は time_slice 条件専用 です。by_count では無視されます。レイテンシのしきい値を設定する場合は、期間フィルターとして良好クエリに含めてください。
• 更新は 全置換 です。PUT /api/slo はボディのすべての列を書き込むため、オブジェクト全体を送信してください（先に GET /api/slo/{id} で読み取ります）。また、ボディには id を含めてください。

Good と Total はアラートクエリの設定です

good_events_filter と total_events_filter は、アラートルールで使われるのと 同じ query_config オブジェクト です。同じ JSON キー、同じ実行エンジン、同じフィールド許可リストを使います。これが最も重要なポイントです。アラートルールのクエリの構築方法について知っていることは、すべてここでも当てはまります。

キー	意味
selectedMode	traces | logs | metrics。空の場合は traces がデフォルト です。
unified_filter	トレース／ログのフィルターツリー：{type, common_filter[], adv_filters{}}
promql	メトリクス専用。メトリクスのクエリ全体です。（アラートルールの queryMode には対応するフィールドがなく、破棄されます。）
value_operation	row_count（通常の選択肢）、unique_count、avg、sum、min、max、パーセンタイル
fields	row_count 以外の value_operation では必須です
groupBy	[{field, type, is_attribute}]。グルーピングを参照してください
alert_ids	アラートタイプの SLO 専用

重要

フィールド名はクエリツールではなく、アラートエンジンの用語に従います。 ログとトレースの SLI クエリは、アラートルールと同じルールエンジンの実行エンジンを通るため、service ではなく app_service、type ではなく level、pod_name／pod、node_name／node、return_code／status_code を使います。許可されるフィールドの完全な一覧は kubesense-alerts にあります。SLO についても、この一覧が基準になります。

知っておくべき違いが 1 つあります。POST /api/slo/preview はクエリを API 独自の Explore エンジンで実行しますが、評価器はルールエンジンで実行します。 フィールドマップには共通部分がありますが、完全には一致しません。そのため、プレビューで問題なく表示された名前でも、評価のたびにエラーになる場合があります。また、プレビューでは、トレースとログに対して row_count が 固定で使用されます（value_operation と fields は無視されるため、レイテンシ SLI のプレビューでもリクエスト数が表示されます）。さらに、メトリクスはすべてのバケットを評価するのではなく、約 300 個のポイントを サンプリング します。プレビューで検出できるのは、フィルターが空、または不適切な場合だけで、数値の検証は行いません。作成後、最初に実際のバケットで確認してください。

数式と比率

複数のクエリと (A/B)*100 のような式で構成された Datadog モニターや SLO は、ひとまとまりのものとして移行できません。移行先によって形が決まります。

移行するもの	移行先	方法
SLI が分子 / 分母である SLO	by_count SLO	数式は使わず、2 つのクエリを指定します。 A → good_events_filter、B → total_events_filter。評価器が自動で除算します。
比率にしきい値を設定するモニター	アラートルール	アラートには実際の数式モードがあります。A、B、expression を別々のクエリとして維持し、metric_query_label を数式のラベルに指定します。kubesense-alerts を参照してください。
各間隔でしきい値と比較する比率の SLI	time_slice SLO	operation と threshold_value を指定し、PromQL を 1 つにインライン化します。
SLO やルールを使わないアドホック分析	analyze-telemetry（MCP）	ラベル付きクエリの配列と {"selectedMode": "formula", "expression": "(A/B)*100"} を指定します。ログ、トレース、メトリクスを横断して組み合わせられます。

警告

SLO では selectedMode: "formula" は機能しません。 評価器は、logs、metrics、traces を認識するエグゼキューターファクトリーを通じてクエリを解決します。それ以外のクエリタイプには unsupported query type: formula を返すため、評価のたびに失敗し、SLO は永久に no_data のままになります。数式をサポートするのはアラートであり、SLO ではありません。

代わりに、1 つの PromQL 文字列にインライン化します。 プロダクトでもこの方法を採用しています。SLO エディターの数式ビルダーは、送信前に各ラベルを、それに対応するクエリを括弧で囲んだものに置き換え、フラットな promql を 1 つ保存します。したがって (A/B)*100 は次のように保存されます。

(sum(increase(http_requests_total{status=~"5.."}[5m])) / sum(increase(http_requests_total[5m]))) * 100

重要

比率を by_count SLO にインライン化しないでください。 ここでは比率そのものが SLO であり、評価器は good/total を計算してエラーバジェットを算出します。total_events_filter にパーセンテージを渡すと、パーセンテージをイベントとしてカウントするため、その後のすべての数値が無意味になります。比率を使うのは time_slice（スライスごとに 1 つの値をしきい値と比較）またはアラートルールです。

インライン化した比率をグループ化する場合は、除算の両側に by (…) を指定し、クエリの groupBy も空にしないでください。by (…) だけでは SLO は単一系列の経路から切り替わりません（「グループ化」を参照）。

グループ化

total_events_filter に groupBy を指定し（good_events_filter にも対応する groupBy を指定します）、SLO をグループごとに 1 つのコンプライアンス値に分割します。グループ ID を基に値が結合されます。

• グループは、すべての kubesense_slo_* 系列で Prometheus ラベルとして出力されます。また、slo_group="*" のラベルが付いた全体集計系列も出力されます。
• slo_id、slo_group、window、target_percentage、error_budget、__name__ は予約済みです。これらの名前に変換されるフィールドを groupBy に指定すると、その指定は破棄されます。workload、namespace、cluster でグループ化すれば、これらを系列に含められます。
• フィールド名は、有効な Prometheus ラベル名に変換されます。[a-zA-Z0-9_] 以外の文字はすべて _ になるため、service.name は service_name になります。
• グループ数の上限は 100 です。 上限を超えると評価器はバケット全体をスキップしてログに記録し、SLO はデータを出力しなくなります。pod、instance、trace_id など、上限のないフィールドでは決してグループ化しないでください。
• good 側のグループに対応する total 側のグループがない場合、そのグループは切り捨てられ、警告が出ます。2 つの groupBy リストは同一にしてください。
• メトリクスの SLI でも groupBy は空にできません。 PromQL の by (…) だけではグループ化は有効になりません。評価器は total_events_filter.groupBy を読み取るため、リストが空のまま複数系列の結果を受け取ると、最初の系列だけが残り、残りは何も通知されずに破棄されます（メトリクスの time_slice は例外で、常に複数系列として実行されます）。references/api-payloads.md を参照してください。

バーンレートアラートは alert_types から作成されます

alert_types を設定すると、API は SLO と同じトランザクション内でアラートルールを作成します。

alert_types の値	ルール	重大度
burn_rate_fast	(days × 24 × 0.02) / 1 に対する kubesense_slo_burn_rate{window="1h"}	critical
burn_rate_slow	(days × 24 × 0.05) / 6 に対する kubesense_slo_burn_rate{window="6h"}	warning
error_budget_critical	kubesense_slo_error_budget_balance < 5	critical
error_budget_low	kubesense_slo_error_budget_balance < 10	warning

しきい値は evaluation_window_days から導出されるため、30 日間のウィンドウでは、おなじみの 14.4× / 6× のマルチウィンドウバーンレートになります。更新のたびに再計算されます。

警告

これらのルールを手動で作成しないでください。 PUT /api/slo は、SLO に紐づくすべてのアラートルールを削除し、alert_types に基づいて再作成します。DELETE はそれらを削除します。 生成されたルールを編集しても、次回の SLO 更新時に変更は通知なく元に戻されます。

「紐づく」とは、PromQL ではなく、ルール自身の labels.slo_id を指します。削除処理は WHERE JSON_EXTRACT(labels, '$.slo_id') = <id> で行われ、誰がルールを作成したかは考慮されません。そのため、クエリで kubesense_slo_burn_rate{slo_id="…"} を単に選択する手書きルールは残りますが、自身のラベルに slo_id を含むルール（生成されたルールをコピーする際に当然行うこと）は、それらと一緒に削除されます。残したいルールのラベルには slo_id を含めないでください。

SLO の notification_channels は、生成されたルールの通知先です。まず list-notification-channels（MCP）または GET /api/alerts/notification-channels を呼び出してください。存在しない ID を指定するとルールの作成に失敗し、作成トランザクション全体が失敗します。

ウィンドウ、間隔、バックフィル

• evaluation_window_days はローリングコンプライアンスウィンドウです（7、30、90 など）。
• evaluation_time_interval_seconds はバケットサイズであり、time_slice の場合はスライスサイズです。UI ではスライスに 60 と 300 が用意されており、Datadog が提供する 2 つの値と同じです。
• evaluate_from は評価の開始位置であり、評価器はそこから現在までを、1 回につき 20 バケットのバッチでバックフィルします。60 秒間隔で数か月前に設定すると、最新の状態に追いつくまでに数万バケットが必要になります。実際に確認したいウィンドウの開始位置に設定してください。
• evaluation_start_time が evaluate_from より前の場合は、evaluate_from 以降に切り詰められます。
• UI と /groups が公開するロールアップ：last_2_hour、last_24_hour、last_7_days、last_28_days。

注意点

注意点	結果
evaluation_time_interval_seconds: 0	作成時に 500 エラーが発生します。既存の値が 0 の場合、評価器は SLO をスキップします
status が "active" ではない	保存・一覧表示されますが、評価されません
/list に status=active を指定しない	「SLO がない」ように見える空の一覧になります
/list または GET /{id} に current_time を指定しない	500 エラーが発生します
selectedMode を省略	黙って traces として扱われます — promql だけを設定したメトリクス SLI はトレースを照会し、何も見つけられません
unified_filter にクエリツールのフィールド名（service、type）を指定	評価のたびにエラーが発生し、SLO は no_data のままになります
groupBy の結果が 100 グループを超える	すべてのバケットがスキップされます — データがなく、UI にエラーも表示されません
正常値と合計値で groupBy のリストが異なる	孤立した正常グループは上限に合わせて調整され、コンプライアンスが 100% と表示されます
alert_ids のないアラート SLO	評価器にスキップされます（そうでなければ、永遠に完璧な 100% を報告してしまいます）
warning_target_percentage が目標値より低い	警告されません — 警告値は目標値より高くする必要があります
time_slice の operation に長形式（less_than）または小文字（lt）を指定	API の検証は通りますが、評価器では読み取れません — すべてのスライスがダウンタイムとして記録され、永久に 0% になります。大文字の GT／GTE／LT／LTE／EQ のみ使用できます
time_slice の operation: "NEQ"	UI のドロップダウンに表示されているにもかかわらず、作成時に拒否されます
by (…) を含むメトリクス by_count で、groupBy が空	最初の系列だけがカウントされ、残りは何も表示されずに消えます
手書きのルール自身のラベルに slo_id が含まれている	次の PUT /api/slo で、生成されたルールとともに削除されます
ルールが存在する前の evaluate_from を指定したアラート SLO	作り出された完全な稼働時間がバックフィルされます — no-data として記録されません
生成されたバーンレートルールを編集	次の PUT /api/slo で元に戻されます
部分的な本文で PUT	全置換されます — 送信されなかったフィールドにはゼロ値が書き込まれます
evaluation_window_days が 7 の倍数ではなく、かつ 31 を超える（例：90）	API 経由では動作しますが、UI の期間入力（1～31 × 日／週）では表現できないため、後で UI から編集すると検証に失敗します

欠損データの扱いはタイプごとに異なります — 意図的な仕様です

• by_count：分母が空の場合は no_data になります。コンプライアンスは計算されず、 バケットもスコアリングされません。
• time_slice：Datadog と同様に、欠損データは稼働時間としてカウントされます。件数を 返すクエリの結果が 0 の場合は「データなし」として扱われるため、トラフィックがゼロの 1 分間は正常な スライスになります。この仕様により、テレメトリの停止が健全な SLO として表示されることがあります。
• alert：ダウンタイムは、指定されたルールの発火区間の和集合です。ウィンドウの端でルールが 発火中の場合、その端まで発火中としてカウントされます。発火行がまったくないバケットは no-data ではなく、完全に健全としてスコアリングされます。そのため、 ルール自体が存在するより前の evaluate_from を指定すると、作り出された完全な稼働時間が予算に バックフィルされます。evaluate_from は、ルールが存在し始めた時点に設定してください。

SLO を引き継ぐ際は、どのタイプに該当するかを伝えてください。「この数値はおかしい」という声の 最も一般的な原因です。

エラーバジェットとバーンレート

• error_budget_percentage = 100 - slo_target_percentage。
• error_budget_balance = (1 - error% / budget%) × 100。上限・下限で制限されません — 予算を 超過すると負の値になります（目標 99.9% に対して実績 99.52% の場合は −380%）。これは Datadog と同じ動作です。負の値を「修正」しないでください。これは予算の消費状況です。
• バーンレートは正規化されています。ウィンドウの長さにかかわらず、1.0 はウィンドウ全体で予算を ちょうど使い切ることを意味します。一覧ページのインジケーターは 2 時間のウィンドウを使用し、 6 を超えると重大、1 を超えると高めと表示します — Datadog と同じしきい値です。
• 出力される系列：kubesense_slo_evaluated_events_total／_good、 kubesense_slo_evaluated_events_bad_percent、kubesense_slo_error_budget_balance、 kubesense_slo_burn_rate（ウィンドウは 1h、2h、6h）、 kubesense_slo_breached、kubesense_slo_status、kubesense_slo_burn_rate_status。 kubesense-metrics で照会できます。

ルール

1. まず実在するメトリクス名とフィールド名を確認します（get-available-metrics、 get-trace-or-log-fields）。決して推測で作らないでください。
2. unified_filter ではアラートエンジンのフィールド語彙を使用します。service ではなく app_service、type ではなく level を使用します。
3. 作成前に必ず POST /api/slo/preview を実行し、返されたコンプライアンスと予算の数値をユーザーに示します。プレビューは無料で、何も保存しません。
4. 両方のフィルターで selectedMode を明示的に設定します。デフォルトは traces です。
5. evaluation_time_interval_seconds > 0 かつ status: "active" を常に設定します。
6. good と total で groupBy を同一にし、グループ数を 100 より十分少なく抑えます。また、by (…) だけでは系列が 1 つになるため、メトリクス SLI でも設定します。
7. バーンレートのアラートルールを手書きしてはいけません。alert_types を使用し、チャンネル ID が存在することを先に確認します。
8. PUT はオブジェクト全体を送信します。編集前に SLO を読み戻してください。
9. time_slice の演算子は大文字の GT、GTE、LT、LTE、EQ です。これ以外は最初から最後まで機能しません。
10. 作成したタイプの欠損データの意味を明記します。アラート SLO では、ルールが作成された時点に evaluate_from を設定します。
11. POST /api/slo が ID を返さない限り、SLO が作成されたと主張してはいけません。また、イベントを含む実際のバケットが返るまでは（ステップ 6）、動作していると言ってはいけません。