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.

# from package root
elastic-package export

3. If you need to modify installed managed dashboards before exporting:

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:

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

kibana-assets-layout

This reference captures Kibana asset layout rules, naming constraints, and practical package patterns for dashboard-related work in this repository.

Spec baseline (kibana/)

Canonical source: docs/extend/kibana-spec.md.

Supported folders under kibana/:

Forbidden for dashboard/visualization/search/map/lens/slo:

• filenames ending in -(ecs|ECS).json

Version notes from spec:

• slo/ support is removed for older package-spec versions (before 3.5.0)
• tags.yml support is removed for older package-spec versions (before 2.10.0)

Canonical directory tree

kibana/
  dashboard/
  visualization/
  search/
  map/
  lens/
  index_pattern/
  security_rule/
  csp_rule_template/
  ml_module/
  tag/
  osquery_pack_asset/
  osquery_saved_query/
  slo/
  tags.yml

Not every package uses every folder. Most observability integrations primarily use dashboard/ + search/, with optional ml_module/, map/, and tag/.

Dashboard JSON anatomy

A typical dashboard asset file contains:

{
  "attributes": { "...": "..." },
  "id": "package-identifier",
  "type": "dashboard",
  "migrationVersion": { "dashboard": "8.x.x" },
  "references": [ { "...": "..." } ]
}

Key attributes members commonly used:

• panelsJSON: embedded panel definitions (often by-value Lens panels)
• kibanaSavedObjectMeta.searchSourceJSON: default query/filter scope
• optionsJSON: dashboard-level display/options settings
• controlGroupInput: dashboard-native controls (dropdowns, etc.)

references usually include index-pattern/search dependencies. Many dashboards point to broad index patterns (logs-*, metrics-*) and then scope with filters like:

• data_stream.dataset: <package>.<dataset>

Naming and alignment rules

Use these together:

• Dashboard title convention:
• [<Metrics | Logs> <PACKAGE NAME>] <Name>
• Visualization title convention:
• <Name> only
• File naming convention:
• {PACKAGE_NAME}-{identifier}.json

Common file-name styles in this repo:

• UUID-based: nginx-046212a0-a2a1-11e7-928f-5dbe6f6f5519.json
• Descriptive: apache-Logs-Apache-Dashboard.json

tags.yml patterns

kibana/tags.yml can assign tags by asset type or by explicit asset IDs.

By asset type:

- text: Security Solution
  asset_types:
    - dashboard
    - search

By asset ID:

- text: Security Solution
  asset_ids:
    - aws-4746e000-bacd-11e9-9f70-1f7bda85a5eb
    - aws-562bdea0-4ba7-11ec-8282-5342b8988acc

Concrete package examples

Representative patterns from the upstream elastic/integrations repository:

• nginx — mostly UUID-named dashboards, includes ml_module/ usage
• apache — descriptive dashboard filenames, includes ml_module/
• system — many dashboards with both logs and metrics focus, includes search/ and alerting_rule_template/ usage
• auditd — dashboard + search + tags.yml
• cisco_duo — includes map/ assets
• aws — significant alerting_rule_template/ usage

Note:

• Some folders seen in upstream packages (for example alerting_rule_template/, security_ai_prompt/) may be package-specific patterns outside the baseline described in kibana-spec.md. Keep dashboard work aligned to the package's existing conventions and run validation commands.

Export and edit commands

Use elastic-package commands from the target package directory:

elastic-package service
elastic-package export

Dashboard-specific helpers:

elastic-package export dashboards
elastic-package edit dashboards

Recommended review loop after export: 1. inspect changed files under kibana/ 2. verify naming/patterns and dataset filters 3. run elastic-package check