Merge "Add Kibana quick start guide"

doc/index.rst

@@ -55,3 +55,4 @@ Kolla Services
    ironic-guide
    manila-guide
    swift-guide
+   kibana-guide

doc/kibana-guide.rst

@@ -0,0 +1,93 @@
+Kibana in Kolla
+===============
+
+Default index pattern
+---------------------
+
+After successful Kibana deployment, it can be accessed on
+<kolla_internal_vip_address>:<kibana_server_port>
+or <kolla_external_vip_address>:<kibana_server_port> in any web
+browser after authenticating with ``<kibana_user>`` and ``<kibana_password>``.
+
+The values ``<kolla_internal_vip_address>``, ``<kolla_external_vip_address>``,
+``<kibana_server_port>`` and ``<kibana_user>`` can be found in
+``<kolla_install_path>/kolla/ansible/group_vars/all.yml`` or if the default
+values are overridden, in ``/etc/kolla/globals.yml``. The value
+``<kibana_password>`` can be found in ``/etc/kolla/passwords.yml``.
+By default kibana_server_port is set to 5601.
+
+When Kibana is opened for the first time, it requires creating a default index
+pattern. To view, analyse and search logs, at least one index pattern has to
+be created. To match indices stored in ElasticSearch, we suggest to use
+following configuration:
+
+- Index contains time-based events - check
+- Use event times to create index names [DEPRECATED] - not checked
+- Index name or pattern - log-*
+- Do not expand index pattern when searching (Not recommended) - not checked
+- Time-field name - Timestamp
+
+After setting parameters, one can create an index with 'Create' button.
+Note: This step is necessary until the default Kibana dashboard is implemented
+in Kolla.
+
+Search logs - Discover tab
+--------------------------
+
+Logs search is available under Discover tab. In the menu on the left side,
+one can choose any field that will be included in a new search. To do this,
+add button has to be pressed. This button appears after pointing any field
+from available ones. After adding a specific field, it is marked as selected
+field in the menu on the left. Search panel is updated automatically. To
+remove field from a current search, remove button has to be pressed. This
+button appears after pointing any field from selected ones.
+Current search can be saved by using 'Save search' option in the menu on the
+right.
+
+Visualize data - Visualize tab
+------------------------------
+
+In the visualization tab a wide range of charts is available. If any
+visualization has not been saved yet, after choosing this tab 'Create a new
+visualization' panel is opened. If a visualization has already been saved,
+after choosing this tab, lately modified visualization is opened. In this
+case, one can create a new visualization by choosing 'add visualization'
+option in the menu on the right. In order to create new visualization, one
+of the available options has to be chosen (pie chart, area chart). Each
+visualization can be created from a saved or a new search. After choosing
+any kind of search, a design panel is opened. In this panel, a chart can be
+generated and previewed. In the menu on the left, metrics for a chart can
+be chosen. The chart can be generated by pressing a green arrow on the top
+of the left-side menu.
+
+NOTE: After creating a visualization, it can be saved by choosing 'save
+visualization' option in the menu on the right. If it is not saved, it will
+be lost after leaving a page or creating another visualization.
+
+Organize visualizations and searches - Dashboard tab
+----------------------------------------------------
+
+In the Dashboard tab all of saved visualizations and searches can be
+organized in one Dashboard. To add visualization or search, one can choose
+'add visualization' option in the menu on the right and then choose an item
+from all saved ones. The order and size of elements can be changed directly
+in this place by moving them or resizing. The color of charts can also be
+changed by checking a colorful dots on the legend near each visualization.
+
+NOTE: After creating a dashboard, it can be saved by choosing 'save dashboard'
+option in the menu on the right. If it is not saved, it will be lost after
+leaving a page or creating another dashboard.
+
+If a Dashboard has already been saved, it can be opened by choosing 'open
+dashboard' option in the menu on the right.
+
+Exporting and importing created items - Settings tab
+------------------------------------------------------------
+
+Once visualizations, searches or dashboards are created, they can be exported
+to a json format by choosing Settings tab and then Objects tab. Each of the
+item can be exported separately by selecting it in the menu. All of the items
+can also be exported at once by choosing 'export everything' option.
+In the same tab (Settings - Objects) one can also import saved items by
+choosing 'import' option.
+

doc/quickstart.rst

@@ -651,11 +651,12 @@ using Kibana, go to:
 ::
 
     http://<kolla_internal_vip_address>:<kibana_server_port>
+    or http://<kolla_external_vip_address>:<kibana_server_port>
 
 and authenticate using ``<kibana_user>`` and ``<kibana_password>``.
 
-The values of ``<kolla_internal_vip_address>``, ``<kibana_server_port>`` and
-``<kibana_user>`` can be found in
+The values ``<kolla_internal_vip_address>``, ``<kolla_external_vip_address>``
+``<kibana_server_port>`` and ``<kibana_user>`` can be found in
 ``<kolla_install_path>/kolla/ansible/group_vars/all.yml`` or if the default
 values are overridden, in ``/etc/kolla/globals.yml``. The value of
 ``<kibana_password>`` can be found in ``/etc/kolla/passwords.yml``.