# Dashboard Compiler - Complete Documentation > This file contains all documentation for the Dashboard Compiler project. --- --- # Source: index.md --- # YAML ➤ Lens Dashboard Compiler Convert human-friendly YAML dashboard definitions into Kibana NDJSON format. ![The Chameleon mascot](./images/project-banner-smaller.png) This tool simplifies the process of creating and managing Kibana dashboards by allowing you to define them in a clean, maintainable YAML format instead of hand-crafting complex JSON. ## Getting Started ### VS Code Extension (Recommended) **Best for interactive development** - Live preview, visual editing, built-in snippets **No Python installation required!** The extension includes a bundled LSP server binary. **Installation:** 1. **Install the extension:** - **Open VSX Registry** (Cursor, VS Code forks): Search "Kibana Dashboard Compiler" - **Manual**: Download `.vsix` from [releases](https://github.com/strawgate/kb-yaml-to-lens/releases) 2. **Create your first dashboard:** Create a new file called `my-dashboard.yaml` and add the following content: ```yaml dashboards: - name: My First Dashboard description: A simple dashboard with markdown panels: - title: Hello Panel markdown: content: | # Hello, Kibana! This is my first markdown panel. size: {w: 24, h: 15} ``` Or use snippets: type `dashboard` and press Tab to insert a template. 3. **Preview your dashboard:** - Save the file (Ctrl+S) to auto-compile - Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) - Run **"YAML Dashboard: Preview Dashboard"** 4. **Upload to Kibana:** - Configure Kibana URL in VS Code settings - Run **"YAML Dashboard: Open in Kibana"** **Full guide:** [VS Code Extension Documentation](vscode-extension.md) --- ### CLI (For Automation & Scripting) **Best for:** CI/CD pipelines, batch processing, programmatic usage **Requirements:** [uv](https://github.com/astral-sh/uv) (recommended) or Python 3.12+ **Installation:** No clone or setup required! Run directly with uvx: ```bash uvx kb-dashboard-cli compile --help ``` **Your First Dashboard:** 1. Create `inputs/my-dashboard.yaml`: ```yaml dashboards: - name: My First Dashboard description: A simple dashboard panels: - title: Welcome size: {w: 24, h: 15} markdown: content: | # Welcome to Kibana! ``` 2. Compile: ```bash uvx kb-dashboard-cli compile --input-file inputs/my-dashboard.yaml ``` 3. Upload to Kibana: ```bash uvx kb-dashboard-cli compile --input-file inputs/my-dashboard.yaml --upload --kibana-url http://localhost:5601 ``` **Full guide:** [CLI Documentation](CLI.md) --- ## Features - **YAML-based Definition** – Define dashboards, panels, filters, and queries in simple, readable YAML. - **Kibana Integration** – Compile to NDJSON format compatible with Kibana 8+. - **Rich Panel Support** – Support for Lens (metric, pie, XY charts), Markdown, Links, Image, and Search panels. - **Color Palettes** – Choose from color-blind safe, brand, and other built-in color palettes. - **Interactive Controls** – Add options lists, range sliders, and time sliders with chaining support. - **Flexible Filtering** – Use a comprehensive filter DSL (exists, phrase, range) or raw KQL/Lucene/ESQL queries. - **Direct Upload** – Compile and upload to Kibana in one step, with support for authentication and API keys. - **Screenshot Export** – Generate high-quality PNG screenshots of your dashboards programmatically. ## More Examples ### Lens Metric Panel Here's a dashboard with a Lens metric panel displaying a count: ```yaml dashboards: - name: Metric Dashboard description: A dashboard with a single metric panel panels: - title: Document Count type: lens size: {w: 24, h: 15} data_view: your-index-pattern-* chart: type: metric metrics: - type: count label: Total Documents ``` ### Programmatic Alternative While this guide focuses on YAML, you can also create dashboards entirely in Python code. This approach offers: - Dynamic dashboard generation based on runtime data - Type safety with Pydantic models - Reusable dashboard templates and components - Integration with existing Python workflows See the [Programmatic Usage Guide](programmatic-usage.md) for examples and patterns. ## Next Steps ### Enhance Your Workflow - **[VS Code Extension Features](vscode-extension.md)** - Visual grid editor, code snippets, keyboard shortcuts - **[CLI Advanced Usage](CLI.md)** - Environment variables, API keys, CI/CD integration - **[Dashboard Decompiling Guide](guides/dashboard-decompiling-guide.md)** - Convert existing Kibana JSON dashboards to YAML - **[Complete Examples](examples/index.md)** - Production-ready dashboard templates ### User Guide Reference documentation for YAML dashboard syntax: - **[Dashboard Configuration](dashboard/dashboard.md)** - Dashboard-level settings and options. - **[Panel Types](panels/base.md)** - Available panel types (Markdown, Charts, Images, Links, etc.). - **[Dashboard Controls](controls/config.md)** - Interactive filtering controls. - **[Filters & Queries](filters/config.md)** - Data filtering and query configuration. ### Developer Guide Advanced documentation for contributors and programmatic usage: - **[Programmatic Usage](programmatic-usage.md)** - Using the Python API directly to generate dashboards. - **[API Reference](api/index.md)** - Auto-generated Python API documentation. - **[Contributing Guide](https://github.com/strawgate/kb-yaml-to-lens/blob/main/CONTRIBUTING.md)** - How to contribute and add new capabilities. ## How It Works ```mermaid graph TB YAML[YAML Definition] KIBANA[Kibana] subgraph "Interactive Development" EXT[VS Code Extension] EXT --> PREVIEW[Live Preview] end subgraph "Automation/CI" CLI[CLI Compiler] CLI --> NDJSON[NDJSON Files] end YAML --> EXT YAML --> CLI EXT --> KIBANA NDJSON --> KIBANA ``` ## License MIT ### Third-Party Content Some example dashboards in `packages/kb-dashboard-docs/content/examples/` are derived from the [Elastic integrations repository](https://github.com/elastic/integrations) and are licensed under the [Elastic License 2.0](https://github.com/strawgate/kb-yaml-to-lens/blob/main/licenses/ELASTIC-LICENSE-2.0.txt). Specifically: - `packages/kb-dashboard-docs/content/examples/system_otel/` - System monitoring dashboards for OpenTelemetry - `packages/kb-dashboard-docs/content/examples/docker_otel/` - Docker container monitoring dashboards for OpenTelemetry See [licenses/README.md](https://github.com/strawgate/kb-yaml-to-lens/blob/main/licenses/README.md) for the complete list of affected files. ## Support For issues and feature requests, please refer to the repository's issue tracker. --- # Source: CLI.md --- # Dashboard Compiler CLI The `kb-dashboard-cli` CLI tool allows you to compile YAML dashboard configurations to Kibana's NDJSON format and optionally upload them directly to Kibana. ## Prerequisites - **[uv](https://github.com/astral-sh/uv)** (recommended) - Enables running the CLI via `uvx` with zero setup - Or **Python 3.12+** with pip for traditional installation **Note:** When using `uvx`, Python and all dependencies are handled automatically. The VS Code Extension does not require Python either - it includes a bundled binary. See [VS Code Extension Documentation](vscode-extension.md) for zero-configuration setup. ## When to Use the CLI **Use the CLI when:** - ✅ Building CI/CD pipelines for dashboard deployment - ✅ Batch processing multiple dashboards - ✅ Scripting dashboard generation (e.g., templates, dynamic data) - ✅ Integrating with other automation tools - ✅ Running in headless/server environments without GUI - ✅ Using Docker containers or serverless functions **Use the VS Code Extension when:** - ✅ Developing dashboards interactively - ✅ Learning the YAML schema - ✅ Making frequent visual adjustments - ✅ Needing live preview and validation **See:** [VS Code Extension Documentation](vscode-extension.md) for interactive development workflow. --- ## Installation ### Using uvx (Recommended) Run the CLI directly without cloning or installing anything: ```bash uvx kb-dashboard-cli compile --help ``` This downloads and runs the published package automatically. No Python environment setup required! ### Development Installation For contributors or development workflows, clone the repository: ```bash git clone https://github.com/strawgate/kb-yaml-to-lens cd kb-yaml-to-lens just cli install ``` See [DEVELOPING.md](https://github.com/strawgate/kb-yaml-to-lens/blob/main/DEVELOPING.md) for full development setup. ## Basic Usage ### Compile Dashboards Compile YAML dashboards to NDJSON format: ```bash uvx kb-dashboard-cli compile ``` This will: - Find all YAML files in `inputs/` (by default) - Compile them to Kibana JSON format - Output NDJSON files to `output/` directory - Create individual NDJSON files per scenario - Create a combined `compiled_dashboards.ndjson` file ### Compile a Single File Compile a specific YAML file without scanning a directory: ```bash uvx kb-dashboard-cli compile --input-file ./dashboards/example.yaml ``` When `--input-file` is provided, `--input-dir` is ignored. ### Export Individual JSON Files For workflows that require one JSON file per dashboard, choose the format based on your target workflow: ```bash # Generic per-dashboard JSON export uvx kb-dashboard-cli compile --format json --output-dir ./output # Elastic integrations/Fleet package workflow (recommended for integrations) uvx kb-dashboard-cli compile --format elastic-integrations --output-dir ./output ``` Format differences: - `--format json`: Pretty-printed JSON files named by dashboard ID, with nested saved-object fields (for example `panelsJSON`/`optionsJSON`) kept as JSON strings. - `--format elastic-integrations`: JSON files named by dashboard ID with nested saved-object fields unwrapped as JSON objects/arrays, matching Elastic integrations packaging expectations. Migration guidance for Fleet/integration workflows: - If your pipeline currently uses `--format json` for Elastic integrations assets, switch to `--format elastic-integrations`. - `--elastic-package-name` is deprecated for filename generation and is ignored with `--format elastic-integrations` (filenames are dashboard-ID-based). ### CI Sync Detection Use the `--exit-non-zero-on-change` flag to detect when YAML and JSON files are out of sync in CI pipelines: ```bash uvx kb-dashboard-cli compile --format elastic-integrations --output-dir ./dashboards --exit-non-zero-on-change if [ $? -ne 0 ]; then echo "Dashboard JSON files are out of sync with YAML sources" exit 1 fi ``` When this flag is enabled, the exit code equals the number of files that changed (capped at 125). By default, the command exits with code 0 on success regardless of whether files changed. ### Compile and Upload to Kibana Compile dashboards and upload them directly to Kibana: ```bash uvx kb-dashboard-cli compile --upload ``` This will compile the dashboards and upload them to a local Kibana instance. ### Screenshot Dashboards Generate a PNG screenshot of a dashboard: ```bash uvx kb-dashboard-cli screenshot --dashboard-id --output ``` This will use Kibana's Reporting API to take a screenshot. ### Export Dashboard for Issue Export a dashboard from Kibana and create a pre-filled GitHub issue: ```bash uvx kb-dashboard-cli export-for-issue --dashboard-id ``` This will export the dashboard and open your browser with a pre-filled GitHub issue containing the dashboard NDJSON export. ### Disassemble Dashboards Break down a Kibana dashboard JSON into components for easier LLM-based conversion: ```bash uvx kb-dashboard-cli disassemble dashboard.ndjson -o output_dir ``` This will extract the dashboard into separate files: - `metadata.json` - Dashboard metadata (id, title, description, version) - `options.json` - Dashboard display options - `controls.json` - Control group configuration - `filters.json` - Dashboard-level filters - `references.json` - Data view references - `panels/` - Individual panel JSON files For a comprehensive guide on using this tool to convert dashboards from JSON to YAML, see the [Dashboard Decompiling Guide](guides/dashboard-decompiling-guide.md). ### Decompile Dashboards Generate a YAML dashboard stub from Kibana NDJSON output: ```bash uvx kb-dashboard-cli decompile dashboard.ndjson -o dashboard.yaml ``` This command emits: - Dashboard metadata (name/id/description where available) - Panel stubs with `id`, `title`, `size`, and `position` - TODO comments containing original panel JSON for non-trivial manual conversion ### Upgrade Legacy YAML Schema Upgrade legacy dashboard YAML from `0.2.7` format to canonical `0.4.0` schema: ```bash uvx kb-dashboard-cli upgrade --input-dir ./dashboards --write ``` Run in check mode (no writes) and fail CI if upgrades are needed: ```bash uvx kb-dashboard-cli upgrade --input-dir ./dashboards --fail-on-change ``` `kb-dashboard upgrade` targets `0.2.7 -> 0.4.0` only; `0.3.x` compatibility is intentionally not preserved. ## Configuration ### Environment Variables The CLI supports configuration via environment variables: ```bash export KIBANA_URL=http://localhost:5601 export KIBANA_USERNAME=elastic export KIBANA_PASSWORD=changeme export KIBANA_SPACE_ID=my-space # Optional: target a specific Kibana space # OR use API key instead export KIBANA_API_KEY=your-api-key-here ``` Then simply run: ```bash uvx kb-dashboard-cli compile --upload ``` ### Command-Line Options All options can also be specified on the command line: ```bash uvx kb-dashboard-cli compile \ --upload \ --kibana-url http://localhost:5601 \ --kibana-username elastic \ --kibana-password changeme ``` To upload to a specific Kibana space: ```bash uvx kb-dashboard-cli compile --upload --kibana-space-id production ``` Or with environment variables: ```bash export KIBANA_SPACE_ID=staging uvx kb-dashboard-cli compile --upload ``` ## Command Reference The following commands are available in the `kb-dashboard-cli` CLI. For detailed information about each command and its options, see the auto-generated reference below. --- # Source: examples/index.md --- # Complete Examples This section provides real-world YAML dashboard examples demonstrating various features and capabilities of the Dashboard Compiler. ## How to Use These Examples 1. **Browse:** Click on any example bundle below to view its README with complete documentation 2. **Copy:** Each bundle contains YAML files you can copy to your local directory 3. **Compile:** Run the compiler using uvx (no clone required): ```bash uvx kb-dashboard-cli compile --input-file my-dashboard.yaml ``` 4. **Upload (Optional):** To upload directly to Kibana: ```bash uvx kb-dashboard-cli compile --input-file my-dashboard.yaml --upload ``` **For contributors:** If you've cloned the repository, you can compile examples from the repo: ```bash uvx kb-dashboard-cli compile --input-dir packages/kb-dashboard-docs/content/examples --output-dir output ``` ## Standalone Examples These single-file examples demonstrate specific features: ### Controls Example Demonstrates dashboard controls including options list, range slider, time slider, control chaining, and custom label positions. ??? example "Dashboard Definition (controls-example.yaml)" ```yaml ``` ### Dimensions Example Shows how to configure dimensions in Lens visualizations including multiple dimension types, custom formatting, and breakdown configurations. ??? example "Dashboard Definition (dimensions-example.yaml)" ```yaml ``` ### Color Palette Example Demonstrates color customization for charts including custom palettes, manual color assignments, and per-chart configuration. **Note:** Manual color assignments are an advanced topic. See the [Custom Color Assignments](../guides/color-assignments.md) guide. ??? example "Dashboard Definition (color-palette-examples.yaml)" ```yaml ``` ### Filters Example Comprehensive filter demonstrations including field existence, phrase filters, range filters, custom DSL, and combined filters. ??? example "Dashboard Definition (filters-example.yaml)" ```yaml ``` ### Multi-Panel Showcase A complete dashboard featuring multiple panel types: markdown, metrics, pie charts, XY charts, images, links, and grid layouts. ??? example "Dashboard Definition (multi-panel-showcase.yaml)" ```yaml ``` ### Navigation Example Demonstrates dashboard navigation features including links panels, dashboard linking patterns, and URL parameter passing. ??? example "Dashboard Definition (navigation-example.yaml)" ```yaml ``` ### Drilldowns Example Demonstrates panel drilldowns including dashboard-to-dashboard navigation and URL drilldowns with template variables. See the [Drilldowns Example](drilldowns/README.md) for complete documentation. ??? example "Dashboard Definition (drilldowns/01-drilldowns-demo.yaml)" ```yaml ``` ### Heatmap Examples Examples of heatmap visualizations. ??? example "Dashboard Definition (heatmap-examples.yaml)" ```yaml ``` ### Metric Formatting Examples Examples of metric formatting options. ??? example "Dashboard Definition (metric-formatting-examples.yaml)" ```yaml ``` ## Integration Bundles Complete dashboard bundles for monitoring various technologies. Each bundle includes multiple dashboards with navigation links and comprehensive documentation. ### OpenTelemetry Integrations | Bundle | Description | | ------ | ----------- | | [Aerospike](aerospike/README.md) | Aerospike NoSQL database monitoring (3 dashboards) | | [Apache HTTP Server](apache_otel/README.md) | Apache web server metrics and logs (1 dashboard) | | [AWS CloudTrail](aws_cloudtrail_otel/README.md) | AWS API activity monitoring with ES\|QL (1 dashboard) | | [AWS VPC Flow Logs](aws_vpcflow_otel/README.md) | VPC network traffic analysis (3 dashboards) | | [Docker](docker_otel/README.md) | Container monitoring with Docker Stats receiver (2 dashboards) | | [Elasticsearch](elasticsearch_otel/README.md) | Elasticsearch cluster monitoring (7 dashboards) | | [Kubernetes Cluster](k8s_cluster_otel/README.md) | K8s cluster health and workload monitoring (5 dashboards) | | [Memcached](memcached_otel/README.md) | Memcached cache monitoring (1 dashboard) | | [MySQL](mysql_otel/README.md) | MySQL database metrics (2 dashboards) | | [PostgreSQL](postgresql_otel/README.md) | PostgreSQL database monitoring (2 dashboards) | | [Redis](redis_otel/README.md) | Redis instance and database monitoring (3 dashboards) | | [System (OTel)](system_otel/README.md) | Host metrics with Host Metrics receiver (5 dashboards) | ### Elastic Agent Integrations | Bundle | Description | | ------ | ----------- | | [CrowdStrike](crowdstrike/README.md) | CrowdStrike EDR security dashboards (6 dashboards) | | [CrowdStrike Modern](crowdstrike-modern/README.md) | Workflow-centric SOC dashboards (4 dashboards) | | [System (Classic)](system/README.md) | Elastic System integration dashboards (14 dashboards) | | [System (Modern)](system_modern/README.md) | Modern System dashboards with style guide patterns (14 dashboards) | ## Viewing Example Source Code All example files are located in the `packages/kb-dashboard-docs/content/examples/` directory of the repository. You can: 1. **View README:** Click the bundle link to see complete setup instructions and dashboard descriptions 2. **Clone locally:** Download the repository to experiment with examples 3. **Compile examples:** Run `uvx kb-dashboard-cli compile --input-dir packages/kb-dashboard-docs/content/examples --output-dir output` to generate NDJSON files ## Using Examples as Templates To use an example as a starting point for your own dashboard: 1. Copy the example YAML file to your `inputs/` directory 2. Modify the dashboard name, description, and ID 3. Adjust panels, filters, and controls to match your data views 4. Compile and upload to Kibana ## Related Documentation - [Dashboard Configuration](../dashboard/dashboard.md) - Dashboard-level settings - [Panel Types](../panels/base.md) - Available panel types and configurations --- # Source: dashboard/dashboard.md --- # Dashboard Configuration The `dashboards` array is the root element in your YAML configuration file. Each dashboard defines the overall structure, content, and global settings for a Kibana dashboard. ## Minimal Configuration Example A minimal dashboard requires a `name` and at least one panel. ```yaml dashboards: - name: "Simple Log Dashboard" panels: - markdown: content: "Welcome to the dashboard!" size: {w: 6, h: 3} ``` ## Complex Configuration Example This example showcases a dashboard with various settings, a global query, filters, controls, and multiple panels. ```yaml dashboards: - name: "Comprehensive Application Overview" description: "An overview of application performance and logs, with interactive filtering." settings: margins: true titles: true sync: cursor: true tooltips: true colors: false # Use distinct color palettes per panel controls: label_position: "above" chain_controls: true query: kql: "NOT response_code:500" # Global KQL query filters: - field: "geo.country_iso_code" equals: "US" - exists: resource.attributes.host.name controls: - type: options label: "Filter by Host" data_view: "metrics-*" field: "resource.attributes.host.name" panels: - markdown: content: "### Key Performance Indicators" size: {w: 12, h: 2} - lens: type: metric primary: aggregation: unique_count field: resource.attributes.host.name data_view: "metrics-*" title: "Total Hosts" size: {w: 4, h: 4} position: {x: 0, y: 2} - lens: type: bar dimension: type: values field: "resource.attributes.os.type" metrics: - aggregation: unique_count field: resource.attributes.host.name data_view: "metrics-*" title: "Hosts by OS Type" size: {w: 8, h: 4} position: {x: 4, y: 2} ``` ## Full Configuration Options ### Dashboard Object The main object defining the dashboard. | YAML Key | Data Type | Description | Compiler Default | Required | | ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `name` | `string` | The title of the dashboard displayed in Kibana. | N/A | Yes | | `id` | `string` | An optional unique identifier for the dashboard. If not provided, one will be generated based on the name. | Generated ID | No | | `description` | `string` | A brief description of the dashboard's purpose or content. | `""` (empty string) | No | | `minimum_kibana_version` | `string` | Optional minimum Kibana version required by this dashboard. Use this when the dashboard intentionally relies on newer Kibana features such as `TS`-based ES\|QL queries. | `None` | No | | `time_range` | `TimeRange` object | A default time range to apply when opening the dashboard. See [Time Range](#time-range-time_range). | `None` | No | | `settings` | `DashboardSettings` object | Global settings for the dashboard. See [Dashboard Settings](#dashboard-settings-settings). | See defaults below | No | | `query` | `Query` object | A global query (KQL or Lucene) applied to the dashboard. See [Queries Documentation](../queries/config.md). | `None` | No | | `filters` | `list of Filter objects` | A list of global filters applied to the dashboard. See [Filters Documentation](../filters/config.md). | `[]` (empty list) | No | | `controls` | `list of Control objects` | A list of control panels for the dashboard. See [Controls Documentation](../controls/config.md). | `[]` (empty list) | No | | `panels` | `list of Panel objects` | A list of Panel objects defining the content and layout. See [Panels Documentation](../panels/base.md). | `[]` (empty list) | Yes | ### Time Range (`time_range`) Configure a default time range that will be restored when opening the dashboard. When `time_range` is set, Kibana will automatically apply the specified time range instead of using the global time picker value. | YAML Key | Data Type | Description | Compiler Default | Required | | -------- | --------- | ----------- | ------- | -------- | | `from` | `string` | The start of the time range. Supports relative time expressions like `now-30d/d`, `now-1h`, etc. | N/A | Yes | | `to` | `string` | The end of the time range. Supports relative time expressions. | `now` | No | **Example:** ```yaml dashboards: - name: "Last 30 Days Overview" time_range: from: "now-30d/d" to: "now" panels: - markdown: content: "This dashboard defaults to the last 30 days." size: {w: 12, h: 3} ``` ### Minimum Kibana Version (`minimum_kibana_version`) Use `minimum_kibana_version` when a dashboard depends on features that are unavailable on older Kibana versions. For example, `section` panels require Kibana 9.1+, and `TS`-based ES|QL queries require Kibana 9.2+. **Example:** ```yaml dashboards: - name: "TS-Based Metrics Dashboard" minimum_kibana_version: "9.2.0" panels: - title: "Request Rate" esql: type: line query: | TS metrics-* | STATS request_rate = SUM(RATE(http.requests)) BY time_bucket = BUCKET(@timestamp, 20, ?_tstart, ?_tend) | SORT time_bucket ASC dimension: field: "time_bucket" metrics: - field: "request_rate" ``` **Example with collapsible sections:** ```yaml dashboards: - name: "Operations Overview" minimum_kibana_version: "9.1.0" panels: - title: "Expanded Details" section: collapsed: true panels: - title: "CPU Usage" size: { w: half, h: 8 } lens: type: metric data_view: "metrics-*" primary: aggregation: average field: system.cpu.total.pct ``` ### Dashboard Settings (`settings`) Global settings for the dashboard, configured under the `dashboard.settings` path. | YAML Key | Data Type | Description | Compiler Default | Required | | ------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `margins` | `boolean` | Whether to put space (margins) between panels in the dashboard. | `true` | No | | `sync` | `DashboardSyncSettings` object | Configures synchronization of cursor, tooltips, and colors across panels. See [Dashboard Sync Settings](#dashboard-sync-settings-settingssync). | See defaults below | No | | `controls` | `ControlSettings` object | Global settings for controls on the dashboard. See [Controls Documentation](../controls/config.md#control-settings-settingscontrols). | See defaults in Controls docs | No | | `titles` | `boolean` | Whether to display the titles in the panel headers. | `true` | No | | `layout_algorithm` | `string` | The auto-layout algorithm for positioning panels without explicit coordinates. Valid values: `up-left`, `left-right`, `blocked`, `first-available-gap`. | `up-left` | No | ### Dashboard Sync Settings (`settings.sync`) Configure whether cursor, tooltips, and colors should synchronize across panels. > **Note:** The compiler applies different defaults than Kibana's native defaults. Kibana's native defaults are all `true`, but the compiler intentionally defaults `tooltips` and `colors` to `false` for a cleaner dashboard experience. | YAML Key | Data Type | Description | Compiler Default | Required | | ---------- | --------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `cursor` | `boolean` | Whether to synchronize the cursor across related panels. | `true` | No | | `tooltips` | `boolean` | Whether to synchronize tooltips across related panels. | `false` | No | | `colors` | `boolean` | Whether to apply the same color palette to all panels on the dashboard. | `false` | No | ## Methods (for programmatic generation) While primarily declarative, the underlying Pydantic models for `Dashboard` support methods for adding components if you are generating configurations programmatically (not directly used in YAML): * `add_filter(filter: FilterTypes)`: Adds a filter to the `filters` list. * `add_control(control: ControlTypes)`: Adds a control to the `controls` list. * `add_panel(panel: PanelTypes)`: Adds a panel to the `panels` list. ## Related Documentation * [Controls Configuration](../controls/config.md) * [Filters Configuration](../filters/config.md) * [Queries Configuration](../queries/config.md) * [Panels Overview](../panels/base.md) --- # Source: panels/base.md --- # Base Panel Configuration All panel types used within a dashboard (e.g., Markdown, Lens charts, Search panels) share a common set of base configuration fields. These fields define fundamental properties like the panel's title, its position and size on the dashboard grid, and an optional description. When defining a panel in your YAML, you must specify the configuration block for that specific panel type (e.g., `markdown`, `lens`) which serves as the key to identify the panel type. --- ## Minimal Example (Illustrating Base Fields within a Specific Panel Type) This example shows how base panel fields are used within a `markdown` panel: ```yaml dashboards: - name: "Example Dashboard" panels: - markdown: content: "System is **operational**." # MarkdownPanel specific config title: "Status Overview" description: "A quick look at system status." # BasePanel field hide_title: false # BasePanel field size: # BasePanel field (recommended) w: quarter # or numeric value like 12 h: 8 position: # BasePanel field (optional) x: 0 y: 0 ``` **Note:** See [Auto-Layout Guide](./auto-layout.md) for details on automatic panel positioning. ## Full Configuration Options ### Base Panel Fields These fields are available for all panel types and are inherited from the `BasePanel` configuration. | YAML Key | Data Type | Description | Kibana Default | Required | | ------------ | --------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------- | -------- | | `id` | `string` | A unique identifier for the panel. If not provided, one may be generated during compilation. | Generated ID | No | | `title` | `string` | The title displayed on the panel header. Can be an empty string if you wish for no visible title. | `""` (empty string) | No | | `hide_title` | `boolean` | If `true`, the panel title (even if defined) will be hidden. | `false` (title is shown) | No | | `description` | `string` | A brief description of the panel's content or purpose. This is often shown on hover or in panel information. | `""` (empty string, if `None`) | No | | `size` | `Size` object | Defines the panel's width and height. See [Size Object Configuration](#size-object-configuration-size) below. | `w: 12, h: 8` | No | | `position` | `Position` object | **Optional:** Defines the panel's x/y coordinates. Omit for automatic positioning. See [Position Object Configuration](#position-object-configuration-position) below. | Auto-calculated | No | | `drilldowns` | `list[Drilldown]` | **Optional:** List of drilldowns for interactive navigation. See [Drilldowns Configuration](./drilldowns.md). | `None` | No | **Note on Panel Types**: Each panel must have exactly one key identifying its type (e.g., `markdown`, `lens`, `search`, `links`, `image`, `esql`). This key contains the type-specific configuration. **Note on Auto-Layout**: For automatic panel positioning without manual coordinate calculation, use the `size` field and omit the `position` field. See the [Auto-Layout Guide](./auto-layout.md) for details. ### Size Object Configuration (`size`) The `size` object defines the panel's width and height on the dashboard grid. This is the **recommended** approach for new dashboards. Both shorthand and verbose parameter names are supported for improved readability. | YAML Key | Verbose Alternative | Data Type | Description | Default | Required | | -------- | ------------------- | --------- | ------------------------------------------------------------ | ------- | -------- | | `w` | `width` | `integer` or `SemanticWidth` | The width of the panel. Accepts semantic values (`whole`, `half`, `third`, `quarter`, `sixth`, `eighth`) or numeric values (1-48). | `12` (quarter) | No | | `h` | `height` | `integer` | The height of the panel in grid units. | `8` | No | **Semantic Width Values:** | Value | Grid Units | Description | | ----- | ---------- | ----------- | | `whole` | 48 | Full dashboard width | | `half` | 24 | Half width | | `third` | 16 | One-third width | | `quarter` | 12 | Quarter width | | `sixth` | 8 | One-sixth width | | `eighth` | 6 | One-eighth width | **Example:** ```yaml size: w: quarter # Semantic value h: 8 # Or with numeric value: size: width: 24 # Numeric value height: 12 ``` ### Position Object Configuration (`position`) The `position` object defines the panel's x/y coordinates on the dashboard grid. This field is **optional** - when omitted, the panel will be automatically positioned using the dashboard's layout algorithm. | YAML Key | Verbose Alternative | Data Type | Description | Default | Required | | -------- | ------------------- | --------- | ------------------------------------------------------------ | ------- | -------- | | `x` | `from_left` | `integer` or `None` | The horizontal starting position (0-based, 0-48). If `None`, position is auto-calculated. | `None` | No | | `y` | `from_top` | `integer` or `None` | The vertical starting position (0-based). If `None`, position is auto-calculated. | `None` | No | **Example with fixed position:** ```yaml position: x: 0 y: 0 # Or verbose: position: from_left: 24 from_top: 10 ``` **Example with auto-positioning (omit position entirely):** ```yaml # No position field - will be auto-positioned size: w: quarter h: 8 ``` ## Panel Types (Specific Configurations) The `BasePanel` fields are common to all panel types. For details on the specific configuration fields available for each panel `type`, refer to their individual documentation pages: * [Markdown Panel](./markdown.md) * [Links Panel](./links.md) * [Search Panel](./search.md) * [Image Panel](./image.md) * [Section Panel](./section.md) (collapsible sections) * [XY Chart Panel](./xy.md) * [Pie Chart Panel](./pie.md) * [Metric Panel](./metric.md) * [Tagcloud Panel](./tagcloud.md) * [Lens Panel](./lens.md) * [ESQL Panel](./esql.md) ## Color Mapping Configuration > **Quick Reference**: Want to customize chart colors? See [Color Mapping Examples](#color-mapping-examples) below for palette selection, or the [Custom Color Assignments](../guides/color-assignments.md) guide for manual color assignments. Many chart panel types (Pie, XY, Metric) support color customization through the `color` field. You can select from built-in color palettes or manually assign specific colors to data values. ### ColorValueMapping Object **kb_dashboard_core.panels.charts.base.config.ColorValueMapping** Categorical color mapping for charts keyed by exact values. Fields: - `palette` (``): The palette ID to use for unassigned colors. Available palettes: - 'default' - Standard EUI palette - 'eui_amsterdam_color_blind' - Color-blind safe palette (default) - 'kibana_palette' or 'legacy' - Legacy Kibana colors - 'elastic_brand' - Elastic brand colors - 'gray' - Grayscale palette - `assignments` (`list[kb_dashboard_core.panels.charts.base.config.ColorValueAssignment]`): Manual color assignments to specific data values. --- # Source: panels/auto-layout.md --- # Auto-Layout Guide This guide explains how to use the automatic panel layout system to position panels on your dashboard without manually specifying coordinates. ## Overview Instead of manually calculating x and y coordinates for every panel, you can use auto-layout to automatically position panels on the dashboard grid. Auto-layout works by: 1. Defining panel **size** (width and height) without position 2. Choosing a **layout algorithm** to determine how panels are arranged 3. Letting the compiler calculate optimal positions for all panels ## Quick Start ### Basic Auto-Layout Example ```yaml dashboards: - name: "Auto-Layout Dashboard" settings: layout_algorithm: up-left # Optional, defaults to 'up-left' panels: # Panel 1: Quarter-width panel (12 units wide) - markdown: content: "First panel" title: "Panel 1" size: w: quarter # Semantic width - 12 units h: 8 # Height in grid units # No position specified - will be auto-positioned # Panel 2: Another quarter-width panel - markdown: content: "Second panel" title: "Panel 2" size: w: quarter h: 8 # Panel 3: Half-width panel - markdown: content: "Third panel" title: "Panel 3" size: w: half # Semantic width - 24 units h: 8 ``` This creates a dashboard where panels are automatically arranged in a 2x2 grid pattern. ## Panel Size Configuration ### The `size` Field Instead of specifying a `grid` object with x, y, w, h coordinates, you can use separate `size` and `position` fields: ```yaml panels: - markdown: content: "My content" title: "My Panel" size: w: 24 # Width (or use semantic values) h: 8 # Height position: # Optional - omit for auto-layout x: 0 y: 0 ``` ### Semantic Width Values The `w` (width) field accepts semantic values for common panel widths: | Semantic Value | Grid Units | Description | | -------------- | ---------- | ----------- | | `whole` | 48 | Full dashboard width | | `half` | 24 | Half width (2 panels per row) | | `third` | 16 | One-third width (3 panels per row) | | `quarter` | 12 | Quarter width (4 panels per row) | | `sixth` | 8 | One-sixth width (6 panels per row) | | `eighth` | 6 | One-eighth width (8 panels per row) | You can also specify numeric values from 1 to 48. ### Default Size If you omit the `size` field entirely, panels default to: - Width: 12 units (quarter width) - Height: 8 units ```yaml panels: - markdown: content: "Uses default size" title: "Default Panel" # No size specified - uses w=12, h=8 ``` ## Layout Algorithms The `layout_algorithm` setting in dashboard `settings` controls how panels are automatically positioned. Choose the algorithm that best fits your dashboard's content flow. ### `up-left` (Default) Floats panels up first, then left. Creates compact, grid-like layouts. **Best for:** Dashboards where you want panels to form neat grids. ```yaml dashboards: - name: "Up-Left Example" settings: layout_algorithm: up-left panels: - markdown: { content: "A" } title: "Panel A" size: { w: quarter, h: 8 } - markdown: { content: "B" } title: "Panel B" size: { w: quarter, h: 8 } - markdown: { content: "C" } title: "Panel C" size: { w: quarter, h: 8 } - markdown: { content: "D" } title: "Panel D" size: { w: quarter, h: 8 } ``` **Result:** Forms a 2x2 grid with panels arranged like: ```text [A][B] [C][D] ``` ### `left-right` Fills rows from left to right before moving to the next row. Row height is determined by the tallest panel in that row. **Best for:** Dashboards where you want panels to appear in reading order (left-to-right, top-to-bottom). ```yaml dashboards: - name: "Left-Right Example" settings: layout_algorithm: left-right panels: - markdown: { content: "A" } size: { w: half, h: 8 } - markdown: { content: "B" } size: { w: half, h: 12 } # Taller panel - markdown: { content: "C" } size: { w: third, h: 8 } - markdown: { content: "D" } size: { w: third, h: 8 } ``` **Result:** ```text Row 1: [A (h=8)][B (h=12)] <- Row height = 12 Row 2: [C (h=8)][D (h=8)] <- Row height = 8 ``` ### `blocked` Never fills gaps above the current bottom. Maintains strict top-to-bottom flow. **Best for:** Dashboards where vertical ordering matters more than space efficiency. ```yaml dashboards: - name: "Blocked Example" settings: layout_algorithm: blocked panels: - markdown: { content: "Tall panel" } size: { w: half, h: 20 } position: { x: 0, y: 0 } # Locked position - markdown: { content: "Auto panel 1" } size: { w: half, h: 8 } # Will go to x=24, y=0 (right of tall panel) - markdown: { content: "Auto panel 2" } size: { w: half, h: 8 } # Will go to y=20 (below the tall panel, not filling the gap) ``` ### `first-available-gap` Scans the entire grid from top-left to find the first available gap. Maximizes space utilization. **Best for:** Dashboards where minimizing vertical height is important. ```yaml dashboards: - name: "First Available Gap Example" settings: layout_algorithm: first-available-gap panels: - markdown: { content: "Tall panel" } size: { w: half, h: 20 } position: { x: 0, y: 0 } - markdown: { content: "Small panel 1" } size: { w: half, h: 8 } # Will fill the gap at x=24, y=0 - markdown: { content: "Small panel 2" } size: { w: half, h: 8 } # Will fill the gap at x=24, y=8 ``` ## Mixing Auto-Layout and Fixed Positions You can mix panels with auto-layout and panels with fixed positions (called "locked panels"): ```yaml dashboards: - name: "Mixed Layout" panels: # Locked panel - fixed position - markdown: content: "This stays at the top" title: "Header" size: { w: whole, h: 4 } position: { x: 0, y: 0 } # Auto-positioned panels will flow around the locked panel - markdown: content: "Auto panel 1" title: "Panel 1" size: { w: half, h: 8 } # No position - will be auto-positioned below the header - markdown: content: "Auto panel 2" title: "Panel 2" size: { w: half, h: 8 } ``` The auto-layout algorithm respects locked panels and positions auto panels around them. ## Field Aliases Both `size` and `position` support verbose aliases for readability: ```yaml size: width: 24 # Same as 'w' height: 12 # Same as 'h' position: from_left: 0 # Same as 'x' from_top: 10 # Same as 'y' ``` ## Common Patterns ### Full-Width Header with Grid Below ```yaml panels: # Header - markdown: { content: "Dashboard Title" } title: "Header" size: { w: whole, h: 4 } # Grid of metrics (will auto-arrange in 2x2 grid) - lens: { type: metric, ... } size: { w: quarter } - lens: { type: metric, ... } size: { w: quarter } - lens: { type: metric, ... } size: { w: quarter } - lens: { type: metric, ... } size: { w: quarter } ``` ### Two-Column Layout ```yaml settings: layout_algorithm: left-right panels: - markdown: { content: "Left column content" } size: { w: half, h: 20 } - markdown: { content: "Right column content" } size: { w: half, h: 20 } # These will form the second row - markdown: { content: "Bottom left" } size: { w: half, h: 10 } - markdown: { content: "Bottom right" } size: { w: half, h: 10 } ``` ### Dashboard with Sidebar ```yaml panels: # Fixed sidebar - links: { ... } title: "Navigation" size: { w: eighth, h: 40 } position: { x: 0, y: 0 } # Lock to left side # Main content area (auto-positioned to the right) - lens: { type: xy, ... } title: "Main Chart" size: { w: 42, h: 20 } # 48 - 6 = 42 remaining width - lens: { type: metric, ... } size: { w: 42, h: 20 } ``` ## Related Documentation - [Base Panel Configuration](./base.md) - Common panel fields - [Dashboard Configuration](../dashboard/dashboard.md) - Dashboard settings --- # Source: panels/drilldowns.md --- # Drilldowns Configuration Drilldowns enable interactive navigation from dashboard panels. When users click on chart elements, they can either navigate to another dashboard or open an external URL with context from the clicked element. --- ## Overview Drilldowns can be added to any Lens or ESQL panel by specifying the `drilldowns` field in the panel configuration. There are two types of drilldowns: | Type | Description | Use Case | | ---- | ----------- | -------- | | **Dashboard Drilldown** | Navigate to another Kibana dashboard | Deep-dive analysis, related dashboards | | **URL Drilldown** | Open an external URL | Documentation, external systems, tickets | ## Quick Example ```yaml panels: - title: Events by Status size: { w: half, h: 12 } lens: type: bar data_view: logs-* dimension: type: values field: http.response.status_code id: status metrics: - aggregation: count id: count drilldowns: # Navigate to another dashboard - name: View Status Details dashboard: status-details-dashboard with_filters: true with_time: true # Open external documentation - name: HTTP Status Reference url: "https://httpstatuses.com/{{event.value}}" new_tab: true ``` ## Drilldown Types ### Dashboard Drilldown **kb_dashboard_core.panels.drilldowns.config.DashboardDrilldown** Dashboard-to-dashboard drilldown configuration. Fields: - `id` (`str | None`): Optional unique identifier for the drilldown. If not provided, one will be generated. - `name` (``): Display name for the drilldown. - `triggers` (`list[Annotated[kb_dashboard_core.panels.drilldowns.config.DrilldownTrigger, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=False)])]]`): List of triggers that activate this drilldown. Defaults to ['click']. - `dashboard` (``): Target dashboard ID or friendly identifier. - `with_filters` (``): Whether to carry over current filters to the target dashboard. Defaults to True. - `with_time` (``): Whether to carry over current time range to the target dashboard. Defaults to True. --- # Source: panels/links.md --- # Links Panel Configuration The `links` panel type is used to display a collection of hyperlinks on your dashboard. These links can point to other Kibana dashboards or external web URLs. This panel is useful for creating navigation hubs or providing quick access to related resources. --- ## Links Panel **kb_dashboard_core.panels.links.config.LinksPanel** Represents a Links panel configuration. Links panels are used to display a collection of links to other dashboards, saved objects, or external URLs. Examples: Linking to another Dashboard: ```yaml dashboards: - name: "Main Overview" panels: - title: "Navigate to User Details" size: { w: 24, h: 2 } links: items: - label: "View User Activity Dashboard" dashboard: "user-activity-dashboard-id" ``` Linking to an External URL: ```yaml dashboards: - name: "Main Overview" panels: - title: "External Resources" size: { w: 24, h: 2 } links: items: - label: "Project Documentation" url: "https://docs.example.com/project-alpha" new_tab: true ``` Complex configuration with multiple link types: ```yaml dashboards: - name: "Operations Hub" panels: - title: "Quick Access" size: { w: 48, h: 3 } links: layout: "vertical" items: - label: "Service Health Dashboard" dashboard: "service-health-monitor-v2" - label: "Runbook Wiki" url: "https://internal.wiki/ops/runbooks" new_tab: true ``` Fields: - `id` (`str | None`): A unique identifier for the panel. If not provided, one may be generated during compilation. - `title` (``): The title displayed on the panel header. Can be an empty string. - `hide_title` (`bool | None`): If `true`, the panel title will be hidden. Defaults to `false` (title is shown). - `description` (`str | None`): A brief description of the panel's content or purpose. Defaults to an empty string. - `size` (``): Defines the panel's size on the dashboard grid. - `position` (``): Defines the panel's position on the dashboard grid. If not specified, position will be auto-calculated. - `drilldowns` (`list[DrilldownTypes] | None`): Optional list of drilldowns to attach to this panel. - `links_config` (``): Links panel configuration. --- # Source: panels/markdown.md --- # Markdown Panel Configuration The `markdown` panel type is used to display rich text content, formatted using Markdown syntax, directly on your dashboard. This is equivalent to the "Text" visualization in Kibana. --- ## Markdown Panel **kb_dashboard_core.panels.markdown.config.MarkdownPanel** Represents a Markdown panel configuration. Markdown panels are used to display rich text content using Markdown syntax. Examples: Minimal Markdown panel: ```yaml dashboards: - name: "Dashboard with Markdown" panels: - title: "Welcome Note" size: { w: 48, h: 3 } markdown: content: | ## Welcome to the Dashboard! This panel provides an overview of the key metrics and reports available. - Item 1 - Item 2 ``` Markdown panel with custom font size: ```yaml dashboards: - name: "Informational Dashboard" panels: - title: "Important Instructions" size: { w: 32, h: 5 } markdown: content: | # Setup Guide Please follow the [official documentation](https://strawgate.github.io/kb-yaml-to-lens/) for setup instructions. Key steps: 1. **Download** the installer. 2. **Configure** the `config.yaml` file. 3. **Run** the start script. font_size: 14 ``` Fields: - `id` (`str | None`): A unique identifier for the panel. If not provided, one may be generated during compilation. - `title` (``): The title displayed on the panel header. Can be an empty string. - `hide_title` (`bool | None`): If `true`, the panel title will be hidden. Defaults to `false` (title is shown). - `description` (`str | None`): A brief description of the panel's content or purpose. Defaults to an empty string. - `size` (``): Defines the panel's size on the dashboard grid. - `position` (``): Defines the panel's position on the dashboard grid. If not specified, position will be auto-calculated. - `drilldowns` (`list[DrilldownTypes] | None`): Optional list of drilldowns to attach to this panel. - `markdown` (``): Markdown panel configuration. --- # Source: panels/section.md --- # Section Panel Configuration The `section` panel type creates a collapsible section that groups panels under a named, expandable header. This is useful for organizing complex dashboards by allowing users to collapse groups of related panels to focus on specific areas. > **Requires Kibana 9.1+.** Collapsible sections are not supported on Kibana 8.x. Dashboards containing `section:` panels will fail to import on older versions. --- ## Collapsible Panel **kb_dashboard_core.panels.collapsible.CollapsiblePanel** A collapsible section that groups panels under a named, expandable header. In the outer dashboard grid, a collapsible panel occupies a single full-width row (the section header). Its inner panels are laid out in a separate coordinate space relative to the section. Examples: ```yaml dashboards: - name: "Dashboard with Sections" panels: - title: "Overview" size: { w: 48, h: 6 } markdown: content: "# Overview" - title: "Details" section: collapsed: true panels: - title: "CPU Usage" size: { w: 48, h: 12 } markdown: content: "# CPU" ``` Fields: - `id` (`str | None`): A unique identifier for the panel. If not provided, one may be generated during compilation. - `title` (``): The title displayed on the panel header. Can be an empty string. - `hide_title` (`bool | None`): If `true`, the panel title will be hidden. Defaults to `false` (title is shown). - `description` (`str | None`): A brief description of the panel's content or purpose. Defaults to an empty string. - `size` (``): Section header size. Defaults to full width (48) and 1 row tall. - `position` (``): Defines the panel's position on the dashboard grid. If not specified, position will be auto-calculated. - `drilldowns` (`list[DrilldownTypes] | None`): Optional list of drilldowns to attach to this panel. - `section` (``): Section configuration including collapsed state and inner panels. --- # Source: panels/lens.md --- # Lens Panel Configuration Lens panels in Kibana provide a flexible and user-friendly way to create various types of visualizations, such as metric displays, pie charts, bar charts, line charts, and more. This document covers the YAML configuration for Lens panels using this compiler. The `LensPanel` is the primary container. Its `lens` field contains the specific visualization configuration (for example `metric`, `pie`, `line`, or `datatable`). --- ## Minimal Configuration Examples **Minimal Lens Metric Chart:** ```yaml dashboards: - name: "Key Metrics Dashboard" panels: - title: "Total Users" size: {w: 16, h: 3} lens: type: metric # Specifies a LensMetricChart data_view: "logs-*" query: # Optional panel-specific query kql: "event.dataset:website.visits" primary: aggregation: "unique_count" field: "user.id" label: "Unique Visitors" ``` **Minimal Lens Pie Chart:** ```yaml dashboards: - name: "Traffic Analysis" panels: - title: "Traffic by Source" size: {w: 32, h: 3} position: {x: 16, y: 0} lens: type: pie # Specifies a LensPieChart data_view: "weblogs-*" metrics: - aggregation: "count" label: "Sessions" breakdowns: - type: values field: "source.medium" label: "Traffic Source" size: 5 # Top 5 sources ``` ## Full Configuration Options ### Lens Panel (panel with a `lens:` field) This is the main object for a Lens-based visualization. It inherits from the [Base Panel Configuration](base.md). | YAML Key | Data Type | Description | Kibana Default | Required | | -------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------- | -------- | | `id` | `string` | A unique identifier for the panel. Inherited from BasePanel. | Generated ID | No | | `title` | `string` | The title displayed on the panel header. Inherited from BasePanel. | `""` (empty string) | No | | `hide_title` | `boolean` | If `true`, the panel title will be hidden. Inherited from BasePanel. | `false` | No | | `description` | `string` | A brief description of the panel. Inherited from BasePanel. | `""` (empty string, if `None`) | No | | `size` | `Size` object | Defines the panel's width and height. Inherited from BasePanel. See [Size Object Configuration](base.md#size-object-configuration-size). | `w: 12, h: 8` | No | | `position` | `Position` object | Defines the panel's x/y coordinates. Inherited from BasePanel. See [Position Object Configuration](base.md#position-object-configuration-position). | Auto-calculated | No | | `query` | `LegacyQueryTypes` object (KQL or Lucene) | A panel-specific query to filter data for this Lens visualization. See [Queries Documentation](../queries/config.md). | `None` (uses dashboard query) | No | | `filters` | `list of FilterTypes` | A list of panel-specific filters. See [Filters Documentation](../filters/config.md). | `[]` (empty list) | No | | `lens` | `LensPanelConfig` object | Defines the actual Lens visualization configuration. This includes the inner `type` plus chart-specific fields. | N/A | Yes | **Note**: For XY charts (line, bar, area), a `layers` field is available to add reference lines and additional data layers. See the [XY Chart Panel Configuration](xy.md#reference-lines) documentation for details. --- ## Lens Metric Chart (`lens.type: metric`) Displays a single primary metric, optionally with a secondary metric, a maximum value, and a breakdown dimension. | YAML Key | Data Type | Description | Kibana Default | Required | | ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['metric']` | Specifies the chart type as a Lens Metric visualization. | `metric` | Yes | | `id` | `string` | An optional unique identifier for this specific chart layer. | Generated ID | No | | `primary` | `LensMetricTypes` object | The primary metric to display. This is the main value shown. See [Lens Metrics](#lens-metrics-primary-secondary-maximum-for-metric-metrics-for-pie). | N/A | Yes | | `secondary` | `LensMetricTypes` object | An optional secondary metric to display alongside the primary. See [Lens Metrics](#lens-metrics-primary-secondary-maximum-for-metric-metrics-for-pie). | `None` | No | | `maximum` | `LensMetricTypes` object | An optional maximum metric, used for progress bar scale or context. See [Lens Metrics](#lens-metrics-primary-secondary-maximum-for-metric-metrics-for-pie). | `None` | No | | `breakdown` | `LensDimensionTypes` object | An optional dimension to break down the metric by (e.g., showing primary metric per country). See [Lens Dimensions](#lens-dimensions-breakdown-for-metric-breakdowns-for-pie). | `None` | No | | `appearance` | `MetricAppearance` object | Visual appearance configuration. See [Metric Appearance](#metric-appearance). | `None` | No | | `titles_and_text` | `MetricTitlesAndText` object | Titles and text formatting options. See [Metric Titles and Text](#metric-titles-and-text). | `None` | No | ### Metric Appearance | YAML Key | Data Type | Description | Kibana Default | Required | | ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `primary.icon` | `string` | Icon identifier to display alongside the primary metric value. | `None` | No | | `primary.icon_position` | `Literal['left', 'right']` | Horizontal alignment of the icon. | `None` | No | | `primary.background_chart.type` | `Literal['line', 'bar', 'none']` | Background chart mode for the primary metric. | `None` | No | | `primary.background_chart.direction` | `Literal['horizontal', 'vertical']` | Direction for bar background charts (`type: bar`). | `None` | No | | `primary.font_size` | `Literal['default', 'fit', 'custom']` | Font size mode for the primary metric value. | `None` | No | | `primary.position` | `Literal['top', 'bottom']` | Vertical position of the primary metric value. | `None` | No | | `primary.alignment` | `Literal['left', 'center', 'right']` | Text alignment for the primary metric value. | `None` | No | | `secondary.alignment` | `Literal['left', 'center', 'right']` | Text alignment for the secondary metric value. | `None` | No | | `secondary.label.text` | `string` | Custom label for the secondary metric. | `None` | No | | `secondary.label.position` | `Literal['before', 'after']` | Position for the secondary label. | `None` | No | | `breakdown.column_count` | `int` | Maximum breakdown columns (minimum `1`). | `None` | No | ### Metric Titles and Text | YAML Key | Data Type | Description | Kibana Default | Required | | ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `subtitle` | `string` | Custom subtitle text displayed below the metric title. | `None` | No | | `alignment` | `Literal['left', 'center', 'right']` | Text alignment for the metric title and subtitle. | `None` | No | | `weight` | `Literal['bold', 'normal', 'lighter']` | Font weight for the metric title. | `None` | No | **Example (Lens Metric Chart with Styling):** ```yaml dashboards: - name: "Lens Metric Example" description: "Example of Lens metric panel with primary, secondary, and breakdown" panels: - title: "Data Transfer Metrics" size: {w: 24, h: 15} lens: type: metric data_view: "logs-*" primary: aggregation: "sum" field: "bytes_transferred" label: "Total Data" format: { type: "bytes" } secondary: aggregation: "average" field: "response_time_ms" label: "Avg Response" format: { type: "duration", suffix: " ms" } breakdown: type: values field: "host.name" size: 3 label: "Top Hosts" appearance: primary: background_chart: type: bar direction: horizontal icon: sortUp icon_position: right titles_and_text: subtitle: "Last 24 hours" alignment: center weight: bold ``` --- ## Lens Pie Chart (`lens.type: pie`) Visualizes proportions of categories using slices of a pie or a donut chart. | YAML Key | Data Type | Description | Kibana Default | Required | | ----------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['pie']` | Specifies the chart type as a Lens Pie visualization. | `pie` | Yes | | `id` | `string` | An optional unique identifier for this specific chart layer. | Generated ID | No | | `data_view` | `string` | The ID or title of the data view (index pattern) for this pie chart. | N/A | Yes | | `metrics` | `LensMetricTypes \| list[LensMetricTypes]` object | A single metric or list of metrics that determine the size of each slice. See [Lens Metrics](#lens-metrics-primary-secondary-maximum-for-metric-metrics-for-pie). | N/A | Yes | | `breakdowns` | `list of LensBreakdownTypes` objects | One or more breakdowns that determine how the pie is sliced. See [Lens Dimensions](#lens-dimensions-breakdown-for-metric-breakdowns-for-pie). | N/A | Yes | | `appearance` | `PieChartAppearance` object | Formatting options for the chart appearance. See [Pie Chart Appearance](#pie-chart-appearance-appearance-field). | `None` | No | | `legend` | `PieLegend` object | Formatting options for the chart legend. See [Pie Legend](#pie-legend-legend-field). | `None` | No | | `color` | `ColorValueMapping` object | Formatting options for the chart color palette. See [Color Mapping](#color-mapping-color-field). | `None` | No | **Example (Lens Pie Chart):** ```yaml dashboards: - name: "Lens Pie Chart Example" description: "Example of Lens pie chart with appearance and legend options" panels: - title: "Disk Operations by Device" size: {w: 24, h: 15} lens: type: pie data_view: "metrics-*" metrics: - aggregation: "average" field: "metrics.system.disk.operations" label: "Avg Disk Operations" breakdowns: - type: values field: "resource.attributes.device" size: 5 label: "Device" appearance: donut: "medium" categories: position: "inside" values: format: "percent" legend: visible: "show" width: "large" ``` --- ## Lens Dimensions (`breakdown` for Metric, `breakdowns` for Pie) Dimensions define how data is grouped or bucketed in Lens visualizations. ### Common Dimension Fields (`BaseLensDimension`) All specific dimension types below can include: | YAML Key | Data Type | Description | Kibana Default | Required | | -------- | --------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `id` | `string` | An optional unique identifier for the dimension. | Generated ID | No | | `label` | `string` | A custom display label for the dimension. If not provided, a label is inferred. | Inferred | No | When these shapes are used in chart fields that accept `LensBreakdownTypes` instead of `LensDimensionTypes` (for example pie `breakdowns` or other breakdown-specific configs), the breakdown variant may also allow `collapse`. Plain XY `dimension` / `breakdown` axes do not support `collapse`. ### Top Values Dimension (`type: values`) Groups data by the most frequent unique values of one or more fields. Supports both single-field and multi-field (multi-term) aggregations. | YAML Key | Data Type | Description | Kibana Default | Required | | ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['values']` | Specifies the dimension type. | N/A | Yes | | `field` | `string` | Single field to get top values from. Mutually exclusive with `fields`. | N/A | One of `field` or `fields` | | `fields` | `list of strings` | Multiple fields for multi-term aggregation (minimum 2 fields). Mutually exclusive with `field`. | N/A | One of `field` or `fields` | | `size` | `integer` | The number of top values to display. | `3` | No | | `sort` | `Sort` object | How to sort the terms. `by` can be a metric label or `_term` (alphabetical). `direction` is `asc` or `desc`. | Sort by metric, `desc` | No | | `show_other_bucket` | `boolean` | If `true`, groups remaining values into an "Other" bucket. | `true` | No | | `include_missing_values` | `boolean` | If `true`, creates a bucket for documents where the field is missing. | `false` | No | | `include` | `list of strings` | A list of specific terms to include. When `include_is_regex` is `true`, must contain exactly one entry. | `None` | No | | `exclude` | `list of strings` | A list of specific terms to exclude. When `exclude_is_regex` is `true`, must contain exactly one entry. | `None` | No | | `include_is_regex` | `boolean` | If `true`, treats the single `include` value as a regex pattern. `include` must contain exactly one entry. | `false` | No | | `exclude_is_regex` | `boolean` | If `true`, treats the single `exclude` value as a regex pattern. `exclude` must contain exactly one entry. | `false` | No | **Example - Single Field:** ```yaml breakdowns: - type: values field: agent.name size: 5 ``` **Example - Multi-Field:** ```yaml breakdowns: - type: values fields: - agent.name - agent.type size: 10 label: "Agent Name + Type" ``` **Example - Regex Include/Exclude:** ```yaml breakdowns: - type: values field: log.level include: - "^err(or)?$" include_is_regex: true exclude: - "^debug$" exclude_is_regex: true ``` ### Date Histogram Dimension (`type: date_histogram`) Groups data into time-based buckets (e.g., per hour, day). | YAML Key | Data Type | Description | Kibana Default | Required | | ------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['date_histogram']` | Specifies the dimension type. | N/A | Yes | | `field` | `string` | The date field to use for the histogram. | N/A | Yes | | `minimum_interval` | `string` | The time interval (e.g., `auto`, `1h`, `1d`, `1w`). | `auto` | No | | `partial_intervals` | `boolean` | If `true`, includes buckets for time periods that are only partially covered by the data. | `true` | No | ### Filters Dimension (`type: filters`) Creates buckets based on a list of custom KQL/Lucene queries. | YAML Key | Data Type | Description | Kibana Default | Required | | --------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['filters']` | Specifies the dimension type. | N/A | Yes | | `filters` | `list of LensFiltersDimensionFilter` objects | A list of filter definitions. Each filter object has `query` (KQL/Lucene) and an optional `label`. | N/A | Yes | **`LensFiltersDimensionFilter` Object:** | YAML Key | Data Type | Description | Kibana Default | Required | | -------- | ------------------------- | ------------------------------------------------ | ---------------- | -------- | | `query` | `LegacyQueryTypes` object | The KQL or Lucene query for this filter bucket. | N/A | Yes | | `label` | `string` | A display label for this filter bucket. | Query string | No | ### Intervals Dimension (`type: intervals`) Groups data into numeric ranges (buckets). | YAML Key | Data Type | Description | Kibana Default | Required | | ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['intervals']` | Specifies the dimension type. | N/A | Yes | | `field` | `string` | The numeric field to create intervals from. | N/A | Yes | | `intervals` | `list of LensIntervalsDimensionInterval` objects | A list of custom interval ranges. If not provided, `granularity` is used. | `None` | No | | `granularity` | `integer` (1-7) | Divides the field into evenly spaced intervals. 1 is coarsest, 7 is finest. | `4` | No | | `include_empty_intervals` | `boolean` | If `true`, shows a bucket for documents with missing values for the field. | `false` | No | **`LensIntervalsDimensionInterval` Object:** | YAML Key | Data Type | Description | Kibana Default | Required | | -------- | --------- | ------------------------------------------------ | ---------------- | -------- | | `from` | `integer` | The start of the interval (inclusive). | `None` | No | | `to` | `integer` | The end of the interval (exclusive). | `None` | No | | `label` | `string` | A display label for this interval bucket. | Auto-generated | No | --- ## Lens Metrics (`primary`, `secondary`, `maximum` for Metric; `metrics` for Pie) Metrics define the calculations performed on your data (e.g., count, sum, average). ### Common Metric Fields (`BaseLensMetric`) All specific metric types below can include: | YAML Key | Data Type | Description | Kibana Default | Required | | -------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `id` | `string` | An optional unique identifier for the metric. | Generated ID | No | | `label` | `string` | A custom display label for the metric. If not provided, a label is inferred. | Inferred | No | | `format` | `LensMetricFormatTypes` object | How to format the metric's value (e.g., number, bytes, percent). See [Metric Formatting](#metric-formatting-format-field-within-a-metric). | Default for type | No | | `filter` | `LegacyQueryTypes` object | A KQL or Lucene query to filter data _before_ this metric is calculated. | `None` | No | ### Aggregated Metric Types These metrics perform an aggregation on a field. **Count / Unique Count (`aggregation: count` or `aggregation: unique_count`)** | YAML Key | Data Type | Description | Kibana Default | Required | | --------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `aggregation` | `Literal['count', 'unique_count']` | Type of count. | N/A | Yes | | `field` | `string` | For `unique_count`, the field whose unique values are counted. For `count`, optional (counts all documents if `None`). | `None` for `count` | No (Yes for `unique_count`) | | `exclude_zeros` | `boolean` | If `true`, zero values are excluded from the aggregation. | `true` | No | **Sum (`aggregation: sum`)** | YAML Key | Data Type | Description | Kibana Default | Required | | --------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `aggregation` | `Literal['sum']` | Specifies sum aggregation. | `sum` | Yes | | `field` | `string` | The numeric field to sum. | N/A | Yes | | `exclude_zeros` | `boolean` | If `true`, zero values are excluded from the sum. | `true` | No | **Min, Max, Average, Median (`aggregation: min` / `max` / `average` / `median`)** | YAML Key | Data Type | Description | Kibana Default | Required | | ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `aggregation` | `Literal['min', 'max', 'average', 'median']` | The aggregation type. | N/A | Yes | | `field` | `string` | The numeric field for the aggregation. | N/A | Yes | **Last Value (`aggregation: last_value`)** | YAML Key | Data Type | Description | Kibana Default | Required | | ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `aggregation` | `Literal['last_value']` | Retrieves the most recent value of a field. | `last_value` | Yes | | `field` | `string` | The field whose last value is retrieved. | N/A | Yes | | `date_field` | `string` | The date field used to determine the "last" value. | `@timestamp` | No | **Percentile (`aggregation: percentile`)** | YAML Key | Data Type | Description | Kibana Default | Required | | ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `aggregation` | `Literal['percentile']` | Calculates the value at a specific percentile. | `percentile` | Yes | | `field` | `string` | The numeric field for percentile calculation. | N/A | Yes | | `percentile` | `integer` | The percentile to calculate (e.g., `95` for 95th percentile). | N/A | Yes | **Percentile Rank (`aggregation: percentile_rank`)** | YAML Key | Data Type | Description | Kibana Default | Required | | ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `aggregation` | `Literal['percentile_rank']` | Determines the rank of a specific value within the dataset. | `percentile_rank` | Yes | | `field` | `string` | The numeric field for percentile rank calculation. | N/A | Yes | | `rank` | `integer` | The value for which to find the percentile rank. | N/A | Yes | ### Formula Metric Allows custom calculations using Kibana's native formula syntax. Formulas enable complex calculations that combine multiple aggregations, field operations, and mathematical expressions. | YAML Key | Data Type | Description | Kibana Default | Required | | --------- | ------------------------- | ------------------------------------------------ | ---------------- | -------- | | `formula` | `string` | The formula string using Kibana formula syntax. | N/A | Yes | | `label` | `string` | A custom display label for the metric. | `"Formula"` | No | | `format` | `LensMetricFormatTypes` object | How to format the metric's value. | Default number format | No | **Example Formulas:** Simple arithmetic: ```yaml primary: formula: "count() / 100" label: "Count Percentage" ``` Field aggregations: ```yaml primary: formula: "max(response.time) - min(response.time)" label: "Response Time Range" format: type: duration ``` With filters: ```yaml primary: formula: "count(kql='status:error') / count() * 100" label: "Error Rate %" format: type: percent ``` Number formatting: ```yaml primary: formula: "average(bytes)" label: "Avg Bytes" format: type: bytes compact: true ``` --- ## Metric Formatting (`format` field within a metric) Defines how metric values are displayed in visualizations. ### Standard Format **kb_dashboard_core.panels.charts.lens.metrics.config.LensMetricFormat** Standard format configuration for displaying metric values. Supports common numeric formats with optional suffix and compact notation. Fields: - `type` (`Literal['number', 'bytes', 'bits', 'percent', 'duration']`): The format type for the metric value. Available formats: - **number**: Plain numeric value with optional decimal places - **bytes**: Byte size formatting (B, KB, MB, GB, TB) - **bits**: Bit size formatting (b, Kb, Mb, Gb, Tb) - **percent**: Percentage formatting with % symbol - **duration**: Time duration formatting (ms, s, m, h, d) - `decimals` (`int | None`): The number of decimal places to display. If not specified, defaults to 2 for number/bytes/percent, 0 for bits/duration. - `suffix` (`str | None`): Optional suffix to display after the formatted number (e.g., " requests", " users"). - `compact` (`bool | None`): Whether to use compact notation (e.g., 1.2K instead of 1200). Defaults to Kibana's behavior. --- # Source: panels/esql.md --- # ESQL Panel Configuration ESQL panels leverage the power of Elasticsearch Query Language (ESQL) to create visualizations. This allows for more complex data transformations and aggregations directly within the query that feeds the chart. The `ESQLPanel` is the primary container. Its `esql` field holds both the ESQL query and the specific visualization type configuration (for example `metric`, `pie`, `bar`, or `datatable`). --- ## Minimal Configuration Examples **Minimal ESQL Metric Chart:** ```yaml dashboards: - name: "ESQL Metrics Dashboard" panels: - title: "Total Processed Events" size: {w: 16, h: 3} esql: type: metric query: | FROM logs-* | STATS total_events = COUNT(*) primary: field: "total_events" ``` !!! tip "Advanced: Query Reuse with YAML Anchors" ES|QL queries can also be defined as arrays, enabling reuse patterns with YAML anchors. This lets you define base queries once and extend them across multiple panels. See [ES|QL Query Reuse with YAML Anchors](../guides/esql-views.md) for detailed patterns and examples. **Minimal ESQL Pie Chart:** ```yaml dashboards: - name: "ESQL Event Analysis" panels: - title: "Events by Type (ESQL)" size: {w: 32, h: 3} position: {x: 16, y: 0} esql: type: pie # Specifies an ESQLPieChart query: | FROM logs-* | STATS event_count = COUNT(*) BY event.category | SORT event_count DESC | LIMIT 5 metrics: - field: "event_count" breakdowns: - field: "event.category" ``` ## Full Configuration Options ### ESQL Panel (panel with an `esql:` field) This is the main object for an ESQL-based visualization. It inherits from the [Base Panel Configuration](base.md). The presence of the `esql` field distinguishes it from a Lens panel. | YAML Key | Data Type | Description | Kibana Default | Required | | -------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------- | -------- | | `id` | `string` | A unique identifier for the panel. Inherited from BasePanel. | Generated ID | No | | `title` | `string` | The title displayed on the panel header. Inherited from BasePanel. | `""` (empty string) | No | | `hide_title` | `boolean` | If `true`, the panel title will be hidden. Inherited from BasePanel. | `false` | No | | `description` | `string` | A brief description of the panel. Inherited from BasePanel. | `""` (empty string, if `None`) | No | | `size` | `Size` object | Defines the panel's width and height. Inherited from BasePanel. See [Size Object Configuration](base.md#size-object-configuration-size). | `w: 12, h: 8` | No | | `position` | `Position` object | Defines the panel's x/y coordinates. Inherited from BasePanel. See [Position Object Configuration](base.md#position-object-configuration-position). | Auto-calculated | No | | `esql` | `ESQLPanelConfig` object | Defines the actual ESQL visualization configuration. Contains the query, time_field, inner `type`, and chart-specific fields. | N/A | Yes | ### ESQL Chart Configuration Fields All ESQL chart types share these common panel-level fields: | YAML Key | Data Type | Description | Default | Required | | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `query` | `string` or `ESQLQuery` object | The ESQL query string. See [Queries Documentation](../queries/config.md#esql-query). | N/A | Yes | | `time_field` | `string` | The time field to use for the dashboard time picker. This connects the panel to the dashboard's global time range controls. | `'@timestamp'` | No | | `type` | Chart type literal | The specific chart type (metric, pie, bar, line, area, etc.). See chart-specific sections below. | N/A | Yes | **Example using custom time field:** ```yaml dashboards: - name: "Custom Time Field Example" panels: - title: "Events Over Time" size: {w: 48, h: 20} esql: type: bar query: | FROM logs-* | STATS event_count = COUNT(*) BY timestamp_bucket = BUCKET(event.created, 20, ?_tstart, ?_tend) | SORT timestamp_bucket ASC time_field: "event.created" # Use event.created instead of @timestamp dimension: field: "timestamp_bucket" metrics: - field: "event_count" ``` **Note:** The `BUCKET(@timestamp, 20, ?_tstart, ?_tend)` syntax creates ~20 buckets that automatically adapt to the dashboard time range. The `?_tstart` and `?_tend` parameters are auto-populated by Kibana. --- ## ESQL Metric Chart (`esql.type: metric`) Displays a single primary metric derived from an ESQL query, optionally with a secondary metric, a maximum value, and a breakdown dimension. The `field` names in the chart configuration **must** correspond to column names produced by the ESQL query. | YAML Key | Data Type | Description | Kibana Default | Required | | ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['metric']` | Specifies the chart type as an ESQL Metric visualization. | `metric` | Yes | | `id` | `string` | An optional unique identifier for this specific chart layer. | Generated ID | No | | `primary` | `ESQLMetric` object | The primary metric to display. Its `field` refers to an ESQL result column. See [ESQL Metric Column](#esql-metric-column). | N/A | Yes | | `secondary` | `ESQLMetric` object | An optional secondary metric. Its `field` refers to an ESQL result column. See [ESQL Metric Column](#esql-metric-column). | `None` | No | | `maximum` | `ESQLMetric` object | An optional maximum metric. Its `field` refers to an ESQL result column. See [ESQL Metric Column](#esql-metric-column). | `None` | No | | `breakdown` | `ESQLDimension` object | An optional dimension to break down the metric by. Its `field` refers to an ESQL result column. See [ESQL Dimension Column](#esql-dimension-column). | `None` | No | **Example (ESQL Metric Chart):** ```yaml dashboards: - name: "ESQL Metric Example" description: "Example of ESQL metric panel with primary, secondary, and breakdown" panels: - title: "Service Performance Metrics" size: {w: 24, h: 15} esql: type: metric query: | FROM logs-* | STATS avg_response_time = AVG(response.time), p95_response_time = PERCENTILE(response.time, 95.0) BY service_name primary: field: "avg_response_time" secondary: field: "p95_response_time" breakdown: field: "service_name" ``` --- ## ESQL Pie Chart (`esql.type: pie`) Visualizes proportions of categories using slices of a pie or a donut chart, with data sourced from an ESQL query. The `field` names in the chart configuration **must** correspond to column names produced by the ESQL query. | YAML Key | Data Type | Description | Kibana Default | Required | | ----------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['pie']` | Specifies the chart type as an ESQL Pie visualization. | `pie` | Yes | | `id` | `string` | An optional unique identifier for this specific chart layer. | Generated ID | No | | `metrics` | `ESQLMetric \| list[ESQLMetric]` object | A single metric or list of metrics that determine the size of each slice. Each `field` refers to an ESQL result column. See [ESQL Metric Column](#esql-metric-column). | N/A | Yes | | `breakdowns` | `list of ESQLDimension` objects | One or more breakdowns that determine how the pie is sliced. Each `field` refers to an ESQL result column. See [ESQL Dimension Column](#esql-dimension-column). | N/A | Yes | | `appearance` | `PieChartAppearance` object | Formatting options for the chart appearance. See [Pie Chart Appearance](#pie-chart-appearance-formatting-appearance-field) (shared with Lens). | `None` | No | | `legend` | `PieLegend` object | Formatting options for the chart legend. See [Pie Legend](#pie-legend-formatting-legend-field) (shared with Lens). | `None` | No | | `color` | `ColorValueMapping` object | Formatting options for the chart color palette. See [Color Mapping](#color-mapping-formatting-color-field) (shared with Lens). | `None` | No | **Example (ESQL Pie Chart):** ```yaml dashboards: - name: "ESQL Pie Chart Example" description: "Example of ESQL pie chart with donut appearance" panels: - title: "Error Types Distribution" size: {w: 24, h: 15} esql: type: pie query: | FROM logs-* | STATS error_count = COUNT(error.code) BY error_type | SORT error_count DESC | LIMIT 10 metrics: - field: "error_count" breakdowns: - field: "error_type" appearance: donut: "small" ``` --- ## ESQL Bar Chart (`esql.type: bar`) Displays bar chart visualizations with data sourced from an ESQL query. Supports stacked, unstacked, and percentage modes. The `field` names in the chart configuration **must** correspond to column names produced by the ESQL query. | YAML Key | Data Type | Description | Kibana Default | Required | | ----------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['bar']` | Specifies the chart type as an ESQL Bar visualization. | `bar` | Yes | | `id` | `string` | An optional unique identifier for this specific chart layer. | Generated ID | No | | `mode` | `Literal['stacked', 'unstacked', 'percentage']` | Stacking mode for bar charts. | `'stacked'` | No | | `dimension` | `ESQLDimension` object | A single dimension that determines the X-axis (0 or 1 dimension allowed). The `field` refers to an ESQL result column. See [ESQL Dimension Column](#esql-dimension-column). | `None` | No | | `metrics` | `list of ESQLMetric` objects | One or more metrics that determine the Y-axis values. Each `field` refers to an ESQL result column. See [ESQL Metric Column](#esql-metric-column). | N/A | Yes | | `breakdown` | `ESQLDimension` object | An optional dimension to split the series by. Its `field` refers to an ESQL result column. See [ESQL Dimension Column](#esql-dimension-column). | `None` | No | | `appearance` | `XYAppearance` object | Formatting options for chart appearance. See [XY Chart Appearance](#xy-chart-appearance-formatting-appearance-field). | `None` | No | | `legend` | `XYLegend` object | Formatting options for the chart legend. See [XY Legend](#xy-legend-formatting-legend-field). | `None` | No | | `color` | `ColorValueMapping` object | Formatting options for the chart color palette. See [Color Mapping](#color-mapping-formatting-color-field) (shared with other chart types). | `None` | No | **Example (ESQL Bar Chart):** ```yaml dashboards: - name: "ESQL Bar Chart Example" description: "Example of ESQL bar chart with stacked mode" panels: - title: "Events Over Time by Category" size: {w: 48, h: 20} esql: type: bar query: | FROM logs-* | STATS event_count = COUNT(*) BY timestamp_bucket = BUCKET(@timestamp, 20, ?_tstart, ?_tend), event.category | SORT timestamp_bucket ASC mode: stacked dimension: field: "timestamp_bucket" metrics: - field: "event_count" breakdown: field: "event.category" ``` --- ## ESQL Line Chart (`esql.type: line`) Displays line chart visualizations with data sourced from an ESQL query. The `field` names in the chart configuration **must** correspond to column names produced by the ESQL query. | YAML Key | Data Type | Description | Kibana Default | Required | | ------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['line']` | Specifies the chart type as an ESQL Line visualization. | `line` | Yes | | `id` | `string` | An optional unique identifier for this specific chart layer. | Generated ID | No | | `dimension` | `ESQLDimension` object | A single dimension that determines the X-axis (0 or 1 dimension allowed). The `field` refers to an ESQL result column. See [ESQL Dimension Column](#esql-dimension-column). | `None` | No | | `metrics` | `list of ESQLMetric` objects | One or more metrics that determine the Y-axis values. Each `field` refers to an ESQL result column. See [ESQL Metric Column](#esql-metric-column). | N/A | Yes | | `breakdown` | `ESQLDimension` object | An optional dimension to split the series by. Its `field` refers to an ESQL result column. See [ESQL Dimension Column](#esql-dimension-column). | `None` | No | | `appearance` | `XYAppearance` object | Formatting options for chart appearance. See [XY Chart Appearance](#xy-chart-appearance-formatting-appearance-field). | `None` | No | | `legend` | `XYLegend` object | Formatting options for the chart legend. See [XY Legend](#xy-legend-formatting-legend-field). | `None` | No | | `color` | `ColorValueMapping` object | Formatting options for the chart color palette. See [Color Mapping](#color-mapping-formatting-color-field) (shared with other chart types). | `None` | No | **Example (ESQL Line Chart):** ```yaml dashboards: - name: "ESQL Line Chart Example" description: "Example of ESQL line chart with breakdown" panels: - title: "Average Response Time by Service" size: {w: 48, h: 20} esql: type: line query: | FROM logs-* | STATS avg_response_time = AVG(response.time) BY timestamp_bucket = BUCKET(@timestamp, 20, ?_tstart, ?_tend), service.name | SORT timestamp_bucket ASC dimension: field: "timestamp_bucket" metrics: - field: "avg_response_time" breakdown: field: "service.name" ``` --- ## ESQL Area Chart (`esql.type: area`) Displays area chart visualizations with data sourced from an ESQL query. Supports stacked, unstacked, and percentage modes. The `field` names in the chart configuration **must** correspond to column names produced by the ESQL query. | YAML Key | Data Type | Description | Kibana Default | Required | | ----------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['area']` | Specifies the chart type as an ESQL Area visualization. | `area` | Yes | | `id` | `string` | An optional unique identifier for this specific chart layer. | Generated ID | No | | `mode` | `Literal['stacked', 'unstacked', 'percentage']` | Stacking mode for area charts. | `'stacked'` | No | | `dimension` | `ESQLDimension` object | A single dimension that determines the X-axis (0 or 1 dimension allowed). The `field` refers to an ESQL result column. See [ESQL Dimension Column](#esql-dimension-column). | `None` | No | | `metrics` | `list of ESQLMetric` objects | One or more metrics that determine the Y-axis values. Each `field` refers to an ESQL result column. See [ESQL Metric Column](#esql-metric-column). | N/A | Yes | | `breakdown` | `ESQLDimension` object | An optional dimension to split the series by. Its `field` refers to an ESQL result column. See [ESQL Dimension Column](#esql-dimension-column). | `None` | No | | `appearance` | `XYAppearance` object | Formatting options for chart appearance. See [XY Chart Appearance](#xy-chart-appearance-formatting-appearance-field). | `None` | No | | `legend` | `XYLegend` object | Formatting options for the chart legend. See [XY Legend](#xy-legend-formatting-legend-field). | `None` | No | | `color` | `ColorValueMapping` object | Formatting options for the chart color palette. See [Color Mapping](#color-mapping-formatting-color-field) (shared with other chart types). | `None` | No | **Example (ESQL Area Chart):** ```yaml dashboards: - name: "ESQL Area Chart Example" description: "Example of ESQL area chart with stacked mode" panels: - title: "Total Bytes by Host" size: {w: 48, h: 20} esql: type: area query: | FROM logs-* | STATS bytes_total = SUM(bytes) BY timestamp_bucket = BUCKET(@timestamp, 20, ?_tstart, ?_tend), host.name | SORT timestamp_bucket ASC mode: stacked dimension: field: "timestamp_bucket" metrics: - field: "bytes_total" breakdown: field: "host.name" ``` --- ## ESQL Columns For ESQL panels, the `primary`, `secondary`, `maximum` (in metric charts) and `metrics`, `breakdowns` (in pie charts) fields refer to columns that **must be present in the output of your ESQL query**. !!! note "Static values in ES|QL charts" ES|QL chart metric fields must reference query result columns. If you need a constant value (for example, a gauge goal), add it in the query with `EVAL`, then reference that field in your chart config. Example: ```yaml esql: type: gauge query: | FROM metrics-* | STATS avg_cpu = AVG(system.cpu.total.pct) | EVAL goal_cpu = 80 metric: field: "avg_cpu" goal: field: "goal_cpu" ``` ### ESQL Metric Column Used to specify a metric column from your ESQL query result. | YAML Key | Data Type | Description | Kibana Default | Required | | -------- | --------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `id` | `string` | An optional unique identifier for this metric column definition. | Generated ID | No | | `field` | `string` | The name of the column in your ESQL query result that represents the metric value. | N/A | Yes | | `label` | `string` | An optional display label for the metric. | `None` | No | | `format` | `ESQLMetricFormat` object | Optional format configuration for the metric. See [ESQL Metric Format](#esql-metric-format). | `None` | No | #### ESQL Metric Format Configure how metric values are displayed (number format, suffix, decimal places, etc.). **Standard Format Types:** | YAML Key | Data Type | Description | Kibana Default | Required | | -------- | --------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['number', 'bytes', 'bits', 'percent', 'duration']` | The format type for the metric. | N/A | Yes | | `decimals` | `integer` | Number of decimal places to display. If not specified, defaults to 2 for number/bytes/percent/duration, 0 for bits. | Type-dependent | No | | `suffix` | `string` | Optional suffix to display after the number (e.g., 'KB', 'ms'). | `None` | No | | `compact` | `boolean` | Whether to display the number in a compact format (e.g., '1.2K' instead of '1200'). | `None` | No | | `pattern` | `string` | Optional Numeral.js pattern for custom formatting. Controls decimal places, thousands separators, and more (e.g., '0,0.00' for 2 decimals with comma separator, '0.0000' for 4 decimals). Note: `decimals` provides a simpler way to control decimal places without a pattern. | `None` | No | **Custom Format Type:** For completely custom number formatting, use: | YAML Key | Data Type | Description | Kibana Default | Required | | -------- | --------- | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `type` | `Literal['custom']` | Indicates a custom format pattern. | `'custom'` | Yes | | `pattern` | `string` | Numeral.js pattern for custom formatting (e.g., '0,0.[0000]', '0.00%'). | N/A | Yes | **Example (Metric with Format):** ```yaml dashboards: - name: "ESQL Metric Formatting Example" description: "Example showing various metric formatting options" panels: - title: "Formatted Metrics" size: {w: 48, h: 20} esql: type: bar query: | FROM logs-* | STATS total_bytes = SUM(bytes), event_count = COUNT(*), avg_response_time = AVG(response.time), success_rate = COUNT(status == 200) / COUNT(*) * 100, precise_value = AVG(bytes) BY timestamp_bucket = BUCKET(@timestamp, 20, ?_tstart, ?_tend) | SORT timestamp_bucket ASC dimension: field: "timestamp_bucket" metrics: - field: "total_bytes" label: "Total Data" format: type: bytes decimals: 1 - field: "event_count" label: "Events" format: type: number decimals: 0 - field: "avg_response_time" label: "Avg Response Time" format: type: number decimals: 2 suffix: "ms" - field: "success_rate" label: "Success Rate" format: type: percent decimals: 1 - field: "precise_value" label: "Precise Value" format: type: number pattern: "0,0.0000" ``` ### ESQL Dimension Column Used to specify a dimension/grouping column from your ESQL query result. | YAML Key | Data Type | Description | Kibana Default | Required | | ---------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `id` | `string` | An optional unique identifier for this dimension column definition. | Generated ID | No | | `field` | `string` | The name of the column in your ESQL query result that represents the dimension. | N/A | Yes | | `label` | `string` | An optional display label for the dimension. If not provided, the field name is used. | `None` | No | | `data_type` | `Literal['date'] \| None` | The data type of the field. Set to `'date'` for time/date fields to enable proper sorting and formatting in Kibana. This is particularly useful when using `BUCKET()` to create time series. | `None` | No | When used as a `breakdown` field (on XY, metric, mosaic, or waffle charts), the dimension also supports: | YAML Key | Data Type | Description | Kibana Default | Required | | ---------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `collapse` | `CollapseAggregationEnum \| None` | The collapse function to apply to this breakdown (`sum`, `avg`, `min`, `max`). Used to aggregate values when multiple series exist. Only valid on breakdown fields, not plain dimensions. | `None` | No | **Example using label and data_type for time series:** ```yaml dashboards: - name: "Time Series with BUCKET Example" panels: - title: "Events Over Time (Adaptive Buckets)" size: {w: 48, h: 20} esql: type: bar query: | FROM logs-* | STATS event_count = COUNT(*) BY time_bucket = BUCKET(@timestamp, 20, ?_tstart, ?_tend) | SORT time_bucket ASC dimension: field: "time_bucket" label: "Time" # Friendly display name instead of 'time_bucket' data_type: "date" # Tells Kibana this is a date field for proper formatting metrics: - field: "event_count" ``` **When to use data_type: date:** Use `data_type: 'date'` when your dimension field contains date/time values, especially when using ES|QL's `BUCKET()` function to create time series. This ensures: - Proper date formatting in tooltips and axis labels - Correct chronological sorting - Time-based zoom and pan interactions - Dashboard time picker integration (via `time_field`) --- ## Pie Chart Specific Formatting (Shared with Lens) ESQL Pie Charts share the same formatting options for appearance, titles/text, legend, and colors as Lens Pie Charts. ### Pie Chart Appearance Formatting (`appearance` field) | YAML Key | Data Type | Description | Kibana Default | Required | | -------- | ------------------------------------- | ------------------------------------------------ | ---------------- | -------- | | `donut` | `Literal['small', 'medium', 'large']` | If set, creates a donut chart with the specified hole size. If not specified, Kibana displays as a pie chart (no donut hole). | `None` | No | ### Pie Labels and Values Formatting (`appearance.categories` and `appearance.values`) | YAML Key | Data Type | Description | Kibana Default | Required | | ---------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `appearance.categories.position` | `Literal['hide', 'inside', 'auto']` | How to display labels for each slice. | `None` | No | | `appearance.values.format` | `Literal['hide', 'integer', 'percent']` | How to display the value for each slice. | `None` | No | | `appearance.values.decimal_places` | `integer` (0-10) | Number of decimal places for slice values. | `None` | No | `titles_and_text` is not accepted in `0.4.0`; use `appearance.categories` and `appearance.values` fields instead (or run `kb-dashboard upgrade`). ### Pie Legend Formatting (`legend` field) | YAML Key | Data Type | Description | Kibana Default | Required | | ------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- | -------- | | `visible` | `Literal['show', 'hide', 'auto']` | Controls legend visibility. | `None` | No | | `width` | `Literal['small', 'medium', 'large', 'extra_large']` | Width of the legend area. | `None` | No | | `truncate_labels` | `integer` (0-5) | Max number of lines for legend labels before truncating. `0` disables truncation. | `None` | No | ### Color Mapping Formatting (`color` field) See [ColorValueMapping](base.md#colorvaluemapping-object) for full details on color customization options. | YAML Key | Data Type | Description | Kibana Default | Required | | ------------- | -------------------------- | ------------------------------------------------ | -------------------------------- | -------- | | `palette` | `string` | The ID of the color palette to use (e.g., `eui_amsterdam_color_blind`, `elastic_brand`). | `eui_amsterdam_color_blind` | No | | `assignments` | `list[ColorValueAssignment]` | Manual color assignments to specific data values. See [ColorValueAssignment](base.md#colorvalueassignment-object). | `[]` | No | --- ## XY Chart Specific Formatting (Shared with Lens) ESQL XY Charts (bar, line, area) share the same formatting options for appearance and legend as Lens XY Charts. ### XY Chart Appearance Formatting (`appearance` field) | YAML Key | Data Type | Description | Kibana Default | Required | | ------------- | ------------------------ | -------------------------------------------------------- | ------- | -------- | | `x_axis` | `AxisConfig \| None` | Configuration for the X-axis (horizontal axis). | `None` | No | | `y_left_axis` | `AxisConfig \| None` | Configuration for the left Y-axis (primary vertical axis). | `None` | No | | `y_right_axis` | `AxisConfig \| None` | Configuration for the right Y-axis (secondary vertical axis). | `None` | No | | `series` | `list[XYSeries] \| None` | Per-series visual configuration (axis assignment, colors). | `None` | No | #### AxisConfig Options | YAML Key | Data Type | Description | Kibana Default | Required | | -------- | ------------------------------------------------ | ---------------------------------------------- | ------- | -------- | | `title` | `str \| None` | Custom title for the axis. | `None` | No | | `scale` | `Literal['linear', 'log', 'sqrt', 'time'] \| None` | Scale type for the axis. | `None` | No | | `extent` | `AxisExtent \| None` | Axis bounds/range configuration. | `None` | No | #### AxisExtent Options | YAML Key | Data Type | Description | Kibana Default | Required | | ------------- | -------------------------------------------- | --------------------------------------------------------- | ------- | -------- | | `mode` | `Literal['full', 'data_bounds', 'custom']` | Extent mode: 'full' (entire range), 'data_bounds' (fit to data), 'custom' (manual bounds). | N/A | Yes | | `min` | `float \| None` | Minimum bound (required when mode is 'custom'). | `None` | Conditional | | `max` | `float \| None` | Maximum bound (required when mode is 'custom'). | `None` | Conditional | | `enforce` | `bool \| None` | Whether to enforce the bounds strictly. | `None` | No | | `nice_values` | `bool \| None` | Whether to round bounds to nice values. | `None` | No | #### XYSeries Options | YAML Key | Data Type | Description | Kibana Default | Required | | ----------- | ------------------------------------------------- | ------------------------------------------------------------ | ------- | -------- | | `metric_id` | `str` | ID of the metric this series configuration applies to. | N/A | Yes | | `axis` | `Literal['left', 'right'] \| None` | Which Y-axis this series is assigned to (for dual-axis charts). | `None` | No | | `color` | `str \| None` | Hex color code for the series (e.g., '#2196F3'). | `None` | No | ### XY Legend Formatting (`legend` field) | YAML Key | Data Type | Description | Kibana Default | Required | | ---------- | -------------------------------------------------------- | ------------------------------------------------- | ------- | -------- | | `visible` | `bool \| None` | Whether the legend is visible. | `None` | No | | `position` | `Literal['top', 'bottom', 'left', 'right'] \| None` | Position of the legend (Kibana defaults to 'right'). | `None` | No | --- ## Related Documentation - [Base Panel Configuration](base.md) - [Dashboard Configuration](../dashboard/dashboard.md) - [Queries Configuration](../queries/config.md#esql-query) - Elasticsearch ESQL Reference (external) --- # Source: panels/datatable.md --- # Datatable Chart Panel Configuration The Datatable chart panel displays tabular data with customizable columns, sorting, pagination, and formatting options. Perfect for displaying detailed records and performing quick data analysis. --- ## Lens Datatable Charts **kb_dashboard_core.panels.charts.datatable.config.LensDatatableChart** Represents a Datatable chart configuration within a Lens panel. Datatable charts display tabular data with customizable columns, sorting, pagination, and formatting options. Examples: Simple datatable with metrics and breakdowns: ```yaml lens: type: datatable data_view: "metrics-*" metrics: - id: "service-count" field: "service.name" aggregation: count breakdowns: - id: "service-breakdown" type: values field: "service.name" ``` Datatable with sorting and pagination: ```yaml lens: type: datatable data_view: "logs-*" metrics: - id: "error-count" aggregation: count filter: kql: "log.level:error" breakdowns: - id: "service" type: values field: "service.name" sorting: column_id: "error-count" direction: desc paging: enabled: true page_size: 25 ``` Fields: - `type` (`Literal['datatable']`): The type of chart, which is 'datatable' for this visualization. - `appearance` (`kb_dashboard_core.panels.charts.datatable.config.DatatableAppearance | None`): Appearance settings for the datatable. - `sorting` (`kb_dashboard_core.panels.charts.datatable.config.DatatableSortingConfig | None`): Optional sorting configuration. - `paging` (`kb_dashboard_core.panels.charts.datatable.config.DatatablePagingConfig | None`): Optional pagination configuration. - `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically. - `data_view` (``): The data view that determines the data for the datatable chart. - `metrics` (`list[LensDatatableMetricTypes | LensDataMetricTypes]`): List of metrics to display as columns. - `breakdowns` (`list[LensDatatableBreakdownTypes | LensBreakdownTypes]`): List of breakdowns to use as row groupings. - `metrics_split_by` (`list[LensDatatableDimensionTypes | LensDimensionTypes] | None`): Optional split-metrics-by dimensions (creates separate metric columns for each dimension value). --- # Source: panels/gauge.md --- # Gauge Chart Panel Configuration The Gauge chart panel displays a single metric value with optional min/max ranges and goal indicators, typically used for KPIs and progress tracking toward targets or thresholds. --- ## Lens Gauge Charts **kb_dashboard_core.panels.charts.gauge.config.LensGaugeChart** Represents a Gauge chart configuration within a Lens panel. Gauge charts display a single metric value with optional min/max ranges and goal indicators, typically used to show progress toward a target or threshold. Examples: Minimal gauge with static values: ```yaml lens: type: gauge data_view: "metrics-*" metric: aggregation: average field: system.cpu.total.pct minimum: 0 maximum: 100 goal: 80 ``` Gauge with custom appearance and color: ```yaml lens: type: gauge data_view: "logs-*" metric: aggregation: average field: response_time_ms minimum: 0 maximum: 1000 goal: 500 color: range_type: percent thresholds: - up_to: 0 color: "#00BF6F" - up_to: 80 color: "#FFA500" appearance: shape: arc ``` Fields: - `type` (`Literal['gauge']`): The type of chart, which is 'gauge' for this visualization. - `color` (`kb_dashboard_core.panels.charts.base.config.ColorRangeMapping | None`): Range-based palette configuration for gauge thresholds. When set, enables palette color mode. - `appearance` (`kb_dashboard_core.panels.charts.gauge.config.GaugeAppearance | None`): Visual appearance configuration for the gauge. - `titles_and_text` (`kb_dashboard_core.panels.charts.gauge.config.GaugeTitlesAndText | None`): Title and subtitle options mapped to gauge `label_major` and `label_minor`. - `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically. - `data_view` (``): The data view that determines the data for the gauge chart. - `metric` (`LensDataMetricTypes`): The primary metric to display in the gauge. This is the main value shown. - `minimum` (`LensMetricTypes | int | float | None`): An optional minimum value for the gauge range. Can be a metric (field-based) or a static numeric value. - `maximum` (`LensMetricTypes | int | float | None`): An optional maximum value for the gauge range. Can be a metric (field-based) or a static numeric value. - `goal` (`LensMetricTypes | int | float | None`): An optional goal/target value to display as a reference. Can be a metric (field-based) or a static numeric value. --- # Source: panels/heatmap.md --- # Heatmap Chart Panel Configuration The Heatmap chart panel displays data as a matrix where cell colors represent metric values, typically used for visualizing patterns across two categorical dimensions or time-based intensity analysis. --- ## Minimal Configuration Example ```yaml dashboards: - name: "Server Activity Dashboard" panels: - title: "Activity by Hour and Day" size: {w: 24, h: 15} lens: type: heatmap data_view: "logs-*" x_axis: field: "@timestamp" type: date_histogram label: "Hour of Day" y_axis: field: "host.name" type: values label: "Server" metric: aggregation: count label: "Request Count" ``` ## Grid and Legend Configuration Example Customize the appearance of your heatmap with grid and legend options: ```yaml dashboards: - name: "Customized Heatmap" panels: - title: "Response Time Heatmap" size: {w: 24, h: 15} lens: type: heatmap data_view: "logs-*" x_axis: field: "@timestamp" type: date_histogram y_axis: field: "service.name" type: values metric: aggregation: average field: "response.time" format: type: duration appearance: values: visible: true x_axis: labels: visible: true title: visible: true y_axis: labels: visible: true title: visible: true legend: visible: show position: right ``` ## One-Dimensional Heatmap Example Create a 1D heatmap by omitting the Y-axis: ```yaml dashboards: - name: "Hourly Traffic Pattern" panels: - title: "Traffic Intensity by Hour" size: {w: 48, h: 8} lens: type: heatmap data_view: "logs-*" x_axis: field: "@timestamp" type: date_histogram label: "Hour" metric: aggregation: count label: "Events" ``` ## Appearance Visibility Defaults When visibility fields are omitted under `appearance`, the compiler applies Kibana-aligned defaults: | Field | Default when omitted | | ----- | -------------------- | | `appearance.values.visible` | `false` (cell labels hidden) | | `appearance.x_axis.labels.visible` | `true` | | `appearance.x_axis.title.visible` | `true` | | `appearance.y_axis.labels.visible` | `true` | | `appearance.y_axis.title.visible` | `true` | Set these fields explicitly to override the defaults. ## Lens Heatmap Chart **kb_dashboard_core.panels.charts.heatmap.config.LensHeatmapChart** Represents a Heatmap chart configuration within a Lens panel. Heatmap charts display data as a matrix where cell colors represent metric values, typically used for visualizing patterns across two categorical dimensions. Fields: - `type` (`Literal['heatmap']`): The type of chart, which is 'heatmap' for this visualization. - `appearance` (`kb_dashboard_core.panels.charts.heatmap.config.HeatmapAppearance | None`): Formatting options for the chart appearance. - `color` (`kb_dashboard_core.panels.charts.base.config.ColorRangeMapping | None`): Optional range-based palette configuration for heatmap cell coloring. - `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically. - `data_view` (``): The data view that determines the data for the heatmap chart. - `x_axis` (`LensDimensionTypes`): The dimension to display on the X-axis (horizontal). - `y_axis` (`LensDimensionTypes | None`): The dimension to display on the Y-axis (vertical). Optional for 1D heatmaps. - `metric` (`LensDataMetricTypes`): The metric that determines cell color intensity. --- # Source: panels/metric.md --- # Metric Chart Panel Configuration The Metric chart panel displays a single value or a small set of key metrics, often used for KPIs or summary statistics. --- ## Minimal Configuration Example ```yaml dashboards: - name: "KPI Dashboard" panels: - title: "Total Hosts" size: {w: 12, h: 2} lens: type: metric data_view: "metrics-*" primary: aggregation: unique_count field: resource.attributes.host.name ``` ## Formula Metric Example Formula metrics allow you to create custom calculations using Kibana's formula syntax: ```yaml dashboards: - name: "Error Monitoring" panels: - title: "Error Rate" size: {w: 12, h: 2} lens: type: metric data_view: "logs-*" primary: formula: "count(kql='status:error') / count() * 100" label: "Error Rate %" format: type: percent ``` ## Full Configuration Options ### Lens Metric Chart | YAML Key | Data Type | Description | Default | Required | | ----------- | -------------------------------- | ------------------------------------------------------------- | ---------- | -------- | | `type` | `Literal['metric']` | Specifies the chart type as metric. | `'metric'` | No | | `data_view` | `string` | The data view that determines the data for the metric chart. | N/A | Yes | | `primary` | `LensMetricTypes` | The primary metric to display (main value). | N/A | Yes | | `secondary` | `LensMetricTypes \| None` | Optional secondary metric to display alongside the primary. | `None` | No | | `maximum` | `LensMetricTypes \| None` | Optional maximum metric for comparison or progress bar scale. | `None` | No | | `breakdown` | `LensDimensionTypes \| None` | Optional breakdown dimension for splitting the metric. | `None` | No | | `appearance` | `MetricAppearance \| None` | Visual appearance configuration. See [Metric Appearance](#metric-appearance). | `None` | No | | `titles_and_text` | `MetricTitlesAndText \| None` | Titles and text formatting options. See [Metric Titles and Text](#metric-titles-and-text). | `None` | No | Color thresholds and `apply_to` are configured on the primary metric's `color` field (e.g., `primary.color.thresholds`, `primary.color.apply_to`). Legacy chart-level `color` and `apply_to` are not accepted in `0.4.0`; run `kb-dashboard upgrade` to migrate old files. #### Metric Appearance | YAML Key | Data Type | Description | Default | Required | | ----------- | -------------------------------- | ------------------------------------------------------------- | ---------- | -------- | | `primary.icon` | `string \| None` | Icon identifier to display alongside the primary metric value. | `None` | No | | `primary.icon_position` | `Literal['left', 'right'] \| None` | Horizontal alignment of the icon relative to the primary metric value. | `None` | No | | `primary.background_chart.type` | `Literal['line', 'bar', 'none'] \| None` | Background chart mode for the primary metric. | `None` | No | | `primary.background_chart.direction` | `Literal['horizontal', 'vertical'] \| None` | Direction for bar background charts. Only valid when type is `bar`. | `None` | No | | `primary.font_size` | `Literal['default', 'fit', 'custom'] \| None` | Font size mode for the primary metric value. | `None` | No | | `primary.position` | `Literal['top', 'bottom'] \| None` | Vertical position of the primary metric value within the panel. | `None` | No | | `primary.alignment` | `Literal['left', 'center', 'right'] \| None` | Text alignment for the primary metric value. | `None` | No | | `secondary.alignment` | `Literal['left', 'center', 'right'] \| None` | Text alignment for the secondary metric value. | `None` | No | | `secondary.label.text` | `string \| None` | Custom label text for the secondary metric. | `None` | No | | `secondary.label.position` | `Literal['before', 'after'] \| None` | Position of the secondary label relative to the value. | `None` | No | | `breakdown.column_count` | `int \| None` | Maximum number of columns when displaying broken-down metrics. Minimum value is `1`. | `None` | No | #### Metric Titles and Text | YAML Key | Data Type | Description | Default | Required | | ----------- | -------------------------------- | ------------------------------------------------------------- | ---------- | -------- | | `subtitle` | `string \| None` | Custom subtitle text displayed below the metric title. | `None` | No | | `alignment` | `Literal['left', 'center', 'right'] \| None` | Text alignment for the metric title and subtitle. | `None` | No | | `weight` | `Literal['bold', 'normal', 'lighter'] \| None` | Font weight for the metric title. | `None` | No | #### Lens Metric Types The `primary`, `secondary`, and `maximum` fields accept these metric configurations: | Metric Type | Description | Key Fields | Example Use Case | | ----------- | ----------- | ---------- | ---------------- | | **Count** | Count documents or unique values | `aggregation: 'count' \| 'unique_count'`, `field` (optional) | Count total requests or unique users | | **Sum** | Sum numeric field values | `aggregation: 'sum'`, `field` | Total revenue or bytes transferred | | **Aggregation** | Other aggregations (avg, min, max, median, etc.) | `aggregation`, `field` | Average response time or max CPU usage | | **Last Value** | Most recent value of a field | `aggregation: 'last_value'`, `field` | Latest status or most recent reading | | **Percentile** | Calculate percentile of values | `aggregation: 'percentile'`, `field`, `percentile` | 95th percentile latency | | **Percentile Rank** | Calculate rank of a value | `aggregation: 'percentile_rank'`, `field`, `rank` | What % of requests are faster than 500ms | | **Formula** | Custom calculation using Kibana formula syntax | `formula`, `label` (optional), `format` (optional) | `count(kql='status:error') / count() * 100` | | **Static Value** | Fixed numeric value | `value`, `label` (optional) | Target threshold or goal value | **Common Fields:** All metric types except Static Value support: - `label`: Custom display label - `format`: Number formatting (see [Format Configuration Options](#format-configuration-options) for details) - `filter`: KQL filter to apply before aggregation **Additional Field Details:** - **Count**: Optional `field` (for counting specific field values), optional `exclude_zeros` (exclude zero values from count) - **Sum**: Required `field`, optional `exclude_zeros` (exclude zero values from sum) - **Last Value**: Required `field`, optional `date_field` (determines sort order for finding the most recent value) **Examples:** ```yaml # Count metric primary: aggregation: count label: "Total Requests" # Average metric primary: aggregation: average field: response_time_ms label: "Avg Response Time" format: type: duration # Formula metric primary: formula: "count(kql='status:error') / count() * 100" label: "Error Rate %" format: type: percent ``` ### ESQL Metric Chart | YAML Key | Data Type | Description | Default | Required | | ----------- | -------------------------------- | ------------------------------------------------------------- | ---------- | -------- | | `type` | `Literal['metric']` | Specifies the chart type as metric. | `'metric'` | No | | `primary` | `ESQLMetricTypes` | The primary metric to display (main value). | N/A | Yes | | `secondary` | `ESQLMetricTypes \| None` | Optional secondary metric to display alongside the primary. | `None` | No | | `maximum` | `ESQLMetricTypes \| None` | Optional maximum metric for comparison or progress bar scale. | `None` | No | | `breakdown` | `ESQLDimensionTypes \| None` | Optional breakdown dimension for splitting the metric. | `None` | No | | `appearance` | `MetricAppearance \| None` | Visual appearance configuration. See [Metric Appearance](#metric-appearance). | `None` | No | | `titles_and_text` | `MetricTitlesAndText \| None` | Titles and text formatting options. See [Metric Titles and Text](#metric-titles-and-text). | `None` | No | Color thresholds and `apply_to` are configured on the primary metric's `color` field (e.g., `primary.color.thresholds`, `primary.color.apply_to`). Legacy chart-level `color` and `apply_to` are not accepted in `0.4.0`; run `kb-dashboard upgrade` to migrate old files. #### ESQL Metric Types The `primary`, `secondary`, and `maximum` fields accept these metric configurations: | Metric Type | Description | Key Fields | Example Use Case | | ----------- | ----------- | ---------- | ---------------- | | **ESQL Metric** | Reference a column from your ESQL query result | `field` | Any aggregated value from STATS clause | | **Static Value** | Fixed numeric value | `value`, `label` (optional) | Target threshold or goal value | **ESQL metrics** reference columns produced by your ESQL query. The `field` must match a column name in your query result. **Example:** ```yaml # ESQL metric referencing query result column esql: type: metric query: | FROM logs-* | STATS total_requests = COUNT(*), avg_duration = AVG(event.duration), error_rate = COUNT(kql='event.outcome:failure') / COUNT(*) * 100 primary: field: "total_requests" # References column from STATS secondary: field: "avg_duration" # References column from STATS maximum: field: "error_rate" # References column from STATS ``` The ESQL query determines what metrics are available - each column in your STATS clause becomes a metric you can reference. ## Color Mode Use `primary.color.apply_to` to control how metric colors are applied: - `value`: apply colors to metric value text - `background`: apply colors to metric background (default) ```yaml dashboards: - name: "Metric Color Modes" panels: - title: "Error Rate (Value Colors)" size: {w: 8, h: 4} lens: type: metric data_view: "logs-*" primary: formula: "count(kql='event.outcome:failure') / count() * 100" label: "Error Rate" color: apply_to: value format: type: percent - title: "Availability (Background Colors)" size: {w: 8, h: 4} position: {x: 8, y: 0} lens: type: metric data_view: "logs-*" primary: formula: "count(kql='event.outcome:success') / count() * 100" label: "Availability" color: apply_to: background format: type: percent ``` ## Styling Options Metric panels support a variety of styling options to control layout, alignment, and typography. ### Subtitle and Secondary Label Add contextual information with custom subtitles and secondary metric labels: ```yaml dashboards: - name: "Styled Metrics" panels: - title: "CPU Usage" size: {w: 12, h: 4} lens: type: metric data_view: "metrics-*" appearance: secondary: label: text: "vs. previous day" position: after titles_and_text: subtitle: "Last 24 hours" primary: aggregation: average field: system.cpu.total.norm.pct format: type: percent secondary: aggregation: average field: system.cpu.total.norm.pct filter: kql: "@timestamp < now-1d" ``` ### Progress Bar Display a progress bar below the metric value to show progress toward a maximum: ```yaml dashboards: - name: "Progress Metrics" panels: - title: "Disk Usage" size: {w: 12, h: 4} lens: type: metric data_view: "metrics-*" appearance: primary: background_chart: type: bar direction: horizontal primary: aggregation: average field: system.filesystem.used.pct format: type: percent maximum: value: 1 ``` ### Icon Add an icon alongside the metric value: ```yaml dashboards: - name: "Icon Metrics" panels: - title: "Uptrend Indicator" size: {w: 12, h: 4} lens: type: metric data_view: "metrics-*" appearance: primary: icon: sortUp icon_position: right primary: aggregation: count ``` ### Text Alignment and Typography Control alignment and font properties for different parts of the metric: ```yaml dashboards: - name: "Aligned Metrics" panels: - title: "Centered KPI" size: {w: 12, h: 4} lens: type: metric data_view: "metrics-*" appearance: primary: font_size: fit position: top alignment: center secondary: alignment: center titles_and_text: alignment: center weight: bold primary: aggregation: count label: "Total Events" ``` ### Breakdown Columns Control the number of columns when using breakdown dimensions: ```yaml dashboards: - name: "Multi-Column Metrics" panels: - title: "Events by Host" size: {w: 24, h: 8} lens: type: metric data_view: "metrics-*" appearance: breakdown: column_count: 4 primary: aggregation: count breakdown: type: values field: host.name ``` ## Programmatic Usage (Python) You can create Metric chart panels programmatically using Python: ### Count Metric Example ```python from kb_dashboard_core.panels.charts.config import ( LensMetricPanelConfig, LensPanel, ) from kb_dashboard_core.panels.charts.metric.metrics import ( MetricLensCountAggregatedMetric, ) from kb_dashboard_core.panels.config import Position, Size panel = LensPanel( title='Total Documents', position=Position(x=0, y=0), size=Size(w=24, h=15), lens=LensMetricPanelConfig( type='metric', data_view='logs-*', primary=MetricLensCountAggregatedMetric(), ), ) ``` ### Average Metric Example ```python from kb_dashboard_core.panels.charts.config import ( LensMetricPanelConfig, LensPanel, ) from kb_dashboard_core.panels.charts.metric.metrics import ( MetricLensOtherAggregatedMetric, ) from kb_dashboard_core.panels.config import Position, Size panel = LensPanel( title='Avg Response Time', position=Position(x=0, y=0), size=Size(w=24, h=15), lens=LensMetricPanelConfig( type='metric', data_view='logs-*', primary=MetricLensOtherAggregatedMetric( aggregation='average', field='response_time' ), ), ) ``` ### Formula Metric Example ```python from kb_dashboard_core.panels.charts.config import ( LensMetricPanelConfig, LensPanel, ) from kb_dashboard_core.panels.charts.lens.metrics.config import LensMetricFormat from kb_dashboard_core.panels.charts.metric.metrics import MetricLensFormulaMetric from kb_dashboard_core.panels.config import Position, Size panel = LensPanel( title='Error Rate', position=Position(x=0, y=0), size=Size(w=24, h=15), lens=LensMetricPanelConfig( type='metric', data_view='logs-*', primary=MetricLensFormulaMetric( formula="count(kql='status:error') / count() * 100", label='Error Rate %', format=LensMetricFormat(type='percent'), ), ), ) ``` ## Number Formatting Metric charts support various number formatting options to display values in a user-friendly way. You can add suffixes, use compact notation, or apply custom number patterns. ### Format Configuration Options The `format` field accepts an object with the following properties: | YAML Key | Data Type | Description | Default | Required | | -------- | --------- | ----------- | ------- | -------- | | `type` | `string` | Format type: `'number'`, `'bytes'`, `'bits'`, `'percent'`, `'duration'` | `'number'` | No | | `suffix` | `string` | Custom text appended to the formatted value | `''` | No | | `prefix` | `string` | Custom text prepended to the formatted value | `''` | No | | `compact` | `boolean` | Enable compact notation (e.g., 1.2K instead of 1200) | `false` | No | | `pattern` | `string` | Custom numeral.js format pattern (e.g., `'0,0.00'`) | `null` | No | ### Suffix Formatting Add custom text after metric values to provide context: ```yaml dashboards: - name: "Metrics with Suffixes" panels: - title: "Request Rate" size: {w: 12, h: 4} lens: type: metric data_view: "logs-*" primary: aggregation: count label: "Requests" format: type: number suffix: " req/sec" - title: "Active Users" size: {w: 12, h: 4} position: {x: 12, y: 0} lens: type: metric data_view: "logs-*" primary: aggregation: unique_count field: "user.id" label: "Users" format: type: number suffix: " users" ``` ### Compact Notation Use compact notation to display large numbers in a more readable format (e.g., 1.2K instead of 1200): ```yaml dashboards: - name: "Compact Metrics" panels: - title: "Total Events (Compact)" size: {w: 12, h: 4} lens: type: metric data_view: "logs-*" primary: aggregation: count label: "Events" format: type: number compact: true # Displays as 1.2M, 500K, etc. ``` ### Custom Number Patterns Apply custom formatting patterns using numeral.js syntax: ```yaml dashboards: - name: "Formatted Metrics" panels: - title: "Revenue (Currency)" size: {w: 12, h: 4} lens: type: metric data_view: "sales-*" primary: aggregation: sum field: "transaction.amount" label: "Total Revenue" format: type: custom pattern: "0,0.00" # Comma separators, 2 decimals - title: "Success Rate" size: {w: 12, h: 4} position: {x: 12, y: 0} lens: type: metric data_view: "logs-*" primary: formula: "count(kql='status:success') / count() * 100" label: "Success Rate" format: type: custom pattern: "0.0a" # 1 decimal + suffix (K, M, etc.) suffix: "%" ``` ### Combining Format Options You can combine multiple formatting options for maximum flexibility: ```yaml dashboards: - name: "Combined Formatting" panels: - title: "Bandwidth Usage" size: {w: 12, h: 4} lens: type: metric data_view: "network-*" primary: aggregation: sum field: "network.bytes" label: "Total Bandwidth" format: type: bytes # Built-in bytes format compact: true # Use compact notation (MB, GB) suffix: "/day" # Add custom suffix ``` For more examples of metric formatting, see [metric-formatting-examples.yaml](../examples/metric-formatting-examples.yaml). ## Related - [Base Panel Configuration](./base.md) - [Dashboard Configuration](../dashboard/dashboard.md) - [Metric Formatting Examples](../examples/metric-formatting-examples.yaml) --- # Source: panels/mosaic.md --- # Mosaic Chart Panel Configuration The Mosaic chart panel visualizes categorical data as proportional rectangles, showing category distributions at a glance. Mosaic charts support exactly one metric, one dimension, and an optional breakdown. --- ## Lens Mosaic Charts **kb_dashboard_core.panels.charts.mosaic.config.LensMosaicChart** Represents a Mosaic chart configuration within a Lens panel. Mosaic charts visualize categorical data as proportional rectangles, where each rectangle's area represents its proportion of the whole. Mosaic charts support exactly one metric, one dimension, and an optional breakdown. Examples: Simple mosaic chart showing request distribution: ```yaml lens: type: mosaic data_view: "logs-*" dimension: field: "http.request.method" type: values metric: aggregation: count ``` Mosaic chart with breakdown: ```yaml lens: type: mosaic data_view: "logs-*" dimension: field: "http.request.method" type: values breakdown: field: "service.name" type: values metric: aggregation: count ``` Mosaic chart with custom colors: ```yaml lens: type: mosaic data_view: "metrics-*" dimension: field: "service.name" type: values metric: aggregation: count color: palette: 'eui_amsterdam_color_blind' assignments: - values: ['api-gateway'] color: '#00BF6F' - values: ['database'] color: '#006BB4' ``` Mosaic chart with legend options: ```yaml lens: type: mosaic data_view: "logs-*" dimension: field: "http.request.method" type: values metric: aggregation: count legend: visible: show position: bottom ``` Fields: - `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically. - `type` (`Literal['mosaic']`) - `appearance` (`kb_dashboard_core.panels.charts.mosaic.config.MosaicAppearance | None`): Formatting options for the chart appearance. - `legend` (`kb_dashboard_core.panels.charts.mosaic.config.MosaicLegend | None`): Formatting options for the chart legend. - `color` (`kb_dashboard_core.panels.charts.base.config.ColorValueMapping | None`): Formatting options for the chart color. - `data_view` (``): The data view that determines the data for the mosaic chart. - `metric` (`LensDataMetricTypes`): Metric that determines the size of rectangles. Mosaic charts support only one metric. - `dimension` (`LensDimensionTypes`): Primary dimension for grouping data. Mosaic charts support only one dimension. - `breakdown` (`LensBreakdownTypes | None`): Optional secondary breakdown for splitting the mosaic into sub-groups. --- # Source: panels/pie.md --- # Pie Chart Panel Configuration The Pie chart panel visualizes data as a pie or donut chart, useful for showing proportions of a whole. --- ## Lens Pie Charts **kb_dashboard_core.panels.charts.pie.config.LensPieChart** Represents a Pie chart configuration within a Lens panel. Pie charts are used to visualize the proportion of categories. Examples: Simple pie chart showing traffic sources: ```yaml lens: type: pie data_view: "logs-*" breakdowns: - field: "source.geo.country_name" type: values metrics: - aggregation: count ``` Pie chart with custom colors: ```yaml lens: type: pie data_view: "metrics-*" breakdowns: - field: "resource.attributes.os.type" type: values metrics: - aggregation: unique_count field: resource.attributes.host.name color: palette: 'eui_amsterdam_color_blind' assignments: - values: ['linux'] color: '#00BF6F' - values: ['windows'] color: '#006BB4' ``` Fields: - `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically. - `type` (`Literal['pie']`) - `appearance` (`kb_dashboard_core.panels.charts.pie.config.PieChartAppearance | None`): Formatting options for the chart appearance, including donut size. - `legend` (`kb_dashboard_core.panels.charts.pie.config.PieLegend | None`): Formatting options for the chart legend. - `color` (`kb_dashboard_core.panels.charts.base.config.ColorValueMapping | None`): Formatting options for the chart color. - `data_view` (``): The data view that determines the data for the pie chart. - `metrics` (`list[LensDataMetricTypes]`): Metrics that determine the size of slices. - `breakdowns` (`list[LensBreakdownTypes]`): The breakdowns that determine the slices of the pie chart. First breakdown is primary, additional breakdowns are secondary. --- # Source: panels/tagcloud.md --- # Tag Cloud Chart Panel Configuration The Tag Cloud chart panel visualizes term frequency as a word cloud, where the size of each tag is proportional to its metric value. This is useful for showing the most common or significant terms in your data. --- ## Lens Tagcloud Charts **kb_dashboard_core.panels.charts.tagcloud.config.LensTagcloudChart** Represents a Tagcloud chart configuration within a Lens panel. Tagcloud charts are used to visualize term frequency as word/tag clouds. Examples: Minimal tagcloud: ```yaml dashboards: - name: "Log Analysis" panels: - title: "Top Error Messages" size: { w: 48, h: 6 } lens: type: tagcloud data_view: "logs-*" dimension: type: values field: "error.message" metric: aggregation: count ``` Advanced tagcloud with appearance customization: ```yaml dashboards: - name: "Advanced Tag Cloud" panels: - title: "Service Labels" size: { w: 48, h: 8 } lens: type: tagcloud data_view: "logs-*" dimension: type: values field: "service.name" metric: aggregation: count appearance: min_font_size: 12 max_font_size: 96 orientation: "multiple" labels: visible: false color: palette: "kibana_palette" ``` Fields: - `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically. - `type` (`Literal['tagcloud']`) - `appearance` (`kb_dashboard_core.panels.charts.tagcloud.config.TagcloudAppearance | None`): Formatting options for the chart appearance. - `color` (`kb_dashboard_core.panels.charts.base.config.ColorValueMapping | None`): Formatting options for the chart colors. - `data_view` (``): The data view that determines the data for the tagcloud chart. - `dimension` (`LensDimensionTypes`): The dimension for grouping (terms). This determines the tags shown in the cloud. - `metric` (`LensDataMetricTypes`): The metric for sizing. This determines the size of each tag. --- # Source: panels/treemap.md --- # Treemap Chart Panel Configuration The Treemap chart panel visualizes hierarchical data as nested rectangles, where each rectangle's size represents a metric value. Treemap charts support exactly one metric and require at least one breakdown (maximum two breakdowns). --- ## Lens Treemap Charts **kb_dashboard_core.panels.charts.treemap.config.LensTreemapChart** Represents a Treemap chart configuration within a Lens panel. Fields: - `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically. - `type` (`Literal['treemap']`): The type of chart, which is 'treemap' for this visualization. - `appearance` (`kb_dashboard_core.panels.charts.treemap.config.TreemapAppearance | None`): Formatting options for the chart appearance. - `legend` (`kb_dashboard_core.panels.charts.treemap.config.TreemapLegend | None`): Formatting options for the chart legend. - `color` (`kb_dashboard_core.panels.charts.base.config.ColorValueMapping | None`): Formatting options for the chart color. - `data_view` (``): The data view that determines the data for the treemap chart. - `metric` (`LensDataMetricTypes`): Metric that determines the rectangle sizes. Treemap supports only one metric. - `breakdowns` (`list[LensBreakdownTypes]`): Breakdowns that determine treemap grouping levels. Maximum 2 breakdowns supported. --- # Source: panels/waffle.md --- # Waffle Chart Panel Configuration The Waffle chart panel visualizes categorical data as a grid of colored squares, where each square represents a proportion of the whole. Waffle charts support exactly one metric and an optional breakdown. --- ## Lens Waffle Charts **kb_dashboard_core.panels.charts.waffle.config.LensWaffleChart** Represents a Waffle chart configuration within a Lens panel. Waffle charts visualize categorical data as a grid of colored squares, where each square represents a proportion of the whole. Waffle charts support exactly one metric and an optional breakdown. Examples: Simple waffle chart showing request distribution: ```yaml lens: type: waffle data_view: "logs-*" breakdown: field: "http.request.method" type: values metric: aggregation: count ``` Waffle chart with custom colors: ```yaml lens: type: waffle data_view: "metrics-*" breakdown: field: "service.name" type: values metric: aggregation: count color: palette: 'eui_amsterdam_color_blind' assignments: - values: ['api-gateway'] color: '#00BF6F' - values: ['database'] color: '#006BB4' ``` Waffle chart with legend options: ```yaml lens: type: waffle data_view: "logs-*" breakdown: field: "http.request.method" type: values metric: aggregation: count legend: visible: show position: bottom ``` Fields: - `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically. - `type` (`Literal['waffle']`) - `appearance` (`kb_dashboard_core.panels.charts.waffle.config.WaffleAppearance | None`): Formatting options for the chart appearance. - `legend` (`kb_dashboard_core.panels.charts.waffle.config.WaffleLegend | None`): Formatting options for the chart legend. - `color` (`kb_dashboard_core.panels.charts.base.config.ColorValueMapping | None`): Formatting options for the chart color. - `data_view` (``): The data view that determines the data for the waffle chart. - `metric` (`LensDataMetricTypes`): Metric that determines the size of squares. Waffle charts support only one metric. - `breakdown` (`LensBreakdownTypes | None`): Optional breakdown for grouping data. Waffle charts support only one breakdown. --- # Source: panels/xy.md --- # XY Chart Panel Configuration The XY chart panel creates line, bar, and area charts for time series and other data visualizations. --- ## Lens Bar Charts **kb_dashboard_core.panels.charts.xy.config.LensBarChart** Represents a Bar chart configuration within a Lens panel. Examples: Simple bar chart with time series: ```yaml lens: type: bar data_view: "logs-*" dimension: type: date_histogram field: "@timestamp" metrics: - aggregation: count ``` Stacked bar chart with breakdown: ```yaml lens: type: bar mode: stacked data_view: "logs-*" dimension: type: date_histogram field: "@timestamp" breakdown: type: values field: "service.name" metrics: - aggregation: count ``` Fields: - `data_view` (``): The data view to use for the chart. - `dimension` (`LensDimensionTypes | None`): Defines the X-axis dimension for the chart. XY charts support 0 or 1 dimension. - `metrics` (`list[LensXYMetricTypes]`): Defines the metrics for the chart. At least one metric is required. - `breakdown` (`LensBreakdownTypes | None`): An optional breakdown to split the series by. If provided, it will be used to break down the data into multiple series. - `id` (`str | None`): A unique identifier. If not provided, one will be generated automatically. - `legend` (`kb_dashboard_core.panels.charts.xy.config.XYLegend | None`): Formatting options for the chart legend. - `color` (`kb_dashboard_core.panels.charts.base.config.ColorValueMapping | None`): Formatting options for the chart color palette. - `type` (`Literal['bar']`): The type of XY chart to display. Defaults to 'bar'. - `appearance` (`kb_dashboard_core.panels.charts.xy.config.BarChartAppearance | None`): Formatting options for the chart appearance. - `mode` (`Literal['stacked', 'unstacked', 'percentage']`): The stacking mode for bar and area charts. Defaults to 'stacked'. --- # Source: panels/image.md --- # Image Panel Configuration The `image` panel type is used to display an image directly on your dashboard. This can be useful for branding, diagrams, or other visual elements. --- ## Image Panel **kb_dashboard_core.panels.images.config.ImagePanel** Represents an Image panel configuration. Image panels are used to display images. Examples: Minimal image panel: ```yaml dashboards: - name: "Branded Dashboard" panels: - title: "Company Logo" size: { w: 16, h: 3 } image: from_url: "https://example.com/path/to/your/logo.png" ``` Image panel with custom fit and background: ```yaml dashboards: - name: "Dashboard with Diagram" panels: - title: "System Architecture Diagram" size: { w: 48, h: 6 } image: from_url: "https://example.com/path/to/architecture.svg" fit: "contain" background_color: "#f0f0f0" ``` Fields: - `id` (`str | None`): A unique identifier for the panel. If not provided, one may be generated during compilation. - `title` (``): The title displayed on the panel header. Can be an empty string. - `hide_title` (`bool | None`): If `true`, the panel title will be hidden. Defaults to `false` (title is shown). - `description` (`str | None`): A brief description of the panel's content or purpose. Defaults to an empty string. - `size` (``): Defines the panel's size on the dashboard grid. - `position` (``): Defines the panel's position on the dashboard grid. If not specified, position will be auto-calculated. - `drilldowns` (`list[DrilldownTypes] | None`): Optional list of drilldowns to attach to this panel. - `image` (``): Image panel configuration. --- # Source: panels/search.md --- # Search Panel Configuration The `search` panel type is used to embed the results of a pre-existing, saved Kibana search directly onto your dashboard. This allows you to display dynamic log views, event lists, or any other data set defined by a saved search in Discover. --- ## Search Panel **kb_dashboard_core.panels.search.config.SearchPanel** Represents a Search panel configuration. Search panels are used to display the results of a saved Kibana search. Examples: Minimal search panel: ```yaml dashboards: - name: "Log Monitoring Dashboard" panels: - title: "All System Logs" size: { w: 48, h: 10 } search: saved_search_id: "a1b2c3d4-e5f6-7890-1234-567890abcdef" ``` Search panel with hidden title: ```yaml dashboards: - name: "Security Incidents Overview" panels: - hide_title: true description: "Critical security alerts from the last 24 hours" size: { w: 48, h: 8 } search: saved_search_id: "critical-security-alerts-saved-search" ``` Fields: - `id` (`str | None`): A unique identifier for the panel. If not provided, one may be generated during compilation. - `title` (``): The title displayed on the panel header. Can be an empty string. - `hide_title` (`bool | None`): If `true`, the panel title will be hidden. Defaults to `false` (title is shown). - `description` (`str | None`): A brief description of the panel's content or purpose. Defaults to an empty string. - `size` (``): Defines the panel's size on the dashboard grid. - `position` (``): Defines the panel's position on the dashboard grid. If not specified, position will be auto-calculated. - `drilldowns` (`list[DrilldownTypes] | None`): Optional list of drilldowns to attach to this panel. - `search` (``): Search panel configuration. --- # Source: controls/config.md --- # Controls Configuration Controls are interactive elements that can be added to a dashboard, allowing users to filter data or adjust visualization settings dynamically. They are defined as a list of control objects within each dashboard's `controls` field in the `dashboards:` array. Global behavior of controls can be managed via the `settings.controls` object. ## Minimal Configuration Examples Here's a minimal example of an `options` list control: ```yaml dashboards: - name: "Example Dashboard" controls: - type: options label: "Filter by OS Type" data_view: "metrics-*" field: "resource.attributes.os.type" ``` Here's a minimal example of a `range` slider control: ```yaml dashboards: - name: "Example Dashboard" controls: - type: range label: "CPU Load Average (1m)" data_view: "metrics-*" field: "metrics.system.cpu.load_average.1m" ``` ## Complex Configuration Example This example demonstrates multiple controls with custom widths and global control settings: ```yaml dashboards: - name: "Application Monitoring Dashboard" description: "Dashboard with interactive controls." settings: controls: label_position: "above" chain_controls: true click_to_apply: false controls: - type: options label: "Host Name" width: "medium" data_view: "metrics-*" field: "resource.attributes.host.name" multiple: true match_technique: "contains" - type: range label: "CPU Utilization" width: "large" data_view: "metrics-*" field: "metrics.system.cpu.utilization" step: 0.01 - type: time label: "Custom Time Slice" width: "small" start_offset: 0.1 # 10% from the start of the global time range end_offset: 0.9 # 90% from the start of the global time range ``` ## Full Configuration Options ### Control Settings (`settings.controls`) Global settings for all controls on the dashboard. These are configured under the `settings.controls` path in your main dashboard YAML. **kb_dashboard_core.controls.config.ControlSettings** Settings for controls in a dashboard, defining their behavior and appearance. Fields: - `label_position` (`Optional[Literal['inline', 'above']]`): The position of the control label, either 'inline' or 'above'. Defaults to 'inline' if not set. - `apply_global_filters` (`bool | None`): Whether to apply global filters to the control. Defaults to true if not set. - `apply_global_timerange` (`bool | None`): Whether to apply the global time range to the control. Defaults to true if not set. - `ignore_zero_results` (`bool | None`): Whether to ignore controls that return zero results. Defaults to true if not set. - `chain_controls` (`bool | None`): Whether to chain controls together, allowing one control's selection to filter the next. Defaults to true if not set. - `click_to_apply` (`bool | None`): Whether to require users to click the apply button before applying changes. Defaults to false if not set. --- # Source: filters/config.md --- # Filters Configuration Filters are used to narrow down the data displayed on a dashboard or within individual panels. They are defined as a list of filter objects, typically under the `filters` key of a `dashboard` object or a panel that supports filtering. ## Minimal Configuration Examples **Exists Filter:** Check if the `error.message` field exists. ```yaml filters: - exists: "error.message" ``` **Phrase Filter:** Find documents where `status.keyword` is exactly "active". ```yaml filters: - field: "status.keyword" equals: "active" ``` **Phrases Filter (using `in` alias):** Find documents where `event.category` is "authentication" OR "network". ```yaml filters: - field: "event.category" in: ["authentication", "network"] ``` **Range Filter:** Find documents where `response_time` is between 100 (inclusive) and 500 (exclusive). ```yaml filters: - field: "response_time" gte: "100" # Values are typically strings, Kibana handles conversion lt: "500" ``` ## Complex Configuration Example This example demonstrates a combination of filter types, including logical junctions (`and`, `or`) and a modifier (`not`). ```yaml filters: - alias: "Successful Logins from US or CA" and: # `and_filters` in Pydantic, `and` in YAML - field: "event.action" equals: "user_login" - field: "event.outcome" equals: "success" - or: # `or_filters` in Pydantic, `or` in YAML - field: "source.geo.country_iso_code" equals: "US" - field: "source.geo.country_iso_code" equals: "CA" - alias: "Exclude test users" not: # `not_filter` in Pydantic, `not` in YAML field: "user.name" in: ["test_user_01", "qa_bot"] - exists: "transaction.id" disabled: true # This filter is defined but currently disabled - dsl: query_string: query: "message:(*error* OR *exception*) AND NOT logger_name:debug" ``` ## Full Configuration Options ### Exists Filter Checks for the existence of a specific field. **kb_dashboard_core.filters.config.ExistsFilter** Represents an 'exists' filter configuration in the Config schema. This filter checks for the existence or non-existence of a specific field. Fields: - `alias` (`str | None`): An optional alias for the filter, used for display purposes. - `disabled` (`bool | None`): Indicates whether the filter is disabled. If `true`, the filter will not be applied. - `exists` (``): The field name to check for existence. If the field exists in a document, it will match that document. --- # Source: queries/config.md --- # Queries Configuration Queries are used to define the search criteria for retrieving data. They can be applied globally at the dashboard level or specifically to individual panels that support them. This compiler supports KQL (Kibana Query Language), Lucene, and ESQL (Elasticsearch Query Language). ## Minimal Configuration Examples **KQL Query:** ```yaml # Applied at the dashboard level dashboards: - # ... query: kql: 'response_code:200 AND "user.id": "test-user"' ``` **Lucene Query:** ```yaml # Applied at the dashboard level dashboards: - # ... query: lucene: 'event.module:nginx AND event.dataset:nginx.access' ``` **ESQL Query (typically for specific panel types like ESQL-backed charts):** ```yaml # Example within a panel configuration that supports ESQL panels: - type: some_esql_panel # Hypothetical panel type # ... other panel config query: | FROM my_index | STATS RARE(clientip) ``` ## Full Configuration Options Queries are typically defined under a `query` key, either at the root of the `dashboard` object or within a specific panel's configuration. The structure of the `query` object determines the language. ### KQL Query Filters documents using the Kibana Query Language (KQL). This is often the default query language in Kibana. **kb_dashboard_core.queries.config.KqlQuery** Represents a KQL (Kibana Query Language) query configuration. KQL is the default query language in Kibana and provides a simplified syntax for filtering data. Fields: - `kql` (``): The Kibana Query Language (KQL) query string to apply. --- # Source: guides/index.md --- # Advanced Guides Use the CLI to access bundled guide content: - `kb-dashboard docs list-guides` - `kb-dashboard docs guide ` ## Recommended Workflow Guides | Guide | Use it for | | ----- | ---------- | | [Dashboard Decompiling Guide](dashboard-decompiling-guide.md) | Converting existing Kibana JSON dashboards into YAML | | [Creating Dashboards from OpenTelemetry Receivers](otel-dashboard-guide.md) | Building new dashboards for OpenTelemetry receivers from scratch | | [ES\|QL Language Reference](esql-language-reference.md) | Writing production-ready ES\|QL for dashboard panels | | [Kibana Dashboard Style Guide](dashboard-style-guide.md) | Applying layout, hierarchy, and readability patterns across dashboards | | [Breaking Changes](breaking-changes.md) | Migration checklist for version upgrades | | [Color Assignments](color-assignments.md) | Configuring chart color assignments | | [Legend Configuration](legend-configuration.md) | Legend placement and sizing | | [ES\|QL Views](esql-views.md) | Reusable ES\|QL view definitions | --- # Source: guides/breaking-changes.md --- Guide content is available via the CLI and intentionally excluded from llms-full.txt. Use: - `kb-dashboard docs list-guides` - `kb-dashboard docs guide breaking-changes` --- # Source: guides/dashboard-decompiling-guide.md --- Guide content is available via the CLI and intentionally excluded from llms-full.txt. Use: - `kb-dashboard docs list-guides` - `kb-dashboard docs guide dashboard-decompiling-guide` --- # Source: guides/dashboard-style-guide.md --- Guide content is available via the CLI and intentionally excluded from llms-full.txt. Use: - `kb-dashboard docs list-guides` - `kb-dashboard docs guide dashboard-style-guide` --- # Source: guides/esql-language-reference.md --- Guide content is available via the CLI and intentionally excluded from llms-full.txt. Use: - `kb-dashboard docs list-guides` - `kb-dashboard docs guide esql-language-reference` --- # Source: guides/otel-dashboard-guide.md --- Guide content is available via the CLI and intentionally excluded from llms-full.txt. Use: - `kb-dashboard docs list-guides` - `kb-dashboard docs guide otel-dashboard-guide` --- # Source: guides/color-assignments.md --- Guide content is available via the CLI and intentionally excluded from llms-full.txt. Use: - `kb-dashboard docs list-guides` - `kb-dashboard docs guide color-assignments` --- # Source: guides/legend-configuration.md --- Guide content is available via the CLI and intentionally excluded from llms-full.txt. Use: - `kb-dashboard docs list-guides` - `kb-dashboard docs guide legend-configuration` --- # Source: guides/esql-views.md --- Guide content is available via the CLI and intentionally excluded from llms-full.txt. Use: - `kb-dashboard docs list-guides` - `kb-dashboard docs guide esql-views`