Skills
skills/elastic/agent-skills/kibana-dashboards

kibana-dashboards

SKILL.md

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.

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

{
  "type": "lens",
  "uid": "unique-panel-id",
  "grid": { "x": 0, "y": 0, "w": 24, "h": 15 },
  "config": { ... }
}
Property Type Required Description
type string Yes Embeddable type (e.g., lens, visualization, map)
uid 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

Lens 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
tagcloud Tag/word cloud Yes
datatable Data tables Yes
region_map Region/choropleth maps Yes
pie, donut, treemap, mosaic, waffle Partition charts Yes

Dataset Types

There are three dataset types supported in the Lens API. Each uses different patterns for specifying metrics and dimensions.

Data View Dataset

Use dataView with aggregation operations. Kibana performs the aggregations automatically.

{
  "dataset": {
    "type": "dataView",
    "id": "90943e30-9a47-11e8-b64d-95841ca0b247"
  }
}

Available Aggregation Operations (for dataView):

Operation Description Requires Field
count Document count No
average Average value Yes
sum Sum of values Yes
max Maximum value Yes
min Minimum value Yes
unique_count Cardinality Yes
median Median value Yes
standard_deviation Standard deviation Yes
percentile Percentile (with percentile param) Yes
percentile_rank Percentile rank (with rank param) Yes
last_value Last value (with sort_by field) Yes
date_histogram Time buckets (for x-axis) Yes
terms Top values (for x-axis/breakdown) Yes

ES|QL Dataset

Use esql with a query string. Reference the output columns using { operation: 'value', column: 'column_name' }.

{
  "dataset": {
    "type": "esql",
    "query": "FROM logs | STATS count = COUNT(), avg_bytes = AVG(bytes) BY host"
  }
}

ES|QL Column Reference Pattern:

{
  "operation": "value",
  "column": "count"
}

Key Difference: With ES|QL, you write the aggregation in the query itself, then reference the resulting columns. With dataView, you specify the aggregation operation and Kibana performs it.

Index Dataset

Use index for ad-hoc index patterns without a saved data view:

{
  "dataset": {
    "type": "index",
    "index": "logs-*",
    "time_field": "@timestamp"
  }
}

Examples

For detailed schemas and all chart type options, see Chart Types Reference.

Metric (dataView):

{
  "type": "metric",
  "dataset": { "type": "dataView", "id": "90943e30-9a47-11e8-b64d-95841ca0b247" },
  "metrics": [{ "type": "primary", "operation": "count", "label": "Total Requests" }]
}

Metric (ES|QL):

{
  "type": "metric",
  "dataset": { "type": "esql", "query": "FROM logs | STATS count = COUNT()" },
  "metrics": [{ "type": "primary", "operation": "value", "column": "count", "label": "Total Requests" }]
}

XY Bar Chart (dataView):

{
  "title": "Top Hosts",
  "type": "xy",
  "axis": { "x": { "title": { "visible": false } }, "left": { "title": { "visible": false } } },
  "layers": [
    {
      "type": "bar_horizontal",
      "dataset": { "type": "dataView", "id": "90943e30-9a47-11e8-b64d-95841ca0b247" },
      "x": { "operation": "terms", "fields": ["host.keyword"], "size": 10 },
      "y": [{ "operation": "count" }]
    }
  ]
}

XY Time Series (ES|QL):

{
  "title": "Requests Over Time",
  "type": "xy",
  "axis": { "x": { "title": { "visible": false } }, "left": { "title": { "visible": false } } },
  "layers": [
    {
      "type": "line",
      "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" }]
    }
  ]
}

Tip: Always hide axis titles when the panel title is descriptive. Use bar_horizontal for categorical data with long labels.

Full Documentation

Key Example Files

  • assets/demo-dashboard.json — Complete dashboard with inline Lens panels (dataView format)
  • assets/dashboard-with-lens.json — Dashboard with ES|QL format (for future reference)
  • assets/metric-esql.json — Standalone metric visualization
  • assets/bar-chart-esql.json — Bar chart example
  • assets/line-chart-timeseries.json — Time series line chart

Common Issues

Error Solution
"401 Unauthorized" Check KIBANA_USERNAME/PASSWORD or KIBANA_API_KEY
"404 Not Found" Verify dashboard/visualization ID exists
"409 Conflict" Dashboard/viz with that ID already exists; delete first or use update
"id not allowed in PUT" Remove id and spaces from update body
Schema validation error For ES|QL: ensure column names match query output; use { operation: 'value', column: 'name' }
ES|QL missing operation ES|QL requires { operation: 'value', column: 'col' }, not just { column: 'col' }
Metric uses metric not metrics Metric chart requires metrics (plural) array: [{ type: 'primary', operation: '...' }]
Tagcloud uses tag not tag_by Tagcloud requires tag_by, not tag
Datatable uses columns ES|QL datatable requires metrics + rows arrays, not columns
XY chart fails Put dataset inside each layer (for both dataView and ES|QL)
Heatmap property names Use xAxis, yAxis, metric (not x, y, value)
savedObjectId panels missing Prefer inline attributes definitions over savedObjectId

Guidelines

  1. Design for density — Operational dashboards must show 8-12 panels above the fold (within the first 24 rows). Use compact panel heights: metrics MUST be h=4 to h=6, and charts MUST be h=8 to h=12.
  2. Never use Markdown for titles/headers — Do NOT add DASHBOARD_MARKDOWN panels to act as dashboard titles or section dividers. This wastes critical vertical space. Use descriptive panel titles on the charts themselves.
  3. Prioritize above the fold — Primary KPIs and key trends must be placed at y=0. Deep-dives and data tables should be placed below the charts.
  4. Use descriptive chart titles — Write titles that explain what the chart shows (e.g., "Revenue by Product Category"). Hide axis labels with axis.x.title.visible: false to reduce clutter
  5. Choose the right dataset type — Use dataView for simple aggregations, esql for complex queries with joins, transformations, or custom logic
  6. Inline Lens definitions — Prefer config.attributes over config.savedObjectId for portable dashboards
  7. Test connection first — Run node scripts/kibana-dashboards.js test before creating resources
  8. Get existing examples — Use lens get <id> to see the exact schema for different chart types
  9. Avoid redundant metric labels — For ES|QL metrics, avoid using both a panel title and an inner metric label, as it wastes space. Set the panel title to "" and configure the human-readable label by aliasing the ES|QL column name using backticks (e.g., STATS `Total Requests` = COUNT() and "column": "Total Requests").

Schema Differences: dataView vs ES|QL

Aspect dataView ES|QL
Dataset { type: 'dataView', id: '...' } { type: 'esql', query: '...' }
Metric chart metrics: [{ type: 'primary', operation: 'count' }] metrics: [{ type: 'primary', operation: 'value', column: 'col' }]
XY columns { operation: 'terms', fields: ['host'], size: 10 } { operation: 'value', column: 'host' }
Static values { operation: 'static_value', value: 100 } Use EVAL in query (see below)
XY dataset Inside each layer Inside each layer
Tagcloud tag_by: { operation: 'terms', ... } tag_by: { operation: 'value', column: '...' }
Datatable props metrics, rows arrays metrics, rows arrays with { operation: 'value', column: '...' }

Key Pattern: ES|QL always uses { operation: 'value', column: 'column_name' } to reference columns from the query result. The aggregation happens in the ES|QL query itself.

ES|QL: Time Bucketing

For time series charts, use the BUCKET function to create "auto" buckets that automatically scale with the time range. Always use BUCKET(@timestamp, 75, ?_tstart, ?_tend) instead of hardcoded intervals like DATE_TRUNC(1 hour, @timestamp):

FROM logs | STATS count = COUNT() BY bucket = BUCKET(@timestamp, 75, ?_tstart, ?_tend)

ES|QL: Creating Static/Constant Values

ES|QL does not support static_value operations. Instead, create constant columns using EVAL:

FROM logs | STATS count = COUNT() | EVAL max_value = 20000, goal = 15000

Then reference with { "operation": "value", "column": "max_value" }. For dynamic reference values, use aggregation functions like PERCENTILE() or MAX() in the query.

Design Principles

The APIs follow these principles:

  1. Minimal definitions — Only required properties; defaults are injected
  2. No implementation details — No internal state or machine IDs
  3. Flat structure — Shallow nesting for easy diffing
  4. Semantic names — Clear, readable property names
  5. Git-friendly — Easy to track changes in version control
  6. LLM-optimized — Compact format suitable for one-shot generation
Weekly Installs
18
Repository
elastic/agent-skills
GitHub Stars
16
First Seen
3 days ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
cursor14
opencode12
gemini-cli12
github-copilot12
codex12
kimi-cli12