kibana-dashboards

Files (12)

• SKILL.md
• bar-chart-esql.json · assets/
• dashboard-basic.json · assets/
• dashboard-with-visualizations.json · assets/
• datatable.json · assets/
• demo-dashboard.json · assets/
• ecommerce-analytics-dashboard.json · assets/
• line-chart-timeseries.json · assets/
• metric-esql.json · assets/
• chart-types-reference.md · references/
• dashboard-api-reference.md · references/
• lens-api-reference.md · references/

SKILL.md (first lines)

# 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](references/dashboard-design.md) and
[Chart Design Guidelines](references/chart-design.md) 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](https://github.com/elastic/cli#configuration) 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](#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](#design-essentials) and have a
   fallback for older clusters. Never refuse a dashboard on 9.4 because of them.

2. **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).

3. **Choose the dataset type before building metrics or layers.**

   | User intent                                      | Dataset                                                                    | Metric / axis pattern                                                                                                                    |
   | ------------------------------------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
   | Simple count or aggregation on a saved data view | `data_source.type: "data_view_reference"` with `ref_id`                    | `metrics: [{ type: "primary", operation: "count" }]` (or other aggregation operations)                                                   |
   | Ad-hoc index pattern                             | `data_source.type: "data_view_spec"` with `index_pattern` and `time_field` | Same aggregation `operation` fields                                                                                                      |
   | ES\|QL query (explicit or complex logic)         | `data_source.type: "esql"` with `query`                                    | `metrics: [{ 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.

4. **Design before you write.** Read [Dashboard Design Guidelines](references/dashboard-design.md) and
   [Chart Design Guidelines](references/chart-design.md) 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](#design-essentials) below. Choices you do not make deliberately fall back to those
   defaults; they are not optional polish.

5. **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](references/dashboard-api-reference.md) for panel types and copy workflows.

From elastic/agent-skills, Apache-2.0.

More from elastic/agent-skills