maxmustermann/kibana
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
kibana/docs/settings.asciidoc
Paul Echeverri 2b57a3fd07 Updates deprecation warning.
2015-09-01 13:01:59 -07:00

424 lines
19 KiB
Plaintext
Raw Blame History

[[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`.
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 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 `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 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.
. 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.
. To designate the new pattern as the default pattern to load when you view the Discover tab, click the *favorite*
button.
[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.
[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.
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 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:
----
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
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
{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.
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.
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.
[float]
[[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.
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.
[[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.
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
`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` added[4.2]:: 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. 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]
Reference in a new issue View git blame Copy permalink