elastic/agent-skills

kibana-dashboards

Create and manage Kibana Dashboards and Lens visualizations.

Zobacz źródło

Jak używać

  1. Skopiuj polecenie instalacji i sprawdź źródła przed instalacją we własnym środowisku agenta.
  2. W oryginale sprawdź wymagane narzędzia, dane dostępowe i obsługiwane środowiska.
  3. Opisz dane wejściowe i oczekiwany rezultat; porównaj wynik ze źródłami.
npx skills add https://github.com/elastic/agent-skills --skill kibana-dashboards

Przed rozpoczęciem

  • Instalacja nie obejmuje subskrypcji modelu, limitu API ani uprawnień do plików.
  • Gwiazdki i instalacje pokazują aktywność, a nie niezależny test jakości lub bezpieczeństwa.
Oryginalny dokument Skill

Treść z repozytorium z zachowaniem nagłówków, przykładów, kodu, tabel, linków i obrazów.

Kibana Dashboards and Lens Visualizations

Create, update, and delete Kibana dashboards and standalone Lens visualizations using the Kibana 9.4+ Dashboards and Visualizations APIs. Produce minimal, diffable JSON bodies; prefer inline panel definitions over library references; choose the correct dataset type (data view vs ES|QL) before writing metrics or chart layers; and follow the design guidance in Dashboard Design Guidelines and Chart Design Guidelines so the result reads like a well-made Kibana dashboard, not a schema dump.

<!-- begin-partial: preamble -->

Environment Configuration

This skill executes Elasticsearch operations through the elastic CLI. If the `elastic` CLI is not installed, tell the user what it is needed for. Do not guess credentials, call the HTTP API directly, or attempt other workarounds.

This skill references operations in HTTP-shorthand form (e.g., GET /, GET /_cat/indices, GET /{index}/_mapping, GET /{index}/_settings/index.mode, POST /_query). The Operations table at the end of this document maps each shorthand to the equivalent elastic CLI command — always use the CLI rather than calling the HTTP API directly.

<!-- end-partial: preamble -->

Prerequisites

Version requirement: Kibana 9.4+ (Dashboards and Visualizations APIs).

ES|QL placement:

  • Standalone library charts: PUT kbn:/api/visualizations/{id} with data_source.type: "esql".
  • ES|QL panels embedded in a dashboard: inline vis panel config with data_source.type: "esql" via

PUT kbn:/api/dashboards/{id}.

  • Do not use data_source.type: "data_view_reference" or index-pattern aggregations when the user explicitly requests

ES|QL — the persisted Lens state must use a text-based ES|QL datasource (textBased / esql), not a data-view count operation.

Process

  1. Verify Kibana connectivity. Call GET kbn:/api/status. If the call fails, stop and surface the error — do not

guess endpoints or credentials. Read version.number to confirm the cluster meets the 9.4+ requirement, and keep the version in mind: a few settings are marked 9.5+ or 9.6+ in Design essentials and have a fallback for older clusters. Never refuse a dashboard on 9.4 because of them.

  1. Classify the task. Decide whether the user needs a dashboard (collection of panels, optional time range), a

standalone Lens visualization (library item referenced by id or used alone), or both. Determine whether a deterministic saved-object id was supplied — when given, use upsert (PUT) with that id rather than POST (which auto-generates ids).

  1. Choose the dataset type before building metrics or layers.
User intentDatasetMetric / axis pattern
Simple count or aggregation on a saved data viewdata_source.type: "data_view_reference" with ref_idmetrics: [{ type: "primary", operation: "count" }] (or other aggregation operations)
Ad-hoc index patterndata_source.type: "data_view_spec" with index_pattern and time_fieldSame aggregation operation fields
ES\QL query (explicit or complex logic)data_source.type: "esql" with querymetrics: [{ type: "primary", column: "<alias>" }] or layer axes { column: "<alias>" } — never operation: "count" on the metric

Write the aggregation in the ES|QL query (STATS count = COUNT()), then reference the resulting column by name.

Write the ES|QL with the `elasticsearch-esql` skill. It covers schema discovery, time series data streams (TS, RATE for counters, METRICS_INFO), and query execution. Two dashboard-specific points on top of it:

  • Run every panel query before saving it, substituting fixed expressions such as NOW() - 7 days for ?_tstart and

?_tend, which only Kibana can supply.

  • Check the data's time span (STATS MIN(@timestamp), MAX(@timestamp)). Without a saved time_range, Kibana opens

the dashboard on the last 15 minutes, so a dashboard over older or historical data renders empty panels. Tell the user which range shows data, or ask whether to persist one.

  1. Design before you write. Read Dashboard Design Guidelines and

Chart Design Guidelines and decide the composition, the chart type and grid size of each panel, the per-chart presentation settings, and the exact grid coordinates. The rules most often missed are summarized in Design essentials below. Choices you do not make deliberately fall back to those defaults; they are not optional polish.

  1. Build a dashboard body when creating or updating dashboards. The request body is flat — title, panels, and

optional description, time_range, and pinned_panels at the root. Do not wrap in { data: ... } on write. Required fields:

  • title — exact string the user requested; otherwise a title derived from what the panels measure. Never empty.
  • description — set on every new dashboard.
  • panels — array of panels and sections; use [] when the user asks for an empty dashboard (do not omit the key or

invent panels).

  • time_range — when the user specifies a default time filter, set { "from": "<expr>", "to": "<expr>" } (for

example { "from": "now-7d", "to": "now" }). Supplying time_range persists the dashboard time filter on open (equivalent to enabling time restore in the UI). Do not invent a range the user did not ask for.

  • pinned_panels — the controls chosen in the design step (see the Controls section of the design guidelines).

Upsert with a deterministic id:

json
   {
     "title": "Sales Overview",
     "panels": [],
     "time_range": { "from": "now-7d", "to": "now" }
   }

Call PUT kbn:/api/dashboards/eval-sales-overview with the body above when the user supplies that id.

Inline ES|QL metric panel example (inside panels):

json
   {
     "type": "vis",
     "id": "total-requests",
     "grid": { "x": 0, "y": 0, "w": 12, "h": 5 },
     "config": {
       "type": "metric",
       "data_source": {
         "type": "esql",
         "query": "FROM logs* | STATS `Total requests` = COUNT()"
       },
       "metrics": [{ "type": "primary", "column": "Total requests" }]
     }
   }

The metric has no title because its label already names it, and it is a quarter-width, 5-row panel — both are design defaults, not stylistic choices. Prefer inline config properties over config.ref_id for portable dashboards. Read Dashboard API Reference for panel types and copy workflows.

  1. Build a standalone Lens visualization when the user asks for a library chart. Use the Visualizations API. Upsert

with PUT kbn:/api/visualizations/{id} when an id is supplied; otherwise POST kbn:/api/visualizations and report the generated id from the response.

ES|QL metric (total count from logs):

json
   {
     "type": "metric",
     "title": "Total Requests",
     "data_source": {
       "type": "esql",
       "query": "FROM logs* | STATS count = COUNT()"
     },
     "metrics": [{ "type": "primary", "column": "count" }]
   }

Call PUT kbn:/api/visualizations/eval-total-requests when that id is required. The API persists a Lens saved object whose datasource state uses ES|QL (textBased / esql), not an index-pattern aggregation.

Read Lens API Reference and Chart Types Reference for xy, gauge, heatmap, and other chart schemas, and apply the same Chart Design Guidelines as for dashboard panels.

  1. Edit existing objects in place. PUT replaces the whole document, so GET first, change only what was asked,

and send everything else back unchanged — panel ids, queries, filters, controls, and time_range included.

  1. Execute and confirm. Perform the write with PUT kbn:/api/dashboards/{id} or PUT kbn:/api/visualizations/{id}

(or POST when no id is supplied). Confirm with GET kbn:/api/dashboards/{id} or GET kbn:/api/visualizations/{id}. Report the id and title back to the user — do not claim success without a successful read-back.

A successful read-back proves the object persisted, not that it renders. The API normalizes the body and fills in defaults. Compare the returned config against what you sent and look for values you did not intend, for example legend.visibility: "hidden" on a multi-series chart.

  1. List, export, or delete when requested. Call GET kbn:/api/dashboards or GET kbn:/api/visualizations to

discover existing objects. Call DELETE kbn:/api/dashboards/{id} or DELETE kbn:/api/visualizations/{id} to remove objects. For bulk export or import of saved objects, call POST kbn:/api/saved_objects/_export or POST kbn:/api/saved_objects/_import.

Design essentials

The full rules live in the references; these are the ones most often missed. They apply to every dashboard and visualization you write.

Version-gated settings. Everything else in this skill works on Kibana 9.4. These three need a newer Kibana; below that version use the fallback instead of the setting.

SettingNeedsFallback on older clusters
options_list_control with values_source: "esql"9.5data_view_id and field_name; create a data view if none covers the index
background_chart: { type: "trend" } on an ES\QL metric9.5Omit background_chart; the metric shows the value only
styling: { areas: { fill: "gradient" } }9.6Omit styling.areas; areas render with a solid fill

Dashboard (Dashboard Design Guidelines)

  • Order panels summary metrics → trends → breakdowns. Let the fields drive the panel count; every panel needs a purpose.
  • Non-empty title and a description on every new dashboard, derived from what the queries measure.
  • Sections ({ title, collapsed, grid: { y }, panels } entries in panels) for roughly 6+ visualization panels, each

holding only panels matching its purpose. 3–5 options-list controls in pinned_panels on new dashboards; on an all-ES|QL dashboard, source their values from an ES|QL query (values_source: "esql", 9.5+) instead of a data view.

  • 48-column grid, 20–24 rows above the fold, 8–12 panels in that band. Sizes by chart type:
Panelwh
Metric6, 8, or 125–6
Gauge128
XY, heatmap, tag cloud24 (48 for the primary time series)10
Treemap / waffle / mosaic2410
Pie / donut1210
Markdown24–484–9
Data table24–4812–16

Never make a metric or gauge full-width. Use w values that divide 48. Fill rows left to right; a new row's y is the previous row's y + max(h); panels in a row share h; x + w ≤ 48. Kibana compacts panels upward, so blank rows do not survive — separate groups with sections. Section panels use section-relative coordinates and a section occupies one outer row.

Charts (Chart Design Guidelines)

  • Pick the chart type from the selection list; tag clouds only for short strings, pies for fewer than about 7 slices.
  • No panel title on metric, gauge, tag cloud, and waffle charts; elsewhere a self-explanatory title and no axis titles

(title: { visible: false } on both axes). Never repeat information across title, axes, and labels.

  • Natural units via format: percent, bytes, bits, duration whenever the column reveals one; plain counts unformatted.
  • XY: set legend: { position: "bottom", layout: { type: "list" }, visibility: "visible" } on every chart with a

breakdown_by or more than one y column, and visibility: "hidden" on single-series charts. Use layout: { type: "grid" } only when the legend carries statistics. The API defaults visibility to hidden and layout to grid; it does not count the series. Areas (gradient fill) only up to three series, lines above that. Line charts take the elastic_line_optimized palette on breakdown_by.color. Use scale: "temporal" for time axes, and legend statistics only when asked for avg/min/max "in the legend" (a presentation setting, not an ES|QL aggregation).

  • Metric: trend background or secondary metric when the query supports it; color the value, never the background, and

only for bounded metrics (percentages, error rates) with 3 status bands. Never set apply_color_to without color, and never combine a background chart with color: Lens then colors the background, not the value.

  • Gauge: never invent min/max/goal; default to four equal percentage bands.
  • Heatmap, pie, partition charts, xy series: default palettes unless the user asks. Tables color values as badges only.
  • Color only where it carries meaning, always from the Kibana Palette Catalog, never

invented hex values or legacy palettes; the same category keeps one color across all charts.

  • On edits, preserve explicit user choices and existing thresholds; defaults are preferences, not proof a setting is

wrong.

ES|QL patterns

Time series bucket (dashboard time picker injects ?_tstart / ?_tend):

esql
FROM logs*
| WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart
| STATS count = COUNT() BY BUCKET(@timestamp, 75, ?_tstart, ?_tend)

See Chart Types Reference for axis and layer details.

Time series data stream (TSDS) xy chart. TS queries accept the same BUCKET pattern, so the chart binds the time axis the same way:

esql
TS metrics-otel-default
| WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart AND attributes.device != "lo"
| STATS `Throughput` = SUM(RATE(metrics.system.network.io)) BY BUCKET(@timestamp, 75, ?_tstart, ?_tend), attributes.direction

Metric with trend background. The API copies the query into a hidden trendline layer and adds its own time bucket. On a TS source do not add BUCKET yourself and do not KEEP after STATS; on a FROM source keep the ?_tstart / ?_tend filter, or no trendline is built. Derive values inside STATS:

esql
TS metrics-otel-default
| WHERE attributes.state == "idle"
| STATS `CPU busy` = 1 - AVG(metrics.system.cpu.utilization)

Static reference values — use EVAL in the query, then reference the column:

esql
FROM logs* | STATS count = COUNT() | EVAL goal = 15000

Examples

Two complete dashboard bodies live under assets/. Both use every version-gated setting, so they need Kibana 9.6 as written; on 9.5 drop styling.areas, and on 9.4 also replace the ES|QL-sourced controls and the trend background with their fallbacks.

  • dashboard-esql.json — an ES|QL dashboard over the Kibana sample web logs that follows the design guidance: three

sections, formatted metrics with a trend background and status coloring, a primary time series with legend statistics, breakdown bars, a table, and options-list controls whose values come from ES|QL queries.

  • dashboard-data-view.json — the same dashboard shape built on the sample logs data view with aggregation operations

instead of ES|QL: sections, data-view controls, a primary time series with legend statistics, a heatmap, horizontal bars, and a ranked table with labeled and formatted columns.

Single-chart schema examples for every chart type are in Chart Types Reference.

Guidelines

  1. Minimal payloads, complete presentation — omit derivable metadata and schema defaults, but always set the

presentation settings the design guidance calls for (formats, hidden axis titles, legend position and visibility, gradient areas, metric coloring, gauge bands), subject to the version-gated table in Design essentials. The API does not add these for you.

  1. Read references before complex charts — metric and xy schemas differ between data view and ES|QL; consult

Chart Types Reference before generating partition or table charts.

Common issues

ErrorLikely causeFix
404 on GET after PUTWrong id or spaceConfirm id and retry GET kbn:/api/dashboards/{id}
400 validationES\QL column mismatchAlign metrics[].column / layer column with STATS aliases in the query
ES\QL panel saved as data viewWrong dataset typeUse data_source.type: "esql", not data_view_reference
Empty dashboard missing time filterOmitted time_rangeInclude { "from": "now-7d", "to": "now" } when a default range is required
XY chart failureMissing layer data_sourcePut data_source inside each layer, not only at the root
Metric value rendered greenapply_color_to without colorOmit both, or add a color config alongside apply_color_to: "value"
Metric tile is a solid colored blockbackground_chart combined with color stepsLens colors the background when a trend or bar is present; drop either the background chart or the color
Metric panel: "expected at most one time tbucket"Trend background on a TS query that groups by BUCKET(@timestamp, ...)Remove the BUCKET; the API appends TBUCKET(75) itself (an existing TBUCKET is kept)
Trend metric shows no trend lineFROM query without ?_tstart / ?_tend, or TS query with KEEP after STATSAdd the time filter, or drop the KEEP; see the Metric rules in Chart Design Guidelines
Multi-series xy chart shows no legendlegend.visibility omitted, so the API set it to hiddenSet legend: { position: "bottom", visibility: "visible" } on charts with a breakdown or several y columns
400 on color configCategorical mapping on a numeric column, or steps on a keyword columnMatch the coloring mode to the column type; see Chart Design Guidelines
400 on stepsNon-continuous ranges or missing gte/ltEvery step except the first needs gte, every step except the last needs lt, the last uses lte
400 on format.durationUnit name such as millisecondsUse the short unit codes ps, ns, us, ms, s, min, h, d, w, mo, y; to accepts auto
Control fails validationMissing data_view_idLook the data view up with GET kbn:/api/data_views, create one, or source the options from ES\QL instead
Panels overlap or leave gapsCoordinates not recomputedReflow with the positioning rules in the Dashboard Design Guidelines

Operations

As of CLI v0.4.0 the Dashboards and Visualizations APIs have dedicated elastic kb dashboards and elastic kb visualizations command groups. elastic kb is shorthand for elastic stack kb. Write commands take the JSON body from --input-file '<path.json>' or --body '<json>'. upsert-* takes the id on --id and creates or replaces the object. delete-* requires --yes. Every command accepts --dry-run, which validates flags and JSON syntax only. It does not validate the panel schema. To author several objects at once, build a saved-object NDJSON file and import it with post-saved-objects-import. Read it back with post-saved-objects-export. If the CLI rejects a command name from this table, run elastic stack kb <group> --help and use the listed name.

HTTP API (shorthand)elastic CLI command
GET kbn:/api/statuselastic kb system get-status
POST kbn:/api/saved_objects/_importelastic kb saved-objects post-saved-objects-import --file '<path.ndjson>' --overwrite
POST kbn:/api/saved_objects/_exportelastic kb saved-objects post-saved-objects-export --objects '[{"type":"<type>","id":"<id>"}]' (returns a JSON array, not NDJSON)
GET kbn:/api/dashboardselastic kb dashboards search-dashboards
GET kbn:/api/dashboards/{id}elastic kb dashboards get-dashboard --id '<id>'
PUT kbn:/api/dashboards/{id}elastic kb dashboards upsert-dashboard --id '<id>' --input-file '<path.json>'
POST kbn:/api/dashboards (no id)elastic kb dashboards create-dashboard --input-file '<path.json>'
DELETE kbn:/api/dashboards/{id}elastic kb dashboards delete-dashboard --id '<id>' --yes
GET kbn:/api/visualizationselastic kb visualizations search-visualizations
GET kbn:/api/visualizations/{id}elastic kb visualizations get-visualization --id '<id>'
PUT kbn:/api/visualizations/{id}elastic kb visualizations upsert-visualization --id '<id>' --input-file '<path.json>'
POST kbn:/api/visualizations (no id)elastic kb visualizations create-visualization --input-file '<path.json>'
DELETE kbn:/api/visualizations/{id}elastic kb visualizations delete-visualization --id '<id>' --yes
GET kbn:/api/data_viewselastic kb data-views get-all-data-views-default (to find a data_view_id for controls)
POST kbn:/api/data_views/data_viewelastic kb data-views create-data-view-default --input-file '<path.json>'
GET /_cat/indices, GET /{index}/_mapping, GET /{index}/_settings/index.mode, POST /_queryelastic es cat indices --index '<pattern>', elastic es indices get-mapping --index '<index>', elastic es indices get-settings --index '<index>' --name index.mode, elastic es esql query --format tsv --query "<esql>" [--filter '<query dsl json>']
z tego samego repozytorium

Więcej Skills

Wszystkie Skills
elastic
Społeczność

elasticsearch-anomaly-detection-explainer

Explain Elasticsearch ML anomaly detection scores, model behavior, and result interpretation. Use when the user asks why a score is high or low, how the model learns, what the numbers mean, or how to troubleshoot unexpected anomaly scores.

Instalacje / 1h
1
GitHub Stars
607
Aktualizacja
16 lis
elastic
Społeczność

elasticsearch-search-relevance

Improve Elasticsearch search relevance for content and catalog indices: pin or promote results with query rules (correct rule type, criteria, and rule-query wiring) and tune organic ranking with multimatch, field boosts, and analysis grounded in the index mapping. Use when search results rank poorly, a specific document must appear first for a query, or the user asks to tune full-text matching — not for ES|QL analytics, index ingest, or cluster health.

Instalacje / 1h
1
GitHub Stars
607
Aktualizacja
16 lis
elastic
Społeczność

kibana-alerting-rules

Create and manage Kibana alerting rules. Use when creating, updating, or managing rule lifecycle (enable, disable, mute, snooze), choosing metric threshold rule types and params, or read-only find/list with tag filters.

Instalacje / 1h
1
GitHub Stars
607
Aktualizacja
16 lis
elastic
Społeczność

kibana-cases

Manage investigation and incident cases across Elastic Security, Observability, and Stack Management — create, search, update, and enrich cases with comments, alerts, events, and observables (IOCs). Use when tracking incidents, correlating alerts to a case, adding investigation notes, updating status or severity, or managing triage output.

Instalacje / 1h
1
GitHub Stars
607
Aktualizacja
16 lis