dashboard-guidelines

# dashboard-guidelines ## When to use Use this skill when tasks include: - creating new Kibana dashboards for an integration package - reviewing dashboard JSON changes in `kibana/` folders - exporting dashboard updates from Kibana into package source - verifying dashboard naming and file layout against package spec - checking dashboard/data stream alignment through `data_stream.dataset` filtering ## When not to use Do not use this skill as the primary guide for: - package and data stream directory scaffolding (`create-integration`, `package-structure`) - ingest pipeline parsing and normalization logic (`ingest-pipelines`) - package-wide command orchestration and stack lifecycle decisions (`elastic-package-cli`) - test suite selection outside dashboard-focused checks (`integration-testing` → `references/system-testing.md`) ## Preconditions Before creating or updating dashboard assets, verify: 1. you are in the correct package directory (`packages/<package_name>/`) 2. Kibana/Elastic services are available for editing and exporting assets 3. sample data exists and dashboards can be validated against realistic events/metrics 4. package `manifest.yml` compatibility constraints (`conditions.kibana.version`) are understood ## Workflow: create, export, validate 1. Build or update dashboards in Kibana. - Prefer Lens for new visualizations. - Keep panels in the dashboard itself (by value) unless shared-library behavior is intentionally required. 2. Export assets back into the package. ```bash # from package root elastic-package export ``` 3. If you need to modify installed managed dashboards before exporting: ```bash elastic-package edit dashboards elastic-package export dashboards ``` 4. Review exported files under `kibana/`: - file names match package spec - no stale field names after mapping changes - dashboard filters are scoped to integration datasets 5. Run package validation commands before opening a PR: ```bash elastic-package check ``` ## Naming conventions Use naming conventions from dashboard creation guidance: - Visualization title: - `<Name>` (avoid repeating package name in each panel title) - Dashboard title: - `[<Metrics | Logs> <PACKAGE NAME>] <Name>` - examples: `[Metrics System] Host overview`, `[Logs Nginx] Access overview` - Dashboard asset file: - `{PACKAGE_NAME}-{identifier}.json` - example: `nginx-046212a0-a2a1-11e7-928f-5dbe6f6f5519.json` ## Design and modeling best practices - Use stable released Kibana versions (avoid SNAPSHOT). - Keep dashboards focused; split overloaded boards and provide navigation links. - Prefer by-value panels so dashboards remain self-contained. - Prefer Lens over TSVB for new visualizations. - Add controls using dashboard-native **Controls** (not deprecated input controls visualization). - Include dataset-aware filtering to prevent broad `logs-*` / `metrics-*` queries where possible. - baseline recommendation: filter by `data_stream.dataset` - Keep visual hierarchy clear: - most important summary panels near the top - related charts grouped together - margins enabled for readability - Use concise, self-explanatory panel titles and consistent accessible colors. ## Quality checklist before PR - dashboard assets are in `kibana/dashboard/` and follow expected naming pattern - dashboard content reflects current field names and types - visualizations are embedded by value unless there is a documented exception - dashboard or panel queries include integration-relevant filters (`data_stream.dataset` when applicable) - controls/drilldowns/navigation are coherent for multi-dashboard packages - exported dependencies are committed (dashboards plus required saved objects) - `elastic-package check` passes for the package ## Common pitfalls - exporting from an unstable Kibana build and committing incompatible saved object data - using generic, unfiltered `logs-*`/`metrics-*` queries that cause noisy or slow panels - keeping stale field references after pipeline/field mapping changes - overloading one dashboard instead of splitting into overview and deep-dive views - relying on library visualizations unintentionally, causing hidden dependencies - inconsistent naming between dashboard title, file name, and package context ## Handoff to other skills After dashboard updates are in place, continue with: 1. `dashboard-review` for reviewing dashboard JSON changes in a PR or branch 2. `integration-testing` → `references/system-testing.md` for system test validation 3. `elastic-package-cli` for broader check/lint/test command selection 4. `package-spec` when dashboard changes require a release note entry ## References - `references/kibana-assets-layout.md`