kibana/docs/settings.asciidoc

[[settings]]
== Settings

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 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 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 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 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 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 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 index 
mapping to list all of the fields that contain a timestamp.

. By default, Kibana restricts wildcard expansion of time-based index patterns to indices with data within the currently 
selected time range. Click *Do not expand index pattern when search* to disable this behavior.

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

NOTE: When you define an index pattern, indices that match that pattern must exist in Elasticsearch. Those indices must 
contain data.

To use an event time in an index name, enclose the static text in the pattern and specify the date format using the 
tokens described in the following table.

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

[float]
[[date-format-tokens]]
.Date Format Tokens
[horizontal]
`M`::	Month - cardinal: 1 2 3 ... 12
`Mo`:: Month - ordinal:	1st 2nd 3rd ... 12th
`MM`:: Month - two digit: 	01 02 03 ... 12
`MMM`:: Month - abbreviation: Jan Feb Mar ... Dec
`MMMM`:: Month - full: January February March ... December
`Q`::	Quarter: 1 2 3 4
`D`::	Day of Month - cardinal: 1 2 3 ... 31
`Do`:: Day of Month - ordinal: 1st 2nd 3rd ... 31st
`DD`:: Day of Month - two digit:	01 02 03 ... 31
`DDD`:: Day of Year - cardinal: 1 2 3 ... 365
`DDDo`:: Day of Year - ordinal:	1st 2nd 3rd ... 365th
`DDDD`:: Day of Year - three digit: 001 002 ... 364 365
`d`::	Day of Week - cardinal: 0 1 3 ... 6
`do`:: Day of Week - ordinal:	0th 1st 2nd ... 6th
`dd`:: Day of Week - 2-letter abbreviation:	Su Mo Tu ... Sa
`ddd`:: Day of Week - 3-letter abbreviation: Sun Mon Tue ... Sat
`dddd`:: Day of Week - full: Sunday Monday Tuesday ... Saturday
`e`::	Day of Week (locale): 0 1 2 ... 6
`E`::	Day of Week (ISO): 1 2 3 ... 7
`w`::	Week of Year - cardinal (locale): 1 2 3 ... 53
`wo`:: Week of Year - ordinal (locale): 1st 2nd 3rd ... 53rd
`ww`:: Week of Year - 2-digit (locale): 01 02 03 ... 53
`W`::	Week of Year - cardinal (ISO): 1 2 3 ... 53
`Wo`:: Week of Year - ordinal (ISO): 1st 2nd 3rd ... 53rd
`WW`:: Week of Year - two-digit (ISO): 01 02 03 ... 53
`YY`:: Year - two digit:	70 71 72 ... 30
`YYYY`:: Year - four digit: 1970 1971 1972 ... 2030
`gg`:: Week Year - two digit (locale):	70 71 72 ... 30
`gggg`:: Week Year - four digit (locale):	1970 1971 1972 ... 2030
`GG`:: Week Year - two digit (ISO):	70 71 72 ... 30
`GGGG`::	Week Year - four digit (ISO): 1970 1971 1972 ... 2030
`A`::	AM/PM: AM PM
`a`::	am/pm: am pm
`H`::	Hour: 0 1 2 ... 23
`HH`:: Hour - two digit: 00 01 02 ... 23
`h`::	Hour - 12-hour clock: 1 2 3 ... 12
`hh`:: Hour - 12-hour clock, 2 digit:	01 02 03 ... 12
`m`::	Minute: 0 1 2 ... 59
`mm`:: Minute - two-digit:	00 01 02 ... 59
`s`::	Second: 0 1 2 ...  59
`ss`:: Second - two-digit: 00 01 02 ... 59
`S`::	Fractional Second - 10ths: 0 1 2 ... 9
`SS`:: Fractional Second - 100ths: 	0 1 ... 98 99
`SSS`:: Fractional Seconds - 1000ths:	0 1 ... 998 999
`Z`::	Timezone - zero UTC offset (hh:mm format): -07:00 -06:00 -05:00 .. +07:00
`ZZ`:: Timezone - zero UTC offset (hhmm format):	-0700 -0600 -0500 ... +0700
`X`:: Unix Timestamp:	1360013296
`x`::	Unix Millisecond Timestamp: 1360013296123

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

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

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. 

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. 

[float]
[[delete-pattern]]
=== Deleting an Index Pattern
To delete an index pattern:

. Go to the *Settings > Indices* tab.
. Select the pattern you want to remove in the Index Patterns list.
. Click the pattern's *Delete* button.
. Confirm that you want to remove the 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 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 
*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:

==== String Field Formatters

String fields support the `String` and `Url` formatters.

include::string-formatter.asciidoc[]

include::url-formatter.asciidoc[]

==== Date Field Formatters

Date fields support the `Date`, `Url`, and `String` formatters.

The `Date` formatter enables you to choose the display format of date stamps using the http://moment.js[moment.js]
standard format definitions.

include::string-formatter.asciidoc[]

include::url-formatter.asciidoc[]

==== Geographic Point Field Formatters

Geographic point fields support the `String` formatter.

include::string-formatter.asciidoc[]

==== Numeric Field Formatters

Numeric fields support the `Url`, `String`, `Bytes`, `Number`, `Percentage`, and `Color` formatters.

include::string-formatter.asciidoc[]

include::url-formatter.asciidoc[]

include::color-formatter.asciidoc[]

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

NOTE: Kibana cannot query scripted fields.

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,
see {ref}/modules-scripting.html#_lucene_expressions_scripts[
Lucene Expressions Scripts].

You can reference any single value numeric field in your expressions, for example:

----
doc['field_name'].value
----

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*. 
. Enter a name for the scripted field.
. 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
{ref}/modules-scripting.html[Scripting].

NOTE: In Elasticsearch releases 1.4.3 and later, this functionality requires you to enable 
{ref}/modules-scripting.html[dynamic Groovy scripting].

[float]
[[update-scripted-field]]
=== Updating a Scripted Field
To modify a scripted field:

. Go to *Settings > Indices*
. 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 buggy, you'll get 
exceptions whenever you try to view the dynamically generated data.

[float]
[[delete-scripted-field]]
=== Deleting a Scripted Field
To delete a scripted field:

. Go to *Settings > Indices*
. Click the *Delete* button for the scripted field you want to remove.
. Confirm that you really want to delete the field.

[[advanced-options]]
=== Setting Advanced Options
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. 

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. 
. Click the *Save* button.

include::advanced-settings.asciidoc[]

[[kibana-server-properties]]
=== Setting Kibana Server Properties

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 enable SSL and set a variety of other options.

include::kibana-yml.asciidoc[]

deprecated[4.2, "The names of several Kibana server properties changed in the 4.2 release of Kibana. The previous names remain as functional aliases, but are now deprecated and will be removed in a future release of Kibana"]

[horizontal]
.Kibana Server Properties Changed in the 4.2 Release
`server.port` added[4.2]:: The port that the Kibana server runs on.
+
*alias*: `port` deprecated[4.2]
+ 
*default*: `5601`

`server.host` added[4.2]:: The host to bind the Kibana server to.
+
*alias*: `host` deprecated[4.2]
+
*default*: `"0.0.0.0"`

`elasticsearch.url` added[4.2]:: The Elasticsearch instance where the indices you want to query reside.
+
*alias*: `elasticsearch_url` deprecated[4.2]
+
*default*: `"http://localhost:9200"`

`elasticsearch.preserveHost` added[4.2]:: 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`.
+
*alias*: `elasticsearch_preserve_host` deprecated[4.2]
+ 
*default*: `true`

`elasticsearch.ssl.cert` added[4.2]:: This parameter specifies the path to the SSL certificate for Elasticsearch instances that require a client certificate.
+
*alias*: `kibana_elasticsearch_client_crt` deprecated[4.2]

`elasticsearch.ssl.key` added[4.2]:: This parameter specifies the path to the SSL key for Elasticsearch instances that require a client key.
+
*alias*: `kibana_elasticsearch_client_key` deprecated[4.2]

`elasticsearch.password` added[4.2]:: This parameter specifies the password for Elasticsearch instances that use HTTP basic authentication. Kibana users still need to authenticate with Elasticsearch, which is proxied through the Kibana server.
+
*alias*: `kibana_elasticsearch_password` deprecated[4.2]

`elasticsearch.username` added[4.2]:: This parameter specifies the username for Elasticsearch instances that use HTTP basic authentication. Kibana users still need to authenticate with Elasticsearch, which is proxied through the Kibana server.
+
*alias*: `kibana_elasticsearch_username` deprecated[4.2]

`elasticsearch.pingTimeout` added[4.2]:: This parameter specifies the maximum wait time in milliseconds for ping responses by Elasticsearch.
+
*alias*: `ping_timeout` deprecated[4.2]
+ 
*default*: `1500`

`elasticsearch.startupTimeout` added[4.2]:: This parameter specifies the maximum wait time in milliseconds for Elasticsearch discovery at Kibana startup. Kibana repeats attempts to discover an Elasticsearch cluster after the specified time elapses.
+
*alias*: `startup_timeout` deprecated[4.2]
+ 
*default*: `5000`

`kibana.index` added[4.2]:: The name of the index where saved searched, visualizations, and dashboards will be stored..
+
*alias*: `kibana_index` deprecated[4.2]
+ 
*default*: `.kibana`

`kibana.defaultAppId` added[4.2]:: The page that will be displayed when you launch Kibana: `discover`, `visualize`, `dashboard`, or `settings`.
+
*alias*: `default_app_id` deprecated[4.2]
+ 
*default*: `"discover"`

`logging.silent` added[4.2]:: Set this value to `true` to suppress all logging output.
+
*default*: `false`

`logging.quiet` added[4.2]:: Set this value to `true` to suppress all logging output except for log messages tagged `error`, `fatal`, or Hapi.js errors.
+
*default*: `false`

`logging.verbose` added[4.2]:: Set this value to `true` to log all events, including system usage information and all requests.
+
*default*: `false`

`logging.events` added[4.2]:: You can specify a map of log types to output tags for this parameter to create a customized set of loggable events, as in the following example:
+
[source,json]
{
  log: ['info', 'warning', 'error', 'fatal'],
  response: '*',
  error: '*'
}

`elasticsearch.requestTimeout` added[4.2]:: How long to wait for responses from the Kibana backend or Elasticsearch, in milliseconds.
+
*alias*: `request_timeout` deprecated[4.2]
+ 
*default*: `500000`

`elasticsearch.shardTimeout` added[4.2]:: How long Elasticsearch should wait for responses from shards. Set to 0 to disable.
+
*alias*: `shard_timeout` deprecated[4.2]
+ 
*default*: `0`

`elasticsearch.ssl.verify` added[4.2]:: Indicates whether or not to validate the Elasticsearch SSL certificate. Set to false to disable SSL verification.
+
*alias*: `verify_ssl` deprecated[4.2]
+ 
*default*: `true`

`elasticsearch.ssl.ca`:: An array of paths to the CA certificates for your Elasticsearch instance. Specify if 
you are using a self-signed certificate so the certificate can be verified. Disable `elasticsearch.ssl.verify` otherwise.
+
*alias*: `ca` deprecated[4.2]

`server.ssl.key` added[4.2]:: The path to your Kibana server's key file. Must be set to encrypt communications between the browser and Kibana.
+
*alias*: `ssl_key_file` deprecated[4.2]

`server.ssl.cert` added[4.2]:: The path to your Kibana server's certificate file. Must be set to encrypt communications between the browser and Kibana.
+
*alias*: `ssl_cert_file` deprecated[4.2]

`pid.file` added[4.2]:: The location where you want to store the process ID file.
+
*alias*: `pid_file` deprecated[4.2]
+
*default*: `/var/run/kibana.pid`

`logging.dest` added[4.2]:: 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.
+
*alias*: `log_file` deprecated[4.2]

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

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*, or *Dashboard* page. To view a saved 
object:

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

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. 

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

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

WARNING: Exported dashboards do not include their associated index patterns. Re-create the index patterns manually before 
importing saved dashboards to a Kibana instance running on another Elasticsearch cluster.

To import a set of objects:

. Go to *Settings > Objects*.
. Click *Import* to navigate to the JSON file representing the set of objects to import.
. Click *Open* after selecting the JSON file.
. If any objects in the set would overwrite objects already present in Kibana, confirm the overwrite.