kibana-dashboards

What this skill does

# Kibana Dashboards and Visualizations

## Overview

The Kibana dashboards and visualizations APIs provide a declarative, Git-friendly format for defining dashboards and
visualizations. Definitions are minimal, diffable, and suitable for version control and LLM-assisted generation.

**Key Benefits:**

- Minimal payloads (no implementation details or derivable properties)
- Easy to diff in Git
- Consistent patterns for GitOps workflows
- Designed for LLM one-shot generation
- Robust validation via OpenAPI spec

**Version Requirement:** Kibana 9.4+ (SNAPSHOT)

## Important Caveats

> **ES|QL Visualizations:** ES|QL-based visualizations cannot be created via `/api/visualizations`. They must be created
> as inline panels within dashboards using the Dashboard API.
>
> **Inline vs Saved Object References:** When embedding visualization panels in dashboards, prefer inline definitions
> over `ref_id` references. Inline definitions are more reliable and self-contained.

## Quick Start

### Environment Configuration

Kibana connection is configured via environment variables. Run `node scripts/kibana-dashboards.js test` to verify the
connection. If the test fails, suggest these setup options to the user, then stop. Do not try to explore further until a
successful connection test.

#### Option 1: Elastic Cloud (recommended for production)

```bash
export KIBANA_CLOUD_ID="deployment-name:base64encodedcloudid"
export KIBANA_API_KEY="base64encodedapikey"
```

#### Option 2: Direct URL with API Key

```bash
export KIBANA_URL="https://your-kibana:5601"
export KIBANA_API_KEY="base64encodedapikey"
```

#### Option 3: Basic Authentication

```bash
export KIBANA_URL="https://your-kibana:5601"
export KIBANA_USERNAME="elastic"
export KIBANA_PASSWORD="changeme"
```

#### Option 4: Local Development with start-local

Use [start-local](https://github.com/elastic/start-local) to spin up Elasticsearch/Kibana locally, then source the
generated `.env`:

```bash
curl -fsSL https://elastic.co/start-local | sh
source elastic-start-local/.env
export KIBANA_URL="$KB_LOCAL_URL"
export KIBANA_USERNAME="elastic"
export KIBANA_PASSWORD="$ES_LOCAL_PASSWORD"
```

Then run `node scripts/kibana-dashboards.js test` to verify the connection.

#### Optional: Skip TLS verification (development only)

```bash
export KIBANA_INSECURE="true"
```

### Basic Workflow

```bash
# Test connection and API availability
node scripts/kibana-dashboards.js test

# Dashboard operations
node scripts/kibana-dashboards.js dashboard get <id>
echo '<json>' | node scripts/kibana-dashboards.js dashboard create -
echo '<json>' | node scripts/kibana-dashboards.js dashboard update <id> -
node scripts/kibana-dashboards.js dashboard delete <id>
echo '<json>' | node scripts/kibana-dashboards.js dashboard upsert <id> -

# Visualization operations (standalone saved objects)
node scripts/kibana-dashboards.js vis list
node scripts/kibana-dashboards.js vis get <id>
echo '<json>' | node scripts/kibana-dashboards.js vis create -
echo '<json>' | node scripts/kibana-dashboards.js vis update <id> -
node scripts/kibana-dashboards.js vis delete <id>
echo '<json>' | node scripts/kibana-dashboards.js vis upsert <id> -
```

## Dashboards API

### Dashboard Definition Structure

The API expects a flat request body with `title` and `panels` at the root level. The response wraps these in a `data`
envelope alongside `id`, `meta`, and `spaces`.

```json
{
  "title": "My Dashboard",
  "panels": [ ... ],
  "time_range": {
    "from": "now-24h",
    "to": "now"
  }
}
```

> **Note:** Dashboard IDs are auto-generated by the API. The script also accepts the legacy wrapped format
> `{ id?, data: { title, panels }, spaces? }` and unwraps it automatically.

### Dashboard with Inline Visualization Panels (Recommended)

Use inline definitions (properties directly in `config`) for self-contained, portable dashboards:

```json
{
  "title": "My Dashboard",
  "panels": [
    {
      "type": "vis",
      "id": "metric-panel",
      "grid": { "x": 0, "y": 0, "w": 12, "h": 6 },
      "config": {
        "title": "",
        "type": "metric",
        "data_source": { "type": "esql", "query": "FROM logs | STATS total = COUNT(*)" },
        "metrics": [{ "type": "primary", "column": "total", "label": "Total Count" }]
      }
    },
    {
      "type": "vis",
      "id": "chart-panel",
      "grid": { "x": 12, "y": 0, "w": 36, "h": 8 },
      "config": {
        "title": "Events Over Time",
        "type": "xy",
        "axis": {
          "x": { "scale": "temporal", "domain": { "type": "fit", "rounding": false } }
        },
        "layers": [
          {
            "type": "area",
            "data_source": {
              "type": "esql",
              "query": "FROM logs | WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart | STATS count = COUNT(*) BY BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
            },
            "x": { "column": "BUCKET(@timestamp, 75, ?_tstart, ?_tend)", "label": "@timestamp" },
            "y": [{ "column": "count" }]
          }
        ]
      }
    }
  ],
  "time_range": { "from": "now-24h", "to": "now" }
}
```

### Dashboard Grid System

Dashboards use a **48-column, infinite-row grid**. On 16:9 screens, approximately **20-24 rows** are visible without
scrolling. Design for density—place primary KPIs and key trends above the fold.

| Width   | Columns | Height   | Rows  | Use Case                 |
| ------- | ------- | -------- | ----- | ------------------------ |
| Full    | 48      | Large    | 14-16 | Wide time series, tables |
| Half    | 24      | Standard | 10-12 | Primary charts           |
| Quarter | 12      | Compact  | 5-6   | KPI metrics              |
| Sixth   | 8       | Minimal  | 4-5   | Dense metric rows        |

> **Target:** 8-12 panels above the fold. Use descriptive panel titles on the charts themselves instead of adding
> markdown headers.

**Grid Packing Rules:**

- **Eliminate Dead Space:** Always calculate the bottom edge (`y + h`) of every panel. When starting a new row or
  placing a panel below another, its `y` coordinate must exactly match the `y + h` of the panel immediately above it.
- **Align Row Heights:** If multiple panels are placed side-by-side in a row (e.g., sharing the same `y` coordinate),
  they should generally have the exact same height (`h`). If they do not, you must fill the resulting empty vertical
  space before placing the next full-width panel.

### Panel Schema

```json
{
  "type": "vis",
  "id": "unique-panel-id",
  "grid": { "x": 0, "y": 0, "w": 24, "h": 15 },
  "config": { ... }
}
```

| Property | Type   | Required | Description                                      |
| -------- | ------ | -------- | ------------------------------------------------ |
| `type`   | string | Yes      | Embeddable type (e.g., `vis`, `markdown`, `map`) |
| `id`     | string | No       | Unique panel ID (auto-generated if omitted)      |
| `grid`   | object | Yes      | Position and size (`x`, `y`, `w`, `h`)           |
| `config` | object | Yes      | Panel-specific configuration                     |

## Visualizations API

### Supported Chart Types

| Type                                 | Description                 | ES\|QL Support |
| ------------------------------------ | --------------------------- | -------------- |
| `metric`                             | Single metric value display | Yes            |
| `xy`                                 | Line, area, bar charts      | Yes            |
| `gauge`                              | Gauge visualizations        | Yes            |
| `heatmap`                            | Heatmap charts              | Yes            |
| `tag_cloud`                          | Tag/word cloud              | Yes            |
| `data_table`                         | Data tables                 | Yes            |
| `region_map`                         | Region/choropleth maps      | Yes            |
| `pie`, `treemap`, `mosaic`, `waffle` | Partition charts