Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates for 4.1.10 tilemap service changes. #7752

Merged
merged 1 commit into from
Jul 15, 2016
Merged

Updates for 4.1.10 tilemap service changes. #7752

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 93 additions & 77 deletions docs/settings.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,64 @@
[[settings]]
== Settings

To use Kibana, you have to tell it about the Elasticsearch indices that you
To use Kibana, you have to tell it about the Elasticsearch indices that you
want to explore by configuring one or more index patterns. You can also:

* Create scripted fields that are computed on the fly from your data. You can
* Create scripted fields that are computed on the fly from your data. You can
browse and visualize scripted fields, but you cannot search them.
* Set advanced options such as the number of rows to show in a table and
* Set advanced options such as the number of rows to show in a table and
how many of the most popular fields to show. Use caution when modifying advanced options,
as it's possible to set values that are incompatible with one another.
* Configure Kibana for a production environment

[float]
[[settings-create-pattern]]
=== Creating an Index Pattern to Connect to Elasticsearch
An _index pattern_ identifies one or more Elasticsearch indices that you want to
An _index pattern_ identifies one or more Elasticsearch indices that you want to
explore with Kibana. Kibana looks for index names that match the specified pattern.
An asterisk (*) in the pattern matches zero or more characters. For example, the pattern
`myindex-*` matches all indices whose names start with `myindex-`, such as `myindex-1`
and `myindex-2`.
An asterisk (*) in the pattern matches zero or more characters. For example, the pattern
`myindex-*` matches all indices whose names start with `myindex-`, such as `myindex-1`
and `myindex-2`.

If you use event times to create index names (for example, if you're pushing data
into Elasticsearch from Logstash), the index pattern can also contain a date format.
In this case, the static text in the pattern must be enclosed in brackets, and you
In this case, the static text in the pattern must be enclosed in brackets, and you
specify the date format using the tokens described in <<date-format-tokens>>.

For example, `[logstash-]YYYY.MM.DD` matches all indices whose names have a
timestamp of the form `YYYY.MM.DD` appended to the prefix `logstash-`, such as
For example, `[logstash-]YYYY.MM.DD` matches all indices whose names have a
timestamp of the form `YYYY.MM.DD` appended to the prefix `logstash-`, such as
`logstash-2015.01.31` and `logstash-2015-02-01`.

An index pattern can also simply be the name of a single index.

To create an index pattern to connect to Elasticsearch:

. Go to the *Settings > Indices* tab.
. Specify an index pattern that matches the name of one or more of your Elasticsearch
indices. By default, Kibana guesses that you're you're working with log data being
. Specify an index pattern that matches the name of one or more of your Elasticsearch
indices. By default, Kibana guesses that you're you're working with log data being
fed into Elasticsearch by Logstash.
+
NOTE: When you switch between top-level tabs, Kibana remembers where you were.
For example, if you view a particular index pattern from the Settings tab, switch
to the Discover tab, and then go back to the Settings tab, Kibana displays the
index pattern you last looked at. To get to the create pattern form, click
index pattern you last looked at. To get to the create pattern form, click
the *Add* button in the Index Patterns list.

. If your index contains a timestamp field that you want to use to perform
time-based comparisons, select the *Index contains time-based events* option
and select the index field that contains the timestamp. Kibana reads the
. If your index contains a timestamp field that you want to use to perform
time-based comparisons, select the *Index contains time-based events* option
and select the index field that contains the timestamp. Kibana reads the
index mapping to list all of the fields that contain a timestamp.

. If new indices are generated periodically and have a timestamp appended to
the name, select the *Use event times to create index names* option and select
the *Index pattern interval*. This enables Kibana to search only those indices
that could possibly contain data in the time range you specify. This is
. If new indices are generated periodically and have a timestamp appended to
the name, select the *Use event times to create index names* option and select
the *Index pattern interval*. This enables Kibana to search only those indices
that could possibly contain data in the time range you specify. This is
primarily applicable if you are using Logstash to feed data into Elasticsearch.

. Click *Create* to add the index pattern.
. Click *Create* to add the index pattern.

. To designate the new pattern as the default pattern to load when you view
the Discover tab, click the *favorite* button.
the Discover tab, click the *favorite* button.

[float]
[[date-format-tokens]]
Expand Down Expand Up @@ -116,35 +116,35 @@ the Discover tab, click the *favorite* button.
[float]
[[set-default-pattern]]
=== Setting the Default Index Pattern
The default index pattern is loaded by automatically when you view the *Discover* tab.
Kibana displays a star to the left of the name of the default pattern in the Index Patterns list
The default index pattern is loaded by automatically when you view the *Discover* tab.
Kibana displays a star to the left of the name of the default pattern in the Index Patterns list
on the *Settings > Indices* tab. The first pattern you create is automatically
designated as the default pattern.

To set a different pattern as the default index pattern:

. Go to the *Settings > Indices* tab.
. Select the pattern you want to set as the default in the Index Patterns list.
. Click the pattern's *Favorite* button.
. Click the pattern's *Favorite* button.

NOTE: You can also manually set the default index pattern in *Advanced > Settings*.
NOTE: You can also manually set the default index pattern in *Advanced > Settings*.

[float]
[[reload-fields]]
=== Reloading the Index Fields List
When you add an index mapping, Kibana automatically scans the indices that
When you add an index mapping, Kibana automatically scans the indices that
match the pattern to display a list of the index fields. You can reload the
index fields list to pick up any newly-added fields.
index fields list to pick up any newly-added fields.

Reloading the index fields list also resets Kibana's popularity counters for the fields.
Reloading the index fields list also resets Kibana's popularity counters for the fields.
The popularity counters keep track of the fields you've used most often within Kibana
and are used to sort fields within lists.
and are used to sort fields within lists.

To reload the index fields list:

. Go to the *Settings > Indices* tab.
. Select an index pattern from the Index Patterns list.
. Click the pattern's *Reload* button.
. Click the pattern's *Reload* button.

[float]
[[delete-pattern]]
Expand All @@ -158,11 +158,11 @@ To delete an index pattern:

[[managing-fields]]
=== Managing Fields
The fields for the index pattern are listed in a table. Click a column header to sort the table by that column. Click
the *Controls* button in the rightmost column for a given field to edit the field's properties. You can manually set
The fields for the index pattern are listed in a table. Click a column header to sort the table by that column. Click
the *Controls* button in the rightmost column for a given field to edit the field's properties. You can manually set
the field's format from the *Format* drop-down. Format options vary based on the field's type.

You can also set the field's popularity value in the *Popularity* text entry box to any desired value. Click the
You can also set the field's popularity value in the *Popularity* text entry box to any desired value. Click the
*Update Field* button to confirm your changes or *Cancel* to return to the list of fields.

Kibana has https://www.elastic.co/blog/kibana-4-1-field-formatters[field formatters] for the following field types:
Expand Down Expand Up @@ -200,25 +200,25 @@ include::string-formatter.asciidoc[]

include::url-formatter.asciidoc[]

The `Bytes`, `Number`, and `Percentage` formatters enable you to choose the display formats of numbers in this field using
The `Bytes`, `Number`, and `Percentage` formatters enable you to choose the display formats of numbers in this field using
the https://adamwdraper.github.io/Numeral-js/[numeral.js] standard format definitions.

[float]
[[create-scripted-field]]
=== Creating a Scripted Field
Scripted fields compute data on the fly from the data in your
Elasticsearch indices. Scripted field data is shown on the Discover tab as
Elasticsearch indices. Scripted field data is shown on the Discover tab as
part of the document data, and you can use scripted fields in your visualizations.
(Scripted field values are computed at query time so they aren't indexed and
cannot be searched.)

WARNING: Computing data on the fly with scripted fields can be very resource
intensive and can have a direct impact on Kibana's performance. Keep in mind
that there's no built-in validation of a scripted field. If your scripts are
WARNING: Computing data on the fly with scripted fields can be very resource
intensive and can have a direct impact on Kibana's performance. Keep in mind
that there's no built-in validation of a scripted field. If your scripts are
buggy, you'll get exceptions whenever you try to view the dynamically generated
data.

Scripted fields use the Lucene expression syntax. For more information,
Scripted fields use the Lucene expression syntax. For more information,
see http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#_lucene_expressions_scripts[Lucene Expressions Scripts].

You can reference any single value numeric field in your expressions, for example:
Expand All @@ -232,16 +232,16 @@ To create a scripted field:
. Go to *Settings > Indices*
. Select the index pattern you want to add a scripted field to.
. Go to the pattern's *Scripted Fields* tab.
. Click *Add Scripted Field*.
. Click *Add Scripted Field*.
. Enter a name for the scripted field.
. Enter the expression that you want to use to compute a value on the fly
. Enter the expression that you want to use to compute a value on the fly
from your index data.
. Click *Save Scripted Field*.

For more information about scripted fields in Elasticsearch, see
For more information about scripted fields in Elasticsearch, see
http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html[Scripting].

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].

[float]
Expand All @@ -253,8 +253,8 @@ To modify a scripted field:
. Click the *Edit* button for the scripted field you want to change.
. Make your changes and then click *Save Scripted Field* to update the field.

WARNING: Keep in mind
that there's no built-in validation of a scripted field. If your scripts are
WARNING: Keep in mind
that there's no built-in validation of a scripted field. If your scripts are
buggy, you'll get exceptions whenever you try to view the dynamically generated
data.

Expand All @@ -272,7 +272,7 @@ To delete a scripted field:
The Advanced Settings page enables you to directly edit settings that control
the behavior of the Kibana application. For example, you can change the format
used to display dates, specify the default index pattern, and set the precision
for displayed decimal values.
for displayed decimal values.

WARNING: Changing advanced settings can have unintended consequences. If you aren't
sure what you're doing, it's best to leave these settings as-is.
Expand All @@ -281,60 +281,60 @@ To set advanced options:

. Go to *Settings > Advanced*.
. Click the *Edit* button for the option you want to modify.
. Enter a new value for the option.
. Enter a new value for the option.
. Click the *Save* button.

[float]
[[managing-saved-objects]]
=== Managing Saved Searches, Visualizations, and Dashboards
=== Managing Saved Searches, Visualizations, and Dashboards

You can view, edit, and delete saved searches, visualizations, and dashboards from *Settings > Objects*. You can also
You can view, edit, and delete saved searches, visualizations, and dashboards from *Settings > Objects*. You can also
export or import sets of searches, visualizations, and dashboards.

Viewing a saved object displays the selected item in the *Discover*, *Visualize*,
Viewing a saved object displays the selected item in the *Discover*, *Visualize*,
or *Dashboard* page. To view a saved object:

. Go to *Settings > Objects*.
. Select the object you want to view.
. Select the object you want to view.
. Click the *View* button.

Editing a saved object enables you to directly modify the object definition.
Editing a saved object enables you to directly modify the object definition.
You can change the name of the object, add a description, and modify the
JSON that defines the object's properties.
JSON that defines the object's properties.

If you attempt to access an object whose index has been deleted, Kibana displays
its Edit Object page. You can:

* Recreate the index so you can continue using the object.
* Recreate the index so you can continue using the object.
* Delete the object and recreate it using a different index.
* Change the index name referenced in the object's `kibanaSavedObjectMeta.searchSourceJSON`
to point to an existing index pattern. This is useful if the index you were working
with has been renamed.
with has been renamed.

WARNING: No validation is performed for object properties. Submitting invalid
changes will render the object unusable. Generally, you should use the
*Discover*, *Visualize*, or *Dashboard* pages to create new objects instead of
directly editing existing ones.
WARNING: No validation is performed for object properties. Submitting invalid
changes will render the object unusable. Generally, you should use the
*Discover*, *Visualize*, or *Dashboard* pages to create new objects instead of
directly editing existing ones.

To edit a saved object:

. Go to *Settings > Objects*.
. Select the object you want to edit.
. Select the object you want to edit.
. Click the *Edit* button.
. Make your changes to the object definition.
. Click the *Save Object* button.

To delete a saved object:

. Go to *Settings > Objects*.
. Select the object you want to delete.
. Select the object you want to delete.
. Click the *Delete* button.
. Confirm that you really want to delete the object.

To export a set of objects:

. Go to *Settings > Objects*.
. Select the type of object you want to export. You can export a set of dashboards, searches, or visualizations.
. Select the type of object you want to export. You can export a set of dashboards, searches, or visualizations.
. Click the selection box for the objects you want to export, or click the *Select All* box.
. Click *Export* to select a location to write the exported JSON.

Expand All @@ -350,48 +350,64 @@ To import a set of objects:

The Kibana server reads properties from the `kibana.yml` file on startup. The default
settings configure Kibana to run on `localhost:5601`. To change the host or port number, or
connect to Elasticsearch running on a different machine, you'll need to update your `kibana.yml` file. You can also
connect to Elasticsearch running on a different machine, you'll need to update your `kibana.yml` file. You can also
enable SSL and set a variety of other options.

.Kibana Server Properties
|===
|Property |Description
|Property |Description

|`port`
|The port that the Kibana server runs on. Default: `port: 5601`.
|The port that the Kibana server runs on. Default: `port: 5601`.

|`host`
|The host to bind the Kibana server to. Default: `host: "0.0.0.0"`.

|`elasticsearch_url`
|The Elasticsearch instance where the indices you want to query reside. Default:&nbsp;&nbsp;`elasticsearch_url:
|The Elasticsearch instance where the indices you want to query reside. Default:&nbsp;&nbsp;`elasticsearch_url:
"http://localhost:9200"`.

|[[tilemap-settings]]`tilemap_url` added[4.1.10]
|The URL to the tilemap service Kibana uses for tilemap visualizations. Default:&nbsp;&nbsp;`elasticsearch_url:
"https://tiles.elastic.co/v1/default/{z}/{x}/{y}.png?my_app_name=kibana&my_app_version=<package version>&elastic_tile_service_tos=agree"`.

|`tilemap_min_zoom` added[4.1.10]
| The minimum zoom level. Defaults to 1.

|`tilemap_max_zoom` added[4.1.10]
| The maximum zoom level. Defaults to 7.

|`tilemap_attribution` added[4.1.10]
| The map attribution string. Defaults to `© [Elastic Tile Service](https://www.elastic.co/elastic-tile-service)`

|`tilemap_subdomains` added[4.1.10]
| An array of subdomains used by the tile service. Specify the position of the subdomain the URL with the token `{s}`.

|`elasticsearch_preserve_host`
|By default, the host specified in the incoming request from the browser is specified as the host in the
|By default, the host specified in the incoming request from the browser is specified as the host in the
corresponding request Kibana sends to Elasticsearch. If you set this option to `false`, Kibana uses the host
specified in `elasticsearch_url`. You probably don't need to worry about this setting--just use the default.
specified in `elasticsearch_url`. You probably don't need to worry about this setting--just use the default.
Default: `elasticsearch_preserve_host: true`.

|`kibana_index`
|The name of the index where saved searched, visualizations, and dashboards will be stored. Default: `kibana_index: .kibana`.

|`default_app_id`
|The page that will be displayed when you launch Kibana: `discover`, `visualize`, `dashboard`, or `settings`. Default:
`default_app_id: "discover"`.
|`default_app_id`
|The page that will be displayed when you launch Kibana: `discover`, `visualize`, `dashboard`, or `settings`. Default:
`default_app_id: "discover"`.

|`request_timeout`
|`request_timeout`
|How long to wait for responses from the Kibana backend or Elasticsearch, in milliseconds. Default: `request_timeout: 500000`.

|`shard_timeout`
|How long Elasticsearch should wait for responses from shards. Set to 0 to disable. Default: `shard_timeout: 0`.

|`verify_ssl`
|Indicates whether or not to validate the Elasticsearch SSL certificate. Set to false to disable SSL verification.
|Indicates whether or not to validate the Elasticsearch SSL certificate. Set to false to disable SSL verification.
Default: `verify_ssl: true`.

|`ca`
|The path to the CA certificate for your Elasticsearch instance. Specify if you are using a self-signed certificate
|The path to the CA certificate for your Elasticsearch instance. Specify if you are using a self-signed certificate
so the certificate can be verified. (Otherwise, you have to disable `verify_ssl`.) Default: none.

|`ssl_key_file`
Expand All @@ -401,11 +417,11 @@ so the certificate can be verified. (Otherwise, you have to disable `verify_ssl`
|The path to your Kibana server's certificate file. Must be set to encrypt communications between the browser and Kibana. Default: none.

|`pid_file`
|The location where you want to store the process ID file. If not specified, the PID file is stored in
|The location where you want to store the process ID file. If not specified, the PID file is stored in
`/var/run/kibana.pid`. Default: none.

|`log_file`
|The location where you want to store the Kibana's log output. If not specified, log output is written to standard
|The location where you want to store the Kibana's log output. If not specified, log output is written to standard
output and not stored. Specifying a log file suppresses log writes to standard output. Default: none.

|===
Loading