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

Inline vs Saved Object References: When embedding Lens panels in dashboards, prefer inline attributes definitions over savedObjectId 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)

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

Option 2: Direct URL with API Key

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

Option 3: Basic Authentication

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 to spin up Elasticsearch/Kibana locally, then source the generated .env:

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)

export KIBANA_INSECURE="true"

Basic Workflow

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

# Lens visualization operations
node scripts/kibana-dashboards.js lens list
node scripts/kibana-dashboards.js lens get <id>
echo '<json>' | node scripts/kibana-dashboards.js lens create -
echo '<json>' | node scripts/kibana-dashboards.js lens update <id> -
node scripts/kibana-dashboards.js lens delete <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.

{
  "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.

Create Dashboard

echo '{
  "title": "Sales Dashboard",
  "panels": [],
  "time_range": { "from": "now-7d", "to": "now" }
}' | node scripts/kibana-dashboards.js dashboard create -

Update Dashboard

echo '{
  "title": "Updated Dashboard Title",
  "panels": [ ... ]
}' | node scripts/kibana-dashboards.js dashboard update my-dashboard-id -

Dashboard with Inline Lens Panels (Recommended)

Use inline attributes for self-contained, portable dashboards:

{
  "title": "My Dashboard",
  "panels": [
    {
      "type": "lens",
      "uid": "metric-panel",
      "grid": { "x": 0, "y": 0, "w": 12, "h": 6 },
      "config": {
        "attributes": {
          "title": "",
          "type": "metric",
          "dataset": { "type": "esql", "query": "FROM logs | STATS total = COUNT(*)" },
          "metrics": [{ "type": "primary", "operation": "value", "column": "total", "label": "Total Count" }]
        }
      }
    },
    {
      "type": "lens",
      "uid": "chart-panel",
      "grid": { "x": 12, "y": 0, "w": 36, "h": 8 },
      "config": {
        "attributes": {
          "title": "Events Over Time",
          "type": "xy",
          "layers": [
            {
              "type": "area",
              "dataset": {
                "type": "esql",
                "query": "FROM logs | STATS count = COUNT(*) BY bucket = BUCKET(@timestamp, 75, ?_tstart, ?_tend)"
              },
              "x": { "operation": "value", "column": "bucket" },
              "y": [{ "operation": "value", "column": "count" }]
            }
          ]
        }
      }
    }
  ],
  "time_range": { "from": "now-24h", "to": "now" }
}

Copy Dashboard Between Spaces/Clusters

# 1. Get dashboard from source
node scripts/kibana-dashboards.js dashboard get source-dashboard > dashboard.json

# 2. Edit dashboard.json to change id and/or spaces

# 3. Create on destination
node scripts/kibana-dashboards.js dashboard create dashboard.json

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.

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

{
  "type": "lens",
  "uid": "unique-panel-id",