KubeSense Dashboards

Build a dashboard preset — the same shape the Export button produces, so an exported dashboard can be edited and re-imported.

Two ways to deliver it:

	`create-dashboard` MCP tool	Preset JSON
Applied by	the agent (write tool, needs approval)	the user, via Dashboards → Import
Use when	the user asked you to create one	they asked for the JSON, or want to review first
Shape to emit	the preset object itself	the import envelope, with `preset` stringified

Both go through the same server-side schema check, so a preset that passes

validate-dashboard-json

is one that both paths accept.

When to Use

"Create a dashboard for…" / "Build a dashboard with panels for…" →
```
create-dashboard
```
"Give me the dashboard JSON for…" → preset JSON
"Generate a dashboard preset" → preset JSON

Always Validate Before You Finish

Call validate-dashboard-json
on the preset before creating it or handing it over. It stores nothing, so call it as often as you need.

# 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'

Each

path

is a JSON Pointer to the exact value to fix. Repeat until

valid=true

Pass the preset object as

document

— not the import envelope with the stringified

preset

field. Same for

create-dashboard

preset

argument.

Validation checks shape, not whether the data exists. A query against a metric nobody collects is well-formed and will render empty, so discover names first.

Discover Fields First

If the KubeSense MCP server is connected, discover real names before writing queries — never guess a metric, group-by, or filter field.

To find	Tool
Metric names	`get-available-metrics`
Metric labels (for `by` )	`get-metric-labels`
Log/trace fields	`get-trace-or-log-fields`

Dashboard queries use storage-level field names, not the MCP catalog labels — the webapp posts these directly. Take field names from the discovery output's storage column where they differ, and tell the user to confirm on the panel preview. See kubesense-mcp for the label/storage distinction.

Without MCP, fall back to user-provided names and say they need verifying.

Output Format

json

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

[!IMPORTANT] In this envelope,
preset
is a JSON string, not a nested object. The validator declares
preset: z.string()
and only runs the preset schema after
JSON.parse(preset)
. Emitting an object fails with "Preset must be a valid JSON string that matches the dashboard preset schema".
This applies to the import envelope only.
create-dashboard
and
validate-dashboard-json
take the preset object itself — passing a stringified blob to them works too, but do not wrap it in this envelope.

name

is required and non-empty.

description

is optional.

The object you stringify:

json

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

Only

gridLayout

and

panels

are required; the rest default to

[]

. A sixth optional key,

publicDashboardPath

(string), also validates.

Minimal Valid Dashboard

Verified against the live validator:

json

{
  "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\":[]}"
}

What Hard-Fails Import

Get these wrong and import is rejected with an error:

```
preset
```
not a string.
Missing or empty top-level
```
name
```
.
Missing
```
gridLayout
```
or
```
panels
```
.
A
```
gridLayout
```
item missing any of
```
i
```
,
```
x
```
,
```
y
```
,
```
w
```
,
```
h
```
, or with a wrong type (
```
"6"
```
instead of
```
6
```
).
A panel missing
```
name
```
, or
```
name: ""
```
.
A panel missing the
```
queries
```
array (it may be
```
[]
```
, but the key must exist).
A query whose
```
selectedMode
```
is not
```
metrics
```
|
```
logs
```
|
```
traces
```
|
```
formula
```
.
A logs/traces query missing
columnFields
— the single hard-required field on those queries.
A
```
columnFields[]
```
entry with
```
field: ""
```
.
A formula missing
```
expression
```
, or one containing lowercase letters or a decimal point.
A formula referencing an undefined label, referencing itself, placed before the queries it references, or with a multi-character label.

What Silently Destroys Your Data

More dangerous than hard failures — these validate cleanly and then discard what you sent. Almost every field carries a

.catch()

, so a single bad value resets its whole array or object to the default.

Field	On a bad value
`functions` (metrics query)	The entire array is wiped to `[]` — one malformed entry loses every function
`variables`	All variables deleted — one invalid variable empties the array
`subGrids`	All sub-grids dropped
`subGrids[].panels`	That row's panels emptied
`aggregation`	Resets to `{"function": "row_count"}`
`panelType`	Resets to `"timeSeries"`
`chart_type`	Resets to `"table"`
`yAxisLabelFormatter`	Resets to `"auto"`
`colorScheme`	Resets to `{"type":"palette","palette":"default"}`
`step`	Non-integer (e.g. `60.5` ) resets to `"auto"`
`pagination`	`page_size > 500` resets the whole object to `{page:1,page_size:50}`

Because of this, prefer omitting an optional field over guessing its value — an omitted field takes the default; a wrong one can take out its siblings.

[!WARNING] gridLayout
must have at least as many entries as
panels
. Panels and layout are matched positionally by array index, not by the
i
value. A short
gridLayout
passes validation and then throws a TypeError when the dashboard renders. The
i
string is only used to identify sub-grid rows (via a
sg-
prefix); real exports set it to the index (
"0"
,
"1"
, …).

Panel

json

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

panelType

— 12 values:

timeSeries

stat

table

list

bar

pie

topList

treemap

alert

spl

sql

slo

. Note camelCase

timeSeries

config

can never fail import (the whole object catches), so

{}

is always safe and inherits every default. For the full field list, defaults, and the

colorScheme

thresholds

alignColumns

columnFormatting

visualFormattingRules

shapes, read references/panel-config.md.

For a table panel, per-column display names, visibility, cell type (

number

bar

), and threshold/range colouring go in

config.columnFormatting[]

— see the reference.

For a top-list panel,

config.topListDisplayMode

flat

(default) or

stacked

, and

stacked

needs two or more
groupBy
entries — the first is the row, the rest are the blocks stacked inside it. With one dimension the renderer draws flat whatever the field says. Value-driven colouring goes in

config.visualFormattingRules[]

, which supersedes
thresholds
for this panel type. Both are in the reference.

For a treemap panel, give the query a

groupBy

and leave

config

alone — it has no config of its own beyond

colorScheme

and the unit, and it draws one cell per returned series, sized by value and coloured categorically from the panel palette. It is an instant panel like

pie

topList

, so

config.step

does not apply. Its

chart_type

topList

(see below), since the query-level enum has no

treemap

arm. Every series comes back, so cap the result with the query's own

limit

rather than expecting the panel to trim it.

For an alert panel, the query names a rule and the widget to draw it as:

widgetType

graph

value

summary

graph

and

value

need a

ruleId

(and cache the rule's name in

ruleName

);

graph

also takes

vizType

timeseries

(default) or

topList

, which draws the rule's own query ranked by each series' last value.

value

prints that rule's current figure alone — for a rule firing on several series it is the one furthest past the threshold, highest for a

greater_than

rule and lowest for a

less_than

one.

summary

reads

filters

instead, plus

displayFormat

(

count

list

both

colorPreference

(

text

background

) and

summaryType

(

monitor

group

combined

summaryType

decides what one row is:

monitor

one per rule,

group

one per firing instance (a rule grouped by

pod

gets a row per breaching pod),

combined

one per rule with its firing instances counted beside it. Unlike Datadog's equivalent,

group

cannot list healthy groups — the engine materialises an instance only while it is firing, so a series that never breached has no row to show. Like slo it is served by the alert endpoints, not

/explore/query

, so

config.step

does not apply and its

chart_type

topList

. Datadog's fourth widget, Check Status, has no arm: the engine persists only

normal

and

firing

, so a four-state widget would have nothing to put in two of its cells.

Three config fields the old format got wrong:

thresholdDisplayMode
, not

enableThresholds

. Values:

off

(default),

lines

lines_dashed

filled_regions

filled_regions_and_lines

filled_regions_and_lines_dashed

colorScheme
, not
```
colorPalette
```
. A 5-variant union; the palette variant is
```
{"type":"palette","palette":"default"}
```
and the only palette keys are
```
default
```
,
```
success
```
,
```
warning
```
,
```
error
```
. To pin one query's colour regardless of the panel scheme, use the query's own
```
fieldConfig.color
```
(see Per-query color).
mergeTables
is
```
z.literal(true)
```
and lives in the defaults — it is always
true
and cannot be disabled. Sending
```
false
```
silently becomes
```
true
```
. Just omit it.

Y-axis units

yAxisLabelFormatter

accepts 199 values — the same enum as

fieldConfig.unit

. Common ones:

auto

number

percentage

bytes

bytes/sec

nanoseconds

milliseconds

seconds

mCPU

CPU

. Use

nanoseconds

for any panel aggregating trace

duration

— the formatter auto-scales ns → µs/ms/s. Full list in references/panel-config.md.

[!WARNING]
percent
,
percent_unit
,
short
,
ops
,
bps
,
celsius
,
fahrenheit
, and
none
do not exist and silently become
auto
. Use
percentage
,
CPU
/
mCPU
,
bytes/sec
,
number
instead.

Queries

Discriminated on

selectedMode

metrics

logs

traces

formula

. Note

spl

is not a valid

selectedMode

— use

panelType: "spl"

with a logs/traces query and

filterMode: "SPL"

Metrics query

json

{
  "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": {}
}

Every field is optional.

queryMode

builder

code

— use

code

with

promql

set,

builder

with

selectedMetric

functions

variables

is auto-derived from filters and promql (

$name

references) — anything you supply is overwritten. Don't bother setting it.

Logs / traces query

json

{
  "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": {}
}

[!IMPORTANT] columnFields
is required — include it on every logs/traces query, even as
[]
. Omitting it is a hard import failure. Entry shape:
{"field": "namespace", "type": "string", "is_attribute": false}
with optional
alias
and
label
.
field
must be non-empty.

```
chart_type
```
— 7 values:
```
table
```
,
```
stat
```
,
```
bar
```
,
```
pie
```
,
```
topList
```
,
```
timeseries
```
,
```
list
```
. Lowercase
timeseries
—
```
timeSeries
```
silently becomes
```
table
```
. This is a query-level field, separate from the panel-level
```
panelType
```
. There is deliberately no
treemap
arm: the panel is not offered for SPL/SQL, so a
```
treemap
```
panel sets
```
chart_type
```
to
```
topList
```
the way a
```
stat
```
panel sets
```
table
```
.
```
filterMode
```
—
```
MFD
```
,
```
ADVANCED_QUERY
```
,
```
SPL
```
,
```
SQL
```
. Use
```
ADVANCED_QUERY
```
with a
```
query
```
string for anything MFD's equality-only filters can't express (e.g. a latency threshold).
```
groupBy
```
entries use the same shape as
```
columnFields
```
.
```
list
```
(array) and
```
value
```
(string) are the SPL/SQL column fields. There is no
```
topListLabel
```
/
```
topListValue
```
.

aggregation
is strict about
type
:

json

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

```
row_count
```
— no
```
fields
```
.
```
unique_count
```
—
```
fields
```
required,
```
type
```
is
```
"float"
```
or
```
"string"
```
.

avg

sum

max

min

p99

p95

p90

p75

p50

—

fields

required and

type

must be literally
"float"
.

Get any of that wrong — missing

fields

type: "string"

on a numeric aggregation, or

function: "count"

(not a valid name) — and the whole aggregation silently resets to

row_count

, giving you a row count where you asked for a percentile.

Formula query

json

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

expression

must match

^[A-Z0-9+/*()-]+$

after whitespace is stripped. Consequences:

Uppercase only —
```
a+b
```
fails.
No decimal point —
```
A*1.5
```
fails. Use
```
A*3/2
```
.
Labels are single letters A–Z; a two-character label breaks the dependency check.
The formula must appear after the queries it references in the
```
queries
```
array.
It cannot reference itself, or a label that doesn't exist.

Per-query color

Any query arm (metrics, logs, traces, formula) may carry

fieldConfig.color

. It colours every series that query yields and outranks the panel
colorScheme
, including the stat panel's default base threshold. Only an explicit

colorScheme

of type

thresholds

outranks it. Use it whenever the meaning of a query is fixed — errors red, success green — so the colour does not depend on the query's position in the panel.

json

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

```
single
```
— one hex colour (
```
#rgb
```
,
```
#rrggbb
```
, or with alpha). A grouped query that returns several series is drawn in shades of it, not all identical.
```
palette
```
—
```
default
```
|
```
success
```
|
```
warning
```
|
```
error
```
, cycled from the query's first series. Optional
```
offset
```
(integer ≥ 0) starts at a later slot.
Omit
```
color
```
(or the whole
```
fieldConfig
```
) to inherit the panel scheme.

A non-hex colour or an unknown palette name fails validation on import; the UI, if it ever reads one, drops back to the panel scheme. Full shape in references/panel-config.md.

Filters

filters

Record<string, string[]>

json

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

Attribute keys are prefixed
```
@_@
```
, e.g.
```
"@_@user.id": ["abc"]
```
.
Exclusion is a
```
-
```
prefix on the value:
```
{"namespace": ["-kube-system"]}
```
.
A
```
$name
```
value is a dashboard-variable reference.

Metrics Query Functions

functions

is an ordered pipeline. One malformed entry wipes the entire array, and argument counts are exact tuples — so build these carefully.

type	names	arguments
`range`	`rate` , `increase` , `resets`	`[{arg_name:"over", arg_value:"5m"}]` — any string
`aggregations`	`sum` , `avg` , `max` , `min` , `count` , `No_Aggregations`	`[{arg_name:"by", arg_value:["namespace"]}]` — must be an array
`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"}]` — restricted to `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` (none)	arg names in parens; the `arguments` key is still required — use `[]` for the zero-arg ones

[!WARNING]
range.over
accepts any string, but rollup.over
only accepts
30s
,
1m
,
5m
,
30m
,
1h
,
1d
. A
rollup
with
over: "7m"
silently deletes every function on that query.

Typical time-series pipeline:

rate

then

aggregations

json

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

Grid Layout

json

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

All five keys required. 12-column grid,

rowHeight

100px, panel

minH

2. No bounds are validated —

w: 99

is accepted and renders broken.

```
x
```
: 0–11. Side by side:
```
0, 6
```
for two columns;
```
0, 4, 8
```
for three.
```
y
```
: increment by the previous row's height.
```
i
```
: the array index as a string. Matching is positional, so keep
```
gridLayout
```
in the same order as
```
panels
```
, and at least as long.

Variables and Rows

Both are optional and most dashboards need neither — omit

variables

subGrids

, and

subGridLayout

and they default to

[]

If the dashboard needs a template variable (a dropdown feeding

$name

into query filters) or rows (collapsible panel groups), read references/variables-and-rows.md for the schemas. Two things to carry into that file: a variable's

description

is required (use

""

), and one invalid variable silently deletes every variable.

Delivering It

Creating it directly

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

create-dashboard

takes

name

preset

(the object, or a JSON string containing it) and an optional

description

. It returns the dashboard id and its UI path — quote that path so the user can open it.

It is a write tool: only call it when the user has clearly asked for a dashboard to be created, and say what you are about to create before calling. If it refuses, the response names the JSON Pointer for every problem; fix them and retry rather than falling back to handing over JSON.

Handing over JSON to import

Copy the JSON to a
```
.json
```
file (the import UI requires
```
application/json
```
).
KubeSense → Dashboards → Import.
Upload and review, then save.

On this path never claim the dashboard was created — the user imports and confirms it.

Rules

Rule 0: run

validate-dashboard-json

before creating or handing over, and fix what it reports. Everything in What Hard-Fails Import is machine-checked — the validator names the JSON Pointer, so it needs no checklist here.

This checklist is for what the validator is blind to. Every rule below passes validation and then silently discards your data or crashes at render. A green validation is not a working dashboard — check these by hand before you hand it over.

```
gridLayout
```
must be at least as long as
```
panels
```
, in the same order — matching is positional, and a short layout throws a TypeError when the dashboard renders.
Numeric aggregations need
```
fields[].type: "float"
```
exactly, or the whole aggregation resets to
```
row_count
```
— a row count where you asked for a percentile.
```
chart_type
```
is lowercase
```
timeseries
```
;
```
panelType
```
is camelCase
```
timeSeries
```
. Each resets to its own default (
```
table
```
/
```
timeSeries
```
) on a mismatch.
```
rollup.over
```
only accepts
```
30s
```
/
```
1m
```
/
```
5m
```
/
```
30m
```
/
```
1h
```
/
```
1d
```
; a bad value wipes every function on that query.
Variables need
```
description
```
(use
```
""
```
) and a regex-valid
```
name
```
≤ 20 chars — one bad variable deletes them all.

Use real y-axis units (

percentage

mCPU

bytes/sec

) —

percent

short

none

become

auto

Don't emit
```
enableThresholds
```
,
```
colorPalette
```
,
```
mergeTables: false
```
,
```
topListLabel
```
, or
```
topListValue
```
— none exist, and unknown keys are stripped without comment. On a top list, value colouring goes in
```
visualFormattingRules
```
, not
```
thresholds
```
.
Prefer omitting an optional field to guessing it: an omitted field takes its default, a wrong one can reset its siblings.
Validation checks shape, not existence. Discover metric and field names with MCP before writing queries, and tell the user to confirm on the panel preview.

The one rule that spans both:

preset

is a stringified JSON string in the import envelope, but the plain object when passed to

create-dashboard

validate-dashboard-json

kubesense-dashboards

NPX Install

Tags

SKILL.md Content

KubeSense Dashboards

When to Use

Always Validate Before You Finish

Discover Fields First

Output Format

Minimal Valid Dashboard

What Hard-Fails Import

What Silently Destroys Your Data

Panel

Y-axis units

Queries

Metrics query

Logs / traces query

Formula query

Per-query color

Filters

Metrics Query Functions

Grid Layout

Variables and Rows

Delivering It

Creating it directly

Handing over JSON to import

Rules