[DOCS] Consolidates drilldown pages (#82081)

* [DOCS] Consolidated drilldowns

* Review comments pt 1

* Update docs/user/dashboard/drilldowns.asciidoc

Co-authored-by: Anton Dosov <dosantappdev@gmail.com>

* Fixes supported drilldowns link

* Update src/core/public/doc_links/doc_links_service.ts

Co-authored-by: Anton Dosov <dosantappdev@gmail.com>

* Fixes rogue disable section and fixes intro formatting

* Fixes URL drilldown link

Co-authored-by: Anton Dosov <dosantappdev@gmail.com>
Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
This commit is contained in:
Kaarina Tungseth 2020-11-10 09:11:21 -06:00 committed by GitHub
parent e909cee7f1
commit 1b86d79319
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 255 additions and 243 deletions

View file

@ -1,96 +0,0 @@
[[dashboard-drilldown]]
=== Dashboard drilldown
The dashboard drilldown allows you to navigate from one dashboard to another dashboard.
For example, you might have a dashboard that shows the overall status of multiple data centers.
You can create a drilldown that navigates from this dashboard to a dashboard
that shows a single data center or server.
This example shows a dashboard panel that contains a pie chart with a configured dashboard drilldown:
[role="screenshot"]
image::images/drilldown_on_piechart.gif[Drilldown on pie chart that navigates to another dashboard]
[float]
[[dashboard-drilldown-supported-panels]]
==== Supported panels
The following panels support dashboard drilldowns:
* Lens
* Area
* Data table
* Heat map
* Horizontal bar
* Line
* Maps
* Pie
* TSVB
* Tag cloud
* Timelion
* Vega
* Vertical bar
[float]
[[drilldowns-example]]
==== Try it: Create a dashboard drilldown
Create the *Host Overview* drilldown shown above.
*Set up the dashboards*
. Add the sample web logs data set.
. Create a new dashboard, called `Host Overview`, and include these visualizations
from the sample data set:
+
[%hardbreaks]
*[Logs] Heatmap*
*[Logs] Visitors by OS*
*[Logs] Host, Visits, and Bytes Table*
*[Logs] Total Requests and Bytes*
+
TIP: If you dont see data for a panel, try changing the time range.
. Open the *[Logs] Web traffic* dashboard.
. Set a search and filter.
+
[%hardbreaks]
Search: `extension.keyword: ("gz" or "css" or "deb")`
Filter: `geo.src: CN`
*Create the drilldown*
. In the dashboard menu bar, click *Edit*.
. In *[Logs] Visitors by OS*, open the panel menu, and then select *Create drilldown*.
. Pick *Go to dashboard* action.
. Give the drilldown a name.
. Select *Host Overview* as the destination dashboard.
. Keep both filters enabled so that the drilldown carries over the global filters and date range.
+
Your input should look similar to this:
+
[role="screenshot"]
image::images/drilldown_create.png[Create drilldown with entries for drilldown name and destination]
. Click *Create drilldown.*
. Save the dashboard.
+
If you dont save the drilldown, and then navigate away, the drilldown is lost.
. In *[Logs] Visitors by OS*, click the `win 8` slice of the pie, and then select the name of your drilldown.
+
[role="screenshot"]
image::images/drilldown_on_panel.png[Drilldown on pie chart that navigates to another dashboard]
+
You are navigated to your destination dashboard. Verify that the search query, filters,
and time range are carried over.

View file

@ -1,52 +1,259 @@
[role="xpack"]
[[drilldowns]]
== Use drilldowns for dashboard actions
== Create custom dashboard actions
Drilldowns, also known as custom actions, allow you to configure a
workflow for analyzing and troubleshooting your data.
For example, using a drilldown, you can navigate from one dashboard to another,
taking the current time range, filters, and other parameters with you,
so the context remains the same. You can continue your analysis from a new perspective.
Custom dashboard actions, also known as drilldowns, allow you to create
workflows for analyzing and troubleshooting your data. Drilldowns apply only to the panel that you created the drilldown from, and are not shared across all of the panels. Each panel can have multiple drilldowns.
[role="screenshot"]
image::images/drilldown_on_piechart.gif[Drilldown on pie chart that navigates to another dashboard]
Drilldowns are specific to the dashboard panel for which you create them—they are not shared across panels. A panel can have multiple drilldowns.
Third-party developers can create drilldowns. To learn how to code drilldowns, refer to {kib-repo}blob/{branch}/x-pack/examples/ui_actions_enhanced_examples[this example plugin].
[float]
[[actions]]
=== Drilldown actions
[[supported-drilldowns]]
=== Supported drilldowns
Drilldowns are user-configurable {kib} actions that are stored with the dashboard metadata.
Kibana provides the following types of actions:
[cols="2"]
|===
a| <<dashboard-drilldown, Dashboard drilldown>>
| Navigate to a dashboard.
a| <<url-drilldown, URL drilldown>>
| Navigate to external or internal URL.
|===
{kib} supports two types of drilldowns.
[NOTE]
==============================================
Some action types are paid commercial features, while others are free.
Some drilldowns are paid subscription features, while others are free.
For a comparison of the Elastic subscription levels,
see https://www.elastic.co/subscriptions[the subscription page].
refer https://www.elastic.co/subscriptions[the subscription page].
==============================================
[float]
[[code-drilldowns]]
=== Code drilldowns
Third-party developers can create drilldowns.
Refer to {kib-repo}blob/{branch}/x-pack/examples/ui_actions_enhanced_examples[this example plugin]
to learn how to code drilldowns.
[[dashboard-drilldown]]
==== Dashboard drilldowns
Dashboard drilldowns enable you to open a dashboard from another dashboard,
taking the time range, filters, and other parameters with you,
so the context remains the same. Dashboard drilldowns help you to continue your analysis from a new perspective.
For example, if you have a dashboard that shows the overall status of multiple data center,
you can create a drilldown that navigates from the overall status dashboard to a dashboard
that shows a single data center or server.
[float]
[[url-drilldown]]
==== URL drilldowns
beta[] URL drilldowns enable you to navigate from a dashboard to internal or external URLs.
Destination URLs can be dynamic, depending on the dashboard context or user interaction with a panel.
For example, if you have a dashboard that shows data from a Github repository, you can create a URL drilldown
that opens Github from the dashboard.
Some panels support multiple interactions, also known as triggers.
The <<variables,variables>> you use to create a <<url_templating, URL template>> depends on the trigger you choose. URL drilldowns support these types of triggers:
* *Single click* &mdash; A single data point in the visualization.
* *Range selection* &mdash; A range of values in a visualization.
For example, *Single click* has `{{event.value}}` and *Range selection* has `{{event.from}}` and `{{event.to}}`.
To disable URL drilldowns on your {kib} instance, disable the plugin:
["source","yml"]
-----------
url_drilldown.enabled: false
-----------
[float]
[[dashboard-drilldown-supported-panels]]
=== Supported panels
The following panels support dashboard and URL drilldowns.
[options="header"]
|===
| Panel | Dashboard drilldown | URL drilldown
| Lens
^| X
^| X
| Area
^| X
^| X
| Controls
^|
^|
| Data Table
^| X
^| X
| Gauge
^|
^|
| Goal
^|
^|
| Heat map
^| X
^| X
| Horizontal Bar
^| X
^| X
| Line
^| X
^| X
| Maps
^| X
^|
| Markdown
^|
^|
| Metric
^|
^|
| Pie
^| X
^| X
| TSVB
^| X
^|
| Tag Cloud
^| X
^| X
| Timelion
^| X
^|
| Vega
^| X
^|
| Vertical Bar
^| X
^| X
|===
[float]
[[drilldowns-example]]
=== Try it: Create a dashboard drilldown
To create dashboard drilldowns, you create or locate the dashboards you want to connect, then configure the drilldown that allows you to easily open one dashboard from the other dashboard.
image:images/drilldown_on_piechart.gif[Drilldown on pie chart that navigates to another dashboard]
[float]
==== Create the dashboard
. Add the *Sample web logs* data.
. Create a new dashboard, then add the following panels:
* *[Logs] Heatmap*
* *[Logs] Host, Visits, and Bytes Table*
* *[Logs] Total Requests and Bytes*
* *[Logs] Visitors by OS*
+
If you dont see data for a panel, try changing the <<set-time-filter,time filter>>.
. Save the dashboard. In the *Title* field, enter `Host Overview`.
. Open the *[Logs] Web traffic* dashboard.
. Set a search and filter.
+
[%hardbreaks]
Search: `extension.keyword: ("gz" or "css" or "deb")`
Filter: `geo.src: CN`
[float]
==== Create the drilldown
. In the toolbar, click *Edit*.
. Open the *[Logs] Visitors by OS* panel menu, then select *Create drilldown*.
. Give the drilldown a name, then select *Go to dashboard*.
. From the *Choose a destination dashboard* dropdown, select *Host Overview*.
. To carry over the filter, query, and date range, make sure that *Use filters and query from origin dashboard* and *Use date range from origin dashboard* are selected.
+
[role="screenshot"]
image::images/drilldown_create.png[Create drilldown with entries for drilldown name and destination]
. Click *Create drilldown*.
+
The drilldown is stored as dashboard metadata.
. Save the dashboard.
+
If you fail to save the dashboard, the drilldown is lost when you navigate away from the dashboard.
. In the *[Logs] Visitors by OS* panel, click *win 8*, then select the drilldown.
+
[role="screenshot"]
image::images/drilldown_on_panel.png[Drilldown on pie chart that navigates to another dashboard]
. On the *Host Overview* dashboard, verify that the search query, filters,
and date range are carried over.
[float]
[[create-a-url-drilldown]]
=== Try it: Create a URL drilldown
beta[] To create URL drilldowns, you add <<variables,variables>> to a URL template, which configures the bahavior of the drilldown.
image:images/url_drilldown_go_to_github.gif[Drilldown on pie chart that navigates to Github]
. Add the *Sample web logs* data.
. Open the *[Logs] Web traffic* dashboard. This isnt data from Github, but works for demonstration purposes.
. In the toolbar, click *Edit*.
. Open the *[Logs] Visitors by OS* panel menu, then select *Create drilldown*.
.. In the *Name* field, enter `Show on Github`.
.. Select *Go to URL*.
.. Enter the URL template:
+
[source, bash]
----
https://github.com/elastic/kibana/issues?q=is:issue+is:open+{{event.value}}
----
+
The example URL navigates to {kib} issues on Github. `{{event.value}}` is substituted with a value associated with a selected pie slice. In *URL preview*, `{{event.value}}` is substituted with a <<values-in-preview, dummy>> value.
+
[role="screenshot"]
image:images/url_drilldown_url_template.png[URL template input]
.. Click *Create drilldown*.
+
The drilldown is stored as dashboard metadata.
. Save the dashboard.
+
If you fail to save the dashboard, the drilldown is lost when you navigate away from the dashboard.
. On the *[Logs] Visitors by OS* panel, click any chart slice, then select *Show on Github*.
+
[role="screenshot"]
image:images/url_drilldown_popup.png[URL drilldown popup]
. On the page that lists the issues in the {kib} repository, verify the slice value appears in Github.
+
[role="screenshot"]
image:images/url_drilldown_github.png[Github]
include::dashboard-drilldown.asciidoc[]
include::url-drilldown.asciidoc[]

View file

@ -1,96 +1,9 @@
[[url-drilldown]]
=== URL drilldown
[[url_templating]]
=== URL templating
beta[]
The URL drilldown allows you to navigate from a dashboard to an internal or external URL.
The destination URL can be dynamic, depending on the dashboard context or users interaction with a visualization.
For example, you might have a dashboard that shows data from a Github repository.
You can create a drilldown that navigates from this dashboard to Github.
[role="screenshot"]
image:images/url_drilldown_go_to_github.gif[Drilldown on pie chart that navigates to Github]
NOTE: URL drilldown is available with the https://www.elastic.co/subscriptions[Gold subscription] and higher.
[float]
[[url-drilldown-supported-panels]]
==== Supported panels
The following panels support URL drilldowns:
* Lens
* Area
* Data table
* Heat map
* Horizontal bar
* Line
* Pie
* Tag cloud
* Vertical bar
[float]
[[try-it]]
==== Try it: Create a URL drilldown
This example shows how to create the "Show on Github" drilldown shown above.
. Add the sample web logs data set.
. Open the *[Logs] Web traffic* dashboard. This isnt data from Github, but it should work for demonstration purposes.
. In the dashboard menu bar, click *Edit*.
. In *[Logs] Visitors by OS*, open the panel menu, and then select *Create drilldown*.
. Give the drilldown a name: *Show on Github*.
. Select a drilldown action: *Go to URL*.
+
[role="screenshot"]
image:images/url_drilldown_pick_an_action.png[Action picker]
. Enter a URL template:
+
[source, bash]
----
https://github.com/elastic/kibana/issues?q=is:issue+is:open+{{event.value}}
----
+
This example URL navigates to {kib} issues on Github. `{{event.value}}` will be substituted with a value associated with a clicked pie slice. In _preview_ `{{event.value}}` is substituted with a <<values-in-preview, dummy>> value.
[role="screenshot"]
image:images/url_drilldown_url_template.png[URL template input]
. Click *Create drilldown*.
. Save the dashboard.
+
If you dont save the drilldown, and then navigate away, the drilldown is lost.
. In *[Logs] Visitors by OS*, click any slice of the pie, and then select the drilldown *Show on Github*.
+
[role="screenshot"]
image:images/url_drilldown_popup.png[URL drilldown popup]
+
You are navigated to the issue list in the {kib} repository. Verify that value from a pie slice youve clicked on is carried over to Github.
+
[role="screenshot"]
image:images/url_drilldown_github.png[Github]
[float]
[[trigger-picker]]
==== Picking a trigger for a URL drilldown
Some panels support multiple user interactions (called triggers) for which you can configure a URL drilldown. The list of supported variables in the URL template depends on the trigger you selected.
In the preceding example, you configured a URL drilldown on a pie chart. The only trigger that pie chart supports is clicking on a pie slice, so you didnt have to pick a trigger.
However, the sample *[Logs] Unique Visitors vs. Average Bytes* chart supports both clicking on a data point and selecting a range. When you create a URL drilldown for this chart, you have the following choices:
[role="screenshot"]
image:images/url_drilldown_trigger_picker.png[Trigger picker: Single click and Range selection]
Variables in the URL template differ per trigger.
For example, *Single click* has `{{event.value}}` and *Range selection* has `{{event.from}}` and `{{event.to}}`.
You can create multiple URL drilldowns per panel and attach them to different triggers.
[float]
[[templating]]
==== URL templating language
The URL template input uses Handlebars — a simple templating language. Handlebars templates look like regular text with embedded Handlebars expressions.
The URL template input uses https://handlebarsjs.com/guide/expressions.html#expressions[Handlebars] — a simple templating language. Handlebars templates look like regular text with embedded Handlebars expressions.
[source, bash]
----
@ -99,14 +12,13 @@ https://github.com/elastic/kibana/issues?q={{event.value}}
A Handlebars expression is a `{{`, some contents, followed by a `}}`. When the drilldown is executed, these expressions are replaced by values from the dashboard and interaction context.
[[helpers]]
In addition to https://handlebarsjs.com/guide/builtin-helpers.html[built-in] Handlebars helpers, you can use custom helpers.
Refer to Handlebars https://ela.st/handlebars-docs#expressions[documentation] to learn about advanced use cases.
[[helpers]]
In addition to https://ela.st/handlebars-helpers[built-in] Handlebars helpers, you can use the following custom helpers:
|===
|Helper |Use case
|Custom helper |Use case
|json
a|Serialize variables in JSON format.
@ -133,7 +45,7 @@ a|Format dates. Supports relative dates expressions (for example, "now-15d"). R
Example:
`{{ date event.from “YYYY MM DD”}}` +
`{{date event.from “YYYY MM DD”}}` +
`{{date “now-15”}}`
|formatNumber
@ -240,7 +152,7 @@ For example, `{{context.panel.filters}}` are previewed with the current filters
*Event* variables are extracted during drilldown execution from a user interaction with a panel (for example, from a pie slice that the user clicked on).
Because there is no user interaction with a panel in preview, there is no interaction context to use in a preview.
To work around this, {kib} provides a sample interaction that relies on a picked <<trigger-picker, trigger>>.
To work around this, {kib} provides a sample interaction that relies on a trigger.
So in a preview, you might notice that `{{event.value}}` is replaced with `{{event.value}}` instead of with a sample from your data.
Such previews can help you make sure that the structure of your URL template is valid.
However, to ensure that the configured URL drilldown works as expected with your data, you have to save the dashboard and test in the panel.
@ -340,14 +252,3 @@ Tip: Consider using <<helpers, date>> helper for date formatting.
| Aggregation field behind the selected range, if available.
|===
[float]
[[disable]]
==== Disable URL drilldown
You can disable URL drilldown feature on your {kib} instance by disabling the plugin:
["source","yml"]
-----------
url_drilldown.enabled: false
-----------

View file

@ -39,9 +39,9 @@ export class DocLinksService {
dashboard: {
guide: `${ELASTIC_WEBSITE_URL}guide/en/kibana/${DOC_LINK_VERSION}/dashboard.html`,
drilldowns: `${ELASTIC_WEBSITE_URL}guide/en/kibana/${DOC_LINK_VERSION}/drilldowns.html`,
drilldownsTriggerPicker: `${ELASTIC_WEBSITE_URL}guide/en/kibana/${DOC_LINK_VERSION}/url-drilldown.html#trigger-picker`,
urlDrilldownTemplateSyntax: `${ELASTIC_WEBSITE_URL}guide/en/kibana/${DOC_LINK_VERSION}/url-drilldown.html#templating`,
urlDrilldownVariables: `${ELASTIC_WEBSITE_URL}guide/en/kibana/${DOC_LINK_VERSION}/url-drilldown.html#variables`,
drilldownsTriggerPicker: `${ELASTIC_WEBSITE_URL}guide/en/kibana/${DOC_LINK_VERSION}/drilldowns.html#url-drilldown`,
urlDrilldownTemplateSyntax: `${ELASTIC_WEBSITE_URL}guide/en/kibana/${DOC_LINK_VERSION}/url_templating-language.html`,
urlDrilldownVariables: `${ELASTIC_WEBSITE_URL}guide/en/kibana/${DOC_LINK_VERSION}/url_templating-language.html#variables`,
},
filebeat: {
base: `${ELASTIC_WEBSITE_URL}guide/en/beats/filebeat/${DOC_LINK_VERSION}`,