kibana/docs/user/dashboard/dashboard.asciidoc

[[dashboard]]
= Dashboard

[partintro]
--
**_Visualize your data with dashboards._**

The best way to understand your data is to visualize it. With dashboards, you can turn your data from one or more <<index-patterns, index patterns>> into a collection of panels 
that bring clarity to your data, tell a story about your data, and allow you to focus on only the data that's important to you. Configure each panel to display your data in a chart, table, map, and more, 
then compare the panels side-by-side to identify the patterns and connections in your data. 

[role="screenshot"]
image:images/Dashboard_example.png[Example dashboard]

Dashboards support many types of panels, and provide several editors that you can use to create panels.

[cols="2"]
|===

| <<create-panels-with-editors,Visualization editors>>
| Use the *Lens*, *TSVB*, *Vega*, and *Timelion* editors to help you create visualizations of your data, or create aggregation-based visualizations using {es} <<aggregation-reference,aggregations>>. 
*Lens* is recommended for most users.

| <<maps,Maps>>
| Create beautiful displays of your geographical data.

| <<enhance-dashboards,Tools>>
| Add context to your panels with <<add-text,text>>, or add dynamic filters with <<add-controls,*Controls*>>.

| <<save-your-search,Saved search from Discover>>
| Display a saved search table from <<discover, *Discover*>>. The table results are not aggregated.

| <<logs-app,Log stream>>
| Display a table of live streaming logs.

| <<xpack-ml-anomalies,ML Anomaly Swim Lane>>
| Display the results from machine learning anomaly detection jobs.

|===

[float]
[[create-dashboards]]
== Create dashboards

Dashboards provide you with the space where you add panels of your data.

[float]
[[dashboard-minimum-requirements]]
=== Minimum requirements

To create dashboards, you must meet the minimum requirements. 

* If you need to set up {kib}, use https://www.elastic.co/cloud/elasticsearch-service/signup?baymax=docs-body&elektra=docs[our free trial].

* Make sure you have {ref}/getting-started-index.html[data indexed into {es}] and an <<index-patterns,index pattern>>.

* Have an understanding of {ref}/documents-indices.html[{es} documents and indices].

* When the read-only indicator appears, you have insufficient privileges
to create or save dashboards. The options to create and save dashboards are not visible. For more information,
refer to <<xpack-security-authorization,Granting access to {kib}>>.

[float]
[[open-the-dashboard]]
=== Open the dashboard

Begin with an empty dashboard, or open an existing dashboard. 

. Open the main menu, then click *Dashboard*.

. On the *Dashboards* page, choose one of the following options:

* To start with an empty dashboard, click *Create dashboard*.

* To open an existing dashboard, click the dashboard *Title* you want to open.

[float]
[[add-panels]]
=== Add panels

To add panels to the dashboard, you can use one of the editors to create a new panel, 
add an existing panel from the *Visualize Library*, add a table of live streaming logs, or the add the results from a machine learning anomaly detection job.

[float]
[[create-panels-with-lens]]
==== Create panels

To create panels, use one of the editors, then add the panel to the dashboard.

. On the dashboard, click *Create panel*.

. On the *New visualization* window, click the editor you want to use. *Lens* is recommended for most users.

. To create the panel, configure the editor options.

. To add the panel to the dashboard, choose one of the following options:

* To add the panel to the dashboard without saving to the *Visualize Library*, click *Save and return*. 
+
To add a title to the panel, click *No Title*, enter the *Panel title*, then click *Save*.

* To save the panel to the *Visualize Library*, click *Save to Library*, configure the options, then click *Save and return*.
+
When panels are saved in the *Visualize Library*, image:dashboard/images/visualize-library-icon.png[Visualize Library icon] appears in the header.

[float]
[[add-panels-from-the-library]]
==== Add panels from the library

Add panels that you've already created from the *Visualize Library*. 

. On the dashboard, click *Add from library*.

. On the *Add from library* flyout, click the panels you want to add to the dashboard.

. To close the flyout, click *X*.
+
When a panel contains a stored query, both queries are applied.

. To make changes to the panel, open the panel menu, then select the following options:

* *Edit visualization* &mdash; Opens an editor so that you can reconfigure the panel. 
+
To make changes to the panel without affecting the original version, open the panel menu, then click *More > Unlink from library*.

* *Edit panel title* &mdash; Opens the *Customize panel* window to change the *Panel title* and specify whether you want to display the panel title.

[float]
[[add-a-table-of-live-streaming-logs]]
==== Add a logs panel

Add a panel that displays a table of live streaming logs.

. On the dashboard, click *Add from library*.

. On the *Add from library* flyout, click *Create new*, then select *Log stream*.

[float]
[[add-machine-learning-results]]
==== Add machine learning results

Add a panel that displays the results from machine learning anomaly detection jobs.

. On the dashboard, click *Add from library*.

. On the *Add from library* flyout, click *Create new*, then select *ML Anomaly Swim Lane*.

[[tsvb]]

[float]
[[arrange-panels]]
[[moving-containers]]
[[resizing-containers]]
=== Arrange the panels

To compare the data in the panels, reorganize or remove the panels on the dashboard.

. From the toolbar, click *Edit*, then use the following options:

* To move, click and hold the panel header, then drag to the new location.

* To resize, click the resize control, then drag to the new dimensions.

* To maximize the panel to fullscreen, open the panel menu, then click *More > Maximize panel*.

* To delete, open the panel menu, then click *More > Delete from dashboard*.

. To save your changes, click *Save* in the toolbar.

[float]
[[apply-design-options]]
=== Apply design options

Apply a set of design options to the entire dashboard.

. From the toolbar, click *Edit > Options*.

. Select the following options:

* *Use margins between panels* &mdash; Specifies a margin of space between each panel.

* *Show panel titles* &mdash; Specifies the appearance of titles in the header of each panel.

* *Sync color pallettes across panels* &mdash; Specifies whether the color pallette is applied to all panels.

[float]
[[search-or-filter-your-data]]
=== Search or filter your data

{kib} provides you with several ways to search your data and apply {es} filters. You can combine the filters with any panel
filter to display the data want to you see.

[float]
[[semi-structured-search]]
==== Semi-structured search

Combine free text search with field-based search using the <<kuery-query,{kib} Query Language>>.
Type a search term to match across all fields, or begin typing a field name to
get prompted with field names and operators you can use to build a structured query. 

For example, in the sample web logs data, the following query displays data only for the US:

. Enter `g`, then select *geo.source*.

. Select *equals some value* and *US*, then click *Update*.

. For a more complex search, try:

[source,text]
-------------------
geo.src : "US" and url.keyword : "https://www.elastic.co/downloads/beats/metricbeat"
-------------------

[float]
[[time-filter]]
==== Time filter

The <<set-time-filter,time filter>> restrict the data that appears on the dashboard, but you can override the time filter with panel filters.
  
. To update the time filter, add a panel that displays time-based data along the x-axis.

. Open the panel menu, then select *More > Customize time range*.

. On the *Customize panel time range* window, specify the time range, then click *Add to panel*.
+
[role="screenshot"]
image:images/time_range_per_panel.gif[Time range per dashboard panel]

[float]
[[additional-filters-with-and]]
==== Additional filters with AND

Add filters to a dashboard, or pin filters to multiple places in {kib}. To add filters, you can use the *Edit Filter* options, or the advanced JSON editor for the {es} {ref}/query-dsl.html[Query DSL]. 
When there is one or more index patterns on the dashboard, you can select the index pattern that contains the fields you want to create the filter.

For example, to filter the dashboard to display only ios data from *kibana_sample_data_logs*:

. Click *Add filter*.

. From the *Index Pattern* dropdown, select *kibana_sample_data_logs*.

. Set *Field* to *machine.os*, *Operator* to *is*, and *Value* to *ios*.

. *Save* the filter.
+
To remove the filter, click *x*.

[float]
[[add-dynamic-filters]]
==== Add dynamic filters

When you see data in a panel that you want to use as a filter, you can dynamically create the filter. To dynamically add filters, click the data in a panel.

. Click the data in the panel. 

. Select filters you want to apply to all of the dashboard panels, then click *Apply*.
+
To remove the filters, click *x*.

[float]
[[clone-panels]]
=== Clone panels

To duplicate a panel and the configured functionality, clone the panel. Cloned panels continue to replicate all of the functionality from the original panel, 
including renaming, editing, and cloning. When you clone a panel, the clone appears beside the original panel, and moves other panels to provide a space on the 
dashboard. 

. From the toolbar, click *Edit*. 

. Open the panel menu, then select *Clone panel*. 
+
[role="screenshot"]
image:images/clone_panel.gif[clone panel]
+
When cloned panels are saved in the *Visualize Library*, image:dashboard/images/visualize-library-icon.png[Visualize Library icon] appears in the header.

[float]
[[copy-to-dashboard]]
=== Copy panels

To add a panel to another dashboard, copy the panel.

. Open the panel menu, then select *More > Copy to dashboard*.

. On the *Copy to dashboard* window, select the dashboard, then click *Copy and go to dashboard*.

[float]
[[explore-the-underlying-data]]
=== Explore the underlying documents

View the underlying documents in a panel, or in a data series. 

TIP: *Explore underlying data* is supported only for visualization panels with a single index pattern.

To view the underlying documents in the panel: 

. Open the panel menu.

. Click *Explore underlying data*.
+
*Discover* opens with the same time range and filters as the panel.
+
[role="screenshot"]
image::images/explore_data_context_menu.png[Explore underlying data from panel context menu]

To view the underlying documents in a data series:

. In kibana.yml, add the following:
+
["source","yml"]
-----------
xpack.discoverEnhanced.actions.exploreDataInChart.enabled: true
-----------

. Open the dashboard, then click on the data series you want to view. 
+
[role="screenshot"]
image::images/explore_data_in_chart.png[Explore underlying data from chart]

[float]
[[download-csv]]
=== Download the panel data

Download panel data in a CSV file. You can download most panels in a CSV file, but there is a shortcut available
for *Lens* panels.

[role="xpack"]
To download *Lens* panel data in a CSV file:

. Open the *Lens* panel menu.

. Select *More > Download as CSV*.
+
[role="screenshot"]
image::images/download_csv_context_menu.png[Download as CSV from panel context menu]

Each layer produces a single CSV file with columns.
When you download multiple layers, the file names combine the visualization and layer index names.

To download all other panel data in a CSV file:

. Open the panel menu, then select *Inspect*.

. Click *Download CSV*, then select the CSV type from the dropdown:
* *Formatted CSV* &mdash; Contains human-readable dates and numbers.

* *Unformatted* &mdash; Best used for computer use.
+
[role="screenshot"]
image:images/Dashboard_inspect.png[Inspect in dashboard]

[float]
[[save-the-dashboard]]
=== Save the dashboard

When you're finished making changes, save the dashboard.

From the toolbar, choose one of the following options:

* *Save as* &mdash; Opens the *Save dashboard* window, which allows you to specify the title and dashboard options.

* *Save* &mdash; Allows you to save the changes you've made to an existing dashboard.

* *Switch to view mode* &mdash; Allows you to exit *Edit* mode without saving your changes, or you can discard the changes you've made. All dashboards with unsaved changes display *Unsaved changes* in the toolbar.

[float]
[[share-the-dashboard]]
=== Share the dashboard

To share the dashboard with a larger audience, click *Share* in the toolbar, then choose one of the following options:

* *Embed code* &mdash; Embed a fully interactive dashboard as an iframe on a web page. To access embedded dashboards, you can require users to
log in using their {kib} credentials, via reverse proxy, or enable <<anonymous-access-and-embedding, anonymous access>>.

* *Permalinks* &mdash; Share a direct link to a {kib} dashboard. User authentication is required.

* *PDF Reports* &mdash; Generate a PDF report. For more information, refer to <<reporting-getting-started,Reporting>>.

* *PNG Reports* &mdash; Generate a PNG report. For more information, refer to <<reporting-getting-started,Reporting>>.

[float]
[[import-dashboards]]
=== Export the dashboard

To automate {kib}, you can export dashboards as JSON using the <<dashboard-api,import and export dashboard APIs>>. It is important to export dashboards with all references needed.

--
include::tutorial-create-a-dashboard-of-lens-panels.asciidoc[]

include::lens-advanced.asciidoc[]

include::create-panels-with-editors.asciidoc[]

include::enhance-dashboards.asciidoc[]

include::drilldowns.asciidoc[]

include::aggregation-reference.asciidoc[]