Create and export dashboards

Visualizing integration data in a meaningful way is a key aspect of building a great integration. Dashboards help users quickly understand and explore the data your integration ingests

1. Create or customize a dashboard

• In Kibana, create a new dashboard or customize an existing one to visualize your integration’s data.

• Use Lens for new visualizations whenever possible. If Lens doesn’t meet your needs, use TSVB.

2. Boot up the service stack

Use elastic-package to start the service stack for your integration:

elastic-package service

3. Export dashboards and dependencies

When you’re done, export your dashboards and their dependencies to the package source

elastic-package export

Many integrations cover more than one component of a target system. For example, the RabbitMQ module provides several metricsets covering connection, exchange, node, queue. It makes sense to break this information down into several interconnected dashboards. The default one is an overview of a target system, and the others provide deep-dives into the various parts of the target system. The content of the Overview dashboard should be cherry-picked from all datasets and individually compiled for every such integration.

Always check the type of a metric and ensure that the correct transformation is applied where applicable. For example, in most cases for cumulative counters, it makes sense to use the rate function.

For new visualizations, we recommend using Lens first. If what you’re trying to achieve cannot be accomplished with the current capabilities of Lens, try TSVB.

When building a dashboard, always consider adding a filter dropdown. Why? In most cases, the integrations monitor multiple instances of a target system, so we need to provide a way to switch between them.

To build a filter dropdown, use the Controls visualization. Here’s an example of a host name dropdown that you can add to the System dashboard:

If an integration has several dashboards, ensure that you can easily navigate all of them. To build dashboard navigation, use the Markdown visualization type.

For example, the System dashboard provides the following navigation:

Source:

[System Overview](#/dashboard/system-Metrics-system-overview-ecs)  | [Host Overview](#/dashboard/system-79ffd6e0-faa0-11e6-947f-177f697178b8-ecs) |
[Containers overview](#/dashboard/system-CPU-slash-Memory-per-container-ecs)

While this can work, it doesn’t highlight the selected dashboard. Unfortunately the Markdown control is not optimized for navigation, which makes it cumbersome to build navigation with highlighted links because each link should be highlighted separately. This means that the navigation control you’re building has to be cloned as many times as there are dashboard to ensure proper link highlighting. E.g.

**[System Overview](#/dashboard/system-Metrics-system-overview-ecs)**  | [Host Overview](#/dashboard/system-79ffd6e0-faa0-11e6-947f-177f697178b8-ecs) |
[Containers overview](#/dashboard/system-CPU-slash-Memory-per-container-ecs)

[System Overview](#/dashboard/system-Metrics-system-overview-ecs)  | **[Host Overview](#/dashboard/system-79ffd6e0-faa0-11e6-947f-177f697178b8-ecs)** |
[Containers overview](#/dashboard/system-CPU-slash-Memory-per-container-ecs)

[System Overview](#/dashboard/system-Metrics-system-overview-ecs)  | [Host Overview](#/dashboard/system-79ffd6e0-faa0-11e6-947f-177f697178b8-ecs) |
**[Containers overview](#/dashboard/system-CPU-slash-Memory-per-container-ecs)**

Currently we don’t make it a rule to show on a dashboard what system it’s designed to monitor. The only way to see it is through the dashboard name.

When using multiple dashboards on bigger screens, it makes it hard to distinguish between the dashboards. You can improve this by using the Markdown control to display the target system the dashboard is used for.

When building dashboards, use the following naming convention.

<Name>

Examples:

• Memory Usage Gauge
• New groups

To avoid adding repetitive information such as the package name, rename all visualizations added to a dashboard only to show the <Name> part.

[<Metrics | Logs> <PACKAGE NAME>] <Name>

Examples:

• [Metrics System] Host overview
• [Metrics MongoDB] Overview

Letter casing is important for screenshot descriptions. Descriptions are shown in the Kibana UI, so try and keep them clean and consistent.

These descriptions are visualized in the Kibana UI. It would be better experience to have them clean and consistent.

• Bad candidate: filebeat running on ec2 machine
• Good candidates: Filebeat running on AWS EC2 machine

When your dashboards are ready, export them with:

elastic-package export

This command exports dashboards and their dependencies to your integration package.

• Use stable Kibana versions: Build dashboards on officially released Kibana versions, not SNAPSHOTs.

• Limit visualizations per dashboard: Avoid overcrowding. Split into multiple dashboards if needed.

• Update dashboards for field changes: If field names or types change, update all affected dashboards.

• Add visualizations by value: Prefer adding visualizations by value (not by reference) to avoid accidental deletion or dependency issues.

• Link dashboards with drilldowns: Use drilldowns(external, opens in a new tab or window) for advanced navigation between dashboards.