kubesense-dashboards

KubeSense ダッシュボード

ダッシュボードのプリセットを作成します。エクスポートボタンで生成されるものと同じ形式なので、エクスポートしたダッシュボードを編集して再インポートできます。

提供方法は 2 つあります。

	create-dashboard MCP ツール	プリセット JSON
適用する人	エージェント（書き込みツールのため、承認が必要です）	ユーザー（ダッシュボード → インポートから）
使用する場合	ユーザーが作成を依頼した場合	JSON を求められた場合、または先に内容を確認したい場合
出力する形式	プリセットオブジェクトそのもの	インポートエンベロープ。preset は文字列化します

どちらも同じサーバー側スキーマチェックを通るため、validate-dashboard-json を通過するプリセットは、どちらの方法でも受け入れられます。

使用する場合

• 「……のダッシュボードを作成して」／「……のパネルがあるダッシュボードを作って」→ create-dashboard
• 「……のダッシュボード JSON をください」→ プリセット JSON
• 「ダッシュボードのプリセットを生成して」→ プリセット JSON

完了前に必ず検証する

プリセットを作成する前、またはユーザーに渡す前に、validate-dashboard-json を呼び出してください。 何も保存されないため、必要なだけ呼び出せます。

# valid=false findings=2
path                              rule   message
/panels/0/queries/0/selectedMode  shape  value must be one of 'logs', 'metrics', 'traces', 'formula'
/gridLayout/0                     shape  must have required property 'h'

各 path は、修正すべき値を正確に示す JSON Pointer です。valid=true になるまで繰り返してください。

document にはプリセットオブジェクトを渡してください。preset フィールドを文字列化したインポートエンベロープではありません。create-dashboard の preset 引数も同様です。

検証でチェックするのは形式であり、データが存在するかどうかではありません。誰も収集していないメトリクスに対するクエリも形式上は正しく、結果は空になります。そのため、先に名前を確認してください。

先にフィールドを確認する

KubeSense MCP サーバーが接続されている場合は、クエリを作成する前に実際の名前を確認してください。メトリクス、グループ化フィールド、フィルターフィールドを推測してはいけません。

確認する項目	ツール
メトリクス名	get-available-metrics
メトリクスラベル（by 用）	get-metric-labels
ログ／トレースのフィールド	get-trace-or-log-fields

ダッシュボードのクエリでは、MCP カタログのラベル名ではなく、ストレージレベルのフィールド名を使用します。これらはウェブアプリから直接送信されます。異なる場合は、検出結果のストレージ列からフィールド名を取得し、パネルのプレビューで確認するようユーザーに伝えてください。ラベルとストレージの違いについては、kubesense-mcp を参照してください。

MCP を使用できない場合は、ユーザーから提供された名前を使用し、確認が必要であることを伝えてください。

出力形式

{
  "name": "<dashboard name>",
  "description": "",
  "preset": "<stringified JSON of the preset object>"
}

重要

このエンベロープでは、preset はネストされたオブジェクトではなく JSON の文字列です。 バリデーターは preset: z.string() を宣言しており、JSON.parse(preset) の後にのみプリセットスキーマを実行します。 オブジェクトを出力すると、"Preset must be a valid JSON string that matches the dashboard preset schema" エラーが発生します。

これはインポートエンベロープにのみ適用されます。create-dashboard と validate-dashboard-json にはプリセットオブジェクトそのものを渡します。文字列化したデータを渡しても動作しますが、このエンベロープでラップしないでください。

name は必須で、空でない値を指定してください。description は省略可能です。

文字列化するオブジェクト：

{
  "gridLayout": [],
  "panels": [],
  "variables": [],
  "subGrids": [],
  "subGridLayout": []
}

必須なのは gridLayout と panels のみです。それ以外は [] がデフォルト値になります。6 つ目の省略可能なキー publicDashboardPath（文字列）も検証されます。

最小限の有効なダッシュボード

稼働中のバリデーターで検証済みです。

{
  "name": "Minimal",
  "description": "",
  "preset": "{\"gridLayout\":[{\"i\":\"0\",\"x\":0,\"y\":0,\"w\":12,\"h\":4}],\"panels\":[{\"name\":\"Up\",\"panelType\":\"timeSeries\",\"queries\":[{\"selectedMode\":\"metrics\",\"label\":\"A\",\"selectedMetric\":\"up\",\"functions\":[]}],\"config\":{}}],\"variables\":[],\"subGrids\":[],\"subGridLayout\":[]}"
}

インポート時に必ずエラーになる項目

次の項目に誤りがあると、インポートはエラーで拒否されます。

1. preset が文字列ではない。
2. トップレベルの name がない、または空である。
3. gridLayout または panels がない。
4. gridLayout の項目に i、x、y、w、h のいずれかがない、または型が正しくない（6 ではなく "6" など）。
5. パネルに name がない、または name: "" である。
6. パネルに queries 配列がない（[] でも構いませんが、キーは必須です）。
7. selectedMode が metrics | logs | traces | formula のいずれでもないクエリ。
8. ログ／トレースのクエリに columnFields がない — これらのクエリで唯一、必須となるフィールドです。
9. columnFields[] の項目で field: "" になっている。
10. expression がない数式、または小文字や小数点を含む数式。
11. 未定義のラベルを参照する数式、自身を参照する数式、参照先のクエリより前に配置された数式、または複数文字のラベルを含む数式。

データをひそかに破壊するもの

ハードエラーよりも危険です。これらは検証を問題なく通過した後、送信したデータを破棄します。 ほぼすべてのフィールドに .catch() が付いているため、不正な値が1つあるだけで、その配列またはオブジェクト全体がデフォルト値にリセットされます。

フィールド	不正な値の場合
functions（メトリクスのクエリ）	配列全体が [] に消去されます — エントリーが1つ不正なだけで、すべての関数が失われます
variables	すべての変数が削除されます — 変数が1つ無効なだけで、配列が空になります
subGrids	すべてのサブグリッドが破棄されます
subGrids[].panels	その行のパネルが空になります
aggregation	{"function": "row_count"} にリセットされます
panelType	"timeSeries" にリセットされます
chart_type	"table" にリセットされます
yAxisLabelFormatter	"auto" にリセットされます
colorScheme	{"type":"palette","palette":"default"} にリセットされます
step	整数以外（例：60.5）は "auto" にリセットされます
pagination	page_size > 500 の場合、オブジェクト全体が {page:1,page_size:50} にリセットされます

このため、値を推測するより、任意フィールドを省略することをおすすめします。フィールドを省略すればデフォルト値が使われますが、誤った値を指定すると、同じオブジェクト内のほかのフィールドまで失われることがあります。

警告

gridLayout のエントリー数は、panels の数以上でなければなりません。 パネルとレイアウトは、i の値ではなく、配列インデックスの位置で対応付けられます。gridLayout のエントリーが不足していても検証を通過し、ダッシュボードの描画時に TypeError が発生します。文字列の i は、sg- プレフィックスを使ってサブグリッドの行を識別するためだけに使用されます。実際のエクスポートでは、インデックス（"0"、"1"、…）が設定されます。

パネル

{
  "name": "CPU by namespace",
  "description": "",
  "panelType": "timeSeries",
  "queries": [],
  "config": {}
}

panelType — 12 個の値：timeSeries、stat、table、list、bar、pie、topList、 treemap、alert、spl、sql、slo。timeSeries はキャメルケースである点に注意してください。

config のインポートが失敗することはありません（オブジェクト全体でエラーを捕捉するため）。そのため、{} は常に安全で、すべてのデフォルト値を継承します。フィールド一覧、デフォルト値、および colorScheme ／ thresholds ／ alignColumns ／ columnFormatting ／ visualFormattingRules の構造については、references/panel-config.md を参照してください。

テーブルパネルでは、列ごとの表示名、表示／非表示、セルの種類（number ／ bar）、しきい値／範囲による色分けを config.columnFormatting[] に指定します。リファレンスを参照してください。

トップリストパネルでは、config.topListDisplayMode は flat（デフォルト）または stacked です。stacked には 2 つ以上の groupBy エントリが必要です。最初のエントリが行となり、残りがその行の中に積み重ねて表示されるブロックになります。ディメンションが 1 つの場合、フィールドの値にかかわらずレンダラーはフラット表示します。値に応じた色分けは config.visualFormattingRules[] に指定します。このパネルタイプでは、thresholds よりこちらが優先されます。どちらもリファレンスに記載されています。

ツリーマップパネルでは、クエリに groupBy を指定し、config はそのままにしてください。colorScheme と単位以外の独自設定項目はありません。返された系列ごとに 1 つのセルを描画し、値に応じてサイズを決め、パネルのパレットからカテゴリ別に色を付けます。pie ／ topList と同じくインスタントパネルなので、config.step は適用されません。クエリレベルの列挙型に treemap がないため、chart_type は topList です（以下を参照）。すべての系列が返されるため、パネル側で絞り込まれることを期待せず、クエリ自体の limit で結果数を制限してください。

アラートパネルでは、クエリでルールと、描画に使うウィジェットを指定します。widgetType は graph、value、summary のいずれかです。graph と value には ruleId が必要で、ルール名を ruleName にキャッシュします。graph にはさらに vizType も指定でき、timeseries（デフォルト）または topList を指定します。topList はルール独自のクエリを、各系列の最新値で順位付けして描画します。value はルールの現在の値だけを表示します。ルールが複数の系列で発火している場合、しきい値を最も超えている値を表示します。greater_than ルールでは最大値、less_than ルールでは最小値です。summary では代わりに filters と、displayFormat（count ／ list ／ both）、colorPreference（text ／ background）、summaryType（monitor ／ group ／ combined）を読み取ります。summaryType によって 1 行の単位が決まります。monitor はルールごとに 1 行、group は発火中のインスタンスごとに 1 行（pod でグループ化されたルールなら、違反中の Pod ごとに 1 行）、combined はルールごとに 1 行で、その横に発火中のインスタンス数を表示します。Datadog の同等機能とは異なり、group では正常なグループを一覧表示できません。エンジンは発火中のインスタンスのみを実体化するため、一度も違反していない系列を表示する行はありません。 slo と同様に、これは /explore/query ではなくアラートエンドポイントから提供されるため、config.step は適用されず、chart_type は topList です。Datadog の 4 つ目のウィジェットである Check Status に相当するものはありません。エンジンが永続化するのは normal と firing のみであり、4 状態のウィジェットでは 2 つのセルに表示するものがないためです。

旧形式で誤っていた設定フィールドが 3 つあります。

• enableThresholds ではなく thresholdDisplayMode。値は off（デフォルト）、lines、 lines_dashed、filled_regions、filled_regions_and_lines、 filled_regions_and_lines_dashed です。
• colorPalette ではなく colorScheme。5 種類のバリアントからなるユニオンです。パレットのバリアントは {"type":"palette","palette":"default"} で、パレットキーは default、success、 warning、error のみです。パネルのスキームにかかわらず特定のクエリの色を固定するには、 クエリ独自の fieldConfig.color を使用してください（クエリごとの色を参照）。
• mergeTables は z.literal(true) で、デフォルト値に含まれています。常に true であり、無効にはできません。false を送信しても、暗黙に true になります。省略してください。

Y 軸の単位

yAxisLabelFormatter は 199 個の値（fieldConfig.unit と同じ列挙型）を受け付けます。よく使う値は、auto、number、percentage、bytes、bytes/sec、nanoseconds、milliseconds、seconds、mCPU、CPU です。トレースの duration を集計するパネルには nanoseconds を使用してください。フォーマッターが ns → µs/ms/s に自動スケーリングします。全リストは references/panel-config.md を参照してください。

警告

percent、percent_unit、short、ops、bps、celsius、fahrenheit、none は存在しないため、黙って auto になります。代わりに percentage、CPU / mCPU、 bytes/sec、number を使用してください。

クエリ

selectedMode によって判別されます：metrics | logs | traces | formula。spl は 有効な selectedMode ではありません。logs/traces クエリで panelType: "spl" と filterMode: "SPL" を使用してください。

メトリクスクエリ

{
  "selectedMode": "metrics",
  "label": "A",
  "selectedMetric": "container_cpu_usage_seconds_total",
  "functions": [],
  "filters": {},
  "queryMode": "builder",
  "promql": "",
  "visible": true,
  "labelOptions": { "type": "auto" },
  "pagination": { "page": 1, "page_size": 50 },
  "fieldConfig": {}
}

すべてのフィールドは省略可能です。queryMode は builder または code です。promql を設定する場合は code を、selectedMetric と functions を指定する場合は builder を使用してください。

variables はフィルターと promql（$name 参照）から自動導出されます。指定した値は上書きされるため、設定する必要はありません。

ログ／トレースクエリ

{
  "selectedMode": "logs",
  "label": "A",
  "columnFields": [],
  "filters": {},
  "queryMode": "builder",
  "filterMode": "MFD",
  "aggregation": { "function": "row_count" },
  "groupBy": [],
  "chart_type": "table",
  "visible": true,
  "sorting": {
    "sortBy": { "field": "", "type": "string", "is_attribute": false },
    "sortOrder": "ASC"
  },
  "query": "",
  "pagination": { "page": 1, "page_size": 50 },
  "fieldConfig": {}
}

重要

columnFields は必須です。空の [] であっても、すべての logs/traces クエリに含めてください。 省略するとインポートに失敗します。エントリーの形式は次のとおりです： {"field": "namespace", "type": "string", "is_attribute": false}。alias と label は任意です。field は空にできません。

• chart_type — 7 つの値：table、stat、bar、pie、topList、timeseries、list。 timeseries はすべて小文字です。timeSeries は黙って table になります。これはクエリレベルの フィールドで、パネルレベルの panelType とは別です。SPL/SQL ではこのパネルが提供されないため、意図的に treemap の選択肢はありません。 treemap パネルは、stat パネルが table を設定するのと同様に、chart_type に topList を設定します。
• filterMode — MFD、ADVANCED_QUERY、SPL、SQL。MFD の等価条件のみのフィルターでは表現できないもの（例：レイテンシーのしきい値）には、query 文字列とともに ADVANCED_QUERY を使用してください。
• groupBy のエントリーは columnFields と同じ形式です。
• list（配列）と value（文字列）は SPL/SQL の列フィールドです。topListLabel / topListValue はありません。

aggregation の type は厳密に指定する必要があります：

{ "function": "p99", "fields": [ { "field": "duration", "type": "float", "is_attribute": false } ] }

• row_count — fields は不要です。
• unique_count — fields が必須で、type は "float" または "string" です。
• avg、sum、max、min、p99、p95、p90、p75、p50 — fields が必須で、type は文字どおり "float" でなければなりません。

fields の欠落、数値集計での type: "string"、無効な名前である function: "count" など、いずれかを誤ると、集計全体が黙って row_count にリセットされます。その結果、パーセンタイルを指定したのに行数が返されます。

数式クエリ

{ "selectedMode": "formula", "label": "C", "expression": "A/B", "visible": true, "fieldConfig": {} }

expression は、空白を除去した後で ^[A-Z0-9+/*()-]+$ に一致する必要があります。そのため、次の制約があります。

• 大文字のみ — a+b は失敗します。
• 小数点は使えません — A*1.5 は失敗します。代わりに A*3/2 を使用してください。
• ラベルは A–Z の1文字です。2文字のラベルは依存関係のチェックに失敗します。
• 数式は、参照するクエリよりも後に queries 配列内に記述する必要があります。
• 自身、または存在しないラベルは参照できません。

クエリごとの色

任意のクエリアーム（メトリクス、ログ、トレース、数式）には、fieldConfig.color を設定できます。これにより、そのクエリが返すすべての系列に色が付き、パネルの colorScheme より優先されます。統計パネルのデフォルトの基本しきい値よりも優先されます。これより優先されるのは、タイプが thresholds の明示的な colorScheme だけです。クエリの意味が固定されている場合（エラーは赤、成功は緑など）に使用すると、パネル内でのクエリの位置に色が左右されません。

{ "selectedMode": "traces", "label": "A", "...": "...",
  "fieldConfig": { "color": { "type": "single", "color": "#4AAD5A" } } }
{ "selectedMode": "traces", "label": "B", "...": "...",
  "fieldConfig": { "color": { "type": "palette", "palette": "error" } } }

• single — 1つの16進カラーコード（#rgb、#rrggbb、またはアルファ付き）。複数の系列を返すグループ化クエリでは、すべて同じ色になるのではなく、その色の濃淡で描画されます。
• palette — default | success | warning | error。クエリの最初の系列から順に使用されます。任意の offset（0以上の整数）を指定すると、後のスロットから開始します。
• color（または fieldConfig 全体）を省略すると、パネルの配色を継承します。

16進カラーコード以外の色、または不明なパレット名は、インポート時に検証に失敗します。UIがその値を読み取った場合は、パネルの配色にフォールバックします。完全な形式については、references/panel-config.md を参照してください。

フィルター

filters は Record<string, string[]> です。

{ "namespace": ["production"], "level": ["ERROR", "FATAL"] }

• 属性キーには @_@ を付けます。例："@[email protected]": ["abc"]。
• 除外するには、値の先頭に - を付けます：{"namespace": ["-kube-system"]}。
• $name の値は、ダッシュボード変数への参照です。

メトリクスクエリ関数

functions は順序付きのパイプラインです。形式が不正なエントリーが1つでもあると、配列全体が消去されます。また、引数の数は指定されたタプルと完全に一致する必要があるため、慎重に組み立ててください。

type	names	arguments
range	rate、increase、resets	[{arg_name:"over", arg_value:"5m"}] — 任意の文字列
aggregations	sum、avg、max、min、count、No_Aggregations	[{arg_name:"by", arg_value:["namespace"]}] — 配列である必要があります
top_bottom	top、bottom	[{arg_name:"k",arg_value:5},{arg_name:"by",arg_value:"max"}] — by ∈ max|min|avg|median|last
rollup	avg_over_time、sum_over_time、max_over_time、min_over_time、count_over_time、last_over_time、absent_over_time、present_over_time、increases_over_time、range_over_time、quantile_over_time	[{arg_name:"over", arg_value:"5m"}] — 30s|1m|5m|30m|1h|1d に制限されます
comparison	greater、lesser、greater_than_or_equal、less_than_or_equal、equal、not_equal	[{arg_name:"than"|"to", arg_value:100}]
transform	clamp（min+max）、clamp_max（max）、clamp_min（min）、round（to_nearest）、histogram_quantile（quantile）、abs / sort / sort_desc（なし）	引数名は括弧内のとおりです。引数が0個の場合でも、arguments キーは必須です。引数が0個の関数には [] を使用してください。

警告

range.over には任意の文字列を指定できますが、rollup.over で受け付けられるのは 30s、1m、5m、30m、1h、1d のみです。over: "7m" を指定した rollup は、そのクエリのすべての関数を通知なく削除します。

時系列パイプラインで一般的なのは、rate の後に aggregations を指定する方法です。

"functions": [
  { "type": "range", "name": "rate", "arguments": [ { "arg_name": "over", "arg_value": "5m" } ] },
  { "type": "aggregations", "name": "sum", "arguments": [ { "arg_name": "by", "arg_value": ["namespace"] } ] }
]

グリッドレイアウト

{ "i": "0", "x": 0, "y": 0, "w": 6, "h": 4 }

5つすべてのキーが必須です。12列のグリッドで、rowHeight は100px、パネルの minH は2です。範囲の検証は行われないため、w: 99 も受け付けられますが、正しく表示されません。

• x：0～11。横並びの場合、2列なら 0, 6、3列なら 0, 4, 8。
• y：前の行の高さを加算します。
• i：配列インデックスを文字列にしたものです。位置で対応付けられるため、gridLayout は panels と同じ順序にし、要素数は panels 以上にしてください。

変数と行

どちらも任意で、ほとんどのダッシュボードでは不要です。variables、subGrids、subGridLayout を省略すると、デフォルトで [] になります。

ダッシュボードでテンプレート変数（クエリフィルターに $name を渡すドロップダウン）または行（折りたたみ可能なパネルグループ）が必要な場合は、スキーマについて references/variables-and-rows.md を参照してください。そのファイルに引き継ぐべき点は2つあります。変数の description は必須です（"" を使用してください）。また、無効な変数が1つでもあると、すべての変数が通知なく削除されます。

提供方法

直接作成する

validate-dashboard-json  →  valid=true  →  create-dashboard

create-dashboard は、name、preset（オブジェクト、またはそれを含む JSON 文字列）、および省略可能な description を受け取ります。ダッシュボード ID と UI のパスを返すので、ユーザーが開けるようにそのパスを引用してください。

これは書き込みツールです。ユーザーがダッシュボードの作成を明確に依頼した場合にのみ呼び出し、呼び出す前に作成する内容を伝えてください。拒否された場合、問題ごとの JSON Pointer が応答に示されます。JSON を渡す方法に切り替えるのではなく、問題を修正して再試行してください。

インポート用の JSON を渡す

1. JSON を .json ファイルにコピーします（インポート UI では application/json が必要です）。
2. KubeSense → Dashboards → Import。
3. アップロードして内容を確認し、保存します。

この方法では、ダッシュボードが作成されたと決して言わないでください。ユーザーがインポートして確定します。

ルール

ルール 0：作成または引き渡しの前に validate-dashboard-json を実行し、報告された問題を修正してください。インポート時に致命的なエラーになる項目はすべて機械的にチェックされます。バリデーターが JSON Pointer を示すため、ここでチェックリストを用意する必要はありません。

このチェックリストは、バリデーターが検出できない項目を対象としています。 以下のルールはすべて検証を通過しますが、その後データが黙って破棄されたり、レンダリング時にクラッシュしたりします。検証に合格してもダッシュボードが動作するとは限りません。引き渡す前に、これらの項目を手動で確認してください。

1. gridLayout は panels と同じ順序で、panels 以上の長さにする必要があります。対応付けは位置で行われるため、レイアウトが短いとダッシュボードのレンダリング時に TypeError が発生します。
2. 数値の集計には、fields[].type: "float" が厳密に必要です。そうでない場合、集計全体が row_count にリセットされます。パーセンタイルを指定しても、行数になってしまいます。
3. chart_type は小文字の timeseries、panelType はキャメルケースの timeSeries です。一致しない場合、それぞれのデフォルト（table／timeSeries）にリセットされます。
4. rollup.over で受け付けられるのは 30s／1m／5m／30m／1h／1d のみです。無効な値を指定すると、そのクエリのすべての関数が消去されます。
5. 変数には description（"" を使用）と、正規表現に適合する 20 文字以下の name が必要です。変数が 1 つでも無効だと、すべて削除されます。
6. y 軸には実際に使用できる単位（percentage、mCPU、bytes/sec）を使ってください。percent、short、none は auto になります。
7. enableThresholds、colorPalette、mergeTables: false、topListLabel、topListValue は出力しないでください。いずれも存在せず、不明なキーは何も通知されずに削除されます。トップリストでは、値の色分けは thresholds ではなく visualFormattingRules に指定します。
8. 任意のフィールドは推測して指定するより、省略することを優先してください。省略したフィールドにはデフォルト値が適用されますが、誤った値を指定すると、関連するフィールドまでリセットされる場合があります。
9. 検証で確認されるのは形式であり、実在するかどうかではありません。クエリを作成する前に MCP でメトリクス名とフィールド名を調べ、パネルのプレビューで確認するようユーザーに伝えてください。

両方の方法に共通するルールは 1 つです。インポート用のエンベロープでは preset は JSON 文字列化された文字列ですが、create-dashboard または validate-dashboard-json に渡す場合は通常のオブジェクトです。