======
Kibana
======

Introduction
============

Kibana is an open source (Apache Licensed), browser based analytics and
search dashboard for ElasticSearch. Kibana is a snap to setup and start
using. Written entirely in HTML and Javascript it requires only a plain
webserver, Kibana requires no fancy server side components. Kibana
strives to be easy to get started with, while also being flexible and
powerful, just like Elasticsearch.

10 Minute Walk Through
======================

Kibana is a great tool for real time data analytics and simply being on
this page has put you on your way to making the most of it! If you have
not downloaded Kibana yet, you can get it here: `Download
Kibana <http://www.elasticsearch.org/overview/kibana/installation/>`__.
We recommend you start this tutorial with a clean Elasticsearch
instance.

By the end of this document you will have:

-  Imported some data

-  Tried out the sample dashboard

-  Searched your data

-  Configured Kibana to point only at your new index instead of all
   indices

We will assume you have already:

-  Installed Elasticsearch on your workstation

-  Have webserver installed on your workstation and have the
   distribution extracted into the configured document root.

-  You are familiar with the UNIX command line and have used ``curl``

Import some data
----------------

We will be using the entire collected works of Shakespeare as our
example data. In order to make the best use of Kibana you will likely
want to apply a mapping to your new index. Let’s create the shakespeare
index with the following mapping. Our data will have more fields than
this, but these are the ones we want to explicitly map. Specifically we
do not want to analyze *speaker* and *play\_name*. You’ll see why later
on.

Run in a terminal:

.. code:: json

    curl -XPUT http://localhost:9200/shakespeare -d '
    {
     "mappings" : {
      "_default_" : {
       "properties" : {
        "speaker" : {"type": "string", "index" : "not_analyzed" },
        "play_name" : {"type": "string", "index" : "not_analyzed" },
        "line_id" : { "type" : "integer" },
        "speech_number" : { "type" : "integer" }
       }
      }
     }
    }
    ';

Great, we’ve created the index. Now we want to import the data. You can
download the entire works of shakespeare in elasticsearch bulk import
format here: `shakespeare.json <./snippets/shakespeare.json>`__

Import it into your local elasticsearch instance with the following
command. This may take a few minutes. Shakespeare wrote a lot of stuff!

.. code:: shell

    curl -XPUT localhost:9200/_bulk --data-binary @shakespeare.json

Accessing the Kibana interface
------------------------------

Now that you have data, let’s do something with it. Point your browser
at your local webserver, the one with Kibana already installed.

|Welcome Page|

If you have Kibana extracted to your document root you will be presented
with this lovely welcome page. Click **Sample Dashboard**

|Sample Dashboard| And there you have your sample dashboard! Now if you
started with a clean elasticsearch instance you’ll see a very heavily
weighted pie chart. This represents the type of documents in your index.
As you can see, 99% them are lines for characters, with only a few
denoting acts and scenes.

Below that you will see a long list of JSON formatted lines of
shakespeare.

The first search
----------------

Kibana allows you to search Elasticsearch data via the Lucene Query
String syntax. Queries can be run via the query input at the top of the
page |Sample Dashboard|

Type this in the query bar. Then check out the first few rows of the
table.

.. code:: shell

    friends, romans, countrymen

|Sample Dashboard|

For more information on queries see `Queries and
Filters <./working-with-queries-and-filters.html>`__

Configuring another index
-------------------------

Right now Kibana is pointing at the special Elasticsearch index
``_all``. Think of ``_all`` as a composite index that points at all of
your indices. Right now you only have one, ``shakespeare``, but you
might have more someday and we don’t want Kibana searching all of that
data if you’re only looking for your favorite line from Macbeth.

To configure the index click the configure icon in the top right:

|Sample Dashboard|

From here, you can set your index to ``shakespeare`` and ensure that
Kibana only searches the ``shakespeare`` index

|Sample Dashboard|

Next steps
----------

Congratulations, you’ve installed and configured kibana and dipped your
toes in the water. Next, check out some of our videos and other
tutorials for more advanced usage. Now you can try adding your own
panels to a blank dashboard. For more information on queries see `Rows
and Panels <./rows-and-panels.html>`__

Queries and Filters
===================

Charts and tables and maps oh my! But how do we constrain the data
displayed on them. This is the role of queries and filters. Because
Kibana is powered by Elasticsearch it supports the powerful Lucene Query
String syntax, as well as making use of some of Elasticsearch’s filter
capabilities.

We will assume you have already:

-  Installed Elasticsearch on your workstation.

-  Have a webserver installed on your workstation and have the
   distribution extracted into the configured document root.

-  Have read `Using Kibana for the first
   time <./using-kibana-for-the-first-time.html>`__ and have the
   ``shakespeare`` index populated with the data from the tutorial.

Our Dashboard
-------------

Our dashboard looks like this, we will be searching through lines of
shakespeare. If you would like to follow along with the screenshots in
this guide you can `download the exported dashboard
schema <./snippets/plays.json>`__

|image|

Queries
-------

Type this very simple query into the search bar:

.. code:: shell

    to be or not to be

You will notice, in the table, your first hit is Hamlet as expected.
However, look at the next line by Sir Andrew, it does not contain "to
be", nor does it contain "not to be". The search we have actually
performed is: ``to OR be OR or OR not OR to OR be``.

We can also match the entire phrase:

.. code:: shell

    "to be or not to be"

Or in specifc fields:

.. code:: shell

    line_id:86169

We can express complex searches with AND/OR, note these words must be
capitalized:

.. code:: shell

    food AND love

Or parantheses:

.. code:: shell

    ("played upon" OR "every man") AND stage

Numeric ranges can also be easily searched:

.. code:: shell

    line_id:[30000 TO 80000] AND havoc

And of course to search everything:

.. code:: shell

    *

Multiple queries
----------------

In some cases, you might want to compare the results of two seperate
queries. Kibana can handle multiple queries by joining them with a
logical ``OR`` and using the knowledge that they should be treated as
seperate to influence visualizations.

Adding
~~~~~~

Click the **+** to the right of the query input to add another query.

|image|

You should now have this:

|image|

In the lefthand, green input, type ``"to be"`` and in the right, yellow
input, type ``"not to be"``. This will search for every document that
has ``"to be"`` OR ``"not to be"`` in it, and break that down on our
hits pie chart. So we go from a big green circle to:

|image|

Removing
~~~~~~~~

To remove a query, click the **x** icon that appears when you mouse over
the query input field

|image|

Colors and Legends
------------------

Kibana will automatically determine a free color to use for your
queries, but you can set your color explicitly if you’d like by clicking
the colored dot associated with the query to open the query settings
drop down. From here you can change the color of the query, or set a new
value for the legend

|image|

Filters
-------

Many Kibana charts are interactive and can be used to filter the view of
your data. For example, click on the first bar of the chart. You will
end up with something like this. As you can see, the chart has become
one big green bar. This is because a filter was added to match that term
in the ``play_name`` field.

|image|

"But where" you say?

The answer lies in that little white star that appeared on the filtering
tab. Give the tab a click and we can see that a filter has added to the
*filtering* panel. From the *filtering* panel filters can be added,
edited, toggled and removed. Many panels have the ability to add
filters, including the table, histogram, map and others.

|image|

Filters can also be added manually by clicking the **+**

More reading
------------

Now that you have a solid handle on filters and queries you might be
interested in how they’re described in `the Kibana
schema <./_dashboard_schema.html>`__. If you’re interested in inserting
queries or filters via URL parameters you might also take a look at
`Templated and Scripted
Dashboards <./templated-and-scripted-dashboards.html>`__

Rows and Panels
===============

Kibana’s dashboards are organized into a system of rows and panels.
These can be added, removed and rearranged to suite your needs.

In this section we will cover:

-  Loading a blank dashboard

-  Adding, sizing and hiding rows

-  Adding and sizing panels

-  Removing panels and rows

We will assume you have already:

-  Installed Elasticsearch on your workstation

-  Have webserver installed on your workstation and have the
   distribution extracted into the configured document root.

-  Have read `Using Kibana for the first
   time <./using-kibana-for-the-first-time.html>`__ and have the
   ``shakespeare`` index populated with the data from the tutorial.

Loading a blank dashboard
-------------------------

|home screen|

From the homescreen, select option #3, this will load a Blank Dashboard.
By default, the blank dashboard is configured to look at Elasticsearch’s
``_all`` index, which points to all of your indices. If you would like
to configure Kibana to point at a different index, see `Using Kibana for
the first time <./using-kibana-for-the-first-time.html>`__

Adding a row
------------

|Adding a row|

Your new blank dashboard will appear with the query and filter sections
expanded, a time filter input in the navigation bar at the top, and not
a whole lot else. Click the **Add a row** button on the right to add
your first row.

|Adding a row|

Give your row a title and click **Create Row**. You will see your new
row appear in the list of rows to the left. Click **Save**

The row controls
----------------

|Row buttons|

Now that you have a row, you will notice a few new elements on your
dashboard. Chiefly the 3 brightly colored rectangles to the left. Move
the mouse over them

|Row buttons|

Ah hah! these buttons allow you to accomplish 3 things

-  Collapsing rows (blue)

-  Configuring rows (orange)

-  Adding panels (green)

Adding panels
-------------

For now we’ll focus on the *green* button in the row controls. Give it a
try. You can also click the *grey* button labeled **Add panel to empty
row**, but it’s grey, and what fun is that?

|Add panel|

Let’s add a **terms** panel. The **terms** panel allows us to make use
of the Elasticsearch **terms facet** to find the most popular values in
a field.

|Add panel|

As you can see, the terms panel has a number of optional settings,
however we’ll focus on the general settings in the first section for
now:

1. Title: The name for this panel

2. Span: The width of the panel. Kibana dashboards are made of 12
   equally sized *spans*. Panels can be up to 12 spans wide. Rows can
   contain more than a total of 12, with new panels wrapping to the next
   line. Leave this at 4 for now.

3. Editable: If this panel is configurable later. Leave this checked for
   now.

4. Inspectable: If the user can view the query used for this panel. Also
   leave this checked for now.

5. Click **Save** to add your new **terms** panel to your dashboard

|First panel|

Great! Now you have a panel! You may recognize this breakdown of data
from the pie chart in `Using Kibana for the first
time <./using-kibana-for-the-first-time.html>`__. The ``shakespeare``
data set is comprised largely of lines of speech, with a few markers
between acts and scenes thrown in there.

Collapsing and expanding rows
-----------------------------

|Row buttons|

The blue button collapses your rows. Panels in collapsed rows do not
refresh data and thus require no Elasticsearch resources to keep around.
Collapsed rows are great for data that you don’t need to see often.
Click the blue button again to expand the row.

|Collapsed row|

The query and filter sections at the top can also be collapsed. Click
the colored label to collapse and expand

|Collapsed top row|

Editing rows
------------

Rows can be renamed, resized and edited via the row editor. Click the
orange cog icon button to open the row editor.

|Row edit|

The same dialog also allows you to change the order and size of panels,
as well as remove them.

|Removing Panels|

Moving and Removing panels
--------------------------

Panels can be dragged and dropped within their own row, or into another
row, by dragging the crosshair shaped move icon in the top right of the
panel.

|Removing Panels|

Click the *remove* icon in the top right of a panel to remove it from
the dashboard. Panels can also be removed from the row editor.

|Removing Panels|

Moving and Removing Rows
------------------------

Rows can be re-ordered and removed via the dashboard configuration
screen. Click the cog in the top left of the screen, and select the
**Rows** tab to make changes to the row layout. You may remember this
screen from when we added our first row.

|Removing Rows|

The arrows to the left allow you to change the order of the rows on your
dashboard. The **X** is used to remove rows.

Next steps
----------

Before you close your browser you might want to save this new dashboard.
See `Saving and Loading
dashboards <./saving-and-loading-dashboards.html>`__

Saving and Loading
==================

You’ve built an amazing dashboard! Now you want to share it with your
team, maybe turn on auto-refresh and put it up on a big screen? Kibana
can persist dashboard designs to Elasticsearch and allow you to recall
them via the load menu or links.

|image|

Saving your awesome dashboard
-----------------------------

Saving your flashy new interface is as easy as opening the save drop
down by clicking the **Save** icon in the upper righthand corner. Give
your new dashboard a name and hit *enter*. Now your dashboard has been
saved to a special Elasticsearch index called ``kibana-int``

|image|

Recalling your dashboard
------------------------

To search a list of your saved dashboards click the **Load** icon in the
upper righthand corner. From here you can load, share and remove
dashboards.

|image|

Sharing dashboards
------------------

Saved dashboards can be shared via the URL in your brower’s navigation
bar. Dashboards persisted to Elasticsearch will have a URL that points
to them, such as:

.. code:: shell

    http://your_host/index.html#/dashboard/elasticsearch/MYDASHBOARD

In this example ``MYDASHBOARD`` is the title we have given the dashboard
when saving.

You can also share links to adhoc dashboards by generating a temporary
URL to them by clicking the **Share** icon in the upper righthand corner
of Kibana.

|image|

By default these temporary URLs live for 30 days.

|image|

Saving a static dashboard
-------------------------

Dashboards can also be saved to disk on your server as .json files.
Place them in the ``app/dashboards`` directory and access them via

.. code:: shell

    http://your_host/index.html#/dashboard/file/MYDASHBOARD.json

Where ``MYDASHBOARD.json`` is the name of the file on disk. Note the
path ``/#dashboard/file/`` appears similar to the above path for
accessing Elasticsearch stored dashboards, but in this case we are
accessing a file instead of elasticsearch. For information on exporting
the dashboard schema to a file see `The Dashboard Schema
Explained <./_dashboard_schema.html>`__

Next steps
----------

Now that you know how to save dashboards, how to load them and how to
access them on disk you might be interested in passing them parameters
via the URL so you can programatically make links to data from other
applications. See `Templated and Scripted
Dashboards <./templated-and-scripted-dashboards.html>`__

Dashboard Schema
================

Kibana dashboards can be easily created right in the browser, and in
most cases, the browser is all you will need to build a powerful,
informative, interface. When you need that extra little bit of tweaking,
Kibana allows for the editing of the dashboard schema.

**NOTE**: This section is for advanced users only. JSON syntax is very
strict, a stray comma or missing brace will cause your dashboard not to
load.

|image|

We will be using the above dashboard as an example. You can export the
schema of any dashboard by clicking the **Save** icon in the top right,
selecting advanced and choosing **Export Schema**. You can download this
schema here: `schema.json <./snippets/schema.json>`__

While the dashboard is made up of one large JSON document, we will break
it down into pieces for the purpose of instruction in this guide.

Like any JSON document, we start with an opening brace.

.. code:: json

    {

Services
--------

.. code:: json

      "services": {

Services are persisted objects that are used by multiple panels. There
are currently 2 services that attach to the dashboard object and if
omitted will be automatically populated with query and filter services.

-  Query

-  Filter

Query
~~~~~

.. code:: json

        "query": {
          "list": {
            "0": {
              "query": "play_name:\"Romeo and Juliet\"",
              "alias": "",
              "color": "#7EB26D",
              "id": 0,
              "pin": false,
              "type": "lucene",
              "enable": true
            }
          },
          "ids": [
            0
          ]
        },

The query service is controlled largely by the query dropdown at the top
of the dashboard. It has 2 properties:

-  List: An object made of numericly keyed objects, each describing a
   query object. The query keys are fairly self explanitory and describe
   the look and behavior of the query input.

-  Ids: An array of IDs that must match the keys in the list. The ids
   array is used for ordering the list for the purpose of display.

Filter
~~~~~~

.. code:: json

        "filter": {
          "list": {
            "0": {
              "type": "querystring",
              "query": "speaker:ROMEO",
              "mandate": "must",
              "active": true,
              "alias": "",
              "id": 0
            }
          },
          "ids": [
            0
          ]
        }
      },

Filters behave much like queries, but are not selectable on a panel
level, they filter the entire dashboard view. Much like the query
service, there are are two properties: list and ids. Each of these
behaves like their query counter part.

Pulldown
--------

.. code:: json

      "pulldowns": [

Pulldowns are a special type of panel. Rather, they’re a special place
you can put panels. The panels in the ``pulldown`` section work just
like panels in a row except they don’t get a span, they’re all full
width. Also panels in pulldowns are not movable or editable by the user.
They’re great for panels that take input. the ``pulldown`` property is
an array that contains panel objects. For documentation for specific
panels see `Kibana Panels <./panels.html>`__

.. code:: json

        {
          "type": "query",
          "collapse": false,
          "notice": false,
          "enable": true,
          "query": "*",
          "pinned": true,
          "history": [
            "play_name:\"Romeo and Juliet\"",
            "playname:\"Romeo and Juliet\"",
            "romeo"
          ],
          "remember": 10
        },
        {
          "type": "filtering",
          "collapse": false,
          "notice": true,
          "enable": true
        }
      ],

Pulldown panels have 2 options that traditional row based panels do not
have:

-  Collapse: Set to true or false, this describes whether the panel is
   collapsed or expanded.

-  Notice: This property can be set by the panel and controls a small
   star icon in the pulldown tab’s title. It is usually used to notify
   the user that something has changed in the panel.

Nav
---

The ``nav`` property also contains a list of panels, however these
panels need to be designed to fit into the nav bar at the top of the
screen. The only currently support nav panel is the timepicker

.. code:: json

      "nav": [
        {
          "type": "timepicker",
          "collapse": false,
          "notice": false,
          "enable": true,
          "status": "Stable",
          "time_options": [
            "5m",
            "15m",
            "1h",
            "6h",
            "12h",
            "24h",
            "2d",
            "7d",
            "30d"
          ],
          "refresh_intervals": [
            "5s",
            "10s",
            "30s",
            "1m",
            "5m",
            "15m",
            "30m",
            "1h",
            "2h",
            "1d"
          ],
          "timefield": "@timestamp"
        }
      ],

Loader
------

The ``loader`` property describes the behavior of the save and load
buttons at the top of the dashboard.

.. code:: json

      "loader": {
        "save_gist": false,
        "save_elasticsearch": true,
        "save_local": true,
        "save_default": true,
        "save_temp": true,
        "save_temp_ttl_enable": true,
        "save_temp_ttl": "30d",
        "load_gist": false,
        "load_elasticsearch": true,
        "load_elasticsearch_size": 20,
        "load_local": false,
        "hide": false
      },

Rows Array
----------

``rows`` are where panels are usually placed, and the only place they
can be added via the browser UI.

.. code:: json

    "rows": [
        {
          "title": "Charts",
          "height": "150px",
          "editable": true,
          "collapse": false,
          "collapsable": true,

Row objects contain a panel array as well as several other properties
describing the row:

-  title: The row title

-  height: The height of the row, in pixels, with the *px* designation

-  editable: true/false describing whether or not the panel is editable

-  collapse: true/false describing whether or not the row is collapse

-  collapsable:true/false describing whether or not the user is allowed
   to collapse the row

Panels Array
~~~~~~~~~~~~

The ``panels`` array property of a row contains a list of panel objects
in the order in which they appear in the row. For a list of common panel
properties and documentation for specific panels see `Kibana
Panels <./panels.html>`__

.. code:: json

          "panels": [
            {
              "error": false,
              "span": 8,
              "editable": true,
              "type": "terms",
              "loadingEditor": false,
              "field": "speech_number",
              "exclude": [],
              "missing": false,
              "other": false,
              "size": 10,
              "order": "count",
              "style": {
                "font-size": "10pt"
              },
              "donut": false,
              "tilt": false,
              "labels": true,
              "arrangement": "horizontal",
              "chart": "bar",
              "counter_pos": "above",
              "spyable": true,
              "queries": {
                "mode": "all",
                "ids": [
                  0
                ]
              },
              "tmode": "terms",
              "tstat": "total",
              "valuefield": "",
              "title": "Longest Speeches"
            },
            {
              "error": false,
              "span": 4,
              "editable": true,
              "type": "goal",
              "loadingEditor": false,
              "donut": true,
              "tilt": false,
              "legend": "none",
              "labels": true,
              "spyable": true,
              "query": {
                "goal": 111397
              },
              "queries": {
                "mode": "all",
                "ids": [
                  0
                ]
              },
              "title": "Percentage of Total"
            }
          ]
        }
      ],

Index Settings
--------------

The index property contains information on the Elasticsearch index that
Kibana communicates with.

.. code:: json

      "index": {
        "interval": "none",
        "default": "_all",
        "pattern": "[logstash-]YYYY.MM.DD",
        "warm_fields": false
      },

-  interval: none, hour, day, week, month. This property describes the
   timestamping pattern that the index follows.

-  default: The index to use if ``interval`` is set to none or the
   ``failover`` setting below is set to ``true`` and no indices match
   the pattern

-  pattern: If ``interval`` is set to anything other than *none*, parse
   this pattern, taking into consideration any time filters, to
   determine the indices to query.

-  warm\_fields: If the mapping should be parsed to determine a list of
   fields

The Rest
--------

The following are top level dashboard settings

.. code:: json

      "failover": false,
      "editable": true,
      "style": "dark",
      "refresh": false
    }

-  failover: true/false, whether or not we should use ``index.default``
   if no indices match the index pattern

-  editable: true/false, whether or not to show the configure button for
   the dashboard

-  style: "light" or "dark"

-  refresh: False, or an elasticsearch date math (eg 10s, 1m, 1h)
   expression describing how often to issue a refresh event instructing
   panels to refresh their data.

Importing Schemas
-----------------

By default, importing of schemas is disabled. It can be re-enabled via
the **Controls** tab of the dashboard settings screen by checking the
**Local file** option. Schemas can be imported from the **Load** icon in
the top left of the dashboard by selecting **Advanced** and choosing a
file to import.

Templates and Scripts
=====================

Kibana has support for creating dashboards dynamically via templates,
and more advanced scripts. This allows you to create a based dashboard,
then influence it with parameters, such as inserting a new query or
filter via the URL.

Templates and scripts must be stored on disk, storing them to
Elasticsearch is not supported. They must also be created by editing or
creating a schema. Because of this we highly recommend reading `The
Kibana Schema Explained <./_dashboard_schema.html>`__

The dashboard directory
-----------------------

Dashboards are stored in the ``app/dashboards`` directory within the
Kibana installation directory. You will notice there are 2 types of
files: ``.json`` files and ``.js`` files.

Templated Dashboards ``(.json)``
--------------------------------

``.json`` files are templated dashboards. An example of templating can
be found on the query and filter objects of the ``logstash.json``
dashboard. Templates use handlebar syntax that allow you insert
javascript clauses into your json. URL parameters are available on the
``ARGS`` object. For example, a snippet from ``logstash.json``'s `(on
github) <https://github.com/elasticsearch/kibana/blob/3.0/src/app/dashboards/logstash.json>`__
query and filter services:

.. code:: json

      "0": {
        "query": "{{ARGS.query || '*'}}",
        "alias": "",
        "color": "#7EB26D",
        "id": 0,
        "pin": false
      }

      [...]

      "0": {
        "type": "time",
        "field": "@timestamp",
        "from": "now-{{ARGS.from || '24h'}}",
        "to": "now",
        "mandate": "must",
        "active": true,
        "alias": "",
        "id": 0
      }

This allows us to set 2 parameters, ``query`` and ``from`` in the url.
If they are not set, they will default to the value after the ``||``.
For example, this would search for ``status:200`` in the last 7 days:

**Note**: Take careful note of the ``file`` part of
``#/dashboard/file/logstash.json``

::

    http://yourserver/index.html#/dashboard/file/logstash.json?query=status:200&from=7d

Scripted Dashboards ``(.js)``
-----------------------------

Scripted dashboards are much more powerful than templated dashboards. Of
course, with power comes responsibility, and scripted dashboards are
more complex to build. The goal in a scripted dashboard is to build and
return a javascript object that describes the dashboard schema. A well
commented example scripted dashboard can be found in
``app/dashboards/logstash.js`` `(on
github) <https://github.com/elasticsearch/kibana/blob/3.0/src/app/dashboards/logstash.js>`__.
This file accomplishes the same goals as ``logstash.json``, but with the
added power of scripts we can do things like split queries on commas:

**Note**: Take careful note of the ``script`` part of
``#/dashboard/script/logstash.js``. This instructs kibana to treat this
file as javascript.

::

    http://yourserver/index.html#/dashboard/script/logstash.js?query=status:403,status:404&from=7d

This will create 2 query objects, ``status:403`` and ``status:404`` and
chart them seperately. In fact this dashboard takes another parameter
that describes the string by which to split the query on: ``split``

::

    http://yourserver/index.html#/dashboard/script/logstash.js?query=status:403!status:404&from=7d&split=!

We can see this happening in ``logstash.js`` `(on
github) <https://github.com/elasticsearch/kibana/blob/3.0/src/app/dashboards/logstash.js>`__
here:

.. code:: javascript

    // In this dashboard we let users pass queries as comma separated list to the query parameter.
    // Or they can specify a split character using the split parameter
    // If query is defined, split it into a list of query objects
    // NOTE: ids must be integers, hence the parseInt()s
    if(!_.isUndefined(ARGS.query)) {
      queries = _.object(_.map(ARGS.query.split(ARGS.split||','), function(v,k) {
        return [k,{
          query: v,
          id: parseInt(k,10),
          alias: v
        }];
      }));
    } else {
      // No queries passed? Initialize a single query to match everything
      queries = {
        0: {
          query: '*',
          id: 0,
        }
      };
    }

This dashboard takes more parameters than this, all of which are
described in the comments at the top of ``logstash.js`` `(on
github) <https://github.com/elasticsearch/kibana/blob/3.0/src/app/dashboards/logstash.js>`__

Configuration
=============

config.js is where you will find the core Kibana configuration. This
file contains parameter that must be set before kibana is run for the
first time.

Parameters
----------

elasticsearch
~~~~~~~~~~~~~

The URL to your elasticsearch server. You almost certainly don’t want
``http://localhost:9200`` here. Even if Kibana and Elasticsearch are on
the same host. By default this will attempt to reach ES at the same host
you have kibana installed on. You probably want to set it to the FQDN of
your elasticsearch host

Note: this can also be an object if you want to pass options to the http
client. For example:

::

    +elasticsearch: {server: "http://localhost:9200", withCredentials: true}+

default\_route
~~~~~~~~~~~~~~

This is the default landing page when you don’t specify a dashboard to
load. You can specify files, scripts or saved dashboards here. For
example, if you had saved a dashboard called ‘WebLogs’ to elasticsearch
you might use:

default\_route: */dashboard/elasticsearch/WebLogs*,

kibana-int
~~~~~~~~~~

The default ES index to use for storing Kibana specific object such as
stored dashboards

panel\_name
~~~~~~~~~~~

An array of panel modules available. Panels will only be loaded when
they are defined in the dashboard, but this list is used in the "add
panel" interface.

**Kibana** dashboards are made up of blocks called ``panels``. Panels
are organized into rows and can serve many purposes, though most are
designed to provide the results of a query or multiple queries as a
visualization. Other panels may show collections of documents or allow
you to insert instructions for your users.

Panels can be configured easily via the Kibana web interface. For more
advanced usage, such as templated or scripted dashboards, documentation
of panel properties is available in this section. You may find settings
here which are not exposed via the web interface.

Each panel type has its own properties, however there are several that
are shared.

span
    A number, 1-12, that describes the width of the panel.

editable
    Enable or disable the edit button of the panel

type
    The type of panel this object contains. Each panel type will require
    additional properties. See the panel types list to the right.

Bettermap
=========

Status: **Experimental**

Bettermap is called bettermap for lack of a better name. Bettermap uses
geographic coordinates to create clusters of markers on map and shade
them orange, yellow and green depending on the density of the cluster.

To drill down, click on a cluster. The map will be zoomed and the
cluster broken into smaller cluster. When it no longer makes visual
sense to cluster, individual markers will be displayed. Hover over a
marker to see the tooltip value/

    **Important**

    bettermap requires an internet connection to download its map
    panels.

Parameters
----------

field
    The field that contains the coordinates, in geojson format. GeoJSON
    is ``[longitude,latitude]`` in an array. This is different from most
    implementations, which use latitude, longitude.

size
    The number of documents to use when drawing the map

spyable
    Should the ``inspect`` icon be shown?

tooltip
    Which field to use for the tooltip when hovering over a marker

Queries
~~~~~~~

queries object
    This object describes the queries to use on this panel.

    queries.mode
        Of the queries available, which to use. Options:
        ``all, pinned, unpinned, selected``

    queries.ids
        In ``selected`` mode, which query ids are selected.

Column
======

Status: **Stable**

A pseudo panel that lets you add other panels to be arranged in a column
with defined heights. While the column panel is stable, it does have
many limitations, including the inability to drag and drop panels within
its borders. It may be removed in a future release.

Parameters
----------

panel
    An array of panel objects

Goal
====

Status: **Stable**

The goal panel display progress towards a fixed goal on a pie chart

Parameters
----------

donut
    Draw a hole in the middle of the pie, creating a tasty donut.

tilt
    Tilt the pie back into an oval shape

legend
    The location of the legend, above, below or none

labels
    Set to false to disable drawing labels inside the pie slices

spyable
    Set to false to disable the inspect function.

Query
~~~~~

query object
    query.goal
        the fixed goal for goal mode

Queries
~~~~~~~

queries object
    This object describes the queries to use on this panel.

    queries.mode
        Of the queries available, which to use. Options:
        ``all, pinned, unpinned, selected``

    queries.ids
        In ``selected`` mode, which query ids are selected.

Histogram
=========

Status: **Stable**

The histogram panel allow for the display of time charts. It includes
several modes and tranformations to display event counts, mean, min, max
and total of numeric fields, and derivatives of counter fields.

Parameters
----------

Axis options
~~~~~~~~~~~~

mode
    Value to use for the y-axis. For all modes other than count,
    ``value_field`` must be defined. Possible values: count, mean, max,
    min, total.

time\_field
    x-axis field. This must be defined as a date type in Elasticsearch.

value\_field
    y-axis field if ``mode`` is set to mean, max, min or total. Must be
    numeric.

x-axis
    Show the x-axis

y-axis
    Show the y-axis

scale
    Scale the y-axis by this factor

y\_format
    *none*,\ *bytes*,'short '

Annotations
~~~~~~~~~~~

annotate object
    A query can be specified, the results of which will be displayed as
    markers on the chart. For example, for noting code deploys.

    annotate.enable
        Should annotations, aka markers, be shown?

    annotate.query
        Lucene query\_string syntax query to use for markers.

    annotate.size
        Max number of markers to show

    annotate.field
        Field from documents to show

    annotate.sort
        Sort array in format [field,order], For example
        [‘@timestamp’,‘desc’] ==== Interval options

auto\_int
    Automatically scale intervals?

resolution
    If auto\_int is true, shoot for this many bars.

interval
    If auto\_int is set to false, use this as the interval.

interval
    Array of possible intervals in the **View** selector. Example
    [‘auto’,‘1s’,‘5m’,‘3h’] ==== Drawing options

lines
    Show line chart

fill
    Area fill factor for line charts, 1-10

linewidth
    Weight of lines in pixels

points
    Show points on chart

pointradius
    Size of points in pixels

bars
    Show bars on chart

stack
    Stack multiple series

spyable
    Show inspect icon

zoomlinks
    Show ‘Zoom Out’ link

options
    Show quick view options section

legend
    Display the legend

show\_query
    If no alias is set, should the query be displayed?

interactive
    Enable click-and-drag to zoom functionality

legend\_counts
    Show counts in legend ==== Transformations

timezone
    Correct for browser timezone?. Valid values: browser, utc

percentage
    Show the y-axis as a percentage of the axis total. Only makes sense
    for multiple queries

zerofill
    Improves the accuracy of line charts at a small performance cost.

derivative
    Show each point on the x-axis as the change from the previous point

tooltip object
    tooltip.value\_type
        Individual or cumulative controls how tooltips are display on
        stacked charts

    tooltip.query\_as\_alias
        If no alias is set, should the query be displayed?

grid object
    Min and max y-axis values

    grid.min
        Minimum y-axis value

    grid.max
        Maximum y-axis value

Queries
~~~~~~~

queries object
    This object describes the queries to use on this panel.

    queries.mode
        Of the queries available, which to use. Options:
        ``all, pinned, unpinned, selected``

    queries.ids
        In ``selected`` mode, which query ids are selected.

Hits
====

Status: **Stable**

The hits panel displays the number of hits for each of the queries on
the dashboard in a configurable format specified by the ‘chart’
property.

Parameters
----------

arrangement
    The arrangement of the legend. horizontal or vertical

chart
    bar, pie or none

counter\_pos
    The position of the legend, above or below

donut
    If the chart is set to pie, setting donut to true will draw a hole
    in the midle of it

tilt
    If the chart is set to pie, setting tilt to true will tilt it back
    into an oval

labels
    If the chart is set to pie, setting labels to true will draw labels
    in the slices

spyable
    Setting spyable to false disables the inspect icon.

Queries
~~~~~~~

queries object
    This object describes the queries to use on this panel.

    queries.mode
        Of the queries available, which to use. Options:
        ``all, pinned, unpinned, selected``

    queries.ids
        In ``selected`` mode, which query ids are selected.

Map
===

Status: **Stable**

The map panel translates 2 letter country or state codes into shaded
regions on a map. Currently available maps are world, usa and europe.

Parameters
----------

map
    Map to display. world, usa, europe

colors
    An array of colors to use to shade the map. If 2 colors are
    specified, shades between them will be used. For example [‘#A0E2E2’,
    ‘#265656’]

size
    Max number of regions to shade

exclude
    Exclude this array of regions. For example [‘US’,‘BR’,‘IN’]

spyable
    Setting spyable to false disables the inspect icon.

Queries
~~~~~~~

queries object
    This object describes the queries to use on this panel.

    queries.mode
        Of the queries available, which to use. Options:
        ``all, pinned, unpinned, selected``

    queries.ids
        In ``selected`` mode, which query ids are selected.

Sparklines
==========

Status: **Experimental**

The sparklines panel shows tiny time charts. The purpose of these is not
to give an exact value, but rather to show the shape of the time series
in a compact manner

Parameters
----------

mode
    Value to use for the y-axis. For all modes other than count,
    ``value_field`` must be defined. Possible values: count, mean, max,
    min, total.

time\_field
    x-axis field. This must be defined as a date type in Elasticsearch.

value\_field
    y-axis field if ``mode`` is set to mean, max, min or total. Must be
    numeric.

interval
    Sparkline intervals are computed automatically as long as there is a
    time filter present. In the absence of a time filter, use this
    interval.

spyable
    Show inspect icon

Queries
~~~~~~~

queries object
    This object describes the queries to use on this panel.

    queries.mode
        Of the queries available, which to use. Options:
        ``all, pinned, unpinned, selected``

    queries.ids
        In ``selected`` mode, which query ids are selected.

table
=====

Status: **Stable**

The table panel contains a sortable, pagable view of documents that. It
can be arranged into defined columns and offers several interactions,
such as performing adhoc terms aggregations.

Parameters
----------

size
    The number of hits to show per page

pages
    The number of pages available

offset
    The current page

sort
    An array describing the sort order of the table. For example
    [‘@timestamp’,‘desc’]

overflow
    The css overflow property. ‘min-height’ (expand) or ‘auto’ (scroll)

fields
    The fields used a columns of the table, in an array.

highlight
    The fields on which to highlight, in an array

sortable
    Set sortable to false to disable sorting

header
    Set to false to hide the table column names

paging
    Set to false to hide the paging controls of the table

field\_list
    Set to false to hide the list of fields. The user will be able to
    expand it, but it will be hidden by default

all\_fields
    Set to true to show all fields in the mapping, not just the current
    fields in the table.

trimFactor
    The trim factor is the length at which to truncate fields taking the
    number of columns in the table into consideration. For example, a
    trimFactor of 100, with 5 columns in the table, would trim each
    column at 20 character. The entirety of the field is still available
    in the expanded view of the event.

localTime
    Set to true to adjust the timeField to the browser’s local time

timeField
    If localTime is set to true, this field will be adjusted to the
    browsers local time

spyable
    Set to false to disable the inspect icon

Queries
~~~~~~~

queries object
    This object describes the queries to use on this panel.

    queries.mode
        Of the queries available, which to use. Options:
        ``all, pinned, unpinned, selected``

    queries.ids
        In ``selected`` mode, which query ids are selected.

terms
=====

Status: **Stable**

A table, bar chart or pie chart based on the results of an Elasticsearch
terms facet.

Parameters
----------

field
    The field on which to compute the facet

exclude
    terms to exclude from the results

missing
    Set to false to disable the display of a counter showing how much
    results are missing the field

other
    Set to false to disable the display of a counter representing the
    aggregate of all values outside of the scope of your ``size``
    property

size
    Show this many terms

order
    In terms mode: count, term, reverse\_count or reverse\_term, in
    terms\_stats mode: term, reverse\_term, count, reverse\_count,
    total, reverse\_total, min, reverse\_min, max, reverse\_max, mean or
    reverse\_mean

donut
    In pie chart mode, draw a hole in the middle of the pie to make a
    tasty donut.

tilt
    In pie chart mode, tilt the chart back to appear as more of an oval
    shape

labels
    In pie chart mode, draw labels in the pie slices

arrangement
    In bar or pie mode, arrangement of the legend. horizontal or
    vertical

chart
    table, bar or pie

counter\_pos
    The location of the legend in respect to the chart, above, below, or
    none.

spyable
    Set spyable to false to disable the inspect button

Queries
~~~~~~~

queries object
    This object describes the queries to use on this panel.

    queries.mode
        Of the queries available, which to use. Options:
        ``all, pinned, unpinned, selected``

    queries.ids
        In ``selected`` mode, which query ids are selected.

tmode
    Facet mode: terms or terms\_stats

tstat
    Terms\_stats facet stats field

valuefield
    Terms\_stats facet value field

text
====

Status: **Stable**

The text panel is used for displaying static text formated as markdown,
sanitized html or as plain text.

Parameters
----------

mode
    ‘html’, ‘markdown’ or ‘text’

content
    The content of your panel, written in the mark up specified in
    ``mode``

trends
======

Status: **Beta**

A stock-ticker style representation of how queries are moving over time.
For example, if the time is 1:10pm, your time picker was set to "Last
10m", and the "Time Ago" parameter was set to "1h", the panel would show
how much the query results have changed since 12:00-12:10pm

Parameters
----------

ago
    A date math formatted string describing the relative time period to
    compare the queries to.

arrangement
    ‘horizontal’ or ‘vertical’

spyable
    Set to false to disable the inspect icon

Queries
~~~~~~~

queries object
    This object describes the queries to use on this panel.

    queries.mode
        Of the queries available, which to use. Options:
        ``all, pinned, unpinned, selected``

    queries.ids
        In ``selected`` mode, which query ids are selected.

.. |Welcome Page| image:: ./tutorials/intro/intro.png
.. |Sample Dashboard| image:: ./tutorials/intro/sample_shakespeare.png
.. |Sample Dashboard| image:: ./tutorials/intro/query.png
.. |Sample Dashboard| image:: ./tutorials/intro/firsttable.png
.. |Sample Dashboard| image:: ./tutorials/intro/configicon.png
.. |Sample Dashboard| image:: ./tutorials/intro/indexconfigure.png
.. |image| image:: ./tutorials/queries_filters/plays.png
.. |image| image:: ./tutorials/queries_filters/Addquery.png
.. |image| image:: ./tutorials/queries_filters/split.png
.. |image| image:: ./tutorials/queries_filters/pieslice.png
.. |image| image:: ./tutorials/queries_filters/remove.png
.. |image| image:: ./tutorials/queries_filters/settings.png
.. |image| image:: ./tutorials/queries_filters/comedyoferrors.png
.. |image| image:: ./tutorials/queries_filters/filteradded.png
.. |home screen| image:: ./tutorials/rows_panels/home.png
.. |Adding a row| image:: ./tutorials/rows_panels/Addingrow.png
.. |Adding a row| image:: ./tutorials/rows_panels/addedrow.png
.. |Row buttons| image:: ./tutorials/rows_panels/rowbuttons.png
.. |Row buttons| image:: ./tutorials/rows_panels/buttons_expanded.png
.. |Add panel| image:: ./tutorials/rows_panels/addpanel.png
.. |Add panel| image:: ./tutorials/rows_panels/terms_settings.png
.. |First panel| image:: ./tutorials/rows_panels/firstpanel.png
.. |Collapsed row| image:: ./tutorials/rows_panels/collapsed.png
.. |Collapsed top row| image:: ./tutorials/rows_panels/toprowscollapsed.png
.. |Row edit| image:: ./tutorials/rows_panels/roweditor.png
.. |Removing Panels| image:: ./tutorials/rows_panels/rowpanels.png
.. |Removing Panels| image:: ./tutorials/rows_panels/movepanel.png
.. |Removing Panels| image:: ./tutorials/rows_panels/removing_panels.png
.. |Removing Rows| image:: ./tutorials/rows_panels/rowmove.png
.. |image| image:: ./tutorials/saving_loading/awesome_dashboard.png
.. |image| image:: ./tutorials/saving_loading/savebutton.png
.. |image| image:: ./tutorials/saving_loading/searchdashboards.png
.. |image| image:: ./tutorials/saving_loading/sharebutton.png
.. |image| image:: ./tutorials/saving_loading/sharelink.png
.. |image| image:: ./tutorials/dashboard_schema/schema_dashboard.png
