[7.x] [DOCS] Dashboard docs refresh for 7.11 (#85342) (#88883)

* [DOCS] Dashboard docs refresh for 7.11 (#85342)

* [DOCS] 7.11 Dashboard docs refresh

* [Lens] end to end guide

* Fixes to writer errors

* Fixes errors

* Fixes error

* errors

* small corrections in e2e

* Introduction, CSV download, and end-to-end guide

* End-to-end guide

* End-to-end guide and intro

* Fixes broken external links

* Update docs/user/dashboard/dashboard.asciidoc

Co-authored-by: Wylie Conlon <wylieconlon@gmail.com>

* Update docs/user/dashboard/dashboard.asciidoc

Co-authored-by: Wylie Conlon <wylieconlon@gmail.com>

* Update docs/user/dashboard/dashboard.asciidoc

Co-authored-by: Wylie Conlon <wylieconlon@gmail.com>

* Update docs/user/dashboard/lens-end-to-end/lens-end-to-end.asciidoc

Co-authored-by: Wylie Conlon <wylieconlon@gmail.com>

* Update docs/user/dashboard/lens-end-to-end/lens-end-to-end.asciidoc

Co-authored-by: Marta Bondyra <marta.bondyra@gmail.com>

* Update docs/user/dashboard/lens-end-to-end/lens-end-to-end.asciidoc

Co-authored-by: Wylie Conlon <wylieconlon@gmail.com>

* Update docs/user/dashboard/lens-end-to-end/lens-end-to-end.asciidoc

Co-authored-by: Marta Bondyra <marta.bondyra@gmail.com>

* Review comments

* Review comments and Vega

* Vega tutorials

* Timelion changes

* Bug fixes and clean up

* Introduction

* Clean up

* Link fixes

* Broken links

* Fixes Timelion link

* Minor intro changes

* Fixes Timelion link

* Vega changes

* Add reference content, and move Lens docs to their own page

* Update from review

* Review comments

* Link fixes

* Clean up

Co-authored-by: Marta Bondyra <marta.bondyra@elastic.co>
Co-authored-by: Wylie Conlon <wylieconlon@gmail.com>
Co-authored-by: Marta Bondyra <marta.bondyra@gmail.com>

* Fixes to conflicts, images, and Vega

Co-authored-by: Marta Bondyra <marta.bondyra@elastic.co>
Co-authored-by: Wylie Conlon <wylieconlon@gmail.com>
Co-authored-by: Marta Bondyra <marta.bondyra@gmail.com>

docs/canvas/canvas-elements.asciidoc

@@ -1,167 +0,0 @@
-[role="xpack"]
-[[add-canvas-elements]]
-=== Add elements
-
-Create a story about your data by adding elements to your workpad that include images, text, charts, and more. You can create your own elements and connect them to your data sources, add saved objects, and add your own images.
-
-[float]
-[[create-canvas-element]]
-==== Create an element
-
-Choose the type of element you want to use, then connect it to your own data.
-
-. Click *Add element*, then select the element you want to use.
-+
-[role="screenshot"]
-image::images/canvas-element-select.gif[Canvas elements]
-
-. To familiarize yourself with the element, use the preconfigured data demo data.
-+
-By default, most of the elements you create use demo data until you change the data source. The demo data includes a small data set that you can use to experiment with your element.
-
-. To connect the element to your data, select *Data*, then select one of the following data sources:
-
-* *{es} SQL* — Access your data in {es} using SQL syntax. For information about SQL syntax, refer to {ref}/sql-spec.html[SQL language].
-
-* *{es} documents* &mdash; Access your data in {es} without using aggregations. To use, select an index and fields, and optionally enter a query using the <<lucene-query,Lucene Query Syntax>>. Use the *{es} documents* data source when you have low volume datasets, to view raw documents, or to plot exact, non-aggregated values on a chart.
-
-* *Timelion* &mdash; Access your time series data using <<timelion,Timelion>> queries. To use Timelion queries, you can enter a query using the <<lucene-query,Lucene Query Syntax>>.
-
-Each element can display a different data source. Pages and workpads often contain multiple data sources.
-
-[float]
-[[canvas-add-object]]
-==== Add a saved object
-
-Add <<managing-saved-objects,saved objects>> to your workpad, such as maps and visualizations.
-
-. Click *Add element > Add from Visualize Library*.
-
-. Select the saved object you want to add.
-+
-[role="screenshot"]
-image::images/canvas-map-embed.gif[]
-
-. To use the customization options, click the panel menu, then select one of the following options:
-
-* *Edit map* &mdash; Opens <<maps,Maps>> or <<create-panels,Dashboard>> so that you can edit the original saved object.
-
-* *Edit panel title* &mdash; Adds a title to the saved object.
-
-* *Customize time range* &mdash; Exposes a time filter dedicated to the saved object.
-
-* *Inspect* &mdash; Allows you to drill down into the element data.
-
-[float]
-[[canvas-add-image]]
-==== Add your own image
-
-To personalize your workpad, add your own logos and graphics.
-
-. Click *Add element > Manage assets*.
-
-. On the *Manage workpad assets* window, drag and drop your images.
-
-. To add the image to the workpad, click the *Create image element* icon.
-+
-[role="screenshot"]
-image::images/canvas-add-image.gif[]
-
-[float]
-[[move-canvas-elements]]
-==== Organize elements
-
-Move and resize your elements to meet your design needs.
-
-* To move, click and hold the element, then drag to the new location.
-
-* To move by 1 pixel, select the element, press and hold Shift, then use your arrow keys.
-
-* To move by 10 pixels, select the element, then use your arrow keys.
-
-* To resize, click and drag the resize handles to the new dimensions.
-
-[float]
-[[format-canvas-elements]]
-==== Format elements
-
-For consistency and readability across your workpad pages, align, distribute, and reorder elements.
-
-To align two or more elements:
-
-. Press and hold Shift, then select the elements you want to align.
-
-. Click *Edit > Alignment*, then select the alignment option.
-
-To distribute three or more elements:
-
-. Press and hold Shift, then select the elements you want to distribute.
-
-. Click *Edit > Distribution*, then select the distribution option.
-
-To reorder elements:
-
-. Select the element you want to reorder.
-
-. Click *Edit > Order*, then select the order option.
-
-[float]
-[[data-display]]
-==== Change the element display options
-
-Each element has its own display options to fit your design needs.
-
-To choose the display options, click *Display*, then make your changes.
-
-To define the appearance of the container and border:
-
-. Next to *Element style*, click *+*, then select *Container style*.
-
-. Expand *Container style*.
-
-. Change the *Appearance* and *Border* options.
-
-To apply CSS overrides:
-
-. Next to *Element style*, click *+*, then select *CSS*.
-
-. Enter the *CSS*.
-+
-For example, to center the Markdown element, enter:
-+
-[source,text]
---------------------------------------------------
-.canvasRenderEl h1 {
-text.align: center;
-}
---------------------------------------------------
-
-. Click *Apply stylesheet*.
-
-[float]
-[[save-elements]]
-==== Save elements
-
-To use the elements across all workpads, save the elements.
-
-When you're ready to save your element, select the element, then click *Edit > Save as new element*.
-
-[role="screenshot"]
-image::images/canvas_save_element.png[]
-
-To save a group of elements, press and hold Shift, select the elements you want to save, then click *Edit > Save as new element*.
-
-To access your saved elements, click *Add element > My elements*.
-
-[float]
-[[delete-elements]]
-==== Delete elements
-
-When you no longer need an element, delete it from your workpad.
-
-. Select the element you want to delete.
-
-. Click *Edit > Delete*.
-+
-[role="screenshot"]
-image::images/canvas_element_options.png[]

docs/getting-started/quick-start-guide.asciidoc

@@ -106,7 +106,7 @@ For more information, refer to <<dashboard,*Dashboard*>>.
 [[create-a-visualization]]
 === Create a visualization panel
 
-To create a treemap panel that shows the top regions and manufacturers, use *Lens*, then add the treemap panel to the dashboard.
+Create a treemap panel that shows the top regions and manufacturers, then add the panel to the dashboard.
 
 . From the toolbar, click *Edit*, then click *Create new*.
 
@@ -132,7 +132,7 @@ The treemap appears as the last visualization panel on the dashboard.
 [role="screenshot"]
 image::getting-started/images/tutorial-final-dashboard.gif[Final dashboard with new treemap visualization]
 +
-For more information, refer to <<lens, *Lens*>>.
+For more information, refer to <<dashboard,Dashboard>>.
 
 [float]
 [[quick-start-whats-next]]

docs/index.asciidoc

@@ -7,7 +7,7 @@
 :blog-ref:       https://www.elastic.co/blog/
 :wikipedia:      https://en.wikipedia.org/wiki
 
-include::{docs-root}/shared/versions/stack/{source_branch}.asciidoc[]
+include::{docs-root}/shared/versions/stack/7.10.asciidoc[]
 
 :docker-repo:    docker.elastic.co/kibana/kibana
 :docker-image:   docker.elastic.co/kibana/kibana:{version}

docs/management/numeral.asciidoc

@@ -10,7 +10,7 @@ Numeral formatting patterns are used in multiple places in {kib}, including:
 
 * <<advanced-options, Advanced settings>>
 * <<field-formatters-numeric, Index pattern formatters>>
-* <<tsvb, TSVB>>
+* <<tsvb-advanced-editor, TSVB>>
 * <<canvas, Canvas>>
 
 The simplest pattern format is `0`, and the default {kib} pattern is `0,0.[000]`.

docs/redirects.asciidoc

@@ -112,11 +112,6 @@ More information on this new feature is available in <<apm-alerts>>.
 
 This content has moved to the <<development-rbac, Security>> page.
 
-[role="exclude",id="TSVB"]
-== TSVB
-
-This page was deleted. See <<tsvb>>.
-
 [role="exclude",id="managing-cross-cluster-replication"]
 == Cross-Cluster Replication
 
@@ -218,4 +213,7 @@ This page has moved. Refer to <<url-template-variables>>.
 [role="exclude",id="visualize"]
 == Visualize
 
-This page has been removed. Refer to <<dashboard>>.
+This content has moved. See <<dashboard, **Dashboard**>>.
+
+[role="exclude",id="explore-dashboard-data"]
+This content has moved. See <<dashboard, **Dashboard**>>.

docs/user/canvas.asciidoc

@@ -104,7 +104,7 @@ When you're ready to connect the element to your data, select *Data*, then selec
 
 * *{es} documents* &mdash; Access your data in {es} without using aggregations. To use, select an index and fields, and optionally enter a query using the <<lucene-query,Lucene Query Syntax>>. Use the *{es} documents* data source when you have low volume datasets, to view raw documents, or to plot exact, non-aggregated values on a chart.
 
-* *Timelion* &mdash; Access your time series data using <<timelion,Timelion>> queries. To use Timelion queries, you can enter a query using the <<lucene-query,Lucene Query Syntax>>.
+* *Timelion* &mdash; Access your time series data using <<create-panels-with-timelion,Timelion>> queries. To use Timelion queries, you can enter a query using the <<lucene-query,Lucene Query Syntax>>.
 
 Each element can display a different data source, and pages and workpads often contain multiple data sources.
 

docs/user/dashboard/advanced-editors.asciidoc

@@ -0,0 +1,65 @@
+[[add-panels-with-advanced-editors]]
+== Create panels with the advanced editors
+
+{kib} provides you with three advanced editors that you can use to manually create dashboard panels.
+
+[float]
+[[tsvb-advanced-editor]]
+=== TSVB
+
+*TSVB* is a time series data visualization editor that allows you to use the full power of the {es} aggregation framework. 
+
+With *TSVB*, you can:
+
+* Combine an infinite number of <<aggregation-reference,aggregations>> to display your data.
+* Annotate time series data with timestamped events from an {es} index.
+* View the data in several types of visualizations, including charts, data tables, and markdown panels.
+* Display multiple <<index-patterns, index patterns>> in each visualization.
+* Customize the data with labels and colors.
+
+image::images/tsvb.png[TSVB UI]
+
+[float]
+[[vega-advanced-editor]]
+=== Custom visualizations
+
+*Vega* and *Vega-Lite* are visualization grammars that are integrated into {kib} for custom visualizations.
+
+* *Vega-Lite* &mdash; A high-level grammar for rapid analysis
+
+* *Vega* &mdash; A declarative language with support for interactivity
+
+*Vega* and *Vega-Lite* panels can display one or more data sources, including {es}, Elastic Map Service,
+URL, or static data, and support <<reference-for-kibana-extensions,{kib} extensions>> that allow you to embed the panels on your dashboard and add interactive tools.
+
+Use *Vega* or *Vega-Lite* when you want to create visualizations with:
+
+* Aggregations that use `nested` or `parent/child` mapping
+* Aggregations without an index pattern
+* Queries that use custom time filters
+* Complex calculations
+* Extracted data from _source instead of aggregations
+* Scatter charts, sankey charts, and custom maps
+* An unsupported visual theme
+
+These grammars have some limitations: they do not support tables, and can't run queries conditionally.
+
+image::images/vega.png[Vega UI]
+
+For detailed *Vega* and *Vega-Lite* information and examples, refer to <<resources-and-examples,Resources and examples>>. 
+
+[float]
+[[timelion-advanced-editor]]
+=== Timelion
+
+*Timelion* is driven by a simple expression language that you use to:
+
+* Retrieve time series data from one or more indices
+* Perform math across two or more time series
+* Visualize the results
+
+image:dashboard/images/timelion.png[Timelion]
+
+include::tsvb.asciidoc[]
+include::vega.asciidoc[]
+include::timelion.asciidoc[]

docs/user/dashboard/aggregation-based.asciidoc

@@ -0,0 +1,216 @@
+[[add-aggregation-based-visualization-panels]]
+== Create aggregation-based visualization panels
+
+Aggregation-based visualizations are the core {kib} panels, and are not optimized
+for a specific use case. If you are new to {kib}, <<create-panels-with-lens,Lens>> is recommended as a
+simpler way to get started.
+
+The main features that these panel types have compared to other {kib} panel types are:
+
+* Support for heat map, tag cloud, gauge, and goal chart types
+* Support for split charts at up to 3 levels of aggregation, more than *Lens* and *TSVB*
+* Time series data is not required
+* Ability to use a <<save-open-search,saved search>> as an input
+* Data table can be sorted, also supports summary row and percentage column features
+* Can assign specific colors to series
+* Ability for plugin authors to extend the features
+
+These panel types also have some limitations:
+
+* Not as simple as *Lens*
+* Limited styling options
+* No support for math
+* No support for multiple indices
+
+[float]
+[[types-of-visualization-panels]]
+=== Types of aggregation-based panels
+
+{kib} supports the following types of aggregation-based panels.
+
+[cols="50, 50"]
+|===
+
+a| *Area*
+
+Displays data points, connected by a line, where the area between the line and axes are shaded.
+Use area charts to compare two or more categories over time, and display the magnitude of trends.
+
+| image:images/area.png[Area chart]
+
+a| *Data table*
+
+Displays your aggregation results in a tabular format. Use data tables to display server configuration details, track counts, min,
+or max values for a specific field, and monitor the status of key services.
+
+| image:images/data_table.png[Data table]
+
+a| *Gauge*
+
+Displays your data along a scale that changes color according to where your data falls on the expected scale. Use the gauge to show how metric
+values relate to reference threshold values, or determine how a specified field is performing versus how it is expected to perform.
+
+| image:images/gauge.png[Gauge]
+
+a| *Goal*
+
+Displays how your metric progresses toward a fixed goal. Use the goal to display an easy to read visual of the status of your goal progression.
+
+| image:images/goal.png[Goal]
+
+a| *Heat map*
+
+Displays graphical representations of data where the individual values are represented by colors. Use heat maps when your data set includes
+categorical data. For example, use a heat map to see the flights of origin countries compared to destination countries using the sample flight data.
+
+| image:images/heat_map.png[Heat map]
+
+a| *Horizontal Bar*
+
+Displays bars side-by-side where each bar represents a category. Use bar charts to compare data across a
+large number of categories, display data that includes categories with negative values, and easily identify
+the categories that represent the highest and lowest values. {kib} also supports vertical bar charts.
+
+| image:images/bar.png[Bar chart]
+
+a| *Line*
+
+Displays data points that are connected by a line. Use line charts to visualize a sequence of values, discover
+trends over time, and forecast future values.
+
+| image:images/line.png[Line chart]
+
+a| *Metric*
+
+Displays a single numeric value for an aggregation. Use the metric visualization when you have a numeric value that is powerful enough to tell
+a story about your data.
+
+| image:images/metric.png[Metric]
+
+a| *Pie*
+
+Displays slices that represent a data category, where the slice size is proportional to the quantity it represents.
+Use pie charts to show comparisons between multiple categories, illustrate the dominance of one category over others,
+and show percentage or proportional data.
+
+| image:images/pie.png[Pie chart]
+
+a| *Tag cloud*
+
+Graphical representations of how frequently a word appears in the source text. Use tag clouds to easily produce a summary of large documents and
+create visual art for a specific topic.
+
+| image:images/tag_cloud.png[Tag cloud]
+
+|===
+
+[float]
+[[create-aggregation-based-panel]]
+=== Create an aggregation-based panel
+
+Choose the type of panel you want to create, then use the editor to configure the options. Each panel type supports different options. 
+
+. From the dashboard, click *Create panel*, then click *Aggregation based* on the *New visualization* window.
+
+.. Click the type of panel you want to create.
+
+.. Click the data source you want to visualize.
+
+. From the editor, add the <<aggregation-reference,aggregations>> you want to visualize, then click *Update*. 
++
+NOTE: For the *Date Histogram* to use an *auto interval*, the date field must match the primary time field of the index pattern.
+
+. To change the order, drag the aggregations along the editor. 
++ 
+[role="screenshot"]
+image:images/bar-chart-tutorial-3.png[Option to change the order of aggregations]
+
+. To customize the series colors, click the series in the legend, then select the color you want to use.
++ 
+[role="screenshot"]
+image:images/aggregation-based-color-picker.png[Color picker]
+
+[float]
+[[try-it-aggregation-based-panel]]
+=== Try it: Create an aggregation-based bar chart
+
+You collected data from your web server, and you want to visualize and analyze the data on a dashboard. To create a dashboard panel of the data, create
+a bar chart that displays the top five log traffic sources for every three hours.
+
+[float]
+==== Add the data and create the dashboard
+
+Add the sample web logs data that you'll use to create the bar chart, then create the dashboard.
+
+. From the *Home* page, click *Try our sample data*.
+
+. From *Sample web logs*, click *Add data*.
+
+. Open the main menu, then click *Dashboard*.
+
+. On the *Dashboards* page, click *Create dashboard*.
+
+[float]
+==== Open and set up the aggregation-based bar chart
+
+Open the bar chart visualization builder and change the time range. 
+
+. On the dashboard, click *Create panel*.
+
+. On the *New visualization* window, click *Aggregation based > Vertical bar*.
+
+. On the *Choose a source* window, click *kibana_sample_data_logs*.
+
+. Change the <<set-time-filter, time filter>>> to *Last 7 days*.
+
+[float]
+[[tutorial-configure-the-bar-chart]]
+==== Create the bar chart
+
+To create the bar chart, add a <<bucket-aggregations,bucket aggregation>>, then add the terms sub-aggregation to display the top values.
+
+. Add a *Buckets* aggregation.
+
+.. Click *Add*, then select *X-axis*.
+
+.. From the *Aggregation* dropdown, select *Date Histogram*.
+
+.. Click *Update*.
++
+[role="screenshot"]
+image:images/bar-chart-tutorial-1.png[Bar chart with sample logs data]
+
+. To show the top five log traffic sources, add a sub-bucket aggregation.
+
+.. Click *Add*, then select *Split series*.
++
+TIP: Aggregation-based panels support a maximum of three *Split series*.
+
+.. From the *Sub aggregation* dropdown, select *Terms*.
+
+.. From the *Field* dropdown, select *geo.src*.
+
+.. Click *Update*.
++
+[role="screenshot"]
+image:images/bar-chart-tutorial-2.png[Bar chart with sample logs data]
+
+[float]
+==== Save the panel
+
+Save and add the visualization panel to the dashboard.
+
+. From the toolbar, click *Save*.
+
+. Enter the *Title* and optional *Description*. 
+
+. From the *Tags* drop down, select any applicable tags. 
+
+. Select *Add to Dashboard after saving*.
+
+. Click *Save and return*.
+
+
+
+
+

docs/user/dashboard/aggregation-reference.asciidoc

@@ -1,27 +1,122 @@
 [[aggregation-reference]]
-== Aggregation reference
+== Supported features by panel type
 
-{kib} supports many types of {ref}/search-aggregations.html[{es} aggregations] that you can use to build complex summaries of your data. 
+Each panel type in {kib} supports different features and {ref}/search-aggregations.html[{es} aggregations].
+This reference can help simplify the comparison if you need a specific feature.
 
-By using a series of {es} aggregations to extract and process your data, you can create panels that tell a 
-story about the trends, patterns, and outliers in your data.
+
+[float]
+[[chart-types]]
+=== Supported panel types by editor
+
+[options="header"]
+|===
+
+| Type | Aggregation-based | Lens | TSVB | Timelion | Vega
+
+| Table
+^| X
+^| X
+^| X
+|
+|
+
+| Table with summary row
+^| X
+|
+|
+|
+|
+
+| Bar, line, and area charts
+^| X
+^| X
+^| X
+^| X
+^| X
+
+| Percentage bar or area chart
+|
+^| X
+^| X
+|
+^| X
+
+| Split bar, line, and area charts
+^| X
+|
+|
+|
+^| X
+
+| Pie and donut charts
+^| X
+^| X
+|
+|
+^| X
+
+| Sunburst chart
+^| X
+^| X
+|
+|
+|
+
+| Heat map
+^| X
+|
+|
+|
+^| X
+
+| Gauge and Goal
+^| X
+|
+^| X
+|
+|
+
+| Markdown
+|
+|
+^| X
+|
+|
+
+| Metric
+^| X
+^| X
+^| X
+|
+^| X
+
+| Tag cloud
+^| X
+|
+|
+|
+^| X
+
+|===
 
 [float]
 [[bucket-aggregations]]
 === Bucket aggregations
 
-For information about Elasticsearch bucket aggregations, refer to {ref}/search-aggregations-bucket.html[Bucket aggregations].
+Vega supports all bucket aggregations because it allows custom queries.
+
+For information about {es} bucket aggregations, refer to {ref}/search-aggregations-bucket.html[Bucket aggregations].
 
 [options="header"]
 |===
 
-| Type | Visualizations | Data table | Markdown | Lens | TSVB 
+| Type | Agg-based | Markdown | Lens | TSVB
 
 | Histogram
 ^| X
 ^| X
-^| X
-| 
+^| X 
 | 
 
 | Date histogram
@@ -29,40 +124,34 @@ For information about Elasticsearch bucket aggregations, refer to {ref}/search-a
 ^| X
 ^| X
 ^| X
-^| X
 
 | Date range
 ^| X
 ^| X
-^| X
 | 
 | 
 
 | Filter
 ^| X
 ^| X
-^| X
-| 
+|
 ^| X
 
 | Filters
 ^| X
 ^| X
 ^| X
-| 
 ^| X
 
 | GeoHash grid
 ^| X
 ^| X
-^| X
 | 
 | 
 
 | IP range
 ^| X
 ^| X
-^| X
 | 
 | 
 
@@ -71,19 +160,16 @@ For information about Elasticsearch bucket aggregations, refer to {ref}/search-a
 ^| X
 ^| X
 | 
-| 
 
 | Terms
 ^| X
 ^| X
 ^| X
 ^| X
-^| X
 
 | Significant terms
 ^| X
 ^| X
-^| X
 |
 ^| X
 
@@ -93,66 +179,60 @@ For information about Elasticsearch bucket aggregations, refer to {ref}/search-a
 [[metrics-aggregations]]
 === Metrics aggregations
 
-For information about Elasticsearch metrics aggregations, refer to {ref}/search-aggregations-metrics.html[Metrics aggregations].
+Vega supports all metric aggregations because it allows custom queries.
+
+For information about {es} metrics aggregations, refer to {ref}/search-aggregations-metrics.html[Metrics aggregations].
 
 [options="header"]
 |===
 
-| Type | Visualizations | Data table | Markdown | Lens | TSVB
+| Type | Agg-based | Markdown | Lens | TSVB
 
 | Average
 ^| X
 ^| X
 ^| X
 ^| X
-^| X
 
 | Sum 
 ^| X
 ^| X
 ^| X
 ^| X
-^| X
 
 | Unique count (Cardinality)
 ^| X
 ^| X
 ^| X
 ^| X
-^| X
 
 | Max
 ^| X
 ^| X
 ^| X
 ^| X
-^| X
 
 | Min
 ^| X
 ^| X
 ^| X
 ^| X
-^| X
 
 | Percentiles
 ^| X
 ^| X
-^| X
 | 
 ^| X
 
 | Percentiles Rank
 ^| X
 ^| X
-^| X
 | 
 ^| X
 
 | Top hit 
 ^| X
 ^| X
-^| X
 | 
 ^| X
 
@@ -160,7 +240,6 @@ For information about Elasticsearch metrics aggregations, refer to {ref}/search-
 | 
 | 
 | 
-| 
 ^| X
 
 |===
@@ -169,74 +248,109 @@ For information about Elasticsearch metrics aggregations, refer to {ref}/search-
 [[pipeline-aggregations]]
 === Pipeline aggregations
 
-For information about Elasticsearch pipeline aggregations, refer to {ref}/search-aggregations-pipeline.html[Pipeline aggregations].
+Vega supports all pipeline aggregations because it allows custom queries.
+
+For information about {es} pipeline aggregations, refer to {ref}/search-aggregations-pipeline.html[Pipeline aggregations].
 
 [options="header"]
 |===
 
-| Type | Visualizations | Data table | Markdown | Lens | TSVB
+| Type | Agg-based | Markdown | Lens | TSVB
 
 | Avg bucket  
 ^| X
 ^| X
-^| X
 | 
 ^| X
 
 | Derivative  
 ^| X
 ^| X
-^| X
 | 
 ^| X
 
 | Max bucket   
 ^| X
 ^| X
-^| X
 | 
 ^| X
 
 | Min bucket   
 ^| X
 ^| X
-^| X
 | 
 ^| X
 
 | Sum bucket  
 ^| X
 ^| X
-^| X
-^| 
+| 
 ^| X
  
 | Moving average  
 ^| X
 ^| X
-^| X
-^| 
+| 
 ^| X
 
 | Cumulative sum 
 ^| X
 ^| X
-^| X
-^| 
+| 
 ^| X
 
 | Bucket script 
 | 
 | 
 | 
-| 
 ^| X
 
 | Serial differencing 
 ^| X
 ^| X
-^| X
 | 
 ^| X
 
 |===
+
+[float]
+[[other-features]]
+=== Other features
+
+This comparison is meant for users who are not sure about which {kib} panel type to
+build their advanced visualization.
+
+[options="header"]
+|===
+
+| Type | Agg-based | Lens | TSVB | Timelion | Vega
+
+| Math on aggregated data
+|
+|
+^| X
+^| X
+^| X
+
+| Visualize two indices
+|
+^| X
+^| X
+^| X
+^| X
+
+| Math across indices
+|
+|
+|
+^| X
+^| X
+
+| Fully custom {es} queries
+|
+|
+|
+|
+^| X
+
+|===

docs/user/dashboard/dashboard.asciidoc

@@ -3,489 +3,283 @@
 
 [partintro]
 --
+**_Visualize your data with dashboards._**
 
-A _dashboard_ is a collection of panels that you use to analyze your data. On a dashboard, you can add a variety of panels that
-you can rearrange and tell a story about your data. Panels contain everything you need, including visualizations,
-interactive controls, markdown, and more.
-
-With *Dashboard*, you can:
-
-* Add multiple panels to see many aspects and views of your data in one place.
-
-* Arrange panels for analysis and comparison.
-
-* Add text and images to provide context to the panels and make them easy to consume.
-
-* Create and apply filters to focus on the data you want to display.
-
-* Control who can use your data, and share the dashboard with a small or large audience.
-
-* Generate reports based on your findings.
-
-To begin, open the main menu, click *Dashboard*, then click *Create dashboard*.
+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]
 
-[float]
-[[dashboard-read-only-access]]
-=== [xpack]#Read only access#
-If you see
-the read-only icon in the application header,
-then you don't have sufficient privileges to create and save dashboards. The buttons to create and edit
-dashboards are not visible. For more information, see <<xpack-security-authorization>>.
+[[tsvb]]
 
-[role="screenshot"]
-image::images/dashboard-read-only-badge.png[Example of Dashboard read only access indicator in Kibana header]
+Dashboards support many types of panels, and provide several editors that you can use to create panels.
 
-[float]
-[[types-of-panels]]
-== Types of panels
-
-Panels contain everything you need to tell a story about you data, including visualizations,
-interactive controls, Markdown, and more.
-
-[cols="50, 50"]
+[cols="2"]
 |===
 
-a| *Area*
+| <<create-panels-with-lens,Lens>>
+| The drag and drop editor that creates visualizations of your data. *Lens* is recommended for most users.
 
-Displays data points, connected by a line, where the area between the line and axes are shaded.
-Use area charts to compare two or more categories over time, and display the magnitude of trends.
+| <<maps,Maps>>
+| Create beautiful displays of your geographical data.
 
-| image:images/area.png[Area chart]
+| <<add-panels-with-advanced-editors,Advanced editors>>
+| Visualize time series data with *TSVB* or *Timelion*, or create a custom visualization using *Vega* or *Vega-Lite*.
 
-a| *Stacked area*
+| <<add-aggregation-based-visualization-panels,Aggregation-based visualization panels>>
+| Build most visualization types using {es} <<aggregation-reference,aggregations>>. 
 
-Displays the evolution of the value of several data groups. The values of each group are displayed
-on top of each other. Use stacked area charts to visualize part-to-whole relationships, and to show
-how each category contributes to the cumulative total.
+| <<enhance-dashboards,Tools>>
+| Add context to your panels with <<add-text,text>>, or add dynamic filters with <<add-controls,*Controls*>>.
 
-| image:images/stacked_area.png[Stacked area chart]
-
-a| *Bar*
-
-Displays bars side-by-side where each bar represents a category. Use bar charts to compare data across a
-large number of categories, display data that includes categories with negative values, and easily identify
-the categories that represent the highest and lowest values. Kibana also supports horizontal bar charts.
-
-| image:images/bar.png[Bar chart]
-
-a| *Stacked bar*
-
-Displays numeric values across two or more categories. Use stacked bar charts to compare numeric values between
-levels of a categorical value. Kibana also supports stacked horizontal bar charts.
-
-| image:images/stacked_bar.png[Stacked area chart]
-
-
-a| *Line*
-
-Displays data points that are connected by a line. Use line charts to visualize a sequence of values, discover
-trends over time, and forecast future values.
-
-| image:images/line.png[Line chart]
-
-a| *Pie*
-
-Displays slices that represent a data category, where the slice size is proportional to the quantity it represents.
-Use pie charts to show comparisons between multiple categories, illustrate the dominance of one category over others,
-and show percentage or proportional data.
-
-| image:images/pie.png[Pie chart]
-
-a| *Donut*
-
-Similar to the pie chart, but the central circle is removed. Use donut charts when you’d like to display multiple statistics at once.
-
-| image:images/donut.png[Donut chart]
-
-
-a| *Tree map*
-
-Relates different segments of your data to the whole. Each rectangle is subdivided into smaller rectangles, or sub branches, based on
-its proportion to the whole. Use treemaps to make efficient use of space to show percent total for each category.
-
-| image:images/treemap.png[Tree map]
-
-
-a| *Heat map*
-
-Displays graphical representations of data where the individual values are represented by colors. Use heat maps when your data set includes
-categorical data. For example, use a heat map to see the flights of origin countries compared to destination countries using the sample flight data.
-
-| image:images/heat_map.png[Heat map]
-
-a| *Goal*
-
-Displays how your metric progresses toward a fixed goal. Use the goal to display an easy to read visual of the status of your goal progression.
-
-| image:images/goal.png[Goal]
-
-
-a| *Gauge*
-
-Displays your data along a scale that changes color according to where your data falls on the expected scale. Use the gauge to show how metric
-values relate to reference threshold values, or determine how a specified field is performing versus how it is expected to perform.
-
-| image:images/gauge.png[Gauge]
-
-
-a| *Metric*
-
-Displays a single numeric value for an aggregation. Use the metric visualization when you have a numeric value that is powerful enough to tell
-a story about your data.
-
-| image:images/metric.png[Metric]
-
-
-a| *Data table*
-
-Displays your raw data or aggregation results in a tabular format. Use data tables to display server configuration details, track counts, min,
-or max values for a specific field, and monitor the status of key services.
-
-| image:images/data_table.png[Data table]
-
-
-a| *Tag cloud*
-
-Graphical representations of how frequently a word appears in the source text. Use tag clouds to easily produce a summary of large documents and
-create visual art for a specific topic.
-
-| image:images/tag_cloud.png[Tag cloud]
-
-
-a| *Maps*
-
-For all your mapping needs, use <<maps,Maps>>.
-
-| image:images/maps.png[Maps]
+| <<save-your-search,Saved search table>>
+| Display a previously saved search table from <<discover, *Discover*>>. The table results are not aggregated.
 
+| <<xpack-ml-anomalies,Machine Learning>>
+| Display a previously saved visualization of <<xpack-ml, machine learning>> anomaly detection data.
 
 |===
 
 [float]
-[[create-panels]]
-== Create panels
+[[create-dashboards]]
+== Create dashboards
 
-To create a panel, make sure you have {ref}/getting-started-index.html[data indexed into {es}] and an <<index-patterns,index pattern>>
-to retrieve the data from {es}. If you aren’t ready to use your own data, {kib} comes with several pre-built dashboards that you can test out. For more information,
-refer to <<add-sample-data, Explore {kib} using sample data>>.
+Dashboards provide you with the space where you add panels of your data.
 
-To begin, click *Create new*, then choose one of the following options on the
-*New Visualization* window:
+[float]
+[[dashboard-minimum-requirements]]
+=== Minimum requirements
 
-* Click on the type of panel you want to create, then configure the options.
+To create dashboards, you must meet the minimum requirements. 
 
-* Select an editor to help you create the panel.
+* If you need to set up {kib}, use https://www.elastic.co/cloud/elasticsearch-service/signup?baymax=docs-body&elektra=docs[our free trial].
 
-[role="screenshot"]
-image:images/Dashboard_add_new_visualization.png[Example add new visualization to dashboard]
+* Make sure you have {ref}/getting-started-index.html[data indexed into {es}] and an <<index-patterns,index pattern>>.
 
-{kib} provides you with several editors that help you create panels.
+* 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]
 [[create-panels-with-lens]]
-=== Create panels with Lens
+=== Create panels
 
-*Lens* is the simplest and fastest way to create powerful visualizations of your data. To use *Lens*, you drag and drop as many data fields
-as you want onto the visualization builder pane, and *Lens* uses heuristics to decide how to apply each field to the visualization.
+Choose the type of panel you want to create, then save the panel to the dashboard.
 
-With *Lens*, you can:
+. From the dashboard, choose one of the following options:
 
-* Use the automatically generated suggestions to change the visualization type.
-* Create visualizations with multiple layers and indices.
-* Change the aggregation and labels to customize the data.
+* To create a panel, click *Create panel*, then click the panel type on the *New visualization* window. *Lens* is recommended for most users. 
 
-[role="screenshot"]
-image::images/lens_drag_drop.gif[Drag and drop]
+* To add a saved panel, click *Add from library*, then select the panel you want to add. When a panel contains a stored query, both queries are applied.
 
-TIP: Drag-and-drop capabilities are available only when *Lens* knows how to use the data. If *Lens* is unable to automatically generate a
-visualization, configure the customization options for your visualization.
+. To save the panel, click *Save* in the toolbar, then configure the *Save visualization* options.
+
+.. Enter the *Title* and optional *Description*.
+
+.. From the *Tags* drop down, select any applicable tags. 
+
+.. Select *Add to Dashboard after saving*.
+
+.. Click *Save and return*.
+
+TIP: To access your saved panels, open the main menu, then click *Visualize*.
 
 [float]
-[[fiter-the-data-fields]]
-==== Filter the data fields
+[[arrange-panels]]
+[[moving-containers]]
+[[resizing-containers]]
+=== Arrange panels
 
-The data fields that are displayed are based on the selected <<index-patterns,index pattern>> and the <<set-time-filter,time filter>>.
+To compare the data in the panels, arrange the panels on the dashboard, or remove the panel from the dashboard.
 
-To view the data fields in a different index pattern, click the *Change Index Pattern* dropdown, then select a new one.
+. From the toolbar, click *Edit*, then use the following options:
 
-To filter the data fields:
+* To move, click and hold the panel header, then drag to the new location.
 
-* Enter the data field name in *Search field names*.
-* Click *Field filters*, then select the filter.
+* To resize, click the resize control, then drag to the new dimensions.
+
+* To delete, open the panel menu, then select *Delete from dashboard*.
+
+. To save your changes, click *Save* in the toolbar.
 
 [float]
-[[view-data-summaries]]
-==== View data field summaries
+[[search-or-filter-your-data]]
+=== Search or filter your data
 
-To help you decide exactly the data you want to display, get a quick summary of each data field. The summary shows the distribution of
-values within the specified time range.
-
-To view the data field summary information, navigate to the field, then click *i*.
+{kib} provides you with several ways to search your data and apply {es} filters. You can combine the filters with any panel-specific
+filters to display the data want to you see.
 
 [role="screenshot"]
-image::images/lens_data_info.png[Data summary window]
+image::dashboard/images/dashboard-filters.png[Labeled interface with semi-structured search, time filter, and additional filters]
 
-*Lens* shows a summary depending on the type of data: date fields show the time distribution, string fields show the top 10 values, and numeric fields show a detailed summary with the top 10 values and a value distribution.
+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, this query displays data only for the US:
+
+  . Enter `g`, and then select *geo.source*.
+  . Select *equals some value* and *US*, and then click *Update*.
+  . For a more complex search, try:
+
+    `geo.src : "US" and url.keyword : "https://www.elastic.co/downloads/beats/metricbeat"`
+
+Time filter::
+  Dashboards have a global time filter that restricts the data that displays, but individual panels can
+  override the global time filter.
+  
+  . To update the time filter, add a panel that displays time on the x-axis.
+
+  . Open the panel menu, then select *More > Customize time range*.
+
+  . On the *Customize panel time range* window, specify the new time range, then click *Add to panel*.
 
 [role="screenshot"]
-image::images/lens_data_info_documents.png[Data summary analyzed documents]
+image:images/time_range_per_panel.gif[Time range per dashboard panel]
 
-*Lens* uses a sample of 5,000 documents to perform the field analysis. The bottom line of the summary shows the percentage of sampled documents over all available documents.
+Additional filters with AND::
+  You can add filters to a dashboard, or pin filters to multiple places in {kib}. To add filters, using a basic editor or an advanced JSON editor for the {es} {ref}/query-dsl.html[query DSL].
+  
+  When you use more than one index pattern on a dashboard, the filter editor allows you to filter only one dashboard.
+  
+  To dynamically add filters, click a series on a dashboard. For example, to filter the dashboard to display only ios data:
 
-When *Lens* presents the top 10 values distribution, it also shows the percentage of "Other" values. For array value fields, the percentage distribution is considers each value in the array separate.
-
-[role="screenshot"]
-image::images/lens_data_info_other.png[Data summary window with Other]
-
-NOTE: the sum of all the entries and "Other" may be above 100% by a small amount, that is due to a rounding problem when presenting all values as integers.
+  . Click *Add filter*.
+  . Set *Field* to *machine.os*, *Operator* to *is*, and *Value* to *ios*.
+  . *Save* the filter.
+  . To remove the filter, click *x* next to the filter.
 
 [float]
-[[change-the-visualization-type]]
-==== Change the visualization type
+[[clone-panels]]
+=== Clone panels
 
-Use the automatically generated suggestions to change the visualization type, or manually select the type of visualization you want to view.
+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.
 
-*Suggestions* are shortcuts to alternative visualizations that *Lens* generates for you.
+. From the toolbar, click *Edit*. 
 
-[role="screenshot"]
-image::images/lens_suggestions.gif[Visualization suggestions]
-
-If you’d like to use a visualization type outside of the suggestions, click the visualization type, then select a new one.
-
-[role="screenshot"]
-image::images/lens_viz_types.png[]
-
-When there is an exclamation point (!) next to a visualization type, *Lens* is unable to transfer your data, but still allows you to make the change.
-
-[float]
-[[customize-the-data]]
-==== Customize the data
-
-For each visualization type, you can customize the aggregation and labels. The options available depend on the selected visualization type.
-
-. From the editor, click a data field, or click *Drop a field or click to add*.
-
-. Change the options, then click *Close*.
-
-[float]
-[[add-layers-and-indices]]
-==== Add layers and indices
-
-To compare and analyze data from different sources, you can visualize multiple data layers and indices. Multiple layers and indices are
-supported in area, line, and bar charts.
-
-To add a layer, click *+*, then drag and drop the data fields for the new layer.
-
-[role="screenshot"]
-image::images/lens_layers.png[Add layers]
-
-To view a different index, click the index name in the editor, then select a new one.
-
-[role="screenshot"]
-image::images/lens_index_pattern.png[Add index pattern]
-
-Ready to try out *Lens*? Refer to the <<lens-tutorial,step-by-step tutorial>>.
-
-[float]
-[[tsvb]]
-=== Create panels with TSVB
-
-*TSVB* is a time series data visualizer that allows you to use the full power of the Elasticsearch aggregation framework. To use *TSVB*,
-you can combine an infinite number of <<aggregation-reference,aggregations>> to display your data.
-
-With *TSVB*, you can:
-
-* Create visualizations, data tables, and markdown panels.
-* Create visualizations with multiple indices.
-* Change the aggregation and labels to customize the data.
+. Open the panel menu, then select *Clone panel*. 
 +
 [role="screenshot"]
-image::images/tsvb.png[TSVB UI]
+image:images/clone_panel.gif[clone panel]
++
+{kib} automatically saves the cloned panel in *Visualize*. To access the cloned panel, open the main menu, then click *Visualize*.
 
 [float]
-[[configure-the-data]]
-==== Configure the data
+[[explore-the-underlying-data]]
+=== Explore the underlying documents
 
-With *TSVB*, you can add and display multiple data sets to compare and analyze. {kib} uses many types of <<aggregation-reference,aggregations>> that you can use to build
-complex summaries of that data.
-
-. Select *Data*. If you are using *Table*, select *Columns*.
-. From the *Aggregation* drop down, select the aggregation you want to visualize.
-+
-If you don’t see any data, change the <<set-time-filter,time filter>>.
-+
-To add multiple aggregations, click *+*.
-. From the *Group by* drop down, select how you want to group or split the data.
-. To add another data set, click *+*.
-+
-When you have more than one aggregation, the last value is displayed, which is indicated by the eye icon.
-
-[float]
-[[change-the-data-display]]
-==== Change the data display
-
-To find the best way to display your data, *TSVB* supports several types of panels and charts.
-
-To change the *Time Series* chart type:
-
-. Click *Data > Options*.
-. Select the *Chart type*.
-
-To change the panel type, click on the panel options:
+Dashboard panels have a shortcut to view the underlying documents in *Discover*. Open the panel menu,
+then click *Explore underlying data*. *Discover* will be opened with the same time range and filters as the panel.
 
 [role="screenshot"]
-image::images/tsvb_change_display.gif[TSVB change the panel type]
+image::images/explore_data_context_menu.png[Explore underlying data from panel context menu]
+
+A second shortcut is disabled by default, and creates a new interaction when clicking on a chart.
+This shortcut is similar to a <<drilldowns, drilldown>>, but can show you data for only one series.
+To enable the chart interactivity shortcut, add the following to kibana.yml:
+
+["source","yml"]
+-----------
+xpack.discoverEnhanced.actions.exploreDataInChart.enabled: true
+-----------
+
+[role="screenshot"]
+image::images/explore_data_in_chart.png[Explore underlying data from chart]
+
+TIP: *Explore underlying data* is available only for visualization panels with a single index pattern.
 
 [float]
-[[custommize-the-data]]
-==== Customize the data
+[[download-csv]]
+=== Download panel data as CSV
 
-View data in a different <<index-patterns,index pattern>>, and change the data label name and colors. The options available depend on the panel type.
+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.
 
-To change the index pattern, click *Panel options*, then enter the new *Index Pattern*.
-
-To override the index pattern for a data set, click *Data > Options*. Select *Yes* to override, then enter the new *Index pattern*.
-
-To change the data labels and colors:
-
-. Click *Data*.
-. Enter the *Label* name, which *TSVB* uses on the legends and data labels.
-. Click the color picker, then select the color for the data.
+[role="xpack"]
+Lens::
+Open the *Lens* panel menu, then select *More > Download as CSV*.
 +
 [role="screenshot"]
-image::images/tsvb_color_picker.png[TSVB color picker]
+image::images/download_csv_context_menu.png[Download as CSV from panel context menu]
 
-[float]
-[[add-annotations]]
-==== Add annotations
+All panels::
+  . Open the panel menu, then select *Inspect*.
 
-You can overlay annotation events on top of your *Time Series* charts. The options available depend on the data source.
-
-To begin, click *Annotations*, click *Add data source*, then configure the options.
+  . Click *Download CSV*, then select the CSV type from the dropdown. The *Formatted CSV* contains
+    human-readable dates and numbers, while the *Unformatted* option is for computer use.
 
 [role="screenshot"]
-image::images/tsvb_annotations.png[TSVB annotations]
+image:images/Dashboard_inspect.png[Inspect in dashboard]
 
 [float]
-[[filter-the-panel]]
-==== Filter the panel
+[[save-the-dashboard]]
+=== Save the dashboard
 
-The data that displays on the panel is based on the <<index-patterns,index pattern>> and <<set-time-filter,time filter>>.
-You can filter the data on the panels using the <<lucene-query,Lucene query syntax>>.
+When you're finished making changes, save the dashboard.
 
-Click *Panel options*, then enter the syntax in the *Panel Filter* field.
+. From the toolbar, click *Save*.
 
-If you want to ignore filters from all of {kib}, select *Yes* for *Ignore global filter*.
+. Enter the dashboard *Title* and an optional *Description*.
+
+. From the *Tags* dropdown, select the tags you want to apply.
+
+. To save the time range, select *Store time with dashboard*.
+
+. Click *Save*.
 
 [float]
-[[vega]]
-=== Create custom panels with Vega
+[[share-the-dashboard]]
+=== Share the dashboard
 
-Build custom visualizations using *Vega* and *Vega-Lite*, backed by one or more data sources including {es}, Elastic Map Service,
-URL, or static data. Use the {kib} extensions to embed *Vega* in your dashboard, and add interactive tools.
+To share the dashboard with a larger audience, click *Share* in the toolbar, then choose one of the following options:
 
-Use *Vega* and *Vega-Lite* when you want to create a visualization for:
+* *Embed code* &mdash; Embed the dashboard as an iframe on a web page. Embedded dashboards are fully interactive, but you can
+  hide some parts of the dashboard using the menu options. User authentication is required, which the user provides or via reverse proxy. 
+  <<anonymous-authentication, Anonymous access>> is also supported. For more details,
+  learn about <<kibana-authentication>>.
 
-* Aggregations that use `nested` or `parent/child` mapping
-* Aggregations without an index pattern
-* Queries that use custom time filters
-* Complex calculations
-* Extracting data from _source instead of aggregations
-* Scatter charts, sankey charts, and custom maps
-* Using an unsupported visual theme
+* *Permalinks* &mdash; Share a direct link to a {kib} dashboard. User authentication is required.
 
-[role="screenshot"]
-image::images/vega.png[Vega UI]
+* *PDF Reports* &mdash; Generate a PDF report. For more information, refer to <<reporting-getting-started,Reporting>>.
 
-*Vega* and *Vega-Lite*  are declarative formats that:
-
-* Create complex visualizations
-* Use JSON and a different syntax for declaring visualizations
-* Are not fully interchangeable
-
-For more information about *Vega* and *Vega-Lite*, refer to:
-
-* <<vega-lite-tutorial-create-your-first-visualizations,Create your first visualization>>
-* <<vega-tutorial-update-kibana-filters-from-vega,Update Kibana filters>>
-* <<reference-for-kibana-extensions,Reference for Kibana extensions>>
-* <<resources-and-examples,Resources and examples>>
+* *PNG Reports* &mdash; Generate a PNG report. For more information, refer to <<reporting-getting-started,Reporting>>.
 
 [float]
-[[timelion]]
-=== Create panels with Timelion
+[[import-dashboards]]
+=== Export the dashboard
 
-*Timelion* is a time series data visualizer that enables you to combine independent data sources within a single visualization.
-
-*Timelion* is driven by a simple expression language that you use to:
-
-* Retrieve time series data
-* Perform calculation to tease out the answers to complex questions
-* Visualize the results
-
-[role="screenshot"]
-image::images/timelion.png[Timelion UI]
-
-NOTE: In 7.0 and later, *Timelion* app is deprecated. In 8.0 and later, *Timelion* app is removed from {kib}. To prepare for the removal of *Timelion* app, you must migrate *Timelion* app worksheets to a dashboard.
-For migration information, refer to <<deprecation-v7.10.0>>.
-Only *Timelion* app is deprecated. {kib} continues to support *Timelion*
-visualizations in *Dashboard*, *Visualize*, and *Canvas*.
-
-Ready to try out Timelion? For step-by-step tutorials, refer to:
-
-* <<timelion-tutorial-create-time-series-visualizations,Create time series visualizations>>
-* <<timelion-tutorial-create-visualizations-with-mathematical-functions,Create visualizations with mathematical functions>>
-* <<timelion-tutorial-create-visualizations-withconditional-logic-and-tracking-trends,Create visualizations with conditional logic and tracking trends>>
-
-[float]
-[[save-panels]]
-== Save panels
-
-When you’ve finished making changes, save the panels.
-
-. In the toolbar, click *Save*.
-. Add the *Title* and optional *Description*.
-. Click *Save and return*.
-
-[float]
-[[add-existing-panels]]
-== Add existing panels
-
-Add panels that you’ve already created to your dashboard.
-
-On the dashboard, click *Add an existing*, then select the panel you want to add.
-
-When a panel contains a stored query, both queries are applied.
-
-[role="screenshot"]
-image:images/Dashboard_add_visualization.png[Example add visualization to dashboard]
-
-To make changes to the panel, put the dashboard in *Edit* mode, then select the edit option from the panel menu.
-The changes you make appear in every dashboard that uses the panel, except if you edit the panel title. Changes to the panel title appear only on the dashboard where you made the change.
-
-[float]
-[[save-dashboards]]
-== Save dashboards
-
-When you’ve finished adding the panels, save the dashboard.
-
-. In the toolbar, click *Save*.
-
-. Enter the dashboard *Title* and optional *Description*, then *Save* 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::edit-dashboards.asciidoc[]
+include::lens.asciidoc[]
 
-include::explore-dashboard-data.asciidoc[]
+include::advanced-editors.asciidoc[]
+
+include::aggregation-based.asciidoc[]
+
+include::enhance-dashboards.asciidoc[]
 
 include::drilldowns.asciidoc[]
 
-include::share-dashboards.asciidoc[]
-
-include::tutorials.asciidoc[]
-
 include::aggregation-reference.asciidoc[]
-
-include::vega-reference.asciidoc[]

docs/user/dashboard/download-underlying-data.asciidoc

@@ -1,15 +0,0 @@
-[float]
-[role="xpack"]
-[[download_csv]]
-=== Download CSV
-
-To download the underlying data of the Lens panels on your dashboard, you can use the *Download as CSV* option.
-
-TIP: The *Download as CSV* option supports multiple CSV file downloads from the same Lens visualization out of the box, if configured: for instance with multiple layers on a bar chart.
-
-To use the *Download as CSV* option: 
-
-* Click the from the panel menu, then click *Download as CSV*.
-+
-[role="screenshot"]
-image::images/download_csv_context_menu.png[Download as CSV from panel context menu]

docs/user/dashboard/drilldowns.asciidoc

@@ -14,11 +14,11 @@ Third-party developers can create drilldowns. To learn how to code drilldowns, r
 {kib} supports two types of drilldowns.
 
 [NOTE]
-==============================================
+=====================================
 Some drilldowns are paid subscription features, while others are free.
 For a comparison of the Elastic subscription levels,
 refer https://www.elastic.co/subscriptions[the subscription page].
-==============================================
+=====================================
 
 [float]
 [[dashboard-drilldowns]]

docs/user/dashboard/edit-dashboards.asciidoc

@@ -1,130 +0,0 @@
-[[edit-dashboards]]
-== Edit dashboards
-
-Now that you have added panels to your dashboard, you can add filter panels to interact with the data, and Markdown panels to add context to the dashboard. 
-To make your dashboard look the way you want, use the editing options.
-
-[float]
-[[add-controls]]
-=== Add controls
-
-To filter the data on your dashboard in real-time, add a *Controls* panel.
-
-You can add two types of *Controls*:
-
-* Options list — Filters content based on one or more specified options. The dropdown menu is dynamically populated with the results of a terms aggregation. 
-For example, use the options list on the sample flight dashboard when you want to filter the data by origin city and destination city.
-
-* Range slider — Filters data within a specified range of numbers. The minimum and maximum values are dynamically populated with the results of a 
-min and max aggregation. For example, use the range slider when you want to filter the sample flight dashboard by a specific average ticket price.
-
-[role="screenshot"]
-image::images/dashboard-controls.png[]
-
-To configure *Controls* for your dashboard:
-
-. Click *Options*, then configure the following:
-
-* *Update Kibana filters on each change* — When selected, all interactive inputs create filters that refresh the dashboard. When unselected,
- {kib} filters are created only when you click *Apply changes*.
-
-* *Use time filter* &mdash; When selected, the aggregations that generate the options list and time range are connected to the <<set-time-filter,time filter>>.
-
-* *Pin filters to global state* &mdash; When selected, all filters created by interacting with the inputs are automatically pinned.
-
-. Click *Update*.
-
-[float]
-[[add-markdown]]
-=== Add Markdown
-
-*Markdown* is a text entry field that accepts GitHub-flavored Markdown text. When you enter the text, the tool populates the results on the dashboard. 
-
-Use Markdown when you want to add context to the other panels on your dashboard, such as important information, instructions and images.
-
-For information about GitHub-flavored Markdown text, click *Help*.
-
-For example, when you enter:
-
-[role="screenshot"]
-image::images/markdown_example_1.png[]
-
-The following instructions are displayed:
-
-[role="screenshot"]
-image::images/markdown_example_2.png[]
-
-Or when you enter:
-
-[role="screenshot"]
-image::images/markdown_example_3.png[]
-
-The following image is displayed:
-
-[role="screenshot"]
-image::images/markdown_example_4.png[]
-
-[float]
-[[arrange-panels]]
-[[moving-containers]]
-[[resizing-containers]]
-=== Arrange panels
-
-To make your dashboard panels look exactly how you want, you can move, resize, customize, and delete them.
-
-Put the dashboard in *Edit* mode, 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 delete, open the panel menu, then select *Delete from dashboard*. When you delete a panel from the dashboard, the 
-visualization or saved search from the panel is still available in Kibana.
-
-[float]
-[[sync-colors]]
-=== Synchronize colors
-
-By default, dashboard panels that share a non-gradient based color palette will synchronize their color assignment to improve readability.
-Color assignment is based on the series name, and the total number of colors is based on the number of unique series names.
-
-The color synchronizing logic can make the dashboard less readable when there are too many unique series names. It is possible to disable the synchronization behavior:
-
-. Put the dashboard in *Edit* mode. 
-
-. Click the "Options" button in the top navigation bar.
-
-. Disable "Sync color palettes across panels".
-
-[float]
-[[clone-panels]]
-=== Clone panels
-
-To duplicate a panel and its configured functionality, clone the panel. Cloned panels support all of the original functionality, 
-including renaming, editing, and cloning. 
-
-. Put the dashboard in *Edit* mode. 
-
-. For the panel you want to clone, open the panel menu, then select *Clone panel*. 
-
-Cloned panels appear beside the original, and move other panels down to make room when necessary. 
-All cloned visualization panels appear in the visualization list.
-
-[role="screenshot"]
-image:images/clone_panel.gif[clone panel]
-
-[float]
-[[dashboard-customize-filter]]
-=== Customize time ranges
-
-You can configure each visualization, saved search, and map on your dashboard
-for a specific time range. For example, you might want one visualization to show
-the monthly trend for CPU usage and another to show the current CPU usage.
-
-From the panel menu, select *Customize time range* to expose a time filter
-dedicated to that panel. Panels that are not restricted by a specific
-time range are controlled by the
-<<set-time-filter,time filter>>.
-
-[role="screenshot"]
-image:images/time_range_per_panel.gif[Time range per dashboard panel]

docs/user/dashboard/enhance-dashboards.asciidoc

@@ -0,0 +1,71 @@
+[[enhance-dashboards]]
+== Enhance dashboards
+
+Now that you have added panels to your dashboard, you can add filter panels to interact with the data, and Markdown panels to add context to the data. 
+To make your dashboard look the way you want, use the editing options.
+
+[float]
+[[add-controls]]
+=== Add controls
+
+To filter the data on your dashboard in real-time, add a *Controls* panel.
+
+{kib} supports two types of *Controls*:
+
+* *Options list* — Filters content based on one or more specified options. The dropdown menu is dynamically populated with the results of a terms aggregation. 
+For example, use the options list on the sample flight dashboard when you want to filter the data by origin city and destination city.
+
+* *Range slider* — Filters data within a specified range of numbers. The minimum and maximum values are dynamically populated with the results of a 
+min and max aggregation. For example, use the range slider when you want to filter the sample flight dashboard by a specific average ticket price.
++
+[role="screenshot"]
+image::images/dashboard-controls.png[]
+
+. From the dashboard, click *Create panel*.
+
+. On the *New Visualization* window, click *Controls*.
+
+. Click *Options*, then configure the following, then click *Update*:
+
+* *Update {kib} filters on each change* — When selected, all interactive inputs create filters that refresh the dashboard. When unselected,
+ {kib} filters are created only when you click *Apply changes*.
+
+* *Use time filter* &mdash; When selected, the aggregations that generate the options list and time range are connected to the <<set-time-filter,time filter>>.
+
+* *Pin filters for all applications* &mdash; When selected, all filters created by interacting with the inputs are automatically pinned.
+
+[float]
+[[add-text]]
+=== Add text
+
+Add text panels with *Markdown* when you want to provide context to the other panels on your dashboard, such as important information, instructions, and images.
+
+*Markdown* is a text entry field that accepts GitHub-flavored Markdown text. For information about GitHub-flavored Markdown text, click *Help*.
+
+. From the dashboard, click *Create panel*.
+
+. On the *New Visualization* window, click *Text*.
+
+. In the *Markdown* field, enter the text, then click *Update*.
+
+For example, when you enter:
+
+[role="screenshot"]
+image::images/markdown_example_1.png[]
+
+The following instructions are displayed:
+
+[role="screenshot"]
+image::images/markdown_example_2.png[]
+
+Or when you enter:
+
+[role="screenshot"]
+image::images/markdown_example_3.png[]
+
+The following image is displayed:
+
+[role="screenshot"]
+image::images/markdown_example_4.png[]
+
+

docs/user/dashboard/explore-underlying-data.asciidoc

@@ -1,27 +0,0 @@
-[float]
-[[explore-the-underlying-data]]
-=== Explore the underlying data for panels
-
-To explore the underlying data of the panels on your dashboard, {kib} opens *Discover*,
-where you can view and filter the data in the visualization panel. When {kib} opens *Discover*, the index pattern, filters, query, and time range for the visualization continue to apply.
-
-TIP: The *Explore underlying data* option is available only for visualization panels with a single index pattern.
-
-To use the *Explore underlying data* option: 
-
-* Click the from the panel menu, then click *Explore underlying data*.
-+
-[role="screenshot"]
-image::images/explore_data_context_menu.png[Explore underlying data from panel context menu]
-
-* Interact with the chart, then click *Explore underlying data* on the menu that appears.
-+
-[role="screenshot"]
-image::images/explore_data_in_chart.png[Explore underlying data from chart]
-+
-To enable, open `kibana.yml`, then add the following:
-
-["source","yml"]
------------
-xpack.discoverEnhanced.actions.exploreDataInChart.enabled: true
------------

docs/user/dashboard/lens-end-to-end/lens-end-to-end.asciidoc

@@ -0,0 +1,453 @@
+[float]
+[[lens-end-to-end]]
+== Tutorial: Analyze website data on a dashboard
+
+Most dashboards use similar types of analysis to answer key questions. In this tutorial you will base your analysis off of {kib} sample data which resembles logs from the Apache web server.
+
+When you're finished creating the dashboard, you'll be able to answer the following questions:
+
+* How many users have visited your website?
+* What is the distribution of visitors by operating system? 
+* What is the average of bytes transfer per day?
+* What is the health of your website?
+* What is the traffic for your website by the hour?
+* What is the percentage of small compared to large transferred files?
+* What are the top social media sources of website traffic, and from what countries?
+
+[discrete]
+[[add-the-sample-web-logs-data]]
+=== Add the data and create the dashboard
+
+To create visualizations of the website traffic data, add the data set, then create the dashboard.
+
+. From the *Home* page, click *Try our sample data*.
+
+. From *Sample web logs*, click *Add data*.
+
+. Open the main menu, click *Dashboard*.
+
+. On the *Dashboards* page, click *Create dashboard*.
+
+[discrete]
+[[donut-vis]]
+=== View the distribution of visitors by operating system
+
+To determine the operating systems you should continue to support, and the importance of mobile traffic from iOS devices, 
+create a donut chart that displays the top operating systems that your visitors use to access your webiste.
+
+. From the dashboard, click *Create panel*, then click *Lens* on the *New visualization* window.
+
+. Make sure the *kibana_sample_data_logs* index appears, and the <<set-time-filter,time filter>> is set to *Last 90 days*.
+
+. From the *Chart Type* dropdown, select *Donut*.
+
+. From the *Available fields* list, drag and drop the data fields to the *Drop a field or click to add* fields in the editor.
+
+.. Drag and drop *clientip* to the *Size by* field.
+
+.. Drag and drop *machine.os.keyword* to the *Slice by* field.
++
+[role="screenshot"]
+image::images/lens_end_to_end_2_1_1.png[Donut chart with clientip and machine.os.keyword fields]
+
+. Change the color palette. 
+
+.. From the editor, click *Top values of machine.os.keyword*. 
+
+.. From the *Color palette* dropdown, select *Compability*.
+
+.. Click *Close*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_2_1.png[Donut chart with open config panel]
+
+. Save the visualization, then add it to the dashboard.
+
+.. From the toolbar, click *Save*.
+
+..  In the *Title* field, enter `Visitors by OS`. 
+
+.. Select *Add to dashboard after saving*.
+
+.. Click *Save and return*.
+
+[discrete]
+[[mixed-multiaxis]]
+=== View the average of bytes transfer per day
+
+To prevent potential server failures and optimize the cost of website maintenance, create an area chart that displays the average of bytes transfer, 
+then add a line chart layer to compare the data to the number of visitors to your website.  
+
+. From the dashboard, click *Create panel*, then click *Lens* on the *New visualization* window.
+
+. Make sure the *kibana_sample_data_logs* index appears.
+
+. From the *Available fields* list, drag and drop *bytes* to the visualization builder.
+
+. To zoom in on the data you want to view, click and drag your cursor across the bars. 
++
+[role="screenshot"]
+image::images/lens_end_to_end_3_1_1.gif[Zoom in on the data]
+
+. Change the *timestamp* interval.
+
+.. From the editor, click *timestamp*.
+
+.. Select *Customize time interval*.
+
+.. Change the *Minimum interval* to `1 days`.
++
+[role="screenshot"]
+image::images/lens_end_to_end_3_1.png[Customize time interval]
+
+.. Click *Close*.
+
+. From the *Chart Type* dropdown, select *Area*.
+
+[discrete]
+[[add-a-data-layer]]
+==== Add the line chart layer
+
+To compare the average of bytes transfer to the number of users that visit your website, add a line chart layer.
+
+. From the editor, click *+*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_3_2.png[Add new layer button]
+
+. From the new layer editor, click the *Chart type* dropdown, then click the line chart.
++
+[role="screenshot"]
+image::images/lens_end_to_end_3_3.png[Change layer type]
++
+The chart type for the visualization changes to *Mixed XY*.
+
+. From the *Available fields* list, drag and drop the data fields to the *Drop a field or click to add* fields in the editor.
+
+.. Drag and drop *timestamp* to the *Horizontal axis* field.
+
+.. Drag and drop *clientip* to the *Vertical axis* field.
+
+. Change the *timestamp* interval.
+
+.. From the editor, click *timestamp* in the line chart layer.
+
+.. Select *Customize time interval*.
+
+.. Change the *Minimum interval* to `1 days`.
+
+.. Click *Close*.
+
+. Change the *Unique count of clientip* label and color.
+
+.. From the editor, click *Unique count of clientip*.
+
+.. In the *Display name* field, enter `Unique visitors` in the line chart layer.
+
+.. In the *Series color* field, enter *#CA8EAE*.
+
+.. Click *Close*.
+
+[discrete]
+[[configure-the-multiaxis-chart]]
+==== Configure the y-axes
+
+There is a significant difference between the *timestamp per day* and *Unique visitors* data, which makes the *Unique visitors* data difficult to read. To improve the readability, 
+display the *Unique visitors* data along a second y-axis, then change the formatting. When functions contain multiple formats, separate axes are created by default. 
+
+. From the editor, click *Unique visitors* in the line chart layer.
+
+.. For *Axis side*, click *Right*.
+
+.. Click *Close*.
+
+. From the editor, click *Average of bytes* in the area chart layer. 
+
+.. From the *Value format* dropdown, select *Bytes (1024)*. 
++
+[role="screenshot"]
+image::images/lens_end_to_end_3_4.png[Multiaxis chart]
+
+.. Click *Close*.
+
+[discrete]
+[[lens-legend-position]]
+==== Change the legend position and save the visualization
+
+The visualization is done, but the legend uses a lot of space. Change the legend position to the top of the chart, then save the visualization and add it to the dashboard.
+
+. From the *Legend* dropdown, select the top position.
++
+[role="screenshot"]
+image::images/lens_end_to_end_3_5.png[legend position]
+
+. Save the visualization, then add it to the dashboard.
+
+.. From the toolbar, click *Save*.
+
+..  In the *Title* field, enter `Average Bytes vs. Unique Visitors`. 
+
+.. Select *Add to dashboard after saving*.
+
+.. Click *Save and return*.
+
+[discrete]
+[[percentage-stacked-area]]
+=== View the health of your website 
+
+To detect unusual traffic, bad website links, and server errors, create a percentage stacked area chart that displays the associated response codes.
+
+. From the dashboard, click *Create panel*, then click *Lens* on the *New visualization* window.
+
+. Make sure the *kibana_sample_data_logs* index appears.
+
+. From the *Available fields* list, drag and drop the data fields to the *Drop a field or click to add* fields in the editor.
+
+.. Drag and drop *Records* to the *Vertical axis* field.
+
+.. Drag and drop *@timestamp* to the *Horizontal axis* field.
+
+. From the *Chart Type* dropdown, select *Percentage bar*.
+
+. To remove the vertical axis label, click *Left axis*, then deselect *Show*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_4_3.png[Turn off axis name]
+
+[discrete]
+[[add-the-response-code-filters]]
+==== Add the response code filters
+
+For each response code that you want to display, create a filter. 
+
+. From the editor, click the *Drop a field or click to add* field for *Break down by*. 
+
+. From *Select a function*, click *Filters*.
+
+. Add the filter for the successful response codes. 
+
+.. Click *All records*.
+
+.. In the *KQL* field, enter `response.keyword>=200 AND response.keyword<300`. 
+
+.. In the *Label* field, enter `2XX`.
++
+[role="screenshot"]
+image::images/lens_end_to_end_4_1.png[First filter in filters aggregation]
+
+.. Press Return.
+
+. Add the filter for the redirect codes. 
+
+.. Click *Add a filter*.
+
+.. In the *KQL* field, enter `response.keyword>=300 AND response.keyword<400`. 
+
+.. In the *Label* field, enter `3XX`, then press Return.
+
+. Add the filter for the client error codes. 
+
+.. Click *Add a filter*.
+
+.. In the *KQL* field, enter `response.keyword>=400 AND response.keyword<500`. 
+
+.. In the *Label* field, enter `4XX`, then press Return.
+
+. Add the filter for the server error codes. 
+
+.. Click *Add a filter*.
+
+.. In the *KQL* field, enter `response.keyword>=500 AND response.keyword<600`. 
+
+.. In the *Label* field, enter `5XX`, then press Return.
+
+. To change the color pallette, select *Status* from the *Color palette* dropdown.
+
+.. Click *Close*.
+
+. Save the visualization, then add it to the dashboard.
+
+.. From the toolbar, click *Save*.
+
+..  In the *Title* field, enter `Response Codes Over Time`. 
+
+.. Select *Add to dashboard after saving*.
+
+.. Click *Save and return*.
+
+[discrete]
+[[histogram]]
+=== View the traffic for your website by the hour 
+
+To find the best time to shut down your website for maintenance, create a histogram that displays the traffic for your website by the hour.
+
+. From the dashboard, click *Create panel*, then click *Lens* on the *New visualization* window.
+
+. Make sure the *kibana_sample_data_logs* index appears.
+
+. From the *Available fields* list, drag and drop *bytes* to *Vertical axis* in the editor, then configure the options.
+
+.. Click *Average of bytes*.
+
+.. From *Select a function*, click *Sum*.
+
+.. In the *Display name* field, enter `Transferred bytes`.
+
+.. From the *Value format* dropdown, select `Bytes (1024)`.
+
+.. Click *Close*.
+
+. From the *Available fields* list, drag and drop *hour_of_day* to *Horizontal axis* in the editor, then configure the options.
+
+.. Click *hour_of_day*.
+
+.. Click and slide the *Intervals granularity* slider until the horizontal axis displays hourly intervals.
++
+[role="screenshot"]
+image::images/lens_end_to_end_5_2.png[Create custom ranges]
+
+. Save the visualization, then add it to the dashboard.
+
+.. From the toolbar, click *Save*.
+
+..  In the *Title* field, enter `Hourly Traffic Distribution`. 
+
+.. Select *Add to dashboard after saving*.
+
+.. Click *Save and return*.
+
+[discrete]
+[[custom-ranges]]
+=== View the percent of small versus large transferred files 
+ 
+To determine if your users transfer more small files versus large files, create a pie chart that displays the percentage of each size. 
+
+. From the dashboard, click *Create panel*, then click *Lens* on the *New visualization* window.
+
+. Make sure the *kibana_sample_data_logs* index appears.
+
+. From the *Available fields* list, drag and drop *bytes* to *Vertical axis* in the editor, then configure the options.
+
+.. Click *Average of bytes*.
+
+.. From *Select a function*, click *Sum*.
+
+.. Click *Close*.
+
+. From the *Available fields* list, drag and drop *bytes* to *Break down by* in the editor, then specify the file size ranges.
+
+.. Click *bytes*.
+
+.. Click *Create custom ranges*, enter the following, then press Return:
+
+* *Ranges* &mdash; `0` -> `10240`
+
+* *Label* &mdash; `Below 10KB`
+
+.. Click *Add range*, enter the following, then press Return:
+
+* *Ranges* &mdash; `10240` -> `+∞`
+
+* *Label* &mdash; `Above 10KB`
++
+[role="screenshot"]
+image::images/lens_end_to_end_6_1.png[Custom ranges configuration]
+
+.. From the *Value format* dropdown, select *Bytes (1024)*.
+
+.. Click *Close*.
+
+. From the *Chart Type* dropdown, select *Pie*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_6_2.png[Files size distribution]
+
+. Save the visualization, then add it to the dashboard.
+
+.. From the toolbar, click *Save*.
+
+..  In the *Title* field, enter `File size distribution`. 
+
+.. Select *Add to dashboard after saving*.
+
+.. Click *Save and return*.
+
+[discrete]
+[[treemap]]
+=== View the top sources of website traffic
+
+To determine how users find out about your website and where your users are located, create a treemap that displays the percentage of users that 
+enter your website from specific social media websites, and the top countries where users are located.  
+
+. From the dashboard, click *Create panel*, then click *Lens* on the *New visualization* window.
+
+. Make sure the *kibana_sample_data_logs* index appears.
+
+. From the *Chart Type* dropdown, select *Treemap*.
+
+. From the *Available fields* list, drag and drop *Records* to the *Size by* field in the editor. 
+
+. From the editor, click the *Drop a field or click to add* field for *Group by*, then create a filter for each website traffic source.
+
+.. From *Select a function*, click *Filters*.
+
+.. Click *All records*, enter the following, then press Return:
+
+* *KQL* &mdash; `referer : *facebook.com*`
+
+* *Label* &mdash; `Facebook`
+
+.. Click *Add a filter*, enter the following, then press Return:
+
+* *KQL* &mdash; `referer : *twitter.com*`
+
+* *Label* &mdash; `Twitter`
+
+.. Click *Add a filter*, enter the following, then press Return:
+
+* *KQL* &mdash; `NOT referer : *twitter* OR NOT referer: *facebook.com*`
+
+* *Label* &mdash; `Other`
+
+.. Click *Close*.
+
+[discrete]
+[[add-the-countries]]
+==== Add the geographic data
+
+To determine the top countries where users are located, add the geographic data, then save and add the visualization to the dashboard.
+
+Compare the top sources of website traffic data to the top three countries. 
+
+. From the *Available fields* list, drag and drop *geo.src* to the visualization builder. 
+
+. To change the *Group by* order, click and drag *Top values of geo.src* so that it appears first in the editor.
++
+[role="screenshot"]
+image::images/lens_end_to_end_7_2.png[Treemap vis]
+
+. To view only the Facebook and Twitter data, remove the *Other* category. 
+
+.. From the editor, click *Top values of geo.src*.
+
+.. From the *Advanced* dropdown, deselect *Group other values as "Other"*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_7_3.png[Group other values as Other]
+
+.. Click *Close*.
+
+. Save the visualization, then add it to the dashboard.
+
+.. From the toolbar, click *Save*.
+
+..  In the *Title* field, enter `Traffic Source For Top 3 Countries`. 
+
+.. Select *Add to dashboard after saving*.
+
+.. Click *Save and return*.
+
+That's it! You've created a dashboard that provides you with a complete picture of your website data.
+
+[role="screenshot"]
+image::images/lens_end_to_end_dashboard.png[Final dashboard vis]

docs/user/dashboard/lens.asciidoc

@@ -0,0 +1,436 @@
+[[create-a-dashboard-of-panels-with-web-server-data]]
+== Tutorial: Create a dashboard of panels with web server data
+
+You collected data from your web server, and you want to visualize and analyze the data on a dashboard. To create dashboard panels of the data, open the *Lens* visualization builder, then  
+create the visualization panels that best display the data.
+
+[discrete]
+[[add-the-data-and-create-the-dashboard]]
+=== Add the data and create the dashboard
+
+To create visualizations of the data from the web server, add the data set, then create the dashboard.
+
+. From the {kib} *Home* page, click *Try our sample data*.
+
+. From *Sample web logs*, click *Add data*.
+
+. Open the main menu, click *Dashboard*.
+
+. Click *Create dashboard*.
+
+[float]
+[[open-and-set-up-lens]]
+=== Open and set up Lens
+
+With *Lens*, you identify the data fields you want to visualize, drag and drop the fields, then watch as
+*Lens* uses heuristics to apply the fields and create a visualization for you.
+
+. From the dashboard, click *Create panel*.
+
+. On the *New visualization* window, click *Lens*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_1_1.png[New visualization popover]
+
+. Make sure the *kibana_sample_data_logs* index appears.
++
+The list of fields are dependent on the <<index-patterns,index pattern>>, <<set-time-filter,time filter>>, and field filters. 
+
+[float]
+[[view-the-data-summaries]]
+=== View the data summaries
+
+For each field, *Lens* shows a summary depending on the type of data. Date fields show the time distribution, string fields show the top 10 values, 
+and numeric fields show a detailed summary with the top 10 values and a value distribution.
+
+To view the data summary for a field, click *i* next to the field.
+
+[role="screenshot"]
+image::images/lens_data_info_documents.png[Data summary analyzed documents]
+
+*Lens* uses a sample of 5,000 documents to perform the field analysis. The bottom line of the summary shows the percentage of sampled documents over all available documents.
+
+When *Lens* presents the top 10 values distribution, it also shows the percentage of *Other* values. For array value fields, the percentage distribution considers each value in the array as separate.
+
+[role="screenshot"]
+image::images/lens_data_info.png[Data summary window with Other]
+
+NOTE: The sum of all the *Other* fields can equal more than 100% by a small amount.
+
+[discrete]
+[[view-the-number-of-website-visitors]]
+=== View the number of website visitors
+
+To determine how many users have visited your website within the last 90 days, create a metric visualization, then add it to the dashboard.
+
+. Set the <<set-time-filter,time filter>> to *Last 90 days*.
+
+. From the *Chart Type* dropdown, select *Metric*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_1_2_1.png[Chart Type dropdown with Metric selected]
+
+. From the *Available fields* list, drag and drop *clientip* to the visualization builder.
++
+[role="screenshot"]
+image::images/lens_end_to_end_1_3.png[Changed type and dropped clientip field]
+
+. From the editor, click *Unique count of clientip*.
+
+.. In the *Display name* field, enter `Unique visitors`.
+
+.. Click *Close*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_1_4.png[Flyout config open]
+
+. *Save* the panel, enter `Unique visitors` in the *Title* field, then add the panel to the dashboard.
+
+[discrete]
+[[view-the-distribution-of-visitors-by-operating-system]]
+=== View the distribution of visitors by operating system
+
+To determine the operating systems you should continue to support, and the importance of mobile traffic from iOS devices, 
+create a donut chart that displays the top operating systems that your visitors used to access your website within the last 90 days.
+
+. Open *Lens*, then set the <<set-time-filter,time filter>> to *Last 90 days*.
+
+. From the *Chart Type* dropdown, select *Donut*.
+
+. From the *Available fields* list, drag and drop the data fields to the *Drop a field or click to add* fields in the editor.
+
+.. Drag and drop *clientip* to the *Size by* field.
+
+.. Drag and drop *machine.os.keyword* to the *Slice by* field.
++
+[role="screenshot"]
+image::images/lens_end_to_end_2_1_1.png[Donut chart with clientip and machine.os.keyword fields]
+
+. Change the color palette. 
+
+.. From the editor, click *Top values of machine.os.keyword*. 
+
+.. From the *Color palette* dropdown, select *Compatibility*.
+
+.. Click *Close*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_2_1.png[Donut chart with open config panel]
+
+. *Save* the panel, enter `Visitors by OS` in the *Title* field, then add the panel to the dashboard.
+
+[discrete]
+[[mixed-multiaxis]]
+=== View the average of bytes transfer per day
+
+To prevent potential server failures, and optimize the cost of website maintenance, create an area chart that displays the average of bytes transfer. To compare 
+the data to the number of visitors to your website, add a line chart layer.  
+
+. Open *Lens*.
+
+. From the *Available fields* list, drag and drop *bytes* to the visualization builder.
+
+. To zoom in on the data you want to view, click and drag your cursor across the bars. 
++
+[role="screenshot"]
+image::images/lens_end_to_end_3_1_1.gif[Zoom in on the data]
+
+. Change the *timestamp* interval.
+
+.. From the editor, click *timestamp*.
+
+.. Select *Customize time interval*.
+
+.. Change the *Minimum interval* to `1 days`, then click *Close*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_3_1.png[Customize time interval]
+
+. From the *Chart Type* dropdown, select *Area*.
+
+[discrete]
+[[add-a-data-layer]]
+==== Add the line chart layer
+
+To compare the average of bytes transfer to the number of users that visit your website, add a line chart layer.
+
+. From the editor, click *+*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_3_2.png[Add new layer button]
+
+. From the new layer editor, click the *Chart type* dropdown, then click the line chart.
++
+[role="screenshot"]
+image::images/lens_end_to_end_3_3.png[Change layer type]
++
+The chart type for the visualization changes to *Mixed XY*.
+
+. From the *Available fields* list, drag and drop the data fields to the *Drop a field or click to add* fields in the editor.
+
+.. Drag and drop *timestamp* to the *Horizontal axis* field.
+
+.. Drag and drop *clientip* to the *Vertical axis* field.
+
+. Change the *timestamp* interval.
+
+.. From the editor, click *timestamp* in the line chart layer.
+
+.. Select *Customize time interval*.
+
+.. Change the *Minimum interval* to `1 days`, then click *Close*.
+
+. Change the *Unique count of clientip* label and color.
+
+.. From the editor, click *Unique count of clientip*.
+
+.. In the *Display name* field, enter `Unique visitors` in the line chart layer.
+
+.. In the *Series color* field, enter *#CA8EAE*, then click *Close*.
+
+[discrete]
+[[configure-the-multiaxis-chart]]
+==== Configure the y-axes
+
+There is a significant difference between the *timestamp per day* and *Unique visitors* data, which makes the *Unique visitors* data difficult to read. To improve the readability, 
+display the *Unique visitors* data along a second y-axis, then change the formatting. When functions contain multiple formats, separate axes are created by default. 
+
+. From the editor, click *Unique visitors* in the line chart layer.
+
+. For *Axis side*, click *Right*, then click *Close*.
+
+[float]
+[[change-the-visualization-type]]
+==== Change the visualization type
+
+. From the editor, click *Average of bytes* in the area chart layer. 
+
+. From the *Value format* dropdown, select *Bytes (1024)*, then click *Close*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_3_4.png[Multiaxis chart]
+
+[discrete]
+[[lens-legend-position]]
+==== Change the legend position
+
+The visualization is done, but the legend uses a lot of space. Change the legend position to the top of the chart.
+
+. From the *Legend* dropdown, select the top position.
++
+[role="screenshot"]
+image::images/lens_end_to_end_3_5.png[legend position]
+
+. *Save* the panel, enter `Average Bytes vs. Unique Visitors` in the *Title* field, then add the panel to the dashboard.
+
+[discrete]
+[[percentage-stacked-area]]
+=== View the health of your website 
+
+To detect unusual traffic, bad website links, and server errors, create a percentage stacked area chart that displays the associated response codes.
+
+. Open *Lens*.
+
+. From the *Available fields* list, drag and drop the data fields to the *Drop a field or click to add* fields in the editor.
+
+.. Drag and drop *Records* to the *Vertical axis* field.
+
+.. Drag and drop *@timestamp* to the *Horizontal axis* field.
+
+. From the *Chart Type* dropdown, select *Percentage bar*.
+
+. To remove the vertical axis label, click *Left axis*, then deselect *Show*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_4_3.png[Turn off axis name]
+
+[discrete]
+[[add-the-response-code-filters]]
+==== Add the response code filters
+
+For each response code that you want to display, create a filter. 
+
+. From the editor, click the *Drop a field or click to add* field for *Break down by*. 
+
+. From *Select a function*, click *Filters*.
+
+. Add the filter for the successful response codes. 
+
+.. Click *All records*.
+
+.. In the *KQL* field, enter `response.keyword>=200 AND response.keyword<300`. 
+
+.. In the *Label* field, enter `2XX`, then press Return.
++
+[role="screenshot"]
+image::images/lens_end_to_end_4_1.png[First filter in filters aggregation]
+
+. Add the filter for the redirect codes. 
+
+.. Click *Add a filter*.
+
+.. In the *KQL* field, enter `response.keyword>=300 AND response.keyword<400`. 
+
+.. In the *Label* field, enter `3XX`, then press Return.
+
+. Add the filter for the client error codes. 
+
+.. Click *Add a filter*.
+
+.. In the *KQL* field, enter `response.keyword>=400 AND response.keyword<500`. 
+
+.. In the *Label* field, enter `4XX`, then press Return.
+
+. Add the filter for the server error codes. 
+
+.. Click *Add a filter*.
+
+.. In the *KQL* field, enter `response.keyword>=500 AND response.keyword<600`. 
+
+.. In the *Label* field, enter `5XX`, then press Return.
+
+. To change the color palette, select *Status* from the *Color palette* dropdown, then click *Close*.
+
+. *Save* the panel, enter `Response Codes Over Time` in the *Title* field, then add the panel to the dashboard.
+
+[discrete]
+[[histogram]]
+=== View the traffic for your website by the hour 
+
+To find the best time to shut down your website for maintenance, create a histogram that displays the traffic for your website by the hour.
+
+. Open *Lens*.
+
+. From the *Available fields* list, drag and drop *bytes* to *Vertical axis* in the editor, then configure the options.
+
+.. Click *Average of bytes*.
+
+.. From *Select a function*, click *Sum*.
+
+.. In the *Display name* field, enter `Transferred bytes`.
+
+.. From the *Value format* dropdown, select `Bytes (1024)`, then click *Close*.
+
+. From the *Available fields* list, drag and drop *hour_of_day* to *Horizontal axis* in the editor, then configure the options.
+
+.. Click *hour_of_day*.
+
+.. Click and slide the *Intervals granularity* slider until the horizontal axis displays hourly intervals.
++
+[role="screenshot"]
+image::images/lens_end_to_end_5_2.png[Create custom ranges]
+
+. *Save* the panel, enter `Hourly Traffic Distribution` in the *Title* field, then add the panel to the dashboard.
+
+[discrete]
+[[custom-ranges]]
+=== View the percent of small versus large transferred files 
+ 
+To determine if your users transfer more small files versus large files, create a pie chart that displays the percentage of each size. 
+
+. Open *Lens*.
+
+. From the *Available fields* list, drag and drop *bytes* to *Vertical axis* in the editor, then configure the options.
+
+.. Click *Average of bytes*.
+
+.. From *Select a function*, click *Sum*, then click *Close*.
+
+. From the *Available fields* list, drag and drop *bytes* to *Break down by* in the editor, then specify the file size ranges.
+
+.. Click *bytes*.
+
+.. Click *Create custom ranges*, enter the following, then press Return:
+
+* *Ranges* &mdash; `0` -> `10240`
+
+* *Label* &mdash; `Below 10KB`
+
+.. Click *Add range*, enter the following, then press Return:
+
+* *Ranges* &mdash; `10240` -> `+∞`
+
+* *Label* &mdash; `Above 10KB`
++
+[role="screenshot"]
+image::images/lens_end_to_end_6_1.png[Custom ranges configuration]
+
+.. From the *Value format* dropdown, select *Bytes (1024)*, then click *Close*.
+
+. From the *Chart Type* dropdown, select *Pie*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_6_2.png[Files size distribution]
+
+. *Save* the panel, enter `File size distribution` in the *Title* field, then add the panel to the dashboard.
+
+[discrete]
+[[treemap]]
+=== View the top sources of website traffic
+
+To determine how users find out about your website and where your users are located, create a treemap that displays the percentage of users that 
+enter your website from specific social media websites, and the top countries where users are located.  
+
+. Open *Lens*.
+
+. From the *Chart Type* dropdown, select *Treemap*.
+
+. From the *Available fields* list, drag and drop *Records* to the *Size by* field in the editor. 
+
+. From the editor, click the *Drop a field or click to add* field for *Group by*, then create a filter for each website traffic source.
+
+.. From *Select a function*, click *Filters*.
+
+.. Click *All records*, enter the following, then press Return:
+
+* *KQL* &mdash; `referer : *facebook.com*`
+
+* *Label* &mdash; `Facebook`
+
+.. Click *Add a filter*, enter the following, then press Return:
+
+* *KQL* &mdash; `referer : *twitter.com*`
+
+* *Label* &mdash; `Twitter`
+
+.. Click *Add a filter*, enter the following, then press Return:
+
+* *KQL* &mdash; `NOT referer : *twitter* OR NOT referer: *facebook.com*`
+
+* *Label* &mdash; `Other`
+
+.. Click *Close*.
+
+[discrete]
+[[add-the-countries]]
+==== Add the geographic data
+
+To determine the top countries where users are located, add the geographic data.
+
+Compare the top sources of website traffic data to the top three countries. 
+
+. From the *Available fields* list, drag and drop *geo.src* to the visualization builder. 
+
+. To change the *Group by* order, click and drag *Top values of geo.src* so that it appears first in the editor.
++
+[role="screenshot"]
+image::images/lens_end_to_end_7_2.png[Treemap vis]
+
+. To view only the Facebook and Twitter data, remove the *Other* category. 
+
+.. From the editor, click *Top values of geo.src*.
+
+.. From the *Advanced* dropdown, deselect *Group other values as "Other"*, then click *Close*.
++
+[role="screenshot"]
+image::images/lens_end_to_end_7_3.png[Group other values as Other]
+
+. *Save* the panel, enter `Traffic Source For Top 3 Countries` in the *Title* field, then add the panel to the dashboard.
+
+[float]
+== What's next?
+
+Your dashboard is complete and provides you with an overall picture of the data from your web server.
+
+[role="screenshot"]
+image::images/lens_end_to_end_dashboard.png[Final dashboard vis]

docs/user/dashboard/share-dashboards.asciidoc

@@ -1,27 +0,0 @@
-[[share-dashboards]]
-== Share dashboards
-
-[[embedding-dashboards]]
-Share your dashboard outside of {kib}.
-
-From the *Share* menu, you can:
-
-* Embed the code in a web page. Users must have {kib} access
-to view an embedded dashboard.
-* Share a direct link to a {kib} dashboard
-* Generate a PDF report
-* Generate a PNG report
-
-TIP: To create a link to a dashboard by title, use: +
-`${domain}/${basepath?}/app/dashboards#/list?title=${yourdashboardtitle}`
-
-TIP: When sharing a link to a dashboard snapshot, use the *Short URL*. Snapshot
-URLs are long and can be problematic for Internet Explorer and other
-tools. To create a short URL, you must have write access to {kib}.
-
-[float]
-[[import-dashboards]]
-=== Export the dashboard
-
-To export the dashboard, open the main menu, then click *Stack Management > Saved Objects*. For more information,
-refer to <<managing-saved-objects, Managing saved objects>>.

docs/user/dashboard/timelion.asciidoc

@@ -0,0 +1,532 @@
+[[create-panels-with-timelion]]
+=== Timelion
+
+Instead of using a visual editor to create charts, you define a graph by chaining functions together, using a timelion specific syntax. This syntax enables some features that classical point series charts don't offer - like drawing data from different indices or data sources into one graph.
+
+[NOTE]
+====
+Timelion app deprecation
+
+*Timelion* is still supported, the *Timelion app* is deprecated in 7.0, replaced by
+dashboard features. In 8.0 and later, the *Timelion app* is removed from {kib}. 
+To prepare for the removal of *Timelion app*, you must migrate *Timelion app* worksheets to a dashboard.
+
+For information on how to migrate *Timelion app* worksheets, refer to the 
+link:https://www.elastic.co/guide/en/kibana/current/release-notes-7.10.0.html#deprecation-v7.10.0[7.10.0 Release Notes].
+====
+
+[float]
+==== Timelion expressions
+
+Timelion functions always start with a dot, followed by the function name, followed by parentheses containing all the parameters to the function.
+
+The `.es` (or `.elasticsearch` if you are a fan of typing long words) function gathers data from {es} and draws it over time. By default the .es function will just count the number of documents, resulting in a graph showing the amount of documents over time.
+
+[float]
+==== Function parameters
+
+Functions can have multiple parameters, and so does the `.es` function. Each parameter has a name, that you can use inside the parentheses to set its value. The parameters also have an order, which is shown by the autocompletion or the documentation (using the Docs button in the top menu).
+
+If you don't specify the parameter name, timelion assigns the values to the parameters in the order, they are listed in the documentation.
+
+The fist parameter of the .es function is the parameter q (for query), which is a Query String used to filter the data for this series. You can also explicitly reference this parameter by its name, and I would always recommend doing so as soon as you are passing more than one parameter to the function. The following two expressions are thus equivalent:
+
+.es(*)
+.es(q=*)
+
+Multiple parameters are separated by comma. The .es function has another parameter called index, that can be used to specify an index pattern for this series, so the query won't be executed again all indexes (or whatever you changed the above mentioned setting to).
+
+.es(q=*, index=logstash-*)
+
+If the value of your parameter contains spaces or commas you have to put the value in single or double quotes. You can omit these quotes otherwise.
+
+.es(q='some query', index=logstash-*)
+
+
+[float]
+==== Tutorial: Create visualizations with Timelion 
+
+You collected data from your operating system using Metricbeat, and you want to visualize and analyze the data on a dashboard. To create panels of the data, use *Timelion* to 
+create a time series visualization, 
+
+[float]
+===== Add the data and create the dashboard
+
+Set up Metricbeat, then create the dashboard.
+
+. To set up Metricbeat, go to {metricbeat-ref}/metricbeat-installation-configuration.html[Metricbeat quick start: installation and configuration]
+
+. From {kib}, open the main menu, then click *Dashboard*.
+
+. On the *Dashboards* page, click *Create dashboard*.
+
+[float]
+===== Open and set up Timelion
+
+Open *Timelion* and change the time range. 
+
+. On the dashboard, click *Create panel*.
+
+. On the *New visualization* window, click *Aggregation based > Timelion*.
+
+. Change the <<set-time-filter,time range>> to *Last 7 days*.
+
+[float]
+[[timelion-tutorial-create-time-series-visualizations]]
+==== Create a time series visualization
+
+To compare the real-time percentage of CPU time spent in user space to the results offset by one hour, create a time series visualization.
+
+[float]
+[[define-the-functions]]
+==== Define the functions
+
+To track the real-time percentage of CPU, enter the following in the *Timelion Expression* field, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct')
+----------------------------------
+
+[float]
+[[compare-the-data]]
+==== Compare the data
+
+To compare two data sets, add another series, and offset the data back by one hour, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct'),
+.es(offset=-1h,
+    index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct')
+----------------------------------
+
+[float]
+[[add-label-names]]
+==== Add label names
+
+To easily distinguish between the two data sets, add label names, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(offset=-1h,index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct').label('last hour'),
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct').label('current hour')
+----------------------------------
+
+[float]
+[[add-a-title]]
+==== Add a title
+
+To make is easier for unfamiliar users to understand the purpose of the visualization, add a title, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(offset=-1h,
+    index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct')
+  .label('last hour'),
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct')
+  .label('current hour')
+  .title('CPU usage over time')
+----------------------------------
+
+[float]
+[[change-the-chart-type]]
+==== Change the appearance of the chart lines
+
+To differentiate between the current hour and the last hour, change the appearance of the chart lines, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(offset=-1h,
+    index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct')
+  .label('last hour')
+  .lines(fill=1,width=0.5),
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct')
+  .label('current hour')
+  .title('CPU usage over time')
+----------------------------------
+
+[float]
+[[change-the-line-colors]]
+==== Change the line colors
+
+*Timelion* supports standard color names, hexadecimal values, or a color schema for grouped data.
+
+To make the first data series stand out, change the line colors, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(offset=-1h,
+    index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct')
+  .label('last hour')
+  .lines(fill=1,width=0.5)
+  .color(gray),
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct')
+  .label('current hour')
+  .title('CPU usage over time')
+  .color(#1E90FF)
+----------------------------------
+
+[float]
+[[make-adjustments-to-the-legend]]
+==== Adjust the legend
+
+Move the legend to the north west position  with two columns, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(offset=-1h,
+    index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct')
+  .label('last hour')
+  .lines(fill=1,width=0.5)
+  .color(gray),
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='avg:system.cpu.user.pct')
+  .label('current hour')
+  .title('CPU usage over time')
+  .color(#1E90FF)
+  .legend(columns=2, position=nw) <1>
+----------------------------------
+
+[role="screenshot"]
+image::images/timelion-customize04.png[Final time series visualization]
+{nbsp}
+
+[float]
+==== Save the panel
+
+Save and add the panel to the dashboard.
+
+. From the toolbar, click *Save*.
+
+. Enter the *Title* and optional *Description*. 
+
+. From the *Tags* drop down, select any applicable tags. 
+
+. Select *Add to Dashboard after saving*.
+
+. Click *Save and return*.
+
+[float]
+[[timelion-tutorial-create-visualizations-with-mathematical-functions]]
+=== Visualize the inbound and outbound network traffic
+
+To create a visualization for inbound and outbound network traffic, use mathematical functions.
+
+[float]
+[[mathematical-functions-define-functions]]
+==== Define the functions
+
+To start tracking the inbound and outbound network traffic, enter the following in the *Timelion Expression* field, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(index=metricbeat*,
+    timefield=@timestamp,
+    metric=max:system.network.in.bytes)
+----------------------------------
+
+[float]
+[[mathematical-functions-plot-change]]
+==== Plot the rate of change
+
+To easily monitor the inbound traffic, plots the change in values over time, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(index=metricbeat*,
+    timefield=@timestamp,
+    metric=max:system.network.in.bytes)
+  .derivative()
+----------------------------------
+
+Add a similar calculation for outbound traffic, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(index=metricbeat*,
+    timefield=@timestamp,
+    metric=max:system.network.in.bytes)
+  .derivative(),
+.es(index=metricbeat*,
+    timefield=@timestamp,
+    metric=max:system.network.out.bytes)
+  .derivative()
+  .multiply(-1) <1>
+----------------------------------
+
+<1> `.multiply(-1)` converts the outbound network traffic to a negative value since the outbound network traffic is leaving your machine.
+`.multiply()` multiplies the data series by a number, the result of a data series, or a list of data series. 
+
+[float]
+[[mathematical-functions-convert-data]]
+==== Change the data metric
+
+To make the data easier to analyze, change the data metric from `bytes` to `megabytes`, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(index=metricbeat*,
+    timefield=@timestamp,
+    metric=max:system.network.in.bytes)
+  .derivative()
+  .divide(1048576),
+.es(index=metricbeat*,
+    timefield=@timestamp,
+    metric=max:system.network.out.bytes)
+  .derivative()
+  .multiply(-1)
+  .divide(1048576) <1>
+----------------------------------
+
+<1> `.divide()` accepts the same input as `.multiply()`, then divides the data series by the defined divisor.
+
+[float]
+[[mathematical-functions-add-labels]]
+==== Customize and format the visualization
+
+Customize and format the visualization using the following functions, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(index=metricbeat*,
+    timefield=@timestamp,
+    metric=max:system.network.in.bytes)
+  .derivative()
+  .divide(1048576)
+  .lines(fill=2, width=1)
+  .color(green)
+  .label("Inbound traffic")         
+  .title("Network traffic (MB/s)"), 
+.es(index=metricbeat*,
+    timefield=@timestamp,
+    metric=max:system.network.out.bytes)
+  .derivative()
+  .multiply(-1)
+  .divide(1048576)
+  .lines(fill=2, width=1)           
+  .color(blue)                     
+  .label("Outbound traffic")
+  .legend(columns=2, position=nw)
+----------------------------------
+
+[role="screenshot"]
+image::images/timelion-math05.png[Final visualization that displays inbound and outbound network traffic]
+{nbsp}
+
+[float]
+==== Save the panel
+
+Save and add the panel to the dashboard.
+
+. From the toolbar, click *Save*.
+
+. Enter the *Title* and optional *Description*. 
+
+. From the *Tags* drop down, select any applicable tags. 
+
+. Select *Add to Dashboard after saving*.
+
+. Click *Save and return*.
+
+[float]
+[[timelion-tutorial-create-visualizations-withconditional-logic-and-tracking-trends]]
+=== Detect outliers and discover patterns over time
+
+To easily detect outliers and discover patterns over time, modify the time series data with conditional logic and create a trend with a moving average.
+
+With Timelion conditional logic, you can use the following operator values to compare your data:
+
+[horizontal]
+`eq`:: equal
+`ne`:: not equal
+`lt`:: less than
+`lte`:: less than or equal to
+`gt`:: greater than
+`gte`:: greater than or equal to
+
+[float]
+[[conditional-define-functions]]
+==== Define the functions
+
+To chart the maximum value of `system.memory.actual.used.bytes`, enter the following in the *Timelion Expression* field, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='max:system.memory.actual.used.bytes')
+----------------------------------
+
+[float]
+[[conditional-track-memory]]
+==== Track used memory
+
+To track the amount of memory used, create two thresholds, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='max:system.memory.actual.used.bytes'),
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='max:system.memory.actual.used.bytes')
+  .if(gt,                             <1>
+      11300000000,                    <2>
+      .es(index=metricbeat-*,
+          timefield='@timestamp',
+          metric='max:system.memory.actual.used.bytes'),
+      null)
+    .label('warning')
+    .color('#FFCC11'),
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='max:system.memory.actual.used.bytes')
+  .if(gt,
+      11375000000,
+      .es(index=metricbeat-*,
+          timefield='@timestamp',
+          metric='max:system.memory.actual.used.bytes'),
+      null)
+  .label('severe')
+  .color('red')
+----------------------------------
+
+<1> `if()` compares each point to a number. When the condition is `true`, adjust the styling. When the condition is `false`, use the default styling.
+
+<2> *Timelion* conditional logic for the _greater than_ operator. In this example, the warning threshold is 11.3GB (`11300000000`), 
+and the severe threshold is 11.375GB (`11375000000`). If the threshold values are too high or low for your machine, adjust the values.
+
+[float]
+[[conditional-determine-trend]]
+==== Determine the trend
+
+To determine the trend, create a new data series, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='max:system.memory.actual.used.bytes'),
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='max:system.memory.actual.used.bytes')
+  .if(gt,11300000000,
+      .es(index=metricbeat-*,
+          timefield='@timestamp',
+          metric='max:system.memory.actual.used.bytes'),
+      null)
+      .label('warning')
+      .color('#FFCC11'),
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='max:system.memory.actual.used.bytes')
+  .if(gt,11375000000,
+      .es(index=metricbeat-*,
+          timefield='@timestamp',
+          metric='max:system.memory.actual.used.bytes'),
+      null).
+      label('severe')
+      .color('red'),
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='max:system.memory.actual.used.bytes')
+  .mvavg(10) <1>
+----------------------------------
+
+<1> `mvavg()` calculates the moving average over a specified period of time. 
+In this example, `.mvavg(10)` creates a moving average with a window of 10 data points.
+
+[float]
+[[conditional-format-visualization]]
+==== Customize and format the visualization
+
+Customize and format the visualization using the following functions, then click *Update*:
+
+[source,text]
+----------------------------------
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='max:system.memory.actual.used.bytes')
+  .label('max memory')                    <1>
+  .title('Memory consumption over time'), <2>
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='max:system.memory.actual.used.bytes')
+  .if(gt,
+      11300000000,
+      .es(index=metricbeat-*,
+          timefield='@timestamp',
+          metric='max:system.memory.actual.used.bytes'),
+      null)
+    .label('warning')
+    .color('#FFCC11')                 <3>
+    .lines(width=5),                  <4>
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='max:system.memory.actual.used.bytes')
+  .if(gt,
+      11375000000,
+      .es(index=metricbeat-*,
+          timefield='@timestamp',
+          metric='max:system.memory.actual.used.bytes'),
+      null)
+    .label('severe')
+    .color('red')
+    .lines(width=5),
+.es(index=metricbeat-*,
+    timefield='@timestamp',
+    metric='max:system.memory.actual.used.bytes')
+  .mvavg(10)
+  .label('mvavg')
+  .lines(width=2)
+  .color(#5E5E5E)
+  .legend(columns=4, position=nw)    <5>
+----------------------------------
+
+[role="screenshot"]
+image::images/timelion-conditional04.png[Final visualization that displays outliers and patterns over time]
+{nbsp}
+
+[float]
+==== Save the panel
+
+Save and add the panel to the dashboard.
+
+. From the toolbar, click *Save*.
+
+. Enter the *Title* and optional *Description*. 
+
+. From the *Tags* drop down, select any applicable tags. 
+
+. Select *Add to Dashboard after saving*.
+
+. Click *Save and return*.
+
+For more information about *Timelion* conditions, refer to https://www.elastic.co/blog/timeseries-if-then-else-with-timelion[I have but one .condition()].

docs/user/dashboard/tsvb.asciidoc

@@ -0,0 +1,121 @@
+[[TSVB]]
+=== TSVB
+
+*TSVB* requires a date field and supports <<aggregation-reference, most {es} metric aggregations>>, multiple visualization types, custom functions,
+and some math. 
+
+TIP: With *TSVB*, you can visualize the data from multiple series, but only *Timelion* can perform math across layers.
+
+[float]
+[[tsvb-required-choices]]
+==== Requirements
+
+When you open *TSVB*, click *Panel options*, then verify the following:
+
+* The index pattern, time field, and interval are configured
+* Specify if you want to show the last bucket, which usually contains partial data
+* For non-time series visualizations, specify if you want the *Data timerange mode*.
+* Specify any <<kuery-query, KQL filters>> to select specific documents
+
+[float]
+==== Visualization options
+
+Time series::
+  Supports annotations based on timestamped documents in a separate {es} index.
+
+All other chart types::
+  *Panel options > Data timerange mode* controls the timespan used for matching documents.
+  *Last value* is unable to match all documents, only the specific interval.
+  *Entire timerange* matches all the documents specified in the time filter.
+
+Metric, Top N, and Gauge::
+  *Panel options > Color rules* contains conditional coloring based on the values.
+
+Top N and Table::
+  When you click a series, *TSVB* applies a filter based
+  on the series name. To change this behavior, configure *Panel options > Item URL*,
+  which opens a URL instead of applying a filter on click.
+
+Markdown::
+  Supports Markdown with Handlebars syntax to insert dynamic data. Also supports
+  custom CSS using LESS syntax.
+
+[float]
+[[tsvb-series-options]]
+==== Understanding the TSVB series panel
+
+Every visualization shares the same interface for creating a *Series*.
+Each series can be thought of as a separate {es} aggregation, which prevents
+them from being compared with math. Each series has an *Options* tab
+that controls the styling and {es} options, which are inherited from the *Panel options*.
+Having separate options for each series allows you to compare different
+{es} indices, or to view two time periods from the same index.
+
+To configure the value of each series, select the function first and then the inputs to
+the function. Only the last function is displayed.
+
+Series can optionally have a *Group by*, which will show each group separately in the chart.
+The *Filters* grouping lets you assign a color to each filter. The *Terms* grouping has special
+behavior in the *Time series* chart, which is controlled by *Options > Split color theme*.
+
+[float]
+[[tsvb-reference]]
+==== TSVB reference
+
+TSVB has implemented shortcuts for some frequently-used functions.
+
+Filter ratio::
+  Returns a percent value by calculating a metric on two sets of documents. For example, calculate the error rate as a percentage of the overall events over time.
+
+Counter rate::
+  Used for when dealing with monotonically increasing counters. Shortcut for max, derivative and positive only.
+
+Positive only::
+  Removes any negative values from the results, which can be used as a post-processing step
+  after a derivative.
+
+Series agg::
+  Applies a function to all of the *Group by* series to reduce the values to a single number.
+  This function must always be the last metric in the series.
+  +
+  For example, if the Time series chart is showing 10 series, applying a "sum" series agg will calculate
+  the sum of all 10 bars and output a single Y value per X value. This is often confused
+  with the overall sum function, which outputs a single Y value per unique series.
+
+Math::
+  The math context is able to do both simple and advanced calculations per series.
+  This function must always be the last metric in the series.
+
+[float]
+[[tsvb-faq]]
+==== Frequently asked questions
+
+Why is my TSVB visualization missing data?::
+  It depends, but most often it's two causes:
+
+  1. If looking at a *Time series* chart with a derivative function, the time interval might be too small.
+    Derivatives require sequential values,
+  2. If looking at anything but *Time series* in TSVB, the cause is probably the *Data timerange mode*.
+    This is controlled by *Panel options > Data timerange mode > Entire time range*. This is because
+    TSVB defaults to showing the *last whole bucket*. If the time range is "last 24 hours", and the
+    current time is 9:41, then TSVB metrics will be only show 10 minutes: from 9:30 to 9:40.
+
+How do I calculate the difference between two series?::
+  TSVB doesn't support math across series, but <<create-panels-with-timelion, Timelion>> does. <<vega, Vega>> can also do this.
+
+How do I view the current vs previous month?::
+  While it's not possible to do math on these two, TSVB supports series with time offsets.
+  Click *Clone Series*, and then choose a new color for the new series. Go toc
+  *Options > Offset series time by* and choose an offset value.
+
+How do I calculate a month over month change?::
+  This is not fully supported in TSVB, but there is a special case that is supported *if* the TSVB
+  time range is set to 3 months or more *and* the time interval is one month. Use the `derivative`
+  to get the absolute monthly change. To convert to a percent, add a `math` function with the formula
+  `params.current / (params.current - params.derivative)`, and then set the formatter to Percent.
+  +
+  For other types of month over month calculations, use <<create-panels-with-timelion, Timelion>> or <<vega, Vega>>.
+
+How do I calculate the duration between start and end of an event?::
+  TSVB can't do this because it requires correlation between different time periods. TSVB requires
+  that the duration is pre-calculated.

docs/user/dashboard/vega-reference.asciidoc

@@ -1,13 +1,11 @@
 [[vega-reference]]
-== Vega reference
+==== Vega reference
 
-experimental[]
-
-For additional *Vega* and *Vega-Lite* information, refer to the reference sections.
+Learn more about {kib} extension, additional *Vega* resources, and examples.
 
 [float]
 [[reference-for-kibana-extensions]]
-=== Reference for {kib} extensions
+===== Reference for {kib} extensions
 
 {kib} has extended Vega and Vega-Lite with extensions that support:
 
@@ -17,12 +15,12 @@ For additional *Vega* and *Vega-Lite* information, refer to the reference sectio
 * experimental[] Using the Elastic Map Service in Vega maps
 * Additional tooltip styling
 * Advanced setting to enable URL loading from any domain
-* Limited debugging support using the browser dev tools
+* Debugging support using the {kib} inspector or browser console
 * (Vega only) Expression functions which can update the time range and dashboard filters
 
 [float]
 [[vega-sizing-and-positioning]]
-==== Automatic sizing
+====== Automatic sizing
 
 Most users will want their Vega visualizations to take the full available space, so unlike
 Vega examples, `width` and `height` are not required parameters in {kib}. To set the width
@@ -54,7 +52,7 @@ in the Vega documentation.
 
 [float]
 [[vega-theme]]
-==== Default theme to match {kib}
+====== Default theme to match {kib}
 
 {kib} registers a default https://vega.github.io/vega/docs/schemes/[Vega color scheme]
 with the id `elastic`, and sets a default color for each `mark` type.
@@ -62,7 +60,7 @@ Override it by providing a different `stroke`, `fill`, or `color` (Vega-Lite) va
 
 [float]
 [[vega-queries]]
-==== Writing {es} queries in Vega
+====== Writing {es} queries in Vega
 
 {kib} extends the Vega https://vega.github.io/vega/docs/data/[data] elements
 with support for direct {es} queries specified as `url`.
@@ -217,10 +215,9 @@ try to get about 10-15 data points (buckets).
 
 [float]
 [[vega-with-a-map]]
-=== Vega with a Map
+==== Vega with a Map
 
-To enable Maps, the graph must specify `type=map` in the host
-configuration:
+To enable *Maps*, the graph must specify `type=map` in the host configuration:
 
 [source,yaml]
 ----
@@ -266,7 +263,8 @@ Additionally, you can use `latitude`, `longitude`, and `zoom` signals.
 These signals can be used in the graph, or can be updated to modify the
 position of the map.
 
-experimental[] You can use Vega's https://vega.github.io/vega/docs/data/[data] element to access https://www.elastic.co/elastic-maps-service[Elastic Maps Service (EMS)] vector shapes of administrative boundaries in your Vega map by setting `url.data` to `emsFile`:
+experimental[] You can use the *Vega* https://vega.github.io/vega/docs/data/[data] element to access https://www.elastic.co/elastic-maps-service[Elastic Maps Service (EMS)] 
+vector shapes of administrative boundaries in your Vega map by setting `url.data` to `emsFile`:
 
 [source,yaml]
 ----
@@ -284,7 +282,7 @@ format: {property: "features"}
 
 [float]
 [[vega-tooltip]]
-==== Additional tooltip styling
+====== Additional tooltip styling
 
 {kib} has installed the https://vega.github.io/vega-lite/docs/tooltip.html[Vega tooltip plugin],
 so tooltips can be defined in the ways documented there. Beyond that, {kib} also supports
@@ -306,23 +304,21 @@ a configuration option for changing the tooltip position and padding:
 
 [float]
 [[vega-url-loading]]
-==== Advanced setting to enable URL loading from any domain
+====== Enable URL loading from any domain
 
-Vega can load data from any URL, but this is disabled by default in {kib}.
-To change this, set `vis_type_vega.enableExternalUrls: true` in `kibana.yml`,
+*Vega* can load data from any URL. To enable, set `vis_type_vega.enableExternalUrls: true` in `kibana.yml`,
 then restart {kib}.
 
 [float]
 [[vega-inspector]]
-==== Vega Inspector
-Use the contextual *Inspect* tool to gain insights into different elements.
-For Vega visualizations, there are two different views: *Request* and *Vega debug*.
+===== Vega Inspector
+Use the contextual *Inspect* tool to gain insights into different elements. 
 
 [float]
 [[inspect-elasticsearch-requests]]
-===== Inspect {es} requests
+====== Inspect {es} requests
 
-Vega uses the {ref}/search-search.html[{es} search API] to get documents and aggregation
+*Vega* uses the {ref}/search-search.html[{es} search API] to get documents and aggregation
 results from {es}. To troubleshoot these requests, click *Inspect*, which shows the most recent requests.
 In case your specification has more than one request, you can switch between the views using the *View* dropdown.
 
@@ -346,11 +342,11 @@ the <<vega-browser-debugging-console, Vega browser debugging process>>.
 
 [float]
 [[asking-for-help-with-a-vega-spec]]
-===== Asking for help with a Vega spec
+====== Asking for help with a Vega spec
 
 Because of the dynamic nature of the data in {es}, it is hard to help you with
-Vega specs unless you can share a dataset. To do this, click *Inspect*, select the *Vega debug* view,
-then select the *Spec* tab:
+*Vega* specs unless you can share a dataset. To do this, click *Inspect*, select the *Vega debug* view,
+then select *Spec*.
 
 [role="screenshot"]
 image::visualize/images/vega_tutorial_getting_help.png[]
@@ -361,7 +357,7 @@ and share that when asking for help.
 
 [float]
 [[vega-browser-debugging-console]]
-==== Browser debugging console
+===== Browser debugging console
 
 experimental[] Use browser debugging tools (for example, F12 or Ctrl+Shift+J in Chrome) to
 inspect the `VEGA_DEBUG` variable:
@@ -379,7 +375,7 @@ Vega-Lite compilation.
 
 [float]
 [[vega-expression-functions]]
-==== (Vega only) Expression functions which can update the time range and dashboard filters
+===== Expression functions which can update the time range and dashboard filters
 
 {kib} has extended the Vega expression language with these functions:
 
@@ -408,7 +404,7 @@ kibanaSetTimeFilter(start, end)
 
 [float]
 [[vega-additional-configuration-options]]
-==== Additional configuration options
+===== Additional configuration options
 
 [source,yaml]
 ----
@@ -429,28 +425,29 @@ kibanaSetTimeFilter(start, end)
 }
 ----
 
+[float]
 [[vega-notes]]
 [[resources-and-examples]]
-=== Resources and examples
+==== Resources and examples
 
-experimental[] To learn more about Vega and Vega-Lite, refer to the resources and examples.
+To learn more about Vega and Vega-Lite, refer to the resources and examples.
 
 [float]
 [[vega-editor]]
-==== Vega editor
+===== Vega editor
 The https://vega.github.io/editor/[Vega Editor] includes examples for Vega & Vega-Lite, but does not support any
 {kib}-specific features like {es} requests and interactive base maps.
 
 [float]
 [[vega-lite-resources]]
-==== Vega-Lite resources
+===== Vega-Lite resources
 * https://vega.github.io/vega-lite/tutorials/getting_started.html[Tutorials]
 * https://vega.github.io/vega-lite/docs/[Docs]
 * https://vega.github.io/vega-lite/examples/[Examples]
 
 [float]
 [[vega-resources]]
-==== Vega resources
+===== Vega resources
 * https://vega.github.io/vega/tutorials/[Tutorials]
 * https://vega.github.io/vega/docs/[Docs]
 * https://vega.github.io/vega/examples/[Examples]

docs/user/introduction.asciidoc

@@ -53,7 +53,7 @@ image::images/intro-discover.png[Discover UI]
 === Visualize & analyze
 
 A visualization is worth a thousand log lines, and {kib} provides
-many options for showcasing your data. Use <<lens, Lens>>,
+many options for showcasing your data. Use <<create-panels-with-lens,Lens>>,
 our drag-and-drop interface,
 to rapidly build
 charts, tables, metrics, and more. If there
@@ -78,7 +78,7 @@ questions of your location-based data. Maps supports multiple
 layers and data sources, mapping of individual geo points and shapes,
 and dynamic client-side styling.
 
-* <<tsvb, TSVB>> allows you to combine
+* <<tsvb-advanced-editor, TSVB>> allows you to combine
 an infinite number of aggregations to display complex data.
 With TSVB, you can customize
 every aspect of your visualization. Choose your own date format and color