kibana-vega

Kibana Vega

Create and manage Kibana dashboards and Vega visualizations with ES|QL data sources.

Overview

Vega is a declarative visualization grammar for creating custom charts in Kibana. Combined with ES|QL queries, it enables highly customized visualizations beyond standard Kibana charts.

Important Version Requirement: This skill strictly supports ES|QL data sources and requires Serverless Kibana or version 9.4+ (SNAPSHOT). It will not work reliably on older versions or with older Lucene/KQL data source definitions.

Quick Start

Environment Configuration

Kibana connection is configured via environment variables. Run node scripts/kibana-vega.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

Option 4: Local Development with start-local

For local development and testing, use start-local to quickly spin up Elasticsearch and Kibana using Docker or Podman:

After installation completes, Elasticsearch runs at http://localhost:9200 and Kibana at http://localhost:5601. The script generates a random password for the elastic user, stored in the .env file inside the created elastic-start-local folder.

To configure the environment variables for this skill, source the .env file and export the connection settings:

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

Optional: Skip TLS verification (development only)

Basic Workflow

Note: Use - as the file argument to read JSON from stdin. This enables direct spec creation without intermediate files.

Minimal Vega Spec with ES|QL

IMPORTANT: Always use proper JSON format (not HJSON with triple quotes) to avoid parse errors.

ES|QL Data Source Options

| Property | Description | | --------------------------- | ------------------------------------------ | --------- | | %type%: "esql" | Required. Use ES | QL parser | | %context%: true | Apply dashboard filters | | %timefield%: "@timestamp" | Enable time range with ?_tstart/?_tend |

Examples

Stdin Examples

Dashboard Layout Design

Grid System

Kibana dashboards use a 48-column grid:

Above the Fold (Critical)

Primary information must be visible without scrolling.

Height guidelines:

• h: 10 — Compact bar charts (≤7 items), fits above fold
• h: 12-13 — Standard charts, timelines
• h: 15+ — Detailed views, use below fold

Layout Pattern: Operational Dashboard

Creating Layouts

Option 1: Add panels with positions

Option 2: Apply layout file

Create layout.json:

Apply it:

Design Checklist

1. Above the fold: Primary info in top ~22 height units (1080p)
2. Compact heights: Use h:10 for bar charts with ≤7 items
3. Prioritize: Most important info top-left
4. Group: Related charts side-by-side for comparison
5. Timelines: Full width (w:48), h:12 for compact
6. Below fold: Complementary/detailed panels OK to scroll

Guidelines

1. Use JSON, not HJSON triple-quotes — ''' multi-line strings cause parse errors in Kibana; use single-line queries with escaped quotes \"

2. Rename dotted fields — room.name breaks Vega (interpreted as nested path); use ES|QL RENAME room.name AS room

3. Don't set width/height — use autosize: { type: fit, contains: padding }

4. Set labelLimit on axes — horizontal bar chart labels truncate; use axis: { "labelLimit": 150 }

5. Sort bars by value — pre-sort in ES|QL with SORT field DESC and use sort: null in encoding (preserves data order); avoid sort: "-x" in layered specs (bar + text labels) as it causes "conflicting sort properties" warnings

6. Time axis: no rotated labels — use axis: { "labelAngle": 0, "tickCount": 8 }, let Vega auto-format dates

7. Descriptive titles replace axis titles — good title/subtitle makes axis titles redundant; use title: null on axes

8. Use color sparingly — color is a precious visual attribute; use a single default color (#6092C0) for bar charts where position already encodes value; reserve color encoding for categorical distinction (e.g., multiple lines in a time series)

9. Dark theme compatibility — always include config to avoid bright white borders:

   "config": {
     "axis": { "domainColor": "#444", "tickColor": "#444" },
     "view": { "stroke": null }
   }

CLI Commands

# Dashboards
node scripts/kibana-vega.js dashboards list [search]
node scripts/kibana-vega.js dashboards get <id>
node scripts/kibana-vega.js dashboards create <title>
node scripts/kibana-vega.js dashboards delete <id>
node scripts/kibana-vega.js dashboards add-panel <dash-id> <vis-id> [--x N] [--y N] [--w N] [--h N]
node scripts/kibana-vega.js dashboards apply-layout <dash-id> <file|->
 
# Visualizations (use - for stdin instead of file)
node scripts/kibana-vega.js visualizations list [vega]
node scripts/kibana-vega.js visualizations get <id>
node scripts/kibana-vega.js visualizations create <title> <file|->
node scripts/kibana-vega.js visualizations update <id> <file|->
node scripts/kibana-vega.js visualizations delete <id>

Full Documentation

• Dashboard Layout Reference [blocked] — Grid system, layout patterns, design best practices
• Vega-Lite Reference [blocked] — Complete Vega-Lite grammar, chart patterns, best practices
• ES|QL in Vega Reference [blocked] — ES|QL data source configuration, time filtering, parameters
• Example Specs [blocked] — Ready-to-use chart templates

Common Issues