Merge pull request #2857 from debadair/kibana-docs

First draft of the Kibana intro, setup, and settings topics

docs/access.asciidoc

@@ -1,2 +1,13 @@
 [[access]]
-== Accessing Kibana
+== Accessing Kibana
+
+Kibana is a web application that you access through port 5601. All you need to 
+do is point your web browser at the machine where Kibana is running and 
+specify the port number. For example, `localhost:5601` or `http://YOURDOMAIN.com:5601`.
+
+When you access Kibana, the Discover page loads by default with the default index
+pattern selected. The time filter is set to the last 15 minutes and the search 
+query is set to match-all (*).
+
+If you don't see any documents, try setting the time filter to a wider time range.
+If you still don't see any results, it's possible that you don't *have* any documents.

docs/dashboard.asciidoc

@@ -1,2 +1,129 @@
 [[dashboard]]
-== Working with Dashboards
+== Dashboard
+
+A Kibana _dashboard_ displays a set of saved visualizations in groups that you can arrange freely. You can save a 
+dashboard to share or reload at a later time.
+
+.Sample dashboard
+image:images/tfl-dashboard.png[Example dashboard]
+
+[float]
+[[getting-started]]
+=== Getting Started
+
+You need at least one saved <<visualize, visualization>> to use a dashboard.
+
+[float]
+[[creating-a-new-dashboard]]
+==== Building a New Dashboard
+
+The first time you click the *Dashboard* tab, Kibana displays an empty dashboard.
+
+image:images/NewDashboard.png[New Dashboard screen]
+
+Build your dashboard by adding visualizations.
+
+[float]
+[[adding-visualizations-to-a-dashboard]]
+==== Adding Visualizations to a Dashboard
+
+To add a visualization to the dashboard, click the *Add Visualization* image:images/AddVis.png[Plus] button in the 
+toolbar panel. Select a saved visualization from the list. You can filter the list of visualizations by typing a filter 
+string into the *Visualization Filter* field.
+
+The visualization you select appears in a _container_ on your dashboard.
+
+NOTE: If you see a message about the container's height or width being too small, <<resizing-containers,resize the 
+container>>.
+
+[float]
+[[saving-dashboards]]
+==== Saving Dashboards
+
+To save the dashboard, click the *Save Dashboard* button in the toolbar panel, enter a name for the dashboard in the 
+*Save As* field, and click the *Save* button.
+
+[float]
+[[loading-a-saved-dashboard]]
+==== Loading a Saved Dashboard
+
+Click the *Load Saved Dashboard* button to display a list of existing dashboards. The saved dashboard selector includes 
+a text field to filter by dashboard name and a link to the Object Editor for managing your saved dashboards. You can 
+also access the Object Editor by clicking *Settings > Edit Saved Objects*.
+
+[float]
+[[sharing-dashboards]]
+==== Sharing Dashboards
+
+You can share dashboards with other users. You can share a direct link to the Kibana dashboard or embed the dashboard 
+in your Web page.
+
+NOTE: A user must have Kibana access in order to view embedded dashboards.
+
+Click the *Share* button to display HTML code to embed the dashboard in another Web page, along with a direct link to 
+the dashboard. Click the copy button image:images/Clipboard.png[Copy to Clipboard button] next to either option to copy 
+the code or the link to your clipboard.
+
+[float]
+[[embedding-dashboards]]
+==== Embedding Dashboards
+
+To embed a dashboard, copy the embed code from the _Share_ display into your external web application.
+
+[float]
+[[customizing-your-dashboard]]
+=== Customizing Dashboard Elements
+
+The visualizations in your dashboard are stored in resizable _containers_ that you can arrange on the dashboard. This 
+section discusses customizing these containers.
+
+[float]
+[[moving-containers]]
+==== Moving Containers
+
+Click and hold a container's header to move the container around the dashboard. Other containers will shift as needed 
+to make room for the moving container. Release the mouse button to confirm the container's new location.
+
+[float]
+[[resizing-containers]]
+==== Resizing Containers
+
+Move the cursor to the bottom right corner of the container until the cursor changes to point at the corner. After the 
+cursor changes, click and drag the corner of the container to change the container's size. Release the mouse button to 
+confirm the new container size.
+
+// enhancement request: a way to specify specific dimensions for a container in pixels, or at least display that info?
+
+[float]
+[[removing-containers]]
+==== Removing Containers
+
+Click the *x* icon at the top right corner of a container to remove that container from the dashboard. Removing a 
+container from a dashboard does not delete the saved visualization in that container.
+
+[float]
+[[viewing-detailed-information]]
+==== Viewing Detailed Information
+
+To display the raw data behind the visualization, click the bar at the bottom of the container. Tabs with detailed 
+information about the raw data replace the visualization, as in this example:
+
+[horizontal]
+*Table*:: A representation of the underlying data, presented as a paginated data grid. You can sort the items 
+in the table by clicking on the table headers at the top of each column.
+image:images/NYCTA-Table.png[]
+*Request*:: The raw request used to query the server, presented in JSON format.
+image:images/NYCTA-Request.png[]
+*Response*:: The raw response from the server, presented in JSON format.
+image:images/NYCTA-Response.png[]
+*Statistics*:: A summary of the statistics related to the request and the response, presented as a data grid. The data 
+grid includes the query duration, the request duration, the total number of records found on the server, and the 
+index pattern used to make the query.
+image:images/NYCTA-Statistics.png[]
+
+[float]
+[[changing-the-visualization]]
+=== Changing the Visualization
+
+Click the _Edit_ button image:images/EditVis.png[Pencil button] at the top right of a container to open the 
+visualization in the <<visualize,Visualize>> page.

docs/dashboard.md

@@ -1,81 +0,0 @@
-## Dashboard
-
-The dashboard is used to group and display any Visualizations you've created. Once you have a collection of visualizations that you like, you can save it as a custom dashboard to share or reload later.
-
-### Getting Started
-
-Using the dashboard requires that you have at least one [saved visualization](#visualize).
-
-#### Creating a New Dashboard
-
-The first time you open the Dashboard, it will be ready for you to build a new dashboard. You can create a new dashboard by clicking the left-most icon in the toolbar panel.
-
-#### Adding Visualizations to a Dashboard
-
-To add a visualization to the dashboard, click the plus button in the toolbar panel. A menu of your saved visualizations will appear.
-
-From the menu, click on the visualization you want to include in your dashboard. If you have more then 5 saved visualizations, the list will paginate. You can also filter the list from the **Visualization Filter** at the top of the list.
-
-Once you've clicked on the visualization, you will see it appear in a *container* in the dashboard below.
-
-**NOTE:** You may see a message saying that the height and/or width of the container is too small. If you see this message, you can fix it by making the container larger - described below.
-
-#### Saving Dashboards
-
-Click on the save button in the toolbar panel to save the dashboard to Elasticsearch. Clicking the save icon will show you a menu below the toolbar panel where you can enter a name for your dashboard. After giving it a name, click the *Save* button.
-
-#### Loading a Saved Dashboard
-
-To load an existing dashboard, click on the *Open* icon in the toolbar menu. This will present you with a list of existing dashboard you can load. If you have more then 5 dashboards, you can use the filter input at the top to search for the dashboard you want to load or click the page links at the bottom of the loader panel.
-
-#### Sharing Dashboards
-
-To obtain the code needed to embed a dashboard in other applications, click the right-most icon in the toolbar menu. It will present you with menu containing two links.
-
-##### Embedding Dashboards
-
-Dashboards can be embedded in other web apps by using the embed code. Simply copy the embed code from the *Share* menu and paste it in your external web application. Note that anyone that views an embedded dashboard must also have access to Kibana.
-
-##### Sharing Dashboards
-
-Dashboards can also be shared with anyone that has access to Kibana. Simply copy the share link from the *Share* menu and share it with others via email or other means.
-
-### Customizing Your Dashboard
-
-The dashboard can be customized in a number of ways to suit your needs.
-
-#### Moving Containers
-
-To move containers around, drag the container by clicking and holding the header and moving it where you want it. Other containers may shift around to make room for the container you are moving. When you are happy with the location of the container, release the mouse button.
-
-#### Resizing Containers
-
-As you move the mouse cursor to the bottom right corner of the container, a small move icon will appear. Once your cursor changes the move icon, you can click and drag the container to make it the size you need.  When you let go of the mouse button, the visualization inside the container will adjust to the new container size.
-
-#### Removing Containers
-
-Containers can be removed from your dashboard by clicking on the close icon located in the top right of corner the container. This will not delete the saved visualization, it will remove it from the current Dashboard.
-
-### Viewing Detailed Information
-
-It may sometimes be useful to view the data that is being used to create the visualization. You can view this information by clicking on the bar at the bottom of the container. Doing so will hide the visualization and show the raw data it's using.  There are four tabs at the top of this view that break down the data in various ways.
-
-#### Table
-
-This is a representation of all the underlying data, presented as a paginated data grid. The items in this table can be sorted by clicking on the table headers at the top of each column.
-
-#### Request
-
-This is the raw request used to query the server, presented as prettified JSON text.
-
-#### Response
-
-This is the raw response from the server, presented as prettified JSON text.
-
-#### Statistics
-
-This is a summary of the statistics related to the request and the response, presented as a data grid. It includes information such as the query duration, the request duration, the total number of records found on the server and the index pattern used to make the query.
-
-### Changing the Visualization
-
-To change a visualization, click on the *Edit* icon at the top right of the visualization container. This will open that visualization in the *Visualize* app. Refer to the [Visualize docs](#visualize) for usage instructions.

docs/discover.asciidoc

@@ -1,2 +1,195 @@
 [[discover]]
-== Discovering your Data
+== Discover
+You can interactively explore your data from the Discover page. You have access to every document in every index that matches the selected index pattern. You can submit search queries, filter the search results, and view document data. You can also see the number of documents that match the search query and get field value statistics. If a time field is configured for the selected index pattern, the distribution of documents over time is displayed in a histogram at the top of the page. 
+
+image:images/Discover-Start-Annotated.jpg[Discover Page]
+
+[float]
+[[set-time-filter]]
+=== Setting the Time Filter
+The Time Filter restricts the search results to a specific time period. You can set a time filter if your index contains time-based events and a time-field is configured for the selected index pattern.
+
+By default the time filter is set to the last 15 minutes. You can use the Time Picker to change the time filter
+or select a specific time interval or time range in the histogram at the top of the page.
+
+To set a time filter with the Time Picker:
+
+. Click the Time Filter displayed in the upper right corner of the menu bar to open the Time Picker.
+. To set a quick filter, simply click one of the shortcut links.
+. To specify a relative Time Filter, click *Relative* and enter the relative start time. You can specify
+the relative start time as any number of seconds, minutes, hours, days, months, or years ago.
+. To specify an absolute Time Filter, click *Absolute* and enter the start date in the *From* field and the end date in the *To* field.
+. Click the caret at the bottom of the Time Picker to hide it. 
+
+To set a Time Filter from the histogram, do one of the following:
+
+* Click the bar that represents the time interval you want to zoom in on.
+* Click and drag to view a specific timespan. You must start the selection with the cursor over the background of the chart--the cursor changes to a plus sign when you hover over a valid start point. 
+
+You can use the browser Back button to undo your changes. 
+
+[float]
+[[search]]
+=== Searching Your Data
+You can search the indices that match the current index pattern by submitting a search from the Discover page.
+You can enter simple query strings, use the Lucene https://lucene.apache.org/core/2_9_4/queryparsersyntax.html[query syntax], or use the full JSON-based http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL]. 
+
+When you submit a search, the histogram, Documents table, and Fields list are updated to reflect 
+the search results. The total number of hits (matching documents) is shown in the upper right corner of the
+histogram. The Documents table shows the first five hundred hits. By default, the hits are listed in reverse chronological order, with the newest documents shown first. You can reverse the sort order by by clicking on the Time column header. You can also sort the table using the values in any indexed field. For more information, see <<sorting, Sorting the Documents Table>>.
+
+To search your data:
+
+. Enter a query string in the Search field: 
++
+* To perform a free text search, simply enter a text string. For example, if you're searching web server logs, you could enter `safari` to search all fields for the term `safari`.
++
+* To search for a value in a specific field, you prefix the value with the name of the field. For example, you could enter `status:200` to limit the results to entries that contain the value `200` in the `status` field.
++
+* To search for a range of values, you can use the bracketed range syntax, `[START_VALUE TO END_VALUE]`. For example, to find entries that have 4xx status codes, you could enter `status:[400 TO 499]`.
++
+* To specify more complex search criteria, you can use the Boolean operators `AND`, `OR`, and `NOT`. For example,
+to find entries that have 4xx status codes and have an extension of `php` or `html`, you could enter `status:[400 TO 499] AND (extension:php OR extension:html)`.
++
+NOTE: These examples use the Lucene query syntax. You can also submit queries using the Elasticsearch Query DSL. For examples, see http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax[query string syntax] in the Elasticsearch Reference.
++
+. Press *Enter* or click the *Search* button to submit your search query.
+
+[float]
+[[new-search]]
+==== Starting a New Search
+To clear the current search and start a new search, click the *New Search* button in the Discover toolbar.
+
+image:images/Discover-New-Search.jpg[New Search]
+
+[float]
+[[save-search]]
+==== Saving a Search
+You can reload saved searches on the Discover page and use them as the basis of <<visualize, visualizations>>.
+Saving a search saves both the search query string and the currently selected index pattern.
+
+To save the current search:
+
+. Click the *Save Search* button image:images/SaveButton.jpg[Save Search button] in the Discover toolbar. 
+. Enter a name for the search and click *Save*.
+
+[float]
+[[load-search]]
+==== Loading a Saved Search
+To load a saved search:
+
+. Click the *Load Search* button image:images/LoadButton.jpg[Load Search 
+button] in the Discover toolbar.
+. Select the search you want to load.
+
+If the saved search is associated with a different index pattern than is currently selected, loading the saved search also changes the selected index pattern.
+
+[float]
+[[select-pattern]]
+==== Changing Which Indices You're Searching
+When you submit a search request, the indices that match the currently-selected index pattern are searched. The current index pattern is shown below the search field. To change which indices you are searching, select a different index pattern.
+
+To select a different index pattern:
+
+. Click the *Settings* button image:images/SettingsButton.jpg[Settings 
+button] in the Discover toolbar.
+. Select the pattern you want to use from the Index Pattern list.
+
+For more information about index patterns, see <<settings-create-pattern, Creating an Index Pattern>>.
+
+[float]
+[[auto-refresh]]
+=== Automatically Refreshing the Page
+You can  configure a refresh interval to automatically refresh the Discover page with the latest
+index data. This periodically resubmits the search query.
+
+When a refresh interval is set, it is displayed to the left of the Time Filter in the menu bar.
+
+To set the refresh interval:
+
+. Click the *Time Filter* image:images/TimeFilter.jpg[Time 
+Filter] in the upper right corner of the menu bar.
+. Click the *Refresh Interval* tab.
+. Choose a refresh interval from the list.
+
+[float]
+[[field-filter]]
+=== Filtering by Field
+You can filter the search results to display only those documents that contain a particular value in a field. You can also create negative filters that exclude documents that contain the specified field value.
+
+You can add filters from the Fields list or from the Documents table. When you add a filter, it is displayed in the filter bar below the search query. From the filter bar, you can enable or disable a filter, invert the filter (change it from a positive filter to a negative filter and vice-versa), toggle the filter on or off, or remove it entirely.
+
+To add a filter from the Fields list:
+
+. Click the name of the field you want to filter on. This displays the top five values for that field. To the right of each value, there are two magnifying glass buttons--one for adding a regular (positive) filter, and 
+one for adding a negative filter. 
+. To add a positive filter, click the *Positive Filter* button image:images/PositiveFilter.jpg[Positive Filter Button]. This filters out documents that don't contain that value in the field.
+. To add a negative filter, click the *Negative Filter* button image:images/NegativeFilter.jpg[Negative Filter Button]. This excludes documents that contain that value in the field. 
+
+To add a filter from the Documents table:
+
+. Expand a document in the Documents table by clicking the *Expand* button image:images/ExpandButton.jpg[Expand Button] to the left of the document's entry in the first column (the first column is usually Time). To the right of each field name, there are two magnifying glass buttons--one for adding a regular (positive) filter, and one for adding a negative filter. 
+. To add a positive filter  based on the document's value in a field, click the *Positive Filter* button image:images/PositiveFilter.jpg[Positive Filter Button]. This filters out documents that don't contain the specified value in that field.
+. To add a negative filter based on the document's value in a field, click the *Negative Filter* button image:images/NegativeFilter.jpg[Negative Filter Button]. This excludes documents that contain the specified value in that field. 
+
+[float]
+[[document-data]]
+=== Viewing Document Data
+When you submit a search query, the 500 most recent documents that match the query are listed in the Documents table. You can configure the number of documents shown in the table by setting the `discover:sampleSize` property in <<advanced-options,Advanced Settings>>. By default, the table shows the localized version of the time field specified in the selected index pattern and the document `_source`. You can <<adding-columns, add fields to the Documents table>> from the Fields list. You can <<sorting, sort the listed documents>> by any indexed field that's included in the table.
+
+To view a document's field data:
+
+. Click the *Expand* button image:images/ExpandButton.jpg[Expand Button] to the left of the document's entry in the first column (the first column is usually Time). Kibana reads the document data from Elasticsearch and displays the document fields in a table. The table contains a row for each field that contains the name of the field, add filter buttons, and the field value.
+. To view the original JSON document (pretty-printed), click the *JSON* tab.
+. To view the document data as a separate page, click the link. You can bookmark and share this link to provide direct access to a particular document.
+. To collapse the document details, click the *Collapse* button image:images/CollapseButton.jpg[Collapse Button].
+
+[float]
+[[sorting]]
+==== Sorting the Document List
+You can sort the documents in the Documents table by the values in any indexed field. If a time field is configured for the selected index pattern, by default the documents are sorted in reverse chronological order.
+
+To change the sort order:
+
+* Click the name of the field you want to sort by. The fields you can use for sorting have a sort button to the right of the field name. Clicking the field name a second time reverses the sort order.
+
+[float]
+[[adding-columns]]
+==== Adding Field Columns to the Documents Table
+By default, the Documents table shows the localized version of the time field specified in the selected index pattern and the document `_source`. You can add fields to the table from the Fields list.
+
+To add field columns to the Documents table:
+
+. Mouse over a field in the Fields list and click its  *add* button image:images/AddFieldButton.jpg[Add Field Button].  
+. Repeat until you've added all the fields you want to display in the Documents table.
+
+The added field columns replace the `_source` column in the Documents table. The added fields are also
+listed in the *Selected Fields* section at the top of the field list. 
+
+To rearrange the field columns in the table, mouse over the header of the column you want to move and click the *Move* button.
+
+image:images/Discover-MoveColumn.jpg[Move Column]
+
+[float]
+[[removing-columns]]
+==== Removing Field Columns from the Documents Table
+To remove field columns from the Documents table:
+
+. Mouse over the field you want to remove in the *Selected Fields* section of the Fields list and click its *remove* button image:images/RemoveFieldButton.jpg[Remove Field Button].
+. Repeat until you've removed all the fields you want to drop from the Documents table.
+
+[float]
+[[viewing-field-stats]]
+=== Viewing Field Data Statistics
+From the field list, you can see how many documents in the Documents table contain a particular field, what the top 5 values are, and what percentage of documents contain each value. 
+
+To view field data statistics:
+
+* Click the name of a field in the Fields list. The field can be anywhere in the Fields list--Selected Fields,  Popular Fields, or the list of other fields. 
+
+image:images/Discover-FieldStats.jpg[Field Statistics]
+
+
+TIP: To create a visualization based on the field, click the *Visualize* button below the field statistics.
+
+

docs/discover.md

@@ -1,95 +0,0 @@
-## Discover
-
-Discover is your first step on the road to information enlightenment. From this interface you have access to every document, in every index that matches your configured index pattern. For the purpose of this documentation, we will assume you have selected a time field. If you didn't, ignore anything that mentions time.
-
-You should see a few things:
-
-- A list of documents
-- A list of fields
-- A time chart
-
-If you don't see any documents, it is possible that:
-
-- You don't **have** any documents
-- Your time range is too narrow
-
-By default Kibana shows the last 15 minutes of data. You might want to expand this by clicking the time in the top right of the screen and selecting a broader range.
-
-### Document list
-
-Once you see some documents, you can begin to explore Discover. In the document list, Kibana will show you the localized version of the time field you specified in your index pattern, as well as the `_source` of the Elasticsearch document.
-
-**Tip:** By default the table contains 500 of the most recent documents. You can increase the number of documents in the table from the advanced settings screen. See the [Setting section](#advanced) of the documentation.
-
-Click on the expand button to the left of the time. Kibana will read the fields from the document and present them in a table. The + and - buttons allow you to quickly filter for documents that share common traits with the one you're looking at. Click the JSON tab at the top of the table to see the full, pretty printed, original document.
-
-Click the expand button again to collapse the detailed view of the document.
-
-### Field list
-
-The field list has several powerful functions. The first being the ability to add columns to the document list. If no fields are selected `_source` will be automatically selected and shown in the table. Mouse over a field name and click the **add** button that appears. Now, instead of seeing `_source` in the document list, you have the extracted value of the selected field. In addition, the field name has moved up to the **Selected** section of the field list. Add a few more fields. Sweet!
-
-Now, instead of clicking the **add** button, click the name of the field itself. You will see a breakdown of the 5 most popular values for the field, as well as a count of how many records in the document list the field is present in.
-
-In addition, the Visualize button will pop you over to the **Visualize** application and run a more detailed aggregation on the field. For more information about visualization, see the [Visualize section](#visualize) of the docs.
-
-### Filters
-When you expand a document in the document list you will see two magnifying glasses next to indexed terms, one with a plus sign and one with a minus sign. If you click on the magnifying glass with the plus sign it will add a filter to the query for that term. If you click on the magnifying glass with the minus sign, it will add a negative filter (which will remove any documents containing the term). Both filters will appear in the filter bar underneath the **search bar**. When you hover over the filters in the filter bar you will see an option to toggle or remove them. There is also a link to remove all the filters.
-
-
-### Sorting
-
-You may have noticed that documents appear in reverse chronological order by default, meaning the newest documents are shown first. You can change this by clicking on the **Time** column header. In fact, any column can be sorted in this manner as long as it is indexed in Elasticsearch. Note that some fields are not indexed by default, such as `_id`, and that others may have indexing disabled in the Elasticsearch mapping. See the [Settings > Index Patterns](#indices) section of the docs for more details.
-
-You can also reorder columns by placing your mouse over the column header and clicking the left and right arrows that appear.
-
-### The Time Chart
-
-The time chart runs an Elasticsearch aggregation to show the time stamps associated with documents in the table. Hover over a bar in the chart to see the count of documents contained within it. Clicking on the bar will narrow the selected time range to match the time range of that bar. If you hover over the background of the chart (not a bar) the cursor will become a crosshair. In this mode you can click-and-drag to select a new time range.
-
-### Searching
-
-See the [Querying section](#querying) of the documentation.
-
-### Saving and reloading searches.
-
-Click the save button to save your search for later, or to reuse it in other screens, such as Visualize. Saved searches can be loaded via the folder icon.
-
-
-### Querying
-
-The search bar at the top allows Kibana to use Elasticsearch's support for Lucene Query String syntax. Let's say we're searching web server logs that have been parsed into a few fields.
-
-We can of course do free text search. Find requests that contain the number 200, in any field.
-
-```
-200
-```
-
-Or we can search in a specific field. Find 200 in the status field:
-
-```
-status:200
-```
-
-Find all from 400-499 status codes:
-
-```
-status:[400 TO 499]
-```
-
-Find status codes 400-499 with the extension php:
-
-```
-status:[400 TO 499] AND extension:PHP
-```
-
-Or HTML
-
-```
-status:[400 TO 499] AND (extension:php OR extension:html)
-```
-
-You can read more about the Lucene Query String syntax in the [Lucene documentation](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html).
-
-While Lucene query syntax is simple and very powerful, Kibana also supports the full Elasticsearch, JSON based, Query DSL. See the [Elasticsearch documentation](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax) for usage and examples.

docs/index.asciidoc

@@ -1,6 +1,7 @@
 [[kibana-guide]]
 = Kibana User Guide
 
+:ref: http://www.elasticsearch.org/guide/en/elasticsearch/reference/current
 
 include::introduction.asciidoc[]
 
@@ -16,7 +17,6 @@ include::dashboard.asciidoc[]
 
 include::settings.asciidoc[]
 
+include::production.asciidoc[]
 
-
-
-
+include::whats-new.asciidoc[]

docs/introduction.asciidoc

@@ -1,2 +1,58 @@
 [[introduction]]
-== Introduction
+== Introduction
+
+Kibana is an open source analytics and visualization platform designed to work 
+with Elasticsearch. You use Kibana to search, view, and interact with data 
+stored in Elasticsearch indices. You can easily perform advanced data analysis 
+and visualize your data in a variety of charts, tables, and maps.
+
+Kibana makes it easy to understand large volumes of data. Its simple,
+browser-based interface enables you to quickly create and share dynamic
+dashboards that display changes to Elasticsearch queries in real time.
+
+Setting up Kibana is a snap. You can install Kibana and start exploring your
+Elasticsearch indices in minutes--no code, no additional infrastructure required. 
+
+NOTE: This guide describes how to use Kibana 4. For information about what's new
+in Kibana 4, see <<whats-new>>. For information about Kibana 3, 
+see the http://www.elasticsearch.org/guide/en/kibana/current/index.html[Kibana 3 User Guide].
+
+[float]
+[[data-discovery]]
+=== Data Discovery and Visualization
+
+Let's take a look at how you might use Kibana to explore and visualize data. 
+We've indexed some data from Transport for London (TFL) that shows one week 
+of transit (Oyster) card usage.
+
+From Kibana's Discover page, we can submit search queries, filter the results, and 
+examine the data in the returned documents. For example, we can get all trips 
+completed by the Tube during the week by excluding incomplete trips and trips by bus:
+
+image:images/TFL-CompletedTrips.jpg[Discover]
+
+Right away, we can see the peaks for the morning and afternoon commute hours in the 
+histogram. By default, the Discover page also shows the first 500 entries that match the 
+search criteria. You can change the time filter, interact with the histogram to drill 
+down into the data, and view the details of particular documents. For more 
+information about exploring your data from the Discover page, see <<discover, Discover>>.
+
+You can construct visualizations of your search results from the Visualization page.
+Each visualization is associated with a search. For example, we can create a histogram
+that shows the weekly London commute traffic via the Tube using our previous search. 
+The Y-axis shows the number of trips. The X-axis shows
+the day and time. By adding a sub-aggregation, we can see the top 3 end stations during
+each hour:
+
+image:images/TFL-CommuteHistogram.jpg[Visualize]
+
+You can save and share visualizations and combine them into dashboards to make it easy
+to correlate related information. For example, we could create a dashboard
+that displays several visualizations of the TFL data:
+
+image:images/TFL-Dashboard.jpg[Dashboard]
+
+For more information about creating and sharing visualizations and dashboards, see the <<visualize, Visualize>> 
+and <<dashboard, Dashboard>> topics.
+
+

docs/production.asciidoc

@@ -0,0 +1,94 @@
+[[production]]
+== Using Kibana in a Production Environment
+When you set up Kibana in a production environment, rather than on your local
+machine, you need to consider:
+
+* Where you are going to run Kibana.
+* Whether you need to encrypt communications to and from Kibana.
+* If you need to control access to your data.
+
+=== Deployment Considerations
+How you deploy Kibana largely depends on your use case. If you are the only user,
+you can run Kibana on your local machine and configure it to point to whatever 
+Elasticsearch instance you want to interact with. Conversely, if you have a large 
+number of heavy Kibana users, you might need to load balance across multiple
+Kibana instances that are all connected to the same Elasticsearch instance.
+
+While Kibana isn't terribly resource intensive, we still recommend running Kibana 
+on its own node, rather than on one of your Elasticsearch nodes. 
+
+=== Configuring Kibana to Work with Shield
+If you are using Shield to authenticate Elasticsearch users, you need to provide
+Kibana with user credentials so it can access the `.kibana` index. The Kibana user
+needs permission to perform the following actions on the `.kibana` index:
+
+----
+'.kibana':
+      - indices:admin/create
+      - indices:admin/exists
+      - indices:admin/mapping/put
+      - indices:admin/mappings/fields/get
+      - indices:admin/refresh
+      - indices:admin/validate/query
+      - indices:data/read/get
+      - indices:data/read/mget
+      - indices:data/read/search
+      - indices:data/write/delete
+      - indices:data/write/index
+      - indices:data/write/update
+      - indices:admin/create
+----
+
+For more information about configuring access in Shield, 
+see https://www.elasticsearch.org/guide/en/shield/current/authorization.html[Authorization]
+in the Shield documentation.
+
+To configure credentials for Kibana, set the `kibana_elasticsearch_username` and
+`kibana_elasticsearch_password` properties in `kibana.yml`:
+
+----
+# If your Elasticsearch is protected with basic auth:
+kibana_elasticsearch_username: kibana4
+kibana_elasticsearch_password: kibana4
+----
+=== Enabling SSL
+Kibana supports SSL encryption for both client requests and the requests the Kibana server 
+sends to Elasticsearch.
+
+To encrypt communications between the browser and the Kibana server, you configure the `ssl_key_file `and `ssl_cert_file` properties in `kibana.yml`:
+
+----
+# SSL for outgoing requests from the Kibana Server (PEM formatted)
+ssl_key_file: /path/to/your/server.key
+ssl_cert_file: /path/to/your/server.crt
+----
+
+If you are using Shield or a proxy that provides an HTTPS endpoint for Elasticsearch, 
+you can configure Kibana to access Elasticsearch via HTTPS so communications between
+the Kibana server and Elasticsearch are encrypted. 
+
+To do this, you specify the HTTPS
+protocol when you configure the Elasticsearch URL in `kibana.yml`:
+
+----
+elasticsearch: "https://<your_elasticsearch_host>.com:9200"
+----
+
+If you are using a self-signed certificate for Elasticsearch, set the `ca` property in
+`kibana.yml` to specify the location of the PEM file. Setting the `ca` property lets you  leave the `verify_ssl` option enabled.
+----
+# If you need to provide a CA certificate for your Elasticsarech instance, put
+# the path of the pem file here.
+ca: /path/to/your/ca/cacert.pem
+----
+
+=== Controlling access
+You can use http://www.elasticsearch.org/overview/shield/[Elasticsearch Shield] 
+(Shield) to control what Elasticsearch data users can access through Kibana. 
+Shield provides index-level access control. If a user isn't authorized to run 
+the query that populates a Kibana visualization, the user just sees an empty 
+visualization. 
+
+To configure access to Kibana using Shield, you create one or more Shield roles 
+for Kibana using the `kibana4` default role as a starting point. For more 
+information, see http://www.elasticsearch.org/guide/en/shield/current/_shield_with_kibana_4.html[Using Shield with Kibana 4].

docs/quick_start.md

@@ -1,13 +0,0 @@
-## Quick Start
-
-You're up and running! Fantastic! Kibana is now running on port 5601, so point your browser at http://YOURDOMAIN.com:5601.
-
-The first screen you arrive at will ask you to configure an **index pattern**. An index pattern describes to Kibana how to access your data. We make the guess that you're working with log data, and we hope (because it's awesome) that you're working with Logstash. By default, we fill in `logstash-*` as your index pattern, thus the only thing you need to do is select which field contains the timestamp you'd like to use. Kibana reads your Elasticsearch mapping to find your time fields - select one from the list and hit *Create*.
-
-**Tip:** there's an optimization in the way of the *Use event times to create index names* option. Since Logstash creates an index every day, Kibana uses that fact to only search indices that could possibly contain data in your selected time range.
-
-Congratulations, you have an index pattern! You should now be looking at a paginated list of the fields in your index or indices, as well as some informative data about them. Kibana has automatically set this new index pattern as your default index pattern. If you'd like to know more about index patterns, pop into to the [Settings](#settings) section of the documentation.
-
-**Did you know:** Both *indices* and *indexes* are acceptable plural forms of the word *index*. Knowledge is power.
-
-Now that you've configured an index pattern, you're ready to hop over to the [Discover](#discover) screen and try out a few searches. Click on **Discover** in the navigation bar at the top of the screen.

docs/settings.asciidoc

@@ -1,2 +1,340 @@
 [[settings]]
-== Configuring Kibana
+== 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.
+
+[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.elasticsearch.org/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*. 
++
+TIP: If you are just getting started with scripted fields, you can click 
+*create a few examples from your date fields* to add some scripted fields
+you can use as a starting point.
+
+. 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.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-scripting.html[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.
+
+[float]
+[[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.
+
+=== Managing Saved Searches, Visualizations, and Dashboards ===
+You can view, edit, and delete saved searches, visualizations,
+and dashboards from *Settings > Objects*. 
+
+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.
+
+=== 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.
+
+|===

docs/settings.md

@@ -1,43 +0,0 @@
-## Settings
-
-The settings application is broken up into three pages: Indices, Advanced, and Object.
-
-### Indices
-
-The Indices page manages Index Patterns. Before you can do anything in Kibana you will need to create an Index Pattern to use in other parts of the application. Index Patterns represent one or more indices in Elasticsearch and track associated meta-data, like field types and pattern interval.
-
-#### Creating an Index Pattern
-
-If this is your first time in Kibana you'll be prompted to create your first index pattern. For more information on index pattern creation see the **Getting Started** section of the documentation.
-
-### Advanced
-
-Please, **use caution** on this page, because the advanced editor will let you break things.
-
-The Advanced page allows modification of individual configuration parameters. Each of these parameters can be tweaked to customize the entire Kibana installation. This means that your changes will apply to all users. This could prevent the application from loading if used incorrectly.
-
-#### Edit
-
-Clicking on the edit button for any line will cause the *Value* column on that line to become an input, allowing you change the value.
-
-Click the *Save* button to save your changes.
-
-#### Reset
-
-Clicking on the *Reset* button will undo any changes you made and restore the value back to its default.
-
-### Objects
-
-Please, **use caution** on this page. No support is available for changes made here.
-
-The Objects page manages all of the objects created by Kibana (except Index Patterns which are handled by the Indices page).  Most apps give you all the tools needed to manage objects they create, but if/when they fall short, you can come here to tweak the specifics.
-
-#### View
-
-Clicking on the *View* action loads that item in the associated applications. Refer to the documentation for the associated applications if you need help using them.
-
-#### Edit
-
-Clicking *Edit* will allow you to change the title, description and other settings of the saved object. You can also edit the schema of the stored object.
-
-*Note:* this operation is for advanced users only - making changes here can break large portions of the application.

docs/setup.asciidoc

@@ -1,2 +1,52 @@
 [[setup]]
-== Getting Kibana Up and Running
+== Getting Kibana Up and Running
+You can set up Kibana and start exploring your Elasticsearch indices in minutes.
+All you need is:
+
+* Elasticsearch 1.4.4 or later
+* A modern web browser - http://www.elasticsearch.com/support/matrix[Supported Browsers].
+* Information about your Elasticsearch installation: 
+** URL of the Elasticsearch instance you want to connect to.
+** Which Elasticsearch indices you want to search. 
+
+NOTE: If your Elasticsearch installation is protected by http://www.elasticsearch.org/overview/shield/[Shield] see the http://www.elasticsearch.org/guide/en/shield/current/_shield_with_kibana_4.html#_from_the_kibana_4_server_to_elasticsearch[Shield documentation] for additional setup instructions.
+
+[float]
+[[install]]
+=== Install and Start Kibana
+To get Kibana up and running:
+
+. Download the http://www.elasticsearch.org/overview/kibana/installation/[Kibana 4 binary package] for your platform.
+. Extract the `.zip` or `tar.gz` archive file.
+. Run Kibana from the install directory: `bin/kibana` (Linux/MacOSX) or `bin\kibana.bat` (Windows).
+
+That's it! Kibana is now running on port 5601. 
+
+[float]
+[[connect]]
+=== Connect Kibana with Elasticsearch 	
+Before you can start using Kibana, you need to tell it which Elasticsearch indices you want to explore. The first time you access Kibana, you are prompted to define an _index pattern_ that matches the name of one or more of your indices. That's it. That's all you need to configure to start using Kibana. You can add index patterns at any time from the <<settings-create-pattern,Settings tab>>.
+
+TIP: By default, Kibana connects to the Elasticsearch instance running on `localhost`. To connect to a different Elasticsearch instance, modify the Elasticsearch URL in the `kibana.yml` configuration file and restart Kibana. For information about using Kibana with your production nodes, see <<production>>.
+
+To configure the Elasticsearch indices you want to access with Kibana:
+
+. Point your browser at port 5601 to access the Kibana UI. For example, `localhost:5601` or `http://YOURDOMAIN.com:5601`.
++
+image:images/Start-Page.jpg[Kibana start page]
++
+. 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 data being fed into Elasticsearch by Logstash. If that's the case, you can use the default `logstash-*` as your index pattern. The asterisk (*) matches zero or more characters in an index's name. If your Elasticsearch indices follow some other naming convention, enter an appropriate pattern.  The "pattern" can also simply be the name of a single index.
+. Select the index field that contains the timestamp that you want to use to perform time-based comparisons. Kibana reads the index mapping to list all of the fields that contain a timestamp. If your index doesn't have time-based data, disable the *Index contains time-based events* option. 
+. 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 improves search performance by enabling Kibana to search only those indices that could 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. This first pattern is automatically configured as the default. When you have more than one index pattern, you can designate which one to use as the default from *Settings > Indices*. 
+
+Voila! Kibana is now connected to your Elasticsearch data. Kibana displays a read-only list of fields configured for the matching index.
+
+[float]
+[[explore]]
+=== Start Exploring your Data!
+You're ready to dive in to your data:
+
+* Search and browse your data interactively from the <<discover,Discover>> page. 
+* Chart and map your data from the <<visualize, Visualize>> page. 
+* Create and view custom dashboards from the <<dashboard, Dashboard>> page.

docs/visualize.asciidoc

@@ -1,2 +1,134 @@
 [[visualize]]
-== Visualizing your Data
+== Visualize
+
+You can use the _Visualize_ page to design data visualizations. You can save these visualizations, use
+them individually, or combine visualizations into a _dashboard_. A visualization can be based on one of the following 
+data source types:
+
+* A new interactive search
+* A saved search
+* An existing saved visualization
+
+Visualizations rely on the {ref}/search-aggregations.html[aggregation] feature introduced in Elasticsearch 1.0. 
+
+[float]
+[[createvis]]
+=== Creating a New Visualization
+
+To start the New Visualization wizard, click on the *Visualize* tab at the top left of the page. If you are already 
+creating a visualization, you can click the *New Visualization* button image:images/K4NewDocument.png[New Document 
+button] in the toolbar to the right of the search bar. The wizard guides you through the following steps:
+
+[float]
+[[newvis01]]
+==== Step 1: Choose the Visualization Type
+
+The New Visualization wizard starts with the following page:
+
+image:images/NewViz01.png[]
+
+You can also load a saved visualization that you created earlier. The saved visualization selector includes a text 
+field to filter by visualization name and a link to the Object Editor, accessible through *Settings > Edit Saved 
+Objects*, to manage your saved visualizations.
+
+If your new visualization is a Markdown widget, selecting that type takes you to a text entry field where you enter the 
+text to display in the widget. For all other types of visualization, selecting the type takes you to data source 
+selection.
+
+[float]
+[[newvis02]]
+==== Step 2: Choose a Data Source
+
+You can choose a new or saved search to serve as the data source for your visualization. Searches are associated with
+an index or a set of indexes. When you select _new search_ on a system with multiple indices configured, select an 
+index pattern from the drop-down to bring up the visualization editor. 
+
+// How is this drop-down populated? Is it just a list of all indices in the cluster? Can I configure the contents?
+
+When you create a visualization from a saved search and save the visualization, the search is tied to the visualization.
+When you make changes to the search that is linked to the visualization, the visualization updates automatically.
+
+[float]
+[[visualization-editor]]
+==== Step 3: The Visualization Editor
+
+The visualization editor enables you to configure and edit visualizations. The visualization editor has the following 
+main elements:
+
+1. <<toolbar-panel,Toolbar>>
+2. <<aggregation-builder,Aggregation Builder>>
+3. <<preview-canvas,Preview Canvas>>
+
+image:images/VizEditor.png[]
+
+[float]
+[[toolbar-panel]]
+===== Toolbar
+
+The toolbar has a search field for interactive data searches, as well as controls to manage saving and loading
+visualizations. For visualizations based on saved searches, the search bar is grayed out. To edit the search, replacing 
+the saved search with the edited version, double-click the search field.
+
+// Why does it behave this way? I'd like to be able to say 'for saved searches interactive searches are disabled
+// because $REASONS'.
+
+The toolbar at the right of the search box has buttons for creating new visualizations, saving the current 
+visualization, loading an existing visualization, sharing or embedding the visualization, and refreshing the data for 
+the current visualization.
+
+[float]
+[[aggregation-builder]]
+===== Aggregation Builder
+
+Use the aggregation builder on the left of the page to configure the 
+{ref}/search-aggregations.html#\_metrics_aggregations[metric] and 
+{ref}/search-aggregations.html#\_bucket_aggregations[bucket] aggregations used in your visualization. Buckets are 
+analogous to SQL `GROUP BY` statements. For more information on aggregations, see the main
+{ref}/search-aggregations.html[Elasticsearch aggregations reference].
+
+In bar or line chart visualizations, use _metrics_ for the y-axis and _buckets_ are used for the x-axis, segment bar 
+colors, and row/column splits. For pie charts, use the metric for the slice size and the bucket for the number of 
+slices.
+
+// "Other visualizations may use these in new and different ways." < Such as? Would it be useful to add an appendix
+// on advanced visualizations or a cookbook of neat nonintuitive vis tricks?
+
+Choose the metric aggregation for your visualization's Y axis, such as 
+{ref}/search-aggregations-metrics-valuecount-aggregation.html[count], 
+{ref}/search-aggregations-metrics-avg-aggregation.html[average], 
+{ref}/search-aggregations-metrics-sum-aggregation.html[sum], 
+{ref}/search-aggregations-metrics-min-aggregation.html[min], 
+{ref}/search-aggregations-metrics-max-aggregation.html[max], or 
+{ref}/search-aggregations-metrics-cardinality-aggregation.html[cardinality] 
+(unique count). Use bucket aggregations for the visualization's X axis, color slices, and row/column splits. Common 
+bucket aggregations include date histogram, range, terms, filters, and significant terms.
+
+You can set the order in which buckets execute. In Elasticsearch, the first aggregation determines the data set 
+for any subsequent aggregations. The following example involves a date bar chart of Web page hits for the top 5 file 
+extensions.
+
+To use the same extension across all hits, set this order:
+
+1.  *Color:* Terms aggregation of extensions
+2.  *X-Axis:* Date bar chart of `@timestamp`
+
+Elasticsearch collects the records for the top 5 extensions, then creates a date bar chart for each extension.
+
+To chart the top 5 extensions for each hour, use the following order:
+
+1.  *X-Axis:* Date bar chart of `@timestamp` (with 1 hour interval)
+2.  *Color:* Terms aggregation of extensions
+
+For these requests, Elasticsearch creates a date bar chart from all the records, then groups the top five extensions 
+inside each bucket, which in this example is a one-hour interval.
+
+NOTE: Remember, each subsequent bucket slices the data from the previous bucket.
+
+To render the visualization on the _preview canvas_, click the *Apply* button at the bottom of the aggregation builder.
+
+[float]
+[[preview-canvas]]
+===== Preview Canvas
+
+The preview canvas displays a preview of the visualization you've defined in the aggregation builder. To refresh the 
+visualization preview, clicking the *Refresh* button image:images/K4Refresh.png[Refresh button] on the toolbar.

docs/visualize.md

@@ -1,55 +0,0 @@
-## Visualize
-
-The **Visualize** app is used to design and create saved visualizations that can be used on their own, or added to a dashboard. The data source for a visualization can be based on three types: a new interactive search, a saved search, or an existing saved visualization. Visualizations are based on the aggregation feature introduced in Elasticsearch 1.x. Aggregations are highly performant, but may require significant memory from Elasticsearch.
-
-### Getting Started
-
-To create a new visualization either click on the visualize tab at the top of the screen or the new document button in the toolbar panel to the right of the search bar. This will start the *New Visualization Wizard*.
-
-- **Step 1:** Choose the data source for the new visualization - You have 3 options here:
-  - *"From a new search"* : Pick an index pattern and search as you create your visualization
-  - *"From a saved search"* : Pick a Saved Search and create a visualization from it. If you later save the visualization it will be tied to this search. This means if you edit the search later, say in Discover, any visualization that uses it will also be updated automatically.
-  - *"From an existing visualization"* Pick an existing visualization and make changes to it.
-- **Step 2:** Choose a visualization type from the list of currently available visualizations.
-
-Once the visualization wizard is complete you will be presented with the *visualization editor*.
-
-### Visualization Editor
-
-The visualization editor is where you will configure and edit your visualization. There are three parts to the visualization editor:
-
-1. [Toolbar Panel](#toolbar-panel)
-1. [Aggregation Builder](#aggregation-builder)
-1. [Preview Canvas](#preview-canvas)
-
-#### Toolbar Panel
-
-The toolbar panel is used for interactive searching of data as well as saving and loading visualizations. When you choose *New search* in the wizard, you will be presented with a search bar where you can add your search terms. For visualizations based on saved searches, the search bar will be disabled, but you can double click the grayed out saved search link to convert it to an interactive search.
-
-To the right of the search box there are a row of icons for creating new visualizations, saving the current visualization, loading an existing visualization, sharing or embedding the visualization, and refreshing the data for the current visualization.
-
-#### Aggregation Builder
-
-The aggregation builder on the left of the screen is used for configuring the [metric](http://www.elasticsearch.org/guide/en/elasticsearch/reference/1.x/search-aggregations.html#_metrics_aggregations) and [bucket](http://www.elasticsearch.org/guide/en/elasticsearch/reference/1.x/search-aggregations.html#_bucket_aggregations) aggregations used to create a visualization. (If you are coming from the SQL world, buckets are similar to group-bys. Check out the [Elasticsearch docs](http://www.elasticsearch.org/guide/en/elasticsearch/reference/1.x/search-aggregations.html) for more info) For a bar chart or line chart, the *metric* is used for the y-axis and the *buckets* are used for the x-axis, segment bar colors, and row/column splits. For pie charts the "metric" is used for the size of the slice and the *bucket* is used for the number of slices. Other visualizations may use these in new and different ways.
-
-For the remainder of this documentation we are going to use the bar chart as our example when discussing the features of the aggregation panel. The same concepts apply to the other visualizations but the bar chart is the workhorse of the visualization world.
-
-The aggregation builder allows you to choose which *metric* aggregation you would like to use for the x-axis. Examples include: count, average, sum, min, max, and unique count (cardinality). The *bucket* aggregations are used for the x-axis, color slices, and row/columns splits.  Example *bucket* aggregations include date histogram, range, terms, filters, and significant terms.
-
-You can also change the execution order of the buckets. In Elasticsearch the first aggregation determines the data set for the subsequent aggregations. For example, lets say you want to create a date bar chart of the hits for top 5 extensions.  If you want to have the same extension across all of the hits then you will need to set the order as follows:
-
-1. **Color:** Terms aggregation of extensions
-1. **X-Axis:** Date bar chart of `@timestamp`
-
-Inside Elasticsearch, it collects the records for the top 5 extensions then creates a date bar chart for each of them. Let say you now want the top 5 extensions for each hour then you would use the following order:
-
-1. **X-Axis:** Date bar chart of `@timestamp` (with 1 hour interval)
-1. **Color:** Terms aggregation of extensions
-
-For these requests, Elasticsearch will create a date bar chart from all the records then group the top five extensions inside each bucket (or hour since we specified an hour interval). Just remember each subsequent bucket slices the data from the previous bucket.
-
-#### Preview Canvas
-
-The preview canvas will render the visualization once you click the apply button below the buckets in the aggregation builder.
-
-You can refresh this preview by clicking the refresh button on the far-right of the toolbar.

docs/whats-new.asciidoc

@@ -0,0 +1,58 @@
+[[whats-new]]
+== What's New in Kibana 4
+
+Kibana 4 provides dozens of new features that enable you to compose questions, 
+get answers, and solve problems like never before. It has a brand-new look and 
+feel and improved workflows for discovering and visualizing your data and
+building and sharing dashboards. 
+
+[float]
+[[key-features]]
+=== Key Features
+* New data search and discovery interface 
+* Unified visualization builder for your favorite visualizations and some brand
+new ones:
+** Area Chart
+** Data Table
+** Line Chart
+** Markdown Text Widget
+** Pie Chart (including "doughnut" charts)
+** Raw Document Widget
+** Single Metric Widget
+** Tile Map 
+** Vertical Bar Chart
+* Drag and drop dashboard builder that enables you to quickly add, rearrange, 
+resize, and remove visualizations
+* Advanced aggregation-based analytics capabilities, including support for:
+** Unique counts (cardinality)
+** Non-date histograms
+** Ranges
+** Significant terms
+** Percentiles
+* Expressions-based scripted fields enable you to perform ad-hoc analysis by 
+performing computations on the fly
+
+[float]
+[[improvements]]
+=== Improvements
+* Ability to save searches and visualizations enables you to link 
+searches to visualizations and add the same visualization to multiple dashboards
+* Visualizations support an unlimited number of nested aggregations so you can 
+display new types of visualizations, such as "doughnut" charts
+* New URL format eliminates the need for templated and scripted dashboards
+* Better mobile experience
+* Faster dashboard loading due to a reduction in the number HTTP calls needed to load the page
+* SSL encryption for client requests as well as requests to and from Elasticsearch
+* Search result highlighting
+* Easy to access and export the data behind any visualization: 
+** View in a table or view as JSON
+** Export in CSV format
+** See the Elasticsearch request and response
+* Share and embed individual visualizations as well as dashboards
+
+[float]
+[[nuts-bolts]]
+=== Nuts and Bolts
+* Ships with its own webserver and uses Node.js on the backend--installation 
+binaries are provided for Linux, Windows, and Mac OS
+* Uses the D3 framework to display visualizations