From fabc61dcdeca20e0ef463eaa59fe6630ae6a5c31 Mon Sep 17 00:00:00 2001 From: Paul Echeverri Date: Wed, 6 Jul 2016 14:36:35 -0700 Subject: [PATCH 1/3] Fixes broken link in Getting Started --- docs/getting-started.asciidoc | 148 +++++++++++++++++----------------- 1 file changed, 74 insertions(+), 74 deletions(-) diff --git a/docs/getting-started.asciidoc b/docs/getting-started.asciidoc index ee555edda7e6b0..5a72049b3707f2 100644 --- a/docs/getting-started.asciidoc +++ b/docs/getting-started.asciidoc @@ -1,7 +1,7 @@ [[getting-started]] == Getting Started with Kibana -Now that you have Kibana <>, you can step through this tutorial to get fast hands-on experience with +Now that you have Kibana <>, you can step through this tutorial to get fast hands-on experience with key Kibana functionality. By the end of this tutorial, you will have: * Loaded a sample data set into your Elasticsearch installation @@ -17,7 +17,7 @@ Video tutorials are also available: * https://www.elastic.co/blog/kibana-4-video-tutorials-part-1[High-level Kibana introduction, pie charts] * https://www.elastic.co/blog/kibana-4-video-tutorials-part-2[Data discovery, bar charts, and line charts] * https://www.elastic.co/blog/kibana-4-video-tutorials-part-3[Tile maps] -* https://www.elastic.co/blog/kibana-4-video-tutorials-part-4[Embedding Kibana visualizations] +* https://www.elastic.co/blog/kibana-4-video-tutorials-part-4[Embedding Kibana visualizations] [float] [[tutorial-load-dataset]] @@ -25,11 +25,11 @@ Video tutorials are also available: The tutorials in this section rely on the following data sets: -* The complete works of William Shakespeare, suitably parsed into fields. Download this data set by clicking here: +* The complete works of William Shakespeare, suitably parsed into fields. Download this data set by clicking here: https://www.elastic.co/guide/en/kibana/3.0/snippets/shakespeare.json[shakespeare.json]. -* A set of fictitious accounts with randomly generated data, in CSV format. Download this data set by clicking here: - https://www.github.com/elastic/kibana/docs/tutorial/accounts.csv[accounts.csv] -* A set of randomly generated log files. Download this data set by clicking here: +* A set of fictitious accounts with randomly generated data, in CSV format. Download this data set by clicking here: + https://github.com/elastic/kibana/tree/master/docs/tutorial/accounts.csv[accounts.csv] +* A set of randomly generated log files. Download this data set by clicking here: https://download.elastic.co/demos/kibana/gettingstarted/logs.jsonl.gz[logs.jsonl.gz] Extract the logs with the following command: @@ -75,8 +75,8 @@ The schema for the logs data set has dozens of different fields, but the notable "@timestamp": "date" } -Before we load the Shakespeare and logs data sets, we need to set up {ref}mapping.html[_mappings_] for the fields. -Mapping divides the documents in the index into logical groups and specifies a field's characteristics, such as the +Before we load the Shakespeare and logs data sets, we need to set up {ref}mapping.html[_mappings_] for the fields. +Mapping divides the documents in the index into logical groups and specifies a field's characteristics, such as the field's searchability or whether or not it's _tokenized_, or broken up into separate words. Use the following command to set up a mapping for the Shakespeare data set: @@ -108,7 +108,7 @@ there are multiple words in the field. * The same applies to the _play_name_ field. * The _line_id_ and _speech_number_ fields are integers. -The logs data set requires a mapping to label the latitude/longitude pairs in the logs as geographic locations by +The logs data set requires a mapping to label the latitude/longitude pairs in the logs as geographic locations by applying the `geo_point` type to those fields. Use the following commands to establish `geo_point` mapping for the logs: @@ -170,7 +170,7 @@ curl -XPUT http://localhost:9200/logstash-2015.05.20 -d ' } '; -At this point we're ready to use the Elasticsearch {ref}/docs-bulk.html[`bulk`] API to load the data sets with the +At this point we're ready to use the Elasticsearch {ref}/docs-bulk.html[`bulk`] API to load the data sets with the following commands: [source,shell] @@ -179,7 +179,7 @@ curl -XPOST 'localhost:9200/_bulk?pretty' --data-binary @logs.jsonl These commands may take some time to execute, depending on the computing resources available. -To load the Accounts data set, click the *Management* image:images/SettingsButton.jpg[gear icon] tab, the +To load the Accounts data set, click the *Management* image:images/SettingsButton.jpg[gear icon] tab, the select *Upload CSV*. image::images/management-panel.png[kibana management panel] @@ -188,7 +188,7 @@ Click *Select File*, then navigate to the `accounts.csv` file. Review the sample image::images/csv-sample.png[sample csv import] -Review the index pattern built by the CSV import function. You can change any field types from the drop-downs, but for +Review the index pattern built by the CSV import function. You can change any field types from the drop-downs, but for this tutorial, accept the defaults. Enter `bank` as the name for the index pattern, then click *Save*. image::images/sample-index.png[sample index pattern] @@ -211,24 +211,24 @@ yellow open logstash-2015.05.20 5 1 4750 0 16.4mb [[tutorial-define-index]] === Defining Your Index Patterns -Each set of data loaded to Elasticsearch has an <>. In the previous section, the -Shakespeare data set has an index named `shakespeare`, and the accounts data set has an index named `bank`. An _index -pattern_ is a string with optional wildcards that can match multiple indices. For example, in the common logging use -case, a typical index name contains the date in MM-DD-YYYY format, and an index pattern for May would look something +Each set of data loaded to Elasticsearch has an <>. In the previous section, the +Shakespeare data set has an index named `shakespeare`, and the accounts data set has an index named `bank`. An _index +pattern_ is a string with optional wildcards that can match multiple indices. For example, in the common logging use +case, a typical index name contains the date in MM-DD-YYYY format, and an index pattern for May would look something like `logstash-2015.05*`. -For this tutorial, any pattern that matches the name of an index we've loaded will work. Open a browser and -navigate to `localhost:5601`. Click the *Settings* tab, then the *Indices* tab. Click *Add New* to define a new index +For this tutorial, any pattern that matches the name of an index we've loaded will work. Open a browser and +navigate to `localhost:5601`. Click the *Settings* tab, then the *Indices* tab. Click *Add New* to define a new index pattern. Two of the sample data sets, the Shakespeare plays and the financial accounts, don't contain time-series data. Make sure the *Index contains time-based events* box is unchecked when you create index patterns for these data sets. -Specify `shakes*` as the index pattern for the Shakespeare data set and click *Create* to define the index pattern, then +Specify `shakes*` as the index pattern for the Shakespeare data set and click *Create* to define the index pattern, then define a second index pattern named `ba*`. The Logstash data set does contain time-series data, so after clicking *Add New* to define the index for this data -set, make sure the *Index contains time-based events* box is checked and select the `@timestamp` field from the +set, make sure the *Index contains time-based events* box is checked and select the `@timestamp` field from the *Time-field name* drop-down. -NOTE: When you define an index pattern, indices that match that pattern must exist in Elasticsearch. Those indices must +NOTE: When you define an index pattern, indices that match that pattern must exist in Elasticsearch. Those indices must contain data. [float] @@ -239,14 +239,14 @@ Click the *Discover* image:images/discover-compass.png[Compass icon] tab to disp image::images/tutorial-discover.png[] -Right under the tab itself, there is a search box where you can search your data. Searches take a specific -{ref}/query-dsl-query-string-query.html#query-string-syntax[query syntax] that enable you to create custom searches, +Right under the tab itself, there is a search box where you can search your data. Searches take a specific +{ref}/query-dsl-query-string-query.html#query-string-syntax[query syntax] that enable you to create custom searches, which you can save and load by clicking the buttons to the right of the search box. -Beneath the search box, the current index pattern is displayed in a drop-down. You can change the index pattern by +Beneath the search box, the current index pattern is displayed in a drop-down. You can change the index pattern by selecting a different pattern from the drop-down selector. -You can construct searches by using the field names and the values you're interested in. With numeric fields you can +You can construct searches by using the field names and the values you're interested in. With numeric fields you can use comparison operators such as greater than (>), less than (<), or equals (=). You can link elements with the logical operators AND, OR, and NOT, all in uppercase. @@ -261,8 +261,8 @@ If you're using the linked sample data set, this search returns 5 results: Accou image::images/tutorial-discover-2.png[] -To narrow the display to only the specific fields of interest, highlight each field in the list that displays under the -index pattern and click the *Add* button. Note how, in this example, adding the `account_number` field changes the +To narrow the display to only the specific fields of interest, highlight each field in the list that displays under the +index pattern and click the *Add* button. Note how, in this example, adding the `account_number` field changes the display from the full text of five records to a simple list of five account numbers: image::images/tutorial-discover-3.png[] @@ -270,26 +270,26 @@ image::images/tutorial-discover-3.png[] [[tutorial-visualizing]] === Data Visualization: Beyond Discovery -The visualization tools available on the *Visualize* tab enable you to display aspects of your data sets in several -different ways. +The visualization tools available on the *Visualize* tab enable you to display aspects of your data sets in several +different ways. Click on the *Visualize* image:images/visualize-icon.png[Bar chart icon] tab to start: image::images/tutorial-visualize.png[] -Click on *Pie chart*, then *From a new search*. Select the `ba*` index pattern. +Click on *Pie chart*, then *From a new search*. Select the `ba*` index pattern. -Visualizations depend on Elasticsearch {ref}/search-aggregations.html[aggregations] in two different types: _bucket_ -aggregations and _metric_ aggregations. A bucket aggregation sorts your data according to criteria you specify. For -example, in our accounts data set, we can establish a range of account balances, then display what proportions of the +Visualizations depend on Elasticsearch {ref}/search-aggregations.html[aggregations] in two different types: _bucket_ +aggregations and _metric_ aggregations. A bucket aggregation sorts your data according to criteria you specify. For +example, in our accounts data set, we can establish a range of account balances, then display what proportions of the total fall into which range of balances. The whole pie displays, since we haven't specified any buckets yet. image::images/tutorial-visualize-pie-1.png[] -Select *Split Slices* from the *Select buckets type* list, then select *Range* from the *Aggregation* drop-down -selector. Select the *balance* field from the *Field* drop-down, then click on *Add Range* four times to bring the +Select *Split Slices* from the *Select buckets type* list, then select *Range* from the *Aggregation* drop-down +selector. Select the *balance* field from the *Field* drop-down, then click on *Add Range* four times to bring the total number of ranges to six. Enter the following ranges: [source,text] @@ -304,13 +304,13 @@ Click the *Apply changes* button image:images/apply-changes-button.png[] to disp image::images/tutorial-visualize-pie-2.png[] -This shows you what proportion of the 1000 accounts fall in these balance ranges. To see another dimension of the data, -we're going to add another bucket aggregation. We can break down each of the balance ranges further by the account +This shows you what proportion of the 1000 accounts fall in these balance ranges. To see another dimension of the data, +we're going to add another bucket aggregation. We can break down each of the balance ranges further by the account holder's age. -Click *Add sub-buckets* at the bottom, then select *Split Slices*. Choose the *Terms* aggregation and the *age* field from -the drop-downs. -Click the *Apply changes* button image:images/apply-changes-button.png[] to add an external ring with the new +Click *Add sub-buckets* at the bottom, then select *Split Slices*. Choose the *Terms* aggregation and the *age* field from +the drop-downs. +Click the *Apply changes* button image:images/apply-changes-button.png[] to add an external ring with the new results. image::images/tutorial-visualize-pie-3.png[] @@ -318,74 +318,74 @@ image::images/tutorial-visualize-pie-3.png[] Save this chart by clicking the *Save Visualization* button to the right of the search field. Name the visualization _Pie Example_. -Next, we're going to make a bar chart. Click on *New Visualization*, then *Vertical bar chart*. Select *From a new +Next, we're going to make a bar chart. Click on *New Visualization*, then *Vertical bar chart*. Select *From a new search* and the `shakes*` index pattern. You'll see a single big bar, since we haven't defined any buckets yet: image::images/tutorial-visualize-bar-1.png[] -For the Y-axis metrics aggregation, select *Unique Count*, with *speaker* as the field. For Shakespeare plays, it might -be useful to know which plays have the lowest number of distinct speaking parts, if your theater company is short on +For the Y-axis metrics aggregation, select *Unique Count*, with *speaker* as the field. For Shakespeare plays, it might +be useful to know which plays have the lowest number of distinct speaking parts, if your theater company is short on actors. For the X-Axis buckets, select the *Terms* aggregation with the *play_name* field. For the *Order*, select *Ascending*, leaving the *Size* at 5. Write a description for the axes in the *Custom Label* fields. -Leave the other elements at their default values and click the *Apply changes* button +Leave the other elements at their default values and click the *Apply changes* button image:images/apply-changes-button.png[]. Your chart should now look like this: image::images/tutorial-visualize-bar-2.png[] -Notice how the individual play names show up as whole phrases, instead of being broken down into individual words. This -is the result of the mapping we did at the beginning of the tutorial, when we marked the *play_name* field as 'not +Notice how the individual play names show up as whole phrases, instead of being broken down into individual words. This +is the result of the mapping we did at the beginning of the tutorial, when we marked the *play_name* field as 'not analyzed'. -Hovering on each bar shows you the number of speaking parts for each play as a tooltip. You can turn this behavior off, +Hovering on each bar shows you the number of speaking parts for each play as a tooltip. You can turn this behavior off, as well as change many other options for your visualizations, by clicking the *Options* tab in the top left. -Now that you have a list of the smallest casts for Shakespeare plays, you might also be curious to see which of these -plays makes the greatest demands on an individual actor by showing the maximum number of speeches for a given part. Add -a Y-axis aggregation with the *Add metrics* button, then choose the *Max* aggregation for the *speech_number* field. In -the *Options* tab, change the *Bar Mode* drop-down to *grouped*, then click the *Apply changes* button +Now that you have a list of the smallest casts for Shakespeare plays, you might also be curious to see which of these +plays makes the greatest demands on an individual actor by showing the maximum number of speeches for a given part. Add +a Y-axis aggregation with the *Add metrics* button, then choose the *Max* aggregation for the *speech_number* field. In +the *Options* tab, change the *Bar Mode* drop-down to *grouped*, then click the *Apply changes* button image:images/apply-changes-button.png[]. Your chart should now look like this: image::images/tutorial-visualize-bar-3.png[] -As you can see, _Love's Labours Lost_ has an unusually high maximum speech number, compared to the other plays, and +As you can see, _Love's Labours Lost_ has an unusually high maximum speech number, compared to the other plays, and might therefore make more demands on an actor's memory. -Note how the *Number of speaking parts* Y-axis starts at zero, but the bars don't begin to differentiate until 18. To -make the differences stand out, starting the Y-axis at a value closer to the minimum, check the +Note how the *Number of speaking parts* Y-axis starts at zero, but the bars don't begin to differentiate until 18. To +make the differences stand out, starting the Y-axis at a value closer to the minimum, check the *Scale Y-Axis to data bounds* box in the *Options* tab. Save this chart with the name _Bar Example_. -Next, we're going to make a tile map chart to visualize some geographic data. Click on *New Visualization*, then -*Tile map*. Select *From a new search* and the `logstash-*` index pattern. Define the time window for the events -we're exploring by clicking the time selector at the top right of the Kibana interface. Click on *Absolute*, then set +Next, we're going to make a tile map chart to visualize some geographic data. Click on *New Visualization*, then +*Tile map*. Select *From a new search* and the `logstash-*` index pattern. Define the time window for the events +we're exploring by clicking the time selector at the top right of the Kibana interface. Click on *Absolute*, then set the start time to May 18, 2015 and the end time for the range to May 20, 2015: image::images/tutorial-timepicker.png[] -Once you've got the time range set up, click the *Go* button, then close the time picker by clicking the small up arrow +Once you've got the time range set up, click the *Go* button, then close the time picker by clicking the small up arrow at the bottom. You'll see a map of the world, since we haven't defined any buckets yet: image::images/tutorial-visualize-map-1.png[] -Select *Geo Coordinates* as the bucket, then click the *Apply changes* button image:images/apply-changes-button.png[]. +Select *Geo Coordinates* as the bucket, then click the *Apply changes* button image:images/apply-changes-button.png[]. Your chart should now look like this: image::images/tutorial-visualize-map-2.png[] -You can navigate the map by clicking and dragging, zoom with the image:images/viz-zoom.png[] buttons, or hit the *Fit -Data Bounds* image:images/viz-fit-bounds.png[] button to zoom to the lowest level that includes all the points. You can -also create a filter to define a rectangle on the map, either to include or exclude, by clicking the -*Latitude/Longitude Filter* image:images/viz-lat-long-filter.png[] button and drawing a bounding box on the map. +You can navigate the map by clicking and dragging, zoom with the image:images/viz-zoom.png[] buttons, or hit the *Fit +Data Bounds* image:images/viz-fit-bounds.png[] button to zoom to the lowest level that includes all the points. You can +also create a filter to define a rectangle on the map, either to include or exclude, by clicking the +*Latitude/Longitude Filter* image:images/viz-lat-long-filter.png[] button and drawing a bounding box on the map. A green oval with the filter definition displays right under the query box: image::images/tutorial-visualize-map-3.png[] -Hover on the filter to display the controls to toggle, pin, invert, or delete the filter. Save this chart with the name +Hover on the filter to display the controls to toggle, pin, invert, or delete the filter. Save this chart with the name _Map Example_. -Finally, we're going to define a sample Markdown widget to display on our dashboard. Click on *New Visualization*, then +Finally, we're going to define a sample Markdown widget to display on our dashboard. Click on *New Visualization*, then *Markdown widget*, to display a very simple Markdown entry field: image::images/tutorial-visualize-md-1.png[] @@ -393,11 +393,11 @@ image::images/tutorial-visualize-md-1.png[] Write the following text in the field: [source,markdown] -# This is a tutorial dashboard! +# This is a tutorial dashboard! The Markdown widget uses **markdown** syntax. > Blockquotes in Markdown use the > character. -Click the *Apply changes* button image:images/apply-changes-button.png[] to display the rendered Markdown in the +Click the *Apply changes* button image:images/apply-changes-button.png[] to display the rendered Markdown in the preview pane: image::images/tutorial-visualize-md-2.png[] @@ -407,21 +407,21 @@ Save this visualization with the name _Markdown Example_. [[tutorial-dashboard]] === Putting it all Together with Dashboards -A Kibana dashboard is a collection of visualizations that you can arrange and share. To get started, click the -*Dashboard* tab, then the *Add Visualization* button at the far right of the search box to display the list of saved -visualizations. Select _Markdown Example_, _Pie Example_, _Bar Example_, and _Map Example_, then close the list of -visualizations by clicking the small up-arrow at the bottom of the list. You can move the containers for each -visualization by clicking and dragging the title bar. Resize the containers by dragging the lower right corner of a +A Kibana dashboard is a collection of visualizations that you can arrange and share. To get started, click the +*Dashboard* tab, then the *Add Visualization* button at the far right of the search box to display the list of saved +visualizations. Select _Markdown Example_, _Pie Example_, _Bar Example_, and _Map Example_, then close the list of +visualizations by clicking the small up-arrow at the bottom of the list. You can move the containers for each +visualization by clicking and dragging the title bar. Resize the containers by dragging the lower right corner of a visualization's container. Your sample dashboard should end up looking roughly like this: image::images/tutorial-dashboard.png[] -Click the *Save Dashboard* button, then name the dashboard _Tutorial Dashboard_. You can share a saved dashboard by +Click the *Save Dashboard* button, then name the dashboard _Tutorial Dashboard_. You can share a saved dashboard by clicking the *Share* button to display HTML embedding code as well as a direct link. [float] [[wrapping-up]] === Wrapping Up -Now that you've handled the basic aspects of Kibana's functionality, you're ready to explore Kibana in further detail. +Now that you've handled the basic aspects of Kibana's functionality, you're ready to explore Kibana in further detail. Take a look at the rest of the documentation for more details! From 10d478fadade51fbab38fb05de236c9c5bf213e6 Mon Sep 17 00:00:00 2001 From: Paul Echeverri Date: Wed, 6 Jul 2016 14:46:38 -0700 Subject: [PATCH 2/3] Updated link to raw --- docs/getting-started.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started.asciidoc b/docs/getting-started.asciidoc index 5a72049b3707f2..c52d193d17af8f 100644 --- a/docs/getting-started.asciidoc +++ b/docs/getting-started.asciidoc @@ -28,7 +28,7 @@ The tutorials in this section rely on the following data sets: * The complete works of William Shakespeare, suitably parsed into fields. Download this data set by clicking here: https://www.elastic.co/guide/en/kibana/3.0/snippets/shakespeare.json[shakespeare.json]. * A set of fictitious accounts with randomly generated data, in CSV format. Download this data set by clicking here: - https://github.com/elastic/kibana/tree/master/docs/tutorial/accounts.csv[accounts.csv] + https://raw.githubusercontent.com/elastic/kibana/master/docs/tutorial/accounts.csv[accounts.csv] * A set of randomly generated log files. Download this data set by clicking here: https://download.elastic.co/demos/kibana/gettingstarted/logs.jsonl.gz[logs.jsonl.gz] From 17afa9ffb8481a26edbbf953af80ed79620780e3 Mon Sep 17 00:00:00 2001 From: Paul Echeverri Date: Thu, 30 Jun 2016 14:32:21 -0700 Subject: [PATCH 3/3] Stripped trailing whitespace throughout --- docs/access.asciidoc | 8 +- docs/advanced-settings.asciidoc | 2 +- docs/apps.asciidoc | 2 +- docs/autorefresh.asciidoc | 6 +- docs/color-formatter.asciidoc | 11 +- docs/color-picker.asciidoc | 2 +- docs/dashboard.asciidoc | 46 +++--- docs/discover.asciidoc | 140 ++++++++-------- docs/filter-pinning.asciidoc | 20 +-- docs/introduction.asciidoc | 34 ++-- docs/kibana-yml.asciidoc | 3 +- docs/line.asciidoc | 26 +-- docs/markdown.asciidoc | 4 +- docs/metric.asciidoc | 4 +- docs/production.asciidoc | 228 ++++++++++++++++++++++++--- docs/setup.asciidoc | 4 +- docs/string-formatter.asciidoc | 2 +- docs/url-formatter.asciidoc | 12 +- docs/visualization-raw-data.asciidoc | 12 +- docs/visualize.asciidoc | 64 ++++---- docs/x-axis-aggs.asciidoc | 42 ++--- docs/y-axis-aggs.asciidoc | 24 +-- 22 files changed, 443 insertions(+), 253 deletions(-) diff --git a/docs/access.asciidoc b/docs/access.asciidoc index 43b6ec6689314d..8de87d5efa3e8f 100644 --- a/docs/access.asciidoc +++ b/docs/access.asciidoc @@ -1,11 +1,11 @@ [[access]] == Accessing Kibana -Kibana is a web application that you access through port 5601. All you need to do is point your web browser at the -machine where Kibana is running and specify the port number. For example, `localhost:5601` or +Kibana is a web application that you access through port 5601. All you need to do is point your web browser at the +machine where Kibana is running and specify the port number. For example, `localhost:5601` or `http://YOURDOMAIN.com:5601`. -When you access Kibana, the <> page loads by default with the default index pattern selected. The +When you access Kibana, the <> page loads by default with the default index pattern selected. The time filter is set to the last 15 minutes and the search query is set to match-all (\*). If you don't see any documents, try setting the time filter to a wider time range. @@ -14,7 +14,7 @@ If you still don't see any results, it's possible that you don't *have* any docu [[status]] === Checking Kibana Status -You can reach the Kibana server's status page by navigating to `localhost:5601/status`. The status page displays +You can reach the Kibana server's status page by navigating to `localhost:5601/status`. The status page displays information about the server's resource usage and lists the installed plugins. image::images/kibana-status-page.png[] diff --git a/docs/advanced-settings.asciidoc b/docs/advanced-settings.asciidoc index fae631b0e46c71..c3dcc8e2c854b2 100644 --- a/docs/advanced-settings.asciidoc +++ b/docs/advanced-settings.asciidoc @@ -53,7 +53,7 @@ mentioned use "_default_". `timepicker:refreshIntervalDefaults`:: The time filter's default refresh interval. `dashboard:defaultDarkTheme`:: Set this property to `true` to make new dashboards use the dark theme by default. `filters:pinnedByDefault`:: Set this property to `true` to make filters have a global state by default. -`notifications:banner`:: You can specify a custom banner to display temporary notices to all users. This field supports +`notifications:banner`:: You can specify a custom banner to display temporary notices to all users. This field supports Markdown. `notifications:lifetime:banner`:: Specifies the duration in milliseconds for banner notification displays. The default value is 3000000. Set this field to `Infinity` to disable banner notifications. `notifications:lifetime:error`:: Specifies the duration in milliseconds for error notification displays. The default value is 300000. Set this field to `Infinity` to disable error notifications. diff --git a/docs/apps.asciidoc b/docs/apps.asciidoc index 747619d14d4e35..f1b38e37759142 100644 --- a/docs/apps.asciidoc +++ b/docs/apps.asciidoc @@ -1,7 +1,7 @@ [[kibana-apps]] == Kibana Apps -The Kibana UI serves as a framework that can contain several different applications. You can switch between these +The Kibana UI serves as a framework that can contain several different applications. You can switch between these applications by clicking the image:images/app-button.png[App Picker] *App picker* button to display the app bar: image::images/app-picker.png[] diff --git a/docs/autorefresh.asciidoc b/docs/autorefresh.asciidoc index 927aff68f0d7bd..fff1a3d9236747 100644 --- a/docs/autorefresh.asciidoc +++ b/docs/autorefresh.asciidoc @@ -1,5 +1,5 @@ === Automatically Refreshing the Page -You can configure a refresh interval to automatically refresh the page with the latest index data. This periodically +You can configure a refresh interval to automatically refresh the page with the latest index data. This periodically resubmits the search query. When a refresh interval is set, it is displayed to the left of the Time Filter in the menu bar. @@ -10,10 +10,10 @@ To set the refresh interval: . Click the *Refresh Interval* tab. . Choose a refresh interval from the list. -To automatically refresh the data, click the image:images/autorefresh.png[] *Auto-refresh* button when the time picker +To automatically refresh the data, click the image:images/autorefresh.png[] *Auto-refresh* button when the time picker is open and select an autorefresh interval: image::images/autorefresh-intervals.png[] -When auto-refresh is enabled, Kibana's top bar displays a pause button and the auto-refresh interval: +When auto-refresh is enabled, Kibana's top bar displays a pause button and the auto-refresh interval: image:images/autorefresh-pause.png[]. Click the *Pause* button to pause auto-refresh. diff --git a/docs/color-formatter.asciidoc b/docs/color-formatter.asciidoc index 601a4b3d38ff75..d9ba5e9be11657 100644 --- a/docs/color-formatter.asciidoc +++ b/docs/color-formatter.asciidoc @@ -1,11 +1,10 @@ The `Color` field formatter enables you to specify colors with specific ranges of values for a numeric field. -When you select the `Color` field formatter, Kibana displays the *Range*, *Font Color*, *Background Color*, and *Example* fields. +When you select the `Color` field formatter, Kibana displays the *Range*, *Font Color*, *Background Color*, and +*Example* fields. -Click the *Add Color* button to add a range of values to associate with a particular color. You can click in the *Font Color* and -*Background Color* fields to display a color picker. You can also enter a specific hex code value in the field. The effect of your current -color choices are displayed in the *Example* field. +Click the *Add Color* button to add a range of values to associate with a particular color. You can click in the *Font +Color* and *Background Color* fields to display a color picker. You can also enter a specific hex code value in the +field. The effect of your current color choices are displayed in the *Example* field. image::images/colorformatter.png[] - -//update image diff --git a/docs/color-picker.asciidoc b/docs/color-picker.asciidoc index 5c3bf129d58f76..e0f23262068d39 100644 --- a/docs/color-picker.asciidoc +++ b/docs/color-picker.asciidoc @@ -1,4 +1,4 @@ -You can customize the colors of your visualization by clicking the color dot next to each label to display the +You can customize the colors of your visualization by clicking the color dot next to each label to display the _color picker_. image::images/color-picker.png[An array of color dots that users can select] diff --git a/docs/dashboard.asciidoc b/docs/dashboard.asciidoc index 31d957de8887b7..c46de14bc51b0e 100644 --- a/docs/dashboard.asciidoc +++ b/docs/dashboard.asciidoc @@ -1,7 +1,7 @@ [[dashboard]] == Dashboard -A Kibana _dashboard_ displays a set of saved visualizations in groups that you can arrange freely. You can save a +A Kibana _dashboard_ displays a set of saved visualizations in groups that you can arrange freely. You can save a dashboard to share or reload at a later time. .Sample dashboard @@ -21,7 +21,7 @@ The first time you click the *Dashboard* tab, Kibana displays an empty dashboard image:images/NewDashboard.png[New Dashboard screen] -Build your dashboard by adding visualizations. By default, Kibana dashboards use a light color theme. To use a dark color +Build your dashboard by adding visualizations. By default, Kibana dashboards use a light color theme. To use a dark color theme instead, click the *Options* button and check the *Use dark theme* box. NOTE: You can change the default theme in the *Advanced* section of the *Settings* tab. @@ -34,37 +34,37 @@ include::autorefresh.asciidoc[] [[adding-visualizations-to-a-dashboard]] ==== Adding Visualizations to a Dashboard -To add a visualization to the dashboard, click the *Add* button in the toolbar panel. Select a saved visualization -from the list. You can filter the list of visualizations by typing a filter string into the *Visualization Filter* +To add a visualization to the dashboard, click the *Add* button in the toolbar panel. Select a saved visualization +from the list. You can filter the list of visualizations by typing a filter string into the *Visualization Filter* field. The visualization you select appears in a _container_ on your dashboard. -NOTE: If you see a message about the container's height or width being too small, <>. [float] [[saving-dashboards]] ==== Saving Dashboards -To save the dashboard, click the *Save Dashboard* button in the toolbar panel, enter a name for the dashboard in the -*Save As* field, and click the *Save* button. By default, dashboards store the time period specified in the time filter -when you save a dashboard. To disable this behavior, clear the *Store time with dashboard* box before clicking the +To save the dashboard, click the *Save Dashboard* button in the toolbar panel, enter a name for the dashboard in the +*Save As* field, and click the *Save* button. By default, dashboards store the time period specified in the time filter +when you save a dashboard. To disable this behavior, clear the *Store time with dashboard* box before clicking the *Save* button. [float] [[loading-a-saved-dashboard]] ==== Loading a Saved Dashboard -Click the *Load Saved Dashboard* button to display a list of existing dashboards. The saved dashboard selector includes -a text field to filter by dashboard name and a link to the Object Editor for managing your saved dashboards. You can +Click the *Load Saved Dashboard* button to display a list of existing dashboards. The saved dashboard selector includes +a text field to filter by dashboard name and a link to the Object Editor for managing your saved dashboards. You can also access the Object Editor by clicking *Settings > Objects*. [float] [[sharing-dashboards]] ==== Sharing Dashboards -You can share dashboards with other users. You can share a direct link to the Kibana dashboard or embed the dashboard +You can share dashboards with other users. You can share a direct link to the Kibana dashboard or embed the dashboard in your Web page. NOTE: A user must have Kibana access in order to view embedded dashboards. @@ -72,7 +72,7 @@ NOTE: A user must have Kibana access in order to view embedded dashboards. To share a dashboard, click the *Share* button image:images/share-dashboard.png[] to display the _Sharing_ panel. Click the *Copy to Clipboard* button image:images/share-link.png[] to copy the native URL or embed HTML to the clipboard. -Click the *Generate short URL* button image:images/share-short-link.png[] to create a shortened URL for sharing or +Click the *Generate short URL* button image:images/share-short-link.png[] to create a shortened URL for sharing or embedding. [float] @@ -85,40 +85,40 @@ To embed a dashboard, copy the embed code from the _Share_ display into your ext [[customizing-your-dashboard]] === Customizing Dashboard Elements -The visualizations in your dashboard are stored in resizable _containers_ that you can arrange on the dashboard. This +The visualizations in your dashboard are stored in resizable _containers_ that you can arrange on the dashboard. This section discusses customizing these containers. [float] [[moving-containers]] ==== Moving Containers -Click and hold a container's header to move the container around the dashboard. Other containers will shift as needed +Click and hold a container's header to move the container around the dashboard. Other containers will shift as needed to make room for the moving container. Release the mouse button to confirm the container's new location. [float] [[resizing-containers]] ==== Resizing Containers -Move the cursor to the bottom right corner of the container until the cursor changes to point at the corner. After the -cursor changes, click and drag the corner of the container to change the container's size. Release the mouse button to +Move the cursor to the bottom right corner of the container until the cursor changes to point at the corner. After the +cursor changes, click and drag the corner of the container to change the container's size. Release the mouse button to confirm the new container size. [float] [[removing-containers]] ==== Removing Containers -Click the *x* icon at the top right corner of a container to remove that container from the dashboard. Removing a +Click the *x* icon at the top right corner of a container to remove that container from the dashboard. Removing a container from a dashboard does not delete the saved visualization in that container. [float] [[viewing-detailed-information]] ==== Viewing Detailed Information -To display the raw data behind the visualization, click the bar at the bottom of the container. Tabs with detailed +To display the raw data behind the visualization, click the bar at the bottom of the container. Tabs with detailed information about the raw data replace the visualization, as in this example: .Table -A representation of the underlying data, presented as a paginated data grid. You can sort the items +A representation of the underlying data, presented as a paginated data grid. You can sort the items in the table by clicking on the table headers at the top of each column. image:images/NYCTA-Table.jpg[] @@ -131,20 +131,20 @@ The raw response from the server, presented in JSON format. image:images/NYCTA-Response.jpg[] .Statistics -A summary of the statistics related to the request and the response, presented as a data grid. The data -grid includes the query duration, the request duration, the total number of records found on the server, and the +A summary of the statistics related to the request and the response, presented as a data grid. The data +grid includes the query duration, the request duration, the total number of records found on the server, and the index pattern used to make the query. image:images/NYCTA-Statistics.jpg[] To export the raw data behind the visualization as a comma-separated-values (CSV) file, click on either the -*Raw* or *Formatted* links at the bottom of any of the detailed information tabs. A raw export contains the data as it +*Raw* or *Formatted* links at the bottom of any of the detailed information tabs. A raw export contains the data as it is stored in Elasticsearch. A formatted export contains the results of any applicable Kibana [field formatters]. [float] [[changing-the-visualization]] === Changing the Visualization -Click the _Edit_ button image:images/EditVis.png[Pencil button] at the top right of a container to open the +Click the _Edit_ button image:images/EditVis.png[Pencil button] at the top right of a container to open the visualization in the <> page. [float] diff --git a/docs/discover.asciidoc b/docs/discover.asciidoc index 75f6e58ec5158e..0a003bba5d5241 100644 --- a/docs/discover.asciidoc +++ b/docs/discover.asciidoc @@ -1,17 +1,17 @@ [[discover]] == Discover -You can interactively explore your data from the Discover page. You have access to every document in every index that -matches the selected index pattern. You can submit search queries, filter the search results, and view document data. -You can also see the number of documents that match the search query and get field value statistics. If a time field is -configured for the selected index pattern, the distribution of documents over time is displayed in a histogram at the -top of the page. +You can interactively explore your data from the Discover page. You have access to every document in every index that +matches the selected index pattern. You can submit search queries, filter the search results, and view document data. +You can also see the number of documents that match the search query and get field value statistics. If a time field is +configured for the selected index pattern, the distribution of documents over time is displayed in a histogram at the +top of the page. image::images/Discover-Start-Annotated.jpg[Discover Page] [float] [[set-time-filter]] === Setting the Time Filter -The Time Filter restricts the search results to a specific time period. You can set a time filter if your index +The Time Filter restricts the search results to a specific time period. You can set a time filter if your index contains time-based events and a time-field is configured for the selected index pattern. By default the time filter is set to the last 15 minutes. You can use the Time Picker to change the time filter @@ -23,56 +23,56 @@ To set a time filter with the Time Picker: . To set a quick filter, simply click one of the shortcut links. . To specify a relative Time Filter, click *Relative* and enter the relative start time. You can specify the relative start time as any number of seconds, minutes, hours, days, months, or years ago. -. To specify an absolute Time Filter, click *Absolute* and enter the start date in the *From* field and the end date in +. To specify an absolute Time Filter, click *Absolute* and enter the start date in the *From* field and the end date in the *To* field. -. Click the caret at the bottom of the Time Picker to hide it. +. Click the caret at the bottom of the Time Picker to hide it. To set a Time Filter from the histogram, do one of the following: * Click the bar that represents the time interval you want to zoom in on. -* Click and drag to view a specific timespan. You must start the selection with the cursor over the background of the -chart--the cursor changes to a plus sign when you hover over a valid start point. +* Click and drag to view a specific timespan. You must start the selection with the cursor over the background of the +chart--the cursor changes to a plus sign when you hover over a valid start point. -You can use the browser Back button to undo your changes. +You can use the browser Back button to undo your changes. -The histogram lists the time range you're currently exploring, as well as the intervals that range is currently using. -To change the intervals, click the link and select an interval from the drop-down. The default behavior automatically +The histogram lists the time range you're currently exploring, as well as the intervals that range is currently using. +To change the intervals, click the link and select an interval from the drop-down. The default behavior automatically sets an interval based on the time range. [float] [[search]] === Searching Your Data You can search the indices that match the current index pattern by submitting a search from the Discover page. -You can enter simple query strings, use the -Lucene https://lucene.apache.org/core/2_9_4/queryparsersyntax.html[query syntax], or use the full JSON-based -{ref}/query-dsl.html[Elasticsearch Query DSL]. +You can enter simple query strings, use the +Lucene https://lucene.apache.org/core/2_9_4/queryparsersyntax.html[query syntax], or use the full JSON-based +{ref}/query-dsl.html[Elasticsearch Query DSL]. -When you submit a search, the histogram, Documents table, and Fields list are updated to reflect +When you submit a search, the histogram, Documents table, and Fields list are updated to reflect the search results. The total number of hits (matching documents) is shown in the upper right corner of the -histogram. The Documents table shows the first five hundred hits. By default, the hits are listed in reverse -chronological order, with the newest documents shown first. You can reverse the sort order by by clicking on the Time -column header. You can also sort the table using the values in any indexed field. For more information, see +histogram. The Documents table shows the first five hundred hits. By default, the hits are listed in reverse +chronological order, with the newest documents shown first. You can reverse the sort order by by clicking on the Time +column header. You can also sort the table using the values in any indexed field. For more information, see <>. To search your data: -. Enter a query string in the Search field: +. Enter a query string in the Search field: + -* To perform a free text search, simply enter a text string. For example, if you're searching web server logs, you +* To perform a free text search, simply enter a text string. For example, if you're searching web server logs, you could enter `safari` to search all fields for the term `safari`. + -* To search for a value in a specific field, you prefix the value with the name of the field. For example, you could +* To search for a value in a specific field, you prefix the value with the name of the field. For example, you could enter `status:200` to limit the results to entries that contain the value `200` in the `status` field. + -* To search for a range of values, you can use the bracketed range syntax, `[START_VALUE TO END_VALUE]`. For example, +* To search for a range of values, you can use the bracketed range syntax, `[START_VALUE TO END_VALUE]`. For example, to find entries that have 4xx status codes, you could enter `status:[400 TO 499]`. + * To specify more complex search criteria, you can use the Boolean operators `AND`, `OR`, and `NOT`. For example, -to find entries that have 4xx status codes and have an extension of `php` or `html`, you could enter `status:[400 TO +to find entries that have 4xx status codes and have an extension of `php` or `html`, you could enter `status:[400 TO 499] AND (extension:php OR extension:html)`. + -NOTE: These examples use the Lucene query syntax. You can also submit queries using the Elasticsearch Query DSL. For -examples, see {ref}/query-dsl-query-string-query.html#query-string-syntax[query string syntax] in the Elasticsearch +NOTE: These examples use the Lucene query syntax. You can also submit queries using the Elasticsearch Query DSL. For +examples, see {ref}/query-dsl-query-string-query.html#query-string-syntax[query string syntax] in the Elasticsearch Reference. + . Press *Enter* or click the *Search* button to submit your search query. @@ -90,7 +90,7 @@ Saving a search saves both the search query string and the currently selected in To save the current search: -. Click the *Save* button in the Discover toolbar. +. Click the *Save* button in the Discover toolbar. . Enter a name for the search and click *Save*. [float] @@ -101,13 +101,13 @@ To load a saved search: . Click the *Open* button in the Discover toolbar. . Select the search you want to open. -If the saved search is associated with a different index pattern than is currently selected, opening the saved search +If the saved search is associated with a different index pattern than is currently selected, opening the saved search also changes the selected index pattern. [float] [[select-pattern]] ==== Changing Which Indices You're Searching -When you submit a search request, the indices that match the currently-selected index pattern are searched. The current +When you submit a search request, the indices that match the currently-selected index pattern are searched. The current index pattern is shown below the search field. To change which indices you are searching, click the name of the current index pattern to display a list of the configured index patterns and select a different index pattern. @@ -121,36 +121,36 @@ include::autorefresh.asciidoc[] [float] [[field-filter]] === Filtering by Field -You can filter the search results to display only those documents that contain a particular value in a field. You can +You can filter the search results to display only those documents that contain a particular value in a field. You can also create negative filters that exclude documents that contain the specified field value. -You can add filters from the Fields list or from the Documents table. When you add a filter, it is displayed in the -filter bar below the search query. From the filter bar, you can enable or disable a filter, invert the filter (change -it from a positive filter to a negative filter and vice-versa), toggle the filter on or off, or remove it entirely. +You can add filters from the Fields list or from the Documents table. When you add a filter, it is displayed in the +filter bar below the search query. From the filter bar, you can enable or disable a filter, invert the filter (change +it from a positive filter to a negative filter and vice-versa), toggle the filter on or off, or remove it entirely. Click the small left-facing arrow to the right of the index pattern selection drop-down to collapse the Fields list. To add a filter from the Fields list: -. Click the name of the field you want to filter on. This displays the top five values for that field. To the right of -each value, there are two magnifying glass buttons--one for adding a regular (positive) filter, and -one for adding a negative filter. -. To add a positive filter, click the *Positive Filter* button image:images/PositiveFilter.jpg[Positive Filter Button]. +. Click the name of the field you want to filter on. This displays the top five values for that field. To the right of +each value, there are two magnifying glass buttons--one for adding a regular (positive) filter, and +one for adding a negative filter. +. To add a positive filter, click the *Positive Filter* button image:images/PositiveFilter.jpg[Positive Filter Button]. This filters out documents that don't contain that value in the field. -. To add a negative filter, click the *Negative Filter* button image:images/NegativeFilter.jpg[Negative Filter Button]. -This excludes documents that contain that value in the field. +. To add a negative filter, click the *Negative Filter* button image:images/NegativeFilter.jpg[Negative Filter Button]. +This excludes documents that contain that value in the field. To add a filter from the Documents table: -. Expand a document in the Documents table by clicking the *Expand* button image:images/ExpandButton.jpg[Expand Button] -to the left of the document's entry in the first column (the first column is usually Time). To the right of each field -name, there are two magnifying glass buttons--one for adding a regular (positive) filter, and one for adding a negative -filter. -. To add a positive filter based on the document's value in a field, click the -*Positive Filter* button image:images/PositiveFilter.jpg[Positive Filter Button]. This filters out documents that don't +. Expand a document in the Documents table by clicking the *Expand* button image:images/ExpandButton.jpg[Expand Button] +to the left of the document's entry in the first column (the first column is usually Time). To the right of each field +name, there are two magnifying glass buttons--one for adding a regular (positive) filter, and one for adding a negative +filter. +. To add a positive filter based on the document's value in a field, click the +*Positive Filter* button image:images/PositiveFilter.jpg[Positive Filter Button]. This filters out documents that don't contain the specified value in that field. -. To add a negative filter based on the document's value in a field, click the -*Negative Filter* button image:images/NegativeFilter.jpg[Negative Filter Button]. This excludes documents that contain -the specified value in that field. +. To add a negative filter based on the document's value in a field, click the +*Negative Filter* button image:images/NegativeFilter.jpg[Negative Filter Button]. This excludes documents that contain +the specified value in that field. [float] [[discover-filters]] @@ -159,52 +159,52 @@ include::filter-pinning.asciidoc[] [float] [[document-data]] === Viewing Document Data -When you submit a search query, the 500 most recent documents that match the query are listed in the Documents table. -You can configure the number of documents shown in the table by setting the `discover:sampleSize` property in -<>. By default, the table shows the localized version of the time field specified -in the selected index pattern and the document `_source`. You can <> +When you submit a search query, the 500 most recent documents that match the query are listed in the Documents table. +You can configure the number of documents shown in the table by setting the `discover:sampleSize` property in +<>. By default, the table shows the localized version of the time field specified +in the selected index pattern and the document `_source`. You can <> from the Fields list. You can <> by any indexed field that's included in the table. -To view a document's field data, click the *Expand* button image:images/ExpandButton.jpg[Expand Button] to the left of -the document's entry in the first column (the first column is usually Time). Kibana reads the document data from -Elasticsearch and displays the document fields in a table. The table contains a row for each field that contains the +To view a document's field data, click the *Expand* button image:images/ExpandButton.jpg[Expand Button] to the left of +the document's entry in the first column (the first column is usually Time). Kibana reads the document data from +Elasticsearch and displays the document fields in a table. The table contains a row for each field that contains the name of the field, add filter buttons, and the field value. image::images/Expanded-Document.png[] . To view the original JSON document (pretty-printed), click the *JSON* tab. -. To view the document data as a separate page, click the link. You can bookmark and share this link to provide direct +. To view the document data as a separate page, click the link. You can bookmark and share this link to provide direct access to a particular document. . To collapse the document details, click the *Collapse* button image:images/CollapseButton.jpg[Collapse Button]. -. To toggle a particular field's column in the Documents table, click the +. To toggle a particular field's column in the Documents table, click the image:images/add-column-button.png[Add Column] *Toggle column in table* button. [float] [[sorting]] ==== Sorting the Document List -You can sort the documents in the Documents table by the values in any indexed field. Documents in index patterns that +You can sort the documents in the Documents table by the values in any indexed field. Documents in index patterns that are configured with time fields are sorted in reverse chronological order by default. -To change the sort order, click the name of the field you want to sort by. The fields you can use for sorting have a +To change the sort order, click the name of the field you want to sort by. The fields you can use for sorting have a sort button to the right of the field name. Clicking the field name a second time reverses the sort order. [float] [[adding-columns]] ==== Adding Field Columns to the Documents Table -By default, the Documents table shows the localized version of the time field specified in the selected index pattern +By default, the Documents table shows the localized version of the time field specified in the selected index pattern and the document `_source`. You can add fields to the table from the Fields list or from a document's expanded view. To add field columns to the Documents table: -. Mouse over a field in the Fields list and click its *add* button image:images/AddFieldButton.jpg[Add Field Button]. +. Mouse over a field in the Fields list and click its *add* button image:images/AddFieldButton.jpg[Add Field Button]. . Repeat until you've added all the fields you want to display in the Documents table. -. Alternately, add a field column directly from a document's expanded view by clicking the +. Alternately, add a field column directly from a document's expanded view by clicking the image:images/add-column-button.png[Add Column] *Toggle column in table* button. The added field columns replace the `_source` column in the Documents table. The added fields are also -listed in the *Selected Fields* section at the top of the field list. +listed in the *Selected Fields* section at the top of the field list. -To rearrange the field columns in the table, mouse over the header of the column you want to move and click the *Move* +To rearrange the field columns in the table, mouse over the header of the column you want to move and click the *Move* button. image:images/Discover-MoveColumn.jpg[Move Column] @@ -214,18 +214,18 @@ image:images/Discover-MoveColumn.jpg[Move Column] ==== Removing Field Columns from the Documents Table To remove field columns from the Documents table: -. Mouse over the field you want to remove in the *Selected Fields* section of the Fields list and click its *remove* +. Mouse over the field you want to remove in the *Selected Fields* section of the Fields list and click its *remove* button image:images/RemoveFieldButton.jpg[Remove Field Button]. . Repeat until you've removed all the fields you want to drop from the Documents table. [float] [[viewing-field-stats]] === Viewing Field Data Statistics -From the field list, you can see how many documents in the Documents table contain a particular field, what the top 5 -values are, and what percentage of documents contain each value. +From the field list, you can see how many documents in the Documents table contain a particular field, what the top 5 +values are, and what percentage of documents contain each value. -To view field data statistics, click the name of a field in the Fields list. The field can be anywhere in the Fields -list. +To view field data statistics, click the name of a field in the Fields list. The field can be anywhere in the Fields +list. image:images/Discover-FieldStats.jpg[Field Statistics] diff --git a/docs/filter-pinning.asciidoc b/docs/filter-pinning.asciidoc index ac1176a245a6b0..055cf8f22d171d 100644 --- a/docs/filter-pinning.asciidoc +++ b/docs/filter-pinning.asciidoc @@ -1,6 +1,6 @@ === Working with Filters -When you create a filter anywhere in Kibana, the filter conditions display in an oval under the search text +When you create a filter anywhere in Kibana, the filter conditions display in an oval under the search text entry box: image::images/filter-sample.png[] @@ -9,16 +9,16 @@ Hovering on the filter oval displays the following icons: image::images/filter-allbuttons.png[] -Enable Filter image:images/filter-enable.png[]:: Click this icon to disable the filter without removing it. You can -enable the filter again later by clicking the icon again. Disabled filters display a striped shaded color, grey for +Enable Filter image:images/filter-enable.png[]:: Click this icon to disable the filter without removing it. You can +enable the filter again later by clicking the icon again. Disabled filters display a striped shaded color, grey for inclusion filters and red for exclusion filters. Pin Filter image:images/filter-pin.png[]:: Click this icon to _pin_ a filter. Pinned filters persist across Kibana tabs. -You can pin filters from the _Visualize_ tab, click on the _Discover_ or _Dashboard_ tabs, and those filters remain in +You can pin filters from the _Visualize_ tab, click on the _Discover_ or _Dashboard_ tabs, and those filters remain in place. -NOTE: If you have a pinned filter and you're not seeing any query results, that your current tab's index pattern is one -that the filter applies to. -Toggle Filter image:images/filter-toggle.png[]:: Click this icon to _toggle_ a filter. By default, filters are inclusion -filters, and display in grey. Only elements that match the filter are displayed. To change this to an exclusion +NOTE: If you have a pinned filter and you're not seeing any query results, that your current tab's index pattern is one +that the filter applies to. +Toggle Filter image:images/filter-toggle.png[]:: Click this icon to _toggle_ a filter. By default, filters are inclusion +filters, and display in grey. Only elements that match the filter are displayed. To change this to an exclusion filters, displaying only elements that _don't_ match, toggle the filter. Exclusion filters display in red. Remove Filter image:images/filter-delete.png[]:: Click this icon to remove a filter entirely. Custom Filter image:images/filter-custom.png[]:: Click this icon to display a text field where you can customize the JSON @@ -26,7 +26,7 @@ representation of the filter and specify an alias to use for the filter name: + image::images/filter-custom-json.png[] + -You can use JSON filter representation to implement predicate logic, with `should` for OR, `must` for AND, and `must_not` +You can use JSON filter representation to implement predicate logic, with `should` for OR, `must` for AND, and `must_not` for NOT: + .OR Example @@ -94,5 +94,5 @@ for NOT: ========== Click the *Done* button to update the filter with your changes. -To apply any of the filter actions to all the filters currently in place, click the image:images/filter-actions.png[] +To apply any of the filter actions to all the filters currently in place, click the image:images/filter-actions.png[] *Global Filter Actions* button and select an action. diff --git a/docs/introduction.asciidoc b/docs/introduction.asciidoc index 664e73e89d7f2a..d5f2da894e4583 100644 --- a/docs/introduction.asciidoc +++ b/docs/introduction.asciidoc @@ -1,21 +1,21 @@ [[introduction]] == Introduction -Kibana is an open source analytics and visualization platform designed to work with Elasticsearch. You use Kibana to -search, view, and interact with data stored in Elasticsearch indices. You can easily perform advanced data analysis +Kibana is an open source analytics and visualization platform designed to work with Elasticsearch. You use Kibana to +search, view, and interact with data stored in Elasticsearch indices. You can easily perform advanced data analysis and visualize your data in a variety of charts, tables, and maps. -Kibana makes it easy to understand large volumes of data. Its simple, browser-based interface enables you to quickly +Kibana makes it easy to understand large volumes of data. Its simple, browser-based interface enables you to quickly create and share dynamic dashboards that display changes to Elasticsearch queries in real time. -Setting up Kibana is a snap. You can install Kibana and start exploring your Elasticsearch indices in minutes -- no -code, no additional infrastructure required. +Setting up Kibana is a snap. You can install Kibana and start exploring your Elasticsearch indices in minutes -- no +code, no additional infrastructure required. -For more information about creating and sharing visualizations and dashboards, see the <> -and <> topics. A complete <> covering several aspects of Kibana's +For more information about creating and sharing visualizations and dashboards, see the <> +and <> topics. A complete <> covering several aspects of Kibana's functionality is also available. -NOTE: This guide describes how to use Kibana {version}. For information about what's new in Kibana {version}, see +NOTE: This guide describes how to use Kibana {version}. For information about what's new in Kibana {version}, see the <>. //// @@ -23,25 +23,25 @@ the <>. [[data-discovery]] === Data Discovery and Visualization -Let's take a look at how you might use Kibana to explore and visualize data. -We've indexed some data from Transport for London (TFL) that shows one week +Let's take a look at how you might use Kibana to explore and visualize data. +We've indexed some data from Transport for London (TFL) that shows one week of transit (Oyster) card usage. -From Kibana's Discover page, we can submit search queries, filter the results, and -examine the data in the returned documents. For example, we can get all trips +From Kibana's Discover page, we can submit search queries, filter the results, and +examine the data in the returned documents. For example, we can get all trips completed by the Tube during the week by excluding incomplete trips and trips by bus: image:images/TFL-CompletedTrips.jpg[Discover] -Right away, we can see the peaks for the morning and afternoon commute hours in the -histogram. By default, the Discover page also shows the first 500 entries that match the -search criteria. You can change the time filter, interact with the histogram to drill -down into the data, and view the details of particular documents. For more +Right away, we can see the peaks for the morning and afternoon commute hours in the +histogram. By default, the Discover page also shows the first 500 entries that match the +search criteria. You can change the time filter, interact with the histogram to drill +down into the data, and view the details of particular documents. For more information about exploring your data from the Discover page, see <>. You can construct visualizations of your search results from the Visualization page. Each visualization is associated with a search. For example, we can create a histogram -that shows the weekly London commute traffic via the Tube using our previous search. +that shows the weekly London commute traffic via the Tube using our previous search. The Y-axis shows the number of trips. The X-axis shows the day and time. By adding a sub-aggregation, we can see the top 3 end stations during each hour: diff --git a/docs/kibana-yml.asciidoc b/docs/kibana-yml.asciidoc index 5cda11a363c027..5be95c03e65918 100644 --- a/docs/kibana-yml.asciidoc +++ b/docs/kibana-yml.asciidoc @@ -31,7 +31,8 @@ wait for Elasticsearch to respond to pings. Elasticsearch. This value must be a positive integer. `elasticsearch.requestHeadersWhitelist:`:: *Default: `[ 'authorization' ]`* List of Kibana client-side headers to send to Elasticsearch. To send *no* client-side headers, set this value to [] (an empty list). -`elasticsearch.shardTimeout:`:: *Default: 0* Time in milliseconds for Elasticsearch to wait for responses from shards. Set to 0 to disable. +`elasticsearch.shardTimeout:`:: *Default: 0* Time in milliseconds for Elasticsearch to wait for responses from shards. Set +to 0 to disable. `elasticsearch.startupTimeout:`:: *Default: 5000* Time in milliseconds to wait for Elasticsearch at Kibana startup before retrying. `pid.file:`:: Specifies the path where Kibana creates the process ID file. diff --git a/docs/line.asciidoc b/docs/line.asciidoc index 42b9e7f850570b..b83431093c94f8 100644 --- a/docs/line.asciidoc +++ b/docs/line.asciidoc @@ -6,7 +6,7 @@ This chart's Y axis is the _metrics_ axis. The following aggregations are availa include::y-axis-aggs.asciidoc[] Before you choose a buckets aggregation, specify if you are splitting slices within a single chart or splitting into -multiple charts. A multiple chart split must run before any other aggregations. When you split a chart, you can change +multiple charts. A multiple chart split must run before any other aggregations. When you split a chart, you can change if the splits are displayed in a row or a column by clicking the *Rows | Columns* selector. include::x-axis-aggs.asciidoc[] @@ -19,37 +19,37 @@ You can click the *Advanced* link to display more customization options for your *Exclude Pattern Flags*:: A standard set of Java flags for the exclusion pattern. *Include Pattern*:: Specify a pattern in this field to include in the results. *Include Pattern Flags*:: A standard set of Java flags for the inclusion pattern. -*JSON Input*:: A text field where you can add specific JSON-formatted properties to merge with the aggregation +*JSON Input*:: A text field where you can add specific JSON-formatted properties to merge with the aggregation definition, as in the following example: [source,shell] { "script" : "doc['grade'].value * 1.2" } -NOTE: In Elasticsearch releases 1.4.3 and later, this functionality requires you to enable +NOTE: In Elasticsearch releases 1.4.3 and later, this functionality requires you to enable {ref}/modules-scripting.html[dynamic Groovy scripting]. The availability of these options varies depending on the aggregation you choose. Select the *Options* tab to change the following aspects of the chart: -*Y-Axis Scale*:: You can select *linear*, *log*, or *square root* scales for the chart's Y axis. You can use a log -scale to display data that varies exponentially, such as a compounding interest chart, or a square root scale to -regularize the display of data sets with variabilities that are themselves highly variable. This kind of data, where -the variability is itself variable over the domain being examined, is known as _heteroscedastic_ data. For example, if +*Y-Axis Scale*:: You can select *linear*, *log*, or *square root* scales for the chart's Y axis. You can use a log +scale to display data that varies exponentially, such as a compounding interest chart, or a square root scale to +regularize the display of data sets with variabilities that are themselves highly variable. This kind of data, where +the variability is itself variable over the domain being examined, is known as _heteroscedastic_ data. For example, if a data set of height versus weight has a relatively narrow range of variability at the short end of height, but a wider -range at the taller end, the data set is heteroscedastic. -*Smooth Lines*:: Check this box to curve the line from point to point. Bear in mind that smoothed lines necessarily +range at the taller end, the data set is heteroscedastic. +*Smooth Lines*:: Check this box to curve the line from point to point. Bear in mind that smoothed lines necessarily affect the representation of your data and create a potential for ambiguity. *Show Connecting Lines*:: Check this box to draw lines between the points on the chart. *Show Circles*:: Check this box to draw each data point on the chart as a small circle. *Current time marker*:: For charts of time-series data, check this box to draw a red line on the current time. -*Set Y-Axis Extents*:: Check this box and enter values in the *y-max* and *y-min* fields to set the Y axis to specific -values. +*Set Y-Axis Extents*:: Check this box and enter values in the *y-max* and *y-min* fields to set the Y axis to specific +values. *Show Tooltip*:: Check this box to enable the display of tooltips. -*Scale Y-Axis to Data Bounds*:: The default Y-axis bounds are zero and the maximum value returned in the data. Check +*Scale Y-Axis to Data Bounds*:: The default Y-axis bounds are zero and the maximum value returned in the data. Check this box to change both upper and lower bounds to match the values returned in the data. -After changing options, click the *Apply changes* button to update your visualization, or the grey *Discard +After changing options, click the *Apply changes* button to update your visualization, or the grey *Discard changes* button to keep your visualization in its current state. [float] diff --git a/docs/markdown.asciidoc b/docs/markdown.asciidoc index e107f3a06fbab1..8073390f77557d 100644 --- a/docs/markdown.asciidoc +++ b/docs/markdown.asciidoc @@ -1,7 +1,7 @@ [[markdown-widget]] === Markdown Widget -The Markdown widget is a text entry field that accepts GitHub-flavored Markdown text. Kibana renders the text you enter -in this field and displays the results on the dashboard. You can click the *Help* link to go to the +The Markdown widget is a text entry field that accepts GitHub-flavored Markdown text. Kibana renders the text you enter +in this field and displays the results on the dashboard. You can click the *Help* link to go to the https://help.github.com/articles/github-flavored-markdown/[help page] for GitHub flavored Markdown. Click *Apply* to display the rendered text in the Preview pane or *Discard* to revert to a previous version. diff --git a/docs/metric.asciidoc b/docs/metric.asciidoc index e4ce743a8210b5..d66144d5b6c567 100644 --- a/docs/metric.asciidoc +++ b/docs/metric.asciidoc @@ -7,13 +7,13 @@ include::y-axis-aggs.asciidoc[] You can click the *Advanced* link to display more customization options: -*JSON Input*:: A text field where you can add specific JSON-formatted properties to merge with the aggregation +*JSON Input*:: A text field where you can add specific JSON-formatted properties to merge with the aggregation definition, as in the following example: [source,shell] { "script" : "doc['grade'].value * 1.2" } -NOTE: In Elasticsearch releases 1.4.3 and later, this functionality requires you to enable +NOTE: In Elasticsearch releases 1.4.3 and later, this functionality requires you to enable {ref}/modules-scripting.html[dynamic Groovy scripting]. The availability of these options varies depending on the aggregation you choose. diff --git a/docs/production.asciidoc b/docs/production.asciidoc index f911770e236c69..a950f97062e791 100644 --- a/docs/production.asciidoc +++ b/docs/production.asciidoc @@ -20,31 +20,221 @@ and an Elasticsearch client node on the same machine. For more information, see [float] [[configuring-kibana-shield]] === Configuring Kibana to Work with {scyld} -If you are using {scyld} to authenticate Elasticsearch users, you need to provide -the Kibana server with credentials so it can access the `.kibana` index and monitor -the cluster. -To configure credentials for the Kibana server: +Kibana users have to authenticate when your cluster has {scyld} enabled. You +configure {scyld} roles for your Kibana users to control what data those users +can access. Kibana runs a webserver that makes requests to Elasticsearch on the +client's behalf, so you also need to configure credentials for the Kibana server +so those requests can be authenticated. -. Assign the `kibana4_server` role to a user in {scyld}. For more information, see -{shield}/kibana.html#kibana4-server-role[Configuring a Role for the Kibana Server] -in the {scyld} documentation. +You must configure Kibana to encrypt communications between the browser and the +Kibana server to prevent user passwords from being sent in the clear. If are +using SSL/TLS to encrypt traffic to and from the nodes in your Elasticsearch +cluster, you must also configure Kibana to connect to Elasticsearch via HTTPS. - . Set the `kibana_elasticsearch_username` and -`kibana_elasticsearch_password` properties in `kibana.yml` to specify the credentials -of the user you assigned the `kibana4_server` role: +With {scyld} enabled, if you load a Kibana dashboard that accesses data in an +index that you are not authorized to view, you get an error that indicates the +index does not exist. {scyld} does not currently provide a way to control which +users can load which dashboards. + +To use Kibana with {scyld}: + +. Configure the password for the built-in `kibana` user. The Kibana server uses +this user to gain access to the cluster monitoring APIs and the `.kibana` index. +The server does _not_ need access to user indexes. + -[source,text] ----- -kibana_elasticsearch_username: kibana-user -kibana_elasticsearch_password: kibana-password ----- +By default, the `kibana` user password is set to `changeme`. Change this password +through the reset password API: ++ +[source,shell] +-------------------------------------------------------------------------------- +curl -XPUT 'localhost:9200/_security/user/kibana/_password' -d '{ + "password" : "s0m3th1ngs3cr3t" +}' +-------------------------------------------------------------------------------- ++ +Once reset, you need to add the following property to `kibana.yml`: ++ +[source,yaml] +-------------------------------------------------------------------------------- +elasticsearch.password: "s0m3th1ngs3cr3t" +-------------------------------------------------------------------------------- -Users on release 4.0 and later of Kibana also need access to the `.kibana` index so they can save and load searches, visualizations, and -dashboards. For more information, see {shield}/kibana.html[Using Kibana with {scyld}]. +[[kibana-roles]] +. Derive Kibana user roles from the example <> +user role. Assign the roles to the Kibana users to control which indices they can +access. Kibana users need access to the indices that they will be working with +and the `.kibana` index where their saved searches, visualizations, and dashboards +are stored. Users also need access to the `.kibana-devnull` index. The example +`my_kibana_user` role grants read access to the indices that match the +`logstash-*` pattern and full access to the `.kibana` index, which is required. ++ +TIP: You can define as many different roles for your Kibana users as you need. ++ +[[kibana-user-role]] +For example, the following `my_kibana_user` role only allows users to discover +and visualize data in the `logstash-*` indices. ++ +[source,js] +-------------------------------------------------------------------------------- +{ + "cluster" : [ "monitor" ], + "indices" : [ + { + "names" : [ "logstash-*" ], + "privileges" : [ "view_index_metadata", "read" ] + }, + { + "names" : [ ".kibana*" ], <1> + "privileges" : [ "manage", "read", "index" ] + } + ] +} +-------------------------------------------------------------------------------- +<1> All Kibana users need access to the `.kibana` and `.kibana-devnull` indices. + +. Assign the appropriate roles to your Kibana users or groups of users: + +** If you're using the `native` realm, you can assign roles using the +{shield}/shield-rest.html#shield-users-rest[{scyld} User Management API]. For example, the following +creates a user named `jacknich` and assigns it the `kibana_monitoring` role: ++ +[source,js] +-------------------------------------------------------------------------------- +POST /_xpack/security/user/jacknich +{ + "password" : "t0pS3cr3t", + "roles" : [ "kibana_monitoring" ] +} +-------------------------------------------------------------------------------- + +** If you are using an LDAP or Active Directory realm, you can either assign +roles on a per user basis, or assign roles to groups of users. By default, role +mappings are stored in {shield}/mapping-roles.html[`CONFIGDIR/x-pack/role_mapping.yml`]. +For example, the following snippet assigns the `kibana_monitoring` role to the +group named `admins` and the user named Jack Nicholson: ++ +[source,yaml] +-------------------------------------------------------------------------------- +kibana_monitoring: + - "cn=admins,dc=example,dc=com" + - "cn=Jack Nicholson,dc=example,dc=com" +-------------------------------------------------------------------------------- + +. If you have enabled SSL encryption in {scyld}, configure Kibana to connect +to Elasticsearch via HTTPS. To do this: + +.. Specify the HTTPS protocol in the `elasticsearch.url` setting in the Kibana +configuration file, `kibana.yml`: ++ +[source,yaml] +-------------------------------------------------------------------------------- +elasticsearch.url: "https://.com:9200" +-------------------------------------------------------------------------------- + +.. If you are using your own CA to sign certificates for Elasticsearch, set the +`elasticsearch.ssl.ca` setting in `kibana.yml` to specify the location of the PEM +file. ++ +[source,yaml] +-------------------------------------------------------------------------------- +elasticsearch.ssl.ca: /path/to/your/cacert.pem +-------------------------------------------------------------------------------- + +. Configure Kibana to encrypt communications between the browser and the Kibana +server. To do this, configure the `server.ssl.key` and `server.ssl.cert` properties +in `kibana.yml`: ++ +[source,yaml] +-------------------------------------------------------------------------------- +server.ssl.key: /path/to/your/server.key +server.ssl.cert: /path/to/your/server.crt +-------------------------------------------------------------------------------- ++ +Once you enable SSL encryption between the browser and the Kibana server, access +Kibana via HTTPS. For example, `https://localhost:5601`. ++ +NOTE: Enabling browser encryption is required to prevent passing user credentials + in the clear. + +. Install X-Pack into Kibana. {scyld} secures user sessions and enables users +to log in and out of Kibana. To install the X-Pack on Kibana: + +.. Run the following command in your Kibana installation directory. ++ +[source,console] +-------------------------------------------------------------------------------- +bin/kibana-plugin install x-pack +-------------------------------------------------------------------------------- ++ +[NOTE] +============================================================================= +To perform an offline install, download X-Pack from ++http://download.elasticsearch.org/kibana/x-pack/xpack-{version}.zip+ +(http://download.elasticsearch.org/kibana/x-pack/xpack-{version}.zip.sha1.txt[sha1]) +and run: + +[source,shell] +--------------------------------------------------------- +bin/kibana-plugin install file:///path/to/file/xpack-{version}.tar.gz. +--------------------------------------------------------- +============================================================================= + +.. Set the `xpack.security.encryptionKey` property in the `kibana.yml` configuration file. +You can use any text string as the encryption key. ++ +[source,yaml] +-------------------------------------------------------------------------------- +xpack.security.encryptionKey: "something_secret" +-------------------------------------------------------------------------------- + +.. To change the default session duration, set the `xpack.security.sessionTimeout` property +in the `kibana.yml` configuration file. By default, sessions expire after 30 minutes. +The timeout is specified in milliseconds. For example, set the timeout to 600000 +to expire sessions after 10 minutes: ++ +[source,yaml] +-------------------------------------------------------------------------------- +xpack.security.sessionTimeout: 600000 +-------------------------------------------------------------------------------- + +. Restart Kibana and verify that you can sign in as a user. If you are running +Kibana locally, go to `https://localhost:5601` and enter the credentials for a +user you've assigned a Kibana user role. For example, you could log in as the +`jacknich` user created above. ++ +kibana-login.jpg["Kibana Login",link="images/kibana-login.jpg"] ++ +NOTE: This must be a user who has been assigned a role derived from the example + <>. Kibana server credentials + should only be used internally by the Kibana server. The Kibana server role + doesn't grant permission to access user indices. + +[float] +[[security-ui-settings]] +===== Kibana {scyld} UI Settings +[options="header"] +|====== +| Name | Default | Description +| `xpack.security.encryptionKey` | - | An arbitrary string used to encrypt credentials in a + cookie. It is crucial that this key is not exposed to + users of Kibana. Required. +| `xpack.security.sessionTimeout` | `1800000` (30 minutes) | Sets the session duration (in milliseconds). +| `xpack.security.cookieName` | `"sid"` | Sets the name of the cookie used for the session. +| `xpack.security.skipSslCheck` | `false` | Advanced setting. Set to `true` to enable Kibana to + start if `server.ssl.cert` and `server.ssl.key` are + not specified in `kibana.yml`. This should only be + used if either SSL is configured outside of Kibana + (for example, you are routing requests through a load + balancer or proxy) or + `xpack.security.useUnsafeSessions` is also set to + `true`. +| `xpack.security.useUnsafeSessions` | `false` | Advanced setting. Set to `true` to use insecure + cookies for sessions in Kibana. Requires + `xpack.security.skipSslCheck` to also be set to + `true`. +|====== -TIP: See <> for important information on Kibana and -the dynamic mapping feature in Elasticsearch. [float] [[enabling-ssl]] diff --git a/docs/setup.asciidoc b/docs/setup.asciidoc index e84ece6ddd4ca1..99f4f3f67baf32 100644 --- a/docs/setup.asciidoc +++ b/docs/setup.asciidoc @@ -81,8 +81,8 @@ simply be the name of a single index. reads the index mapping to list all of the fields that contain a timestamp. If your index doesn't have time-based data, disable the *Index contains time-based events* option. + -WARNING: Using event times to create index names is *deprecated* in this release of Kibana. Starting in the 2.1 -release, Elasticsearch includes sophisticated date parsing APIs that Kibana uses to determine date information, +WARNING: Using event times to create index names is *deprecated* in this release of Kibana. Starting in the 2.1 +release, Elasticsearch includes sophisticated date parsing APIs that Kibana uses to determine date information, removing the need to specify dates in the index pattern name. + . Click *Create* to add the index pattern. This first pattern is automatically configured as the default. diff --git a/docs/string-formatter.asciidoc b/docs/string-formatter.asciidoc index 63232c0b7fbea3..ed3aa45873284e 100644 --- a/docs/string-formatter.asciidoc +++ b/docs/string-formatter.asciidoc @@ -3,7 +3,7 @@ The `String` field formatter can apply the following transformations to the fiel * Convert to lowercase * Convert to uppercase * Convert to title case -* Apply the short dots transformation, which replaces the content before a `.` character with the first character of +* Apply the short dots transformation, which replaces the content before a `.` character with the first character of that content, as in the following example: [horizontal] diff --git a/docs/url-formatter.asciidoc b/docs/url-formatter.asciidoc index 819523c6cbf53c..b2c1d149b769e4 100644 --- a/docs/url-formatter.asciidoc +++ b/docs/url-formatter.asciidoc @@ -1,9 +1,9 @@ The `Url` field formatter can take on the following types: -* The *Link* type turn the contents of the field into an URL. +* The *Link* type turn the contents of the field into an URL. * The *Image* type can be used to specify an image directory where a specified image is located. -You can customize either type of URL field formats with templates. A _URL template_ enables you to add specific values +You can customize either type of URL field formats with templates. A _URL template_ enables you to add specific values to a partial URL. Use the string `{{value}}` to add the contents of the field to a fixed URL. For example, when: @@ -14,15 +14,15 @@ For example, when: The resulting URL replaces `{{value}}` with the user ID from the field. -The `{{value}}` template string URL-encodes the contents of the field. When a field encoded into a URL contains -non-ASCII characters, these characters are replaced with a `%` character and the appropriate hexadecimal code. For +The `{{value}}` template string URL-encodes the contents of the field. When a field encoded into a URL contains +non-ASCII characters, these characters are replaced with a `%` character and the appropriate hexadecimal code. For example, field contents `users/admin` result in the URL template adding `users%2Fadmin`. -When the formatter type is set to *Image*, the `{{value}}` template string specifies the name of an image at the +When the formatter type is set to *Image*, the `{{value}}` template string specifies the name of an image at the specified URI. In order to pass unescaped values directly to the URL, use the `{{rawValue}}` string. -A _Label Template_ enables you to specify a text string that displays instead of the raw URL. You can use the +A _Label Template_ enables you to specify a text string that displays instead of the raw URL. You can use the `{{value}}` template string normally in label templates. You can also use the `{{url}}` template string to display the formatted URL. diff --git a/docs/visualization-raw-data.asciidoc b/docs/visualization-raw-data.asciidoc index 0c882a6854ea28..ef50426146e882 100644 --- a/docs/visualization-raw-data.asciidoc +++ b/docs/visualization-raw-data.asciidoc @@ -1,8 +1,8 @@ -To display the raw data behind the visualization, click the bar at the bottom of the container. Tabs with detailed +To display the raw data behind the visualization, click the bar at the bottom of the container. Tabs with detailed information about the raw data replace the visualization: .Table -A representation of the underlying data, presented as a paginated data grid. You can sort the items +A representation of the underlying data, presented as a paginated data grid. You can sort the items in the table by clicking on the table headers at the top of each column. .Request @@ -12,11 +12,11 @@ The raw request used to query the server, presented in JSON format. The raw response from the server, presented in JSON format. .Statistics -A summary of the statistics related to the request and the response, presented as a data grid. The data -grid includes the query duration, the request duration, the total number of records found on the server, and the +A summary of the statistics related to the request and the response, presented as a data grid. The data +grid includes the query duration, the request duration, the total number of records found on the server, and the index pattern used to make the query. To export the raw data behind the visualization as a comma-separated-values (CSV) file, click on either the -*Raw* or *Formatted* links at the bottom of any of the detailed information tabs. A raw export contains the data as it -is stored in Elasticsearch. A formatted export contains the results of any applicable Kibana +*Raw* or *Formatted* links at the bottom of any of the detailed information tabs. A raw export contains the data as it +is stored in Elasticsearch. A formatted export contains the results of any applicable Kibana <>. diff --git a/docs/visualize.asciidoc b/docs/visualize.asciidoc index c598b2ea47acce..87c296cbe58a26 100644 --- a/docs/visualize.asciidoc +++ b/docs/visualize.asciidoc @@ -1,15 +1,15 @@ [[visualize]] == Visualize -You can use the _Visualize_ page to design data visualizations. You can save these visualizations, use them -individually, or combine visualizations into a _dashboard_. A visualization can be based on one of the following +You can use the _Visualize_ page to design data visualizations. You can save these visualizations, use them +individually, or combine visualizations into a _dashboard_. A visualization can be based on one of the following data source types: * A new interactive search * A saved search * An existing saved visualization -Visualizations are based on the {ref}search-aggregations.html[aggregation] feature introduced in Elasticsearch 1.x. +Visualizations are based on the {ref}search-aggregations.html[aggregation] feature introduced in Elasticsearch 1.x. [float] [[createvis]] @@ -27,22 +27,22 @@ Choose a visualization type when you start the New Visualization wizard: [horizontal] <>:: Use area charts to visualize the total contribution of several different series. -<>:: Use data tables to display the raw data of a composed aggregation. You can display the data +<>:: Use data tables to display the raw data of a composed aggregation. You can display the data table for several other visualizations by clicking at the bottom of the visualization. <>:: Use line charts to compare different series. -<>:: Use the Markdown widget to display free-form information or instructions about your +<>:: Use the Markdown widget to display free-form information or instructions about your dashboard. <>:: Use the metric visualization to display a single number on your dashboard. <>:: Use pie charts to display each source's contribution to a total. <>:: Use tile maps to associate the results of an aggregation with geographic points. <>:: Use vertical bar charts as a general-purpose chart. -You can also load a saved visualization that you created earlier. The saved visualization selector includes a text -field to filter by visualization name and a link to the Object Editor, accessible through *Settings > Objects*, to +You can also load a saved visualization that you created earlier. The saved visualization selector includes a text +field to filter by visualization name and a link to the Object Editor, accessible through *Settings > Objects*, to manage your saved visualizations. -If your new visualization is a Markdown widget, selecting that type takes you to a text entry field where you enter the -text to display in the widget. For all other types of visualization, selecting the type takes you to data source +If your new visualization is a Markdown widget, selecting that type takes you to a text entry field where you enter the +text to display in the widget. For all other types of visualization, selecting the type takes you to data source selection. [float] @@ -50,8 +50,8 @@ selection. ==== Step 2: Choose a Data Source You can choose a new or saved search to serve as the data source for your visualization. Searches are associated with -an index or a set of indexes. When you select _new search_ on a system with multiple indices configured, select an -index pattern from the drop-down to bring up the visualization editor. +an index or a set of indexes. When you select _new search_ on a system with multiple indices configured, select an +index pattern from the drop-down to bring up the visualization editor. When you create a visualization from a saved search and save the visualization, the search is tied to the visualization. When you make changes to the search that is linked to the visualization, the visualization updates automatically. @@ -60,7 +60,7 @@ When you make changes to the search that is linked to the visualization, the vis [[visualization-editor]] ==== Step 3: The Visualization Editor -The visualization editor enables you to configure and edit visualizations. The visualization editor has the following +The visualization editor enables you to configure and edit visualizations. The visualization editor has the following main elements: 1. <> @@ -78,37 +78,37 @@ include::autorefresh.asciidoc[] ===== Toolbar The toolbar has a search field for interactive data searches, as well as controls to manage saving and loading -visualizations. For visualizations based on saved searches, the search bar is grayed out. To edit the search, replacing +visualizations. For visualizations based on saved searches, the search bar is grayed out. To edit the search, replacing the saved search with the edited version, double-click the search field. -The toolbar at the right of the search box has buttons for creating new visualizations, saving the current -visualization, loading an existing visualization, sharing or embedding the visualization, and refreshing the data for +The toolbar at the right of the search box has buttons for creating new visualizations, saving the current +visualization, loading an existing visualization, sharing or embedding the visualization, and refreshing the data for the current visualization. [float] [[aggregation-builder]] ===== Aggregation Builder -Use the aggregation builder on the left of the page to configure the {ref}search-aggregations-metrics.html[metric] and {ref}search-aggregations-bucket.html[bucket] aggregations used in your +Use the aggregation builder on the left of the page to configure the {ref}search-aggregations-metrics.html[metric] and {ref}search-aggregations-bucket.html[bucket] aggregations used in your visualization. Buckets are analogous to SQL `GROUP BY` statements. For more information on aggregations, see the main {ref}search-aggregations.html[Elasticsearch aggregations reference]. -Bar, line, or area chart visualizations use _metrics_ for the y-axis and _buckets_ are used for the x-axis, segment bar -colors, and row/column splits. For pie charts, use the metric for the slice size and the bucket for the number of +Bar, line, or area chart visualizations use _metrics_ for the y-axis and _buckets_ are used for the x-axis, segment bar +colors, and row/column splits. For pie charts, use the metric for the slice size and the bucket for the number of slices. -Choose the metric aggregation for your visualization's Y axis, such as -{ref}/search-aggregations-metrics-valuecount-aggregation.html[count], -{ref}/search-aggregations-metrics-avg-aggregation.html[average], -{ref}/search-aggregations-metrics-sum-aggregation.html[sum], -{ref}/search-aggregations-metrics-min-aggregation.html[min], -{ref}/search-aggregations-metrics-max-aggregation.html[max], or -{ref}/search-aggregations-metrics-cardinality-aggregation.html[cardinality] -(unique count). Use bucket aggregations for the visualization's X axis, color slices, and row/column splits. Common +Choose the metric aggregation for your visualization's Y axis, such as +{ref}/search-aggregations-metrics-valuecount-aggregation.html[count], +{ref}/search-aggregations-metrics-avg-aggregation.html[average], +{ref}/search-aggregations-metrics-sum-aggregation.html[sum], +{ref}/search-aggregations-metrics-min-aggregation.html[min], +{ref}/search-aggregations-metrics-max-aggregation.html[max], or +{ref}/search-aggregations-metrics-cardinality-aggregation.html[cardinality] +(unique count). Use bucket aggregations for the visualization's X axis, color slices, and row/column splits. Common bucket aggregations include date histogram, range, terms, filters, and significant terms. -You can set the order in which buckets execute. In Elasticsearch, the first aggregation determines the data set -for any subsequent aggregations. The following example involves a date bar chart of Web page hits for the top 5 file +You can set the order in which buckets execute. In Elasticsearch, the first aggregation determines the data set +for any subsequent aggregations. The following example involves a date bar chart of Web page hits for the top 5 file extensions. To use the same extension across all hits, set this order: @@ -123,7 +123,7 @@ To chart the top 5 extensions for each hour, use the following order: 1. *X-Axis:* Date bar chart of `@timestamp` (with 1 hour interval) 2. *Color:* Terms aggregation of extensions -For these requests, Elasticsearch creates a date bar chart from all the records, then groups the top five extensions +For these requests, Elasticsearch creates a date bar chart from all the records, then groups the top five extensions inside each bucket, which in this example is a one-hour interval. NOTE: Remember, each subsequent bucket slices the data from the previous bucket. @@ -131,8 +131,8 @@ NOTE: Remember, each subsequent bucket slices the data from the previous bucket. To render the visualization on the _preview canvas_, click the *Apply Changes* button at the top right of the Aggregation Builder. -You can learn more about aggregation and how altering the order of aggregations affects your visualizations -https://www.elastic.co/blog/kibana-aggregation-execution-order-and-you[here]. +You can learn more about aggregation and how altering the order of aggregations affects your visualizations +https://www.elastic.co/blog/kibana-aggregation-execution-order-and-you[here]. [float] [[visualize-filters]] @@ -142,7 +142,7 @@ include::filter-pinning.asciidoc[] [[preview-canvas]] ===== Preview Canvas -The preview canvas displays a preview of the visualization you've defined in the aggregation builder. To refresh the +The preview canvas displays a preview of the visualization you've defined in the aggregation builder. To refresh the visualization preview, clicking the *Apply Changes* image:images/apply-changes-button.png[] button on the toolbar. include::area.asciidoc[] diff --git a/docs/x-axis-aggs.asciidoc b/docs/x-axis-aggs.asciidoc index 3b9fd3e9486235..0c8fd2aa2fabaa 100644 --- a/docs/x-axis-aggs.asciidoc +++ b/docs/x-axis-aggs.asciidoc @@ -1,43 +1,43 @@ -The X axis of this chart is the _buckets_ axis. You can define buckets for the X axis, for a split area on the +The X axis of this chart is the _buckets_ axis. You can define buckets for the X axis, for a split area on the chart, or for split charts. This chart's X axis supports the following aggregations. Click the linked name of each aggregation to visit the main Elasticsearch documentation for that aggregation. -*Date Histogram*:: A {ref}search-aggregations-bucket-datehistogram-aggregation.html[_date histogram_] is built from a -numeric field and organized by date. You can specify a time frame for the intervals in seconds, minutes, hours, days, -weeks, months, or years. You can also specify a custom interval frame by selecting *Custom* as the interval and -specifying a number and a time unit in the text field. Custom interval time units are *s* for seconds, *m* for minutes, -*h* for hours, *d* for days, *w* for weeks, and *y* for years. Different units support different levels of precision, +*Date Histogram*:: A {ref}search-aggregations-bucket-datehistogram-aggregation.html[_date histogram_] is built from a +numeric field and organized by date. You can specify a time frame for the intervals in seconds, minutes, hours, days, +weeks, months, or years. You can also specify a custom interval frame by selecting *Custom* as the interval and +specifying a number and a time unit in the text field. Custom interval time units are *s* for seconds, *m* for minutes, +*h* for hours, *d* for days, *w* for weeks, and *y* for years. Different units support different levels of precision, down to one second. -*Histogram*:: A standard {ref}search-aggregations-bucket-histogram-aggregation.html[_histogram_] is built from a -numeric field. Specify an integer interval for this field. Select the *Show empty buckets* checkbox to include empty +*Histogram*:: A standard {ref}search-aggregations-bucket-histogram-aggregation.html[_histogram_] is built from a +numeric field. Specify an integer interval for this field. Select the *Show empty buckets* checkbox to include empty intervals in the histogram. -*Range*:: With a {ref}/search-aggregations-bucket-range-aggregation.html[_range_] aggregation, you can specify ranges -of values for a numeric field. Click *Add Range* to add a set of range endpoints. Click the red *(x)* symbol to remove +*Range*:: With a {ref}/search-aggregations-bucket-range-aggregation.html[_range_] aggregation, you can specify ranges +of values for a numeric field. Click *Add Range* to add a set of range endpoints. Click the red *(x)* symbol to remove a range. -*Date Range*:: A {ref}search-aggregations-bucket-daterange-aggregation.html[_date range_] aggregation reports values -that are within a range of dates that you specify. You can specify the ranges for the dates using -{ref}common-options.html#date-math[_date math_] expressions. Click *Add Range* to add a set of range endpoints. +*Date Range*:: A {ref}search-aggregations-bucket-daterange-aggregation.html[_date range_] aggregation reports values +that are within a range of dates that you specify. You can specify the ranges for the dates using +{ref}common-options.html#date-math[_date math_] expressions. Click *Add Range* to add a set of range endpoints. Click the red *(/)* symbol to remove a range. *IPv4 Range*:: The {ref}search-aggregations-bucket-iprange-aggregation.html[_IPv4 range_] aggregation enables you to -specify ranges of IPv4 addresses. Click *Add Range* to add a set of range endpoints. Click the red *(/)* symbol to +specify ranges of IPv4 addresses. Click *Add Range* to add a set of range endpoints. Click the red *(/)* symbol to remove a range. -*Terms*:: A {ref}search-aggregations-bucket-terms-aggregation.html[_terms_] aggregation enables you to specify the top +*Terms*:: A {ref}search-aggregations-bucket-terms-aggregation.html[_terms_] aggregation enables you to specify the top or bottom _n_ elements of a given field to display, ordered by count or a custom metric. -*Filters*:: You can specify a set of {ref}/search-aggregations-bucket-filters-aggregation.html[_filters_] for the data. -You can specify a filter as a query string or in JSON format, just as in the Discover search bar. Click *Add Filter* to -add another filter. Click the image:images/labelbutton.png[Label button icon] *label* button to open the label field, where +*Filters*:: You can specify a set of {ref}/search-aggregations-bucket-filters-aggregation.html[_filters_] for the data. +You can specify a filter as a query string or in JSON format, just as in the Discover search bar. Click *Add Filter* to +add another filter. Click the image:images/labelbutton.png[Label button icon] *label* button to open the label field, where you can type in a name to display on the visualization. -*Significant Terms*:: Displays the results of the experimental +*Significant Terms*:: Displays the results of the experimental {ref}/search-aggregations-bucket-significantterms-aggregation.html[_significant terms_] aggregation. -Once you've specified an X axis aggregation, you can define sub-aggregations to refine the visualization. Click *+ Add +Once you've specified an X axis aggregation, you can define sub-aggregations to refine the visualization. Click *+ Add Sub Aggregation* to define a sub-aggregation, then choose *Split Area* or *Split Chart*, then select a sub-aggregation from the list of types. -When multiple aggregations are defined on a chart's axis, you can use the up or down arrows to the right of the +When multiple aggregations are defined on a chart's axis, you can use the up or down arrows to the right of the aggregation's type to change the aggregation's priority. Enter a string in the *Custom Label* field to change the display label. diff --git a/docs/y-axis-aggs.asciidoc b/docs/y-axis-aggs.asciidoc index f404abb42dbbb4..397e167de8ffe8 100644 --- a/docs/y-axis-aggs.asciidoc +++ b/docs/y-axis-aggs.asciidoc @@ -1,23 +1,23 @@ -*Count*:: The {ref}/search-aggregations-metrics-valuecount-aggregation.html[_count_] aggregation returns a raw count of +*Count*:: The {ref}/search-aggregations-metrics-valuecount-aggregation.html[_count_] aggregation returns a raw count of the elements in the selected index pattern. -*Average*:: This aggregation returns the {ref}/search-aggregations-metrics-avg-aggregation.html[_average_] of a numeric +*Average*:: This aggregation returns the {ref}/search-aggregations-metrics-avg-aggregation.html[_average_] of a numeric field. Select a field from the drop-down. -*Sum*:: The {ref}/search-aggregations-metrics-sum-aggregation.html[_sum_] aggregation returns the total sum of a numeric +*Sum*:: The {ref}/search-aggregations-metrics-sum-aggregation.html[_sum_] aggregation returns the total sum of a numeric field. Select a field from the drop-down. -*Min*:: The {ref}/search-aggregations-metrics-min-aggregation.html[_min_] aggregation returns the minimum value of a +*Min*:: The {ref}/search-aggregations-metrics-min-aggregation.html[_min_] aggregation returns the minimum value of a numeric field. Select a field from the drop-down. -*Max*:: The {ref}/search-aggregations-metrics-max-aggregation.html[_max_] aggregation returns the maximum value of a +*Max*:: The {ref}/search-aggregations-metrics-max-aggregation.html[_max_] aggregation returns the maximum value of a numeric field. Select a field from the drop-down. -*Unique Count*:: The {ref}/search-aggregations-metrics-cardinality-aggregation.html[_cardinality_] aggregation returns +*Unique Count*:: The {ref}/search-aggregations-metrics-cardinality-aggregation.html[_cardinality_] aggregation returns the number of unique values in a field. Select a field from the drop-down. -*Standard Deviation*:: The {ref}/search-aggregations-metrics-extendedstats-aggregation.html[_extended stats_] +*Standard Deviation*:: The {ref}/search-aggregations-metrics-extendedstats-aggregation.html[_extended stats_] aggregation returns the standard deviation of data in a numeric field. Select a field from the drop-down. -*Percentiles*:: The {ref}/search-aggregations-metrics-percentile-aggregation.html[_percentile_] aggregation divides the -values in a numeric field into percentile bands that you specify. Select a field from the drop-down, then specify one -or more ranges in the *Percentiles* fields. Click the *X* to remove a percentile field. Click *+ Add* to add a +*Percentiles*:: The {ref}/search-aggregations-metrics-percentile-aggregation.html[_percentile_] aggregation divides the +values in a numeric field into percentile bands that you specify. Select a field from the drop-down, then specify one +or more ranges in the *Percentiles* fields. Click the *X* to remove a percentile field. Click *+ Add* to add a percentile field. -*Percentile Rank*:: The {ref}/search-aggregations-metrics-percentile-rank-aggregation.html[_percentile ranks_] -aggregation returns the percentile rankings for the values in the numeric field you specify. Select a numeric field +*Percentile Rank*:: The {ref}/search-aggregations-metrics-percentile-rank-aggregation.html[_percentile ranks_] +aggregation returns the percentile rankings for the values in the numeric field you specify. Select a numeric field from the drop-down, then specify one or more percentile rank values in the *Values* fields. Click the *X* to remove a values field. Click *+Add* to add a values field.