maxmustermann/kibana
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
kibana/docs/settings.asciidoc
Paul Echeverri 221578f344 Incorporates newest round of feedback. Notable changes: 
- Chunking for Settings pages
- Updates several screenshots
- Autorefresh added
- See PR conversation for way more deets
2015-05-28 10:34:06 -07:00

374 lines
16 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.
.Kibana Server Properties
|===
|Property |Description
|`port`
|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:
"http://localhost:9200"`.
|`elasticsearch_preserve_host`
|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.
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"`.
|`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.
Default: `verify_ssl: true`.
|`ca`
|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`
|The path to your Kibana server's key file. Must be set to encrypt communications between the browser and Kibana. Default: none.
|`ssl_cert_file`
|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
`/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
output and not stored. Specifying a log file suppresses log writes to standard output. Default: none.
|===
Reference in a new issue View git blame Copy permalink