From 732ef0e7154d72434f767d5eed09f14ec5e4b5a2 Mon Sep 17 00:00:00 2001
From: akwasniewska <alicja.kwasniewska@intel.com>
Date: Thu, 14 Apr 2016 13:33:44 +0200
Subject: [PATCH] Add Kibana quick start guide
Includes basic information about how to search, visualize and analyse logs,
create a Dashboard and export/import created items.
Closes-Bug: #1570544
Change-Id: I70ce5d28a6bb719a94570d23e85d5ba4aa0b114e
---
doc/index.rst | 1 +
doc/kibana-guide.rst | 93 ++++++++++++++++++++++++++++++++++++++++++++
doc/quickstart.rst | 5 ++-
3 files changed, 97 insertions(+), 2 deletions(-)
create mode 100644 doc/kibana-guide.rst
diff --git a/doc/index.rst b/doc/index.rst
index aeb1a13364..7bb7705491 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -54,3 +54,4 @@ Kolla Services
ironic-guide
manila-guide
swift-guide
+ kibana-guide
diff --git a/doc/kibana-guide.rst b/doc/kibana-guide.rst
new file mode 100644
index 0000000000..40071ffedc
--- /dev/null
+++ b/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.
+
diff --git a/doc/quickstart.rst b/doc/quickstart.rst
index e9ef4c7acf..20a4f6e3c9 100644
--- a/doc/quickstart.rst
+++ b/doc/quickstart.rst
@@ -650,11 +650,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``.
--
GitLab