From 3589b557eb164c25737b65fb3d4a7df9f6d63210 Mon Sep 17 00:00:00 2001 From: Paul Echeverri Date: Thu, 14 Jul 2016 13:39:57 -0700 Subject: [PATCH] Updates doc for 4.5.3 release --- docs/kibana-yml.asciidoc | 52 ++++++++++++-------- docs/tilemap.asciidoc | 102 ++++++++++++++++++++------------------- 2 files changed, 85 insertions(+), 69 deletions(-) diff --git a/docs/kibana-yml.asciidoc b/docs/kibana-yml.asciidoc index 54d52636330ae..ce5792cf827fa 100644 --- a/docs/kibana-yml.asciidoc +++ b/docs/kibana-yml.asciidoc @@ -2,43 +2,55 @@ [horizontal] `server.port:`:: *Default: 5601* Kibana is served by a back end server. This setting specifies the port to use. `server.host:`:: *Default: "0.0.0.0"* This setting specifies the IP address of the back end server. -`server.basePath:`:: Enables you to specify a path to mount Kibana at if you are running behind a proxy. This setting cannot -end in a slash (`/`). +`server.basePath:`:: Enables you to specify a path to mount Kibana at if you are running behind a proxy. This setting +cannot end in a slash (`/`). `server.maxPayloadBytes:`:: *Default: 1048576* The maximum payload size in bytes for incoming server requests. -`elasticsearch.url:`:: *Default: "http://localhost:9200"* The URL of the Elasticsearch instance to use for all your +`elasticsearch.url:`:: *Default: "http://localhost:9200"* The URL of the Elasticsearch instance to use for all your queries. -`elasticsearch.preserveHost:`:: *Default: true* When this setting’s value is true Kibana uses the hostname specified in -the `server.host` setting. When the value of this setting is `false`, Kibana uses the hostname of the host that connects +`elasticsearch.preserveHost:`:: *Default: true* When this setting’s value is true Kibana uses the hostname specified in +the `server.host` setting. When the value of this setting is `false`, Kibana uses the hostname of the host that connects to this Kibana instance. -`kibana.index:`:: *Default: ".kibana"* Kibana uses an index in Elasticsearch to store saved searches, visualizations and +`kibana.index:`:: *Default: ".kibana"* Kibana uses an index in Elasticsearch to store saved searches, visualizations and dashboards. Kibana creates a new index if the index doesn’t already exist. `kibana.defaultAppId:`:: *Default: "discover"* The default application to load. -`elasticsearch.username:` and `elasticsearch.password:`:: If your Elasticsearch is protected with basic authentication, -these settings provide the username and password that the Kibana server uses to perform maintenance on the Kibana index at +[[tilemap-settings]]`tilemap_url:`:: *Default: `elasticsearch_url: +"https://tiles.elastic.co/v1/default/{z}/{x}/{y}.png?my_app_name=kibana&my_app_version=&elastic_tile_service_tos=agree"`* The URL to the tilemap service Kibana uses for tilemap visualizations. +added[4.5.3] +`tilemap_min_zoom:`:: *Default: 1* The minimum zoom level. added[4.5.3] +`tilemap_max_zoom:`:: *Default: 7* The maximum zoom level. added[4.5.3] +`tilemap_attribution:`:: *Default: `© [Elastic Tile Service](https://www.elastic.co/elastic-tile-service)`* The map +attribution string. added[4.5.3] +`tilemap_subdomains:`:: An array of subdomains used by the tile service. Specify the position of the subdomain the URL +with the token `{s}`.added[4.5.3] + + +`elasticsearch.username:` and `elasticsearch.password:`:: If your Elasticsearch is protected with basic authentication, +these settings provide the username and password that the Kibana server uses to perform maintenance on the Kibana index at startup. Your Kibana users still need to authenticate with Elasticsearch, which is proxied through the Kibana server. -`server.ssl.cert:` and `server.ssl.key:`:: Paths to the PEM-format SSL certificate and SSL key files, respectively. These +`server.ssl.cert:` and `server.ssl.key:`:: Paths to the PEM-format SSL certificate and SSL key files, respectively. These files enable SSL for outgoing requests from the Kibana server to the browser. -`elasticsearch.ssl.cert:` and `elasticsearch.ssl.key:`:: Optional settings that provide the paths to the PEM-format SSL +`elasticsearch.ssl.cert:` and `elasticsearch.ssl.key:`:: Optional settings that provide the paths to the PEM-format SSL certificate and key files. These files validate that your Elasticsearch backend uses the same key files. -`elasticsearch.ssl.ca:`:: Optional setting that enables you to specify a path to the PEM file for the certificate +`elasticsearch.ssl.ca:`:: Optional setting that enables you to specify a path to the PEM file for the certificate authority for your Elasticsearch instance. -`elasticsearch.ssl.verify:`:: *Default: true* To disregard the validity of SSL certificates, change this setting’s value +`elasticsearch.ssl.verify:`:: *Default: true* To disregard the validity of SSL certificates, change this setting’s value to `false`. -`elasticsearch.pingTimeout:`:: *Default: the value of the `elasticsearch.requestTimeout` setting* Time in milliseconds to +`elasticsearch.pingTimeout:`:: *Default: the value of the `elasticsearch.requestTimeout` setting* Time in milliseconds to wait for Elasticsearch to respond to pings. -`elasticsearch.requestTimeout:`:: *Default: 30000* Time in milliseconds to wait for responses from the back end or +`elasticsearch.requestTimeout:`:: *Default: 30000* Time in milliseconds to wait for responses from the back end or Elasticsearch. This value must be a positive integer. -`elasticsearch.shardTimeout:`:: *Default: 0* Time in milliseconds for Elasticsearch to wait for responses from shards. Set +`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 +`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. `logging.dest:`:: *Default: `stdout`* Enables you specify a file where Kibana stores log output. -`logging.filter.:`:: *Default:* `authorization` Replace with the string to filter. Set the value of this -setting to `remove` to remove matching keys from all logged objects. Set the value of this setting to `censor` to replace +`logging.filter.:`:: *Default:* `authorization` Replace with the string to filter. Set the value of this +setting to `remove` to remove matching keys from all logged objects. Set the value of this setting to `censor` to replace each character in the key's value with an `X` character. `logging.silent:`:: *Default: false* Set the value of this setting to `true` to suppress all logging output. -`logging.quiet:`:: *Default: false* Set the value of this setting to `true` to suppress all logging output other than +`logging.quiet:`:: *Default: false* Set the value of this setting to `true` to suppress all logging output other than error messages. -`logging.verbose`:: *Default: false* Set the value of this setting to `true` to log all events, including system usage +`logging.verbose`:: *Default: false* Set the value of this setting to `true` to log all events, including system usage information and all requests. diff --git a/docs/tilemap.asciidoc b/docs/tilemap.asciidoc index 4d959de0ed258..58f1b6a3ae04f 100644 --- a/docs/tilemap.asciidoc +++ b/docs/tilemap.asciidoc @@ -3,72 +3,72 @@ A tile map displays a geographic area overlaid with circles keyed to the data determined by the buckets you specify. -The default _metrics_ aggregation for a tile map is the *Count* aggregation. You can select any of the following +The default _metrics_ aggregation for a tile map is the *Count* aggregation. You can select any of the following aggregations as the metrics aggregation: -*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. Enter a string in the *Custom Label* field to change the display label. The _buckets_ aggregations determine what information is being retrieved from your data set. -Before you choose a buckets aggregation, specify if you are splitting the chart or displaying the buckets as *Geo +Before you choose a buckets aggregation, specify if you are splitting the chart or displaying the buckets as *Geo Coordinates* on a single chart. A multiple chart split must run before any other aggregations. Tile maps use the *Geohash* aggregation as their initial aggregation. Select a field, typically coordinates, from the -drop-down. The *Precision* slider determines the granularity of the results displayed on the map. See the documentation -for the {ref}/search-aggregations-bucket-geohashgrid-aggregation.html#_cell_dimensions_at_the_equator[geohash grid] +drop-down. The *Precision* slider determines the granularity of the results displayed on the map. See the documentation +for the {ref}/search-aggregations-bucket-geohashgrid-aggregation.html#_cell_dimensions_at_the_equator[geohash grid] aggregation for details on the area specified by each precision level. Kibana supports a maximum geohash length of 7. -NOTE: Higher precisions increase memory usage for the browser displaying Kibana as well as for the underlying +NOTE: Higher precisions increase memory usage for the browser displaying Kibana as well as for the underlying Elasticsearch cluster. -Once you've specified a buckets aggregation, you can define sub-aggregations to refine the visualization. Tile maps -only support sub-aggregations as split charts. Click *+ Add Sub Aggregation*, then *Split Chart* to select a +Once you've specified a buckets aggregation, you can define sub-aggregations to refine the visualization. Tile maps +only support sub-aggregations as split charts. Click *+ Add Sub Aggregation*, then *Split Chart* to select a sub-aggregation from the list of types: -*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. -After changing options, click the green *Apply changes* button to update your visualization, or the grey *Discard +After changing options, click the green *Apply changes* button to update your visualization, or the grey *Discard changes* button to keep your visualization in its current state. -*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 to open the label field, where you can type +*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 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 -{ref}search-aggregations-bucket-significantterms-aggregation.html[_significant terms_] aggregation. The value of the +*Significant Terms*:: Displays the results of the experimental +{ref}search-aggregations-bucket-significantterms-aggregation.html[_significant terms_] aggregation. The value of the *Size* parameter defines the number of entries this aggregation returns. -*Geohash*:: The {ref}search-aggregations-bucket-geohashgrid-aggregation.html[_geohash_] aggregation displays points +*Geohash*:: The {ref}search-aggregations-bucket-geohashgrid-aggregation.html[_geohash_] aggregation displays points based on the geohash coordinates. NOTE: By default, the *Change precision on map zoom* box is checked. Uncheck the box to disable this behavior. @@ -81,13 +81,13 @@ 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. @@ -97,14 +97,14 @@ Select the *Options* tab to change the following aspects of the chart: *Map type*:: Select one of the following options from the drop-down. *_Scaled Circle Markers_*:: Scale the size of the markers based on the metric aggregation's value. *_Shaded Circle Markers_*:: Displays the markers with different shades based on the metric aggregation's value. -*_Shaded Geohash Grid_*:: Displays the rectangular cells of the geohash grid instead of circular markers, with different +*_Shaded Geohash Grid_*:: Displays the rectangular cells of the geohash grid instead of circular markers, with different shades based on the metric aggregation's value. -*_Heatmap_*:: A heat map applies blurring to the circle markers and applies shading based on the amount of overlap. +*_Heatmap_*:: A heat map applies blurring to the circle markers and applies shading based on the amount of overlap. Heatmaps have the following options: * *Radius*: Sets the size of the individual heatmap dots. * *Blur*: Sets the amount of blurring for the heatmap dots. -* *Maximum zoom*: Tilemaps in Kibana support 18 zoom levels. This slider defines the maximum zoom level at which the +* *Maximum zoom*: Tilemaps in Kibana support 18 zoom levels. This slider defines the maximum zoom level at which the heatmap dots appear at full intensity. * *Minimum opacity*: Sets the opacity cutoff for the dots. * *Show Tooltip*: Check this box to have a tooltip with the values for a given dot when the cursor is on that dot. @@ -114,29 +114,33 @@ heatmap dots appear at full intensity. Map Service (WMS) standard. Specify the following elements: * *WMS url*: The URL for the WMS map service. -* *WMS layers*: A comma-separated list of the layers to use in this visualization. Each map server provides its own list of -layers. +* *WMS layers*: A comma-separated list of the layers to use in this visualization. Each map server provides its own list +of layers. * *WMS version*: The WMS version used by this map service. * *WMS format*: The image format used by this map service. The two most common formats are `image/png` and `image/jpeg`. -* *WMS attribution*: An optional, user-defined string that identifies the map source. Maps display the attribution string +* *WMS attribution*: An optional, user-defined string that identifies the map source. Maps display the attribution string in the lower right corner. -* *WMS styles*: A comma-separated list of the styles to use in this visualization. Each map server provides its own styling -options. +* *WMS styles*: A comma-separated list of the styles to use in this visualization. Each map server provides its own +styling options. -After changing options, click the green *Apply changes* button to update your visualization, or the grey *Discard +After changing options, click the green *Apply changes* button to update your visualization, or the grey *Discard changes* button to keep your visualization in its current state. +NOTE: Prior to the 4.5.3 release of Kibana, tilemap visualizations used an external source of map data. The 4.5.3 +release of Kibana uses the Elastic Tile Service. You can configure the <> for Kibana in +the `kibana.yml` settings file. + [float] [[navigating-map]] ==== Navigating the Map Once your tilemap visualization is ready, you can explore the map in several ways: -* Click and hold anywhere on the map and move the cursor to move the map center. Hold Shift and drag a bounding box -across the map to zoom in on the selection. +* Click and hold anywhere on the map and move the cursor to move the map center. Hold Shift and drag a bounding box +across the map to zoom in on the selection. * Click the *Zoom In/Out* image:images/viz-zoom.png[] buttons to change the zoom level manually. -* Click the *Fit Data Bounds* image:images/viz-fit-bounds.png[] button to automatically crop the map boundaries to the +* Click the *Fit Data Bounds* image:images/viz-fit-bounds.png[] button to automatically crop the map boundaries to the geohash buckets that have at least one result. -* Click the *Latitude/Longitude Filter* image:images/viz-lat-long-filter.png[] button, then drag a bounding box across the +* Click the *Latitude/Longitude Filter* image:images/viz-lat-long-filter.png[] button, then drag a bounding box across the map, to create a filter for the box coordinates. [float]