Fix broken image link
[platform-oam.git] / docs / user-guide.rst
1 .. ===============LICENSE_START=======================================================
2 .. Acumos
3 .. ===================================================================================
4 .. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
5 .. ===================================================================================
6 .. This Acumos documentation file is distributed by AT&T and Tech Mahindra
7 .. under the Creative Commons Attribution 4.0 International License (the "License");
8 .. you may not use this file except in compliance with the License.
9 .. You may obtain a copy of the License at
10 ..  
11 ..      http://creativecommons.org/licenses/by/4.0
12 ..  
13 .. This file is distributed on an "AS IS" BASIS,
14 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 .. See the License for the specific language governing permissions and
16 .. limitations under the License.
17 .. ===============LICENSE_END=========================================================
18
19 =====================================================================
20 Platform Operations, Administration, and Management (OA&M) User Guide
21 =====================================================================
22
23 Operations, Administration and Management/Maintenance are the processes, activities, tools, and standards involved with operating, administering, managing and maintaining any system. 
24
25 Acumos Elastic Stack for Log Analytics
26 ======================================
27 One of the functions of (OA&M) for the Acumos platform is to collect and correlate log files from the other platform components in order to support debugging, metrics, alarms, etc. for development and operations purposes. These metrics can reveal issues and potential risks so administrators can take corrective action. To this end, the OA&M component has defined a logging standard to be used by all of those components in order to support correlation. OA&M uses the `Elasticsearch, Logstack, Kibana stack <https://www.elastic.co/elk-stack>`_  and `Filebeat <https://www.elastic.co/products/beats/filebeat>`_ to collect and centralize logs that are generated via the microservices.  This guide that describes how to use the Acumos Elastic Stack (formerly known as the ELK Stack).
28
29 Target Users
30 ------------
31 Acumos Platform super admins
32
33
34 Assumptions
35 -----------
36 All the modules are following the Acumos Logging Guidelines
37
38
39 Elastic Stack Architecture
40 --------------------------
41
42 .. image:: images/elk_stack.png
43
44 Elastic Stack Component Versions
45 --------------------------------
46
47 - elasticsearch 5.5.1
48 - kibana:5.5.1
49 - logstash:5.5.1
50 - filebeat:6.0.1
51
52 Elastic Stack Setup
53 -------------------
54 Elastic Stack installation is automated with Docker Compose. Installation is done on a server separate from where Acumos has been installed.
55
56 Prerequisites
57 -------------
58 `Docker <https://docs.docker.com/>`_ and `Docker Compose <https://docs.docker.com/compose/install/>`_ installed
59
60
61 Steps
62 -----
63
64 1. Clone the platform-oam repository 
65
66 .. code:: bash
67
68    $ git clone https://gerrit.acumos.org/r/platform-oam
69
70
71 2. The docker-compose.yaml file as well as component directories are located in the elk-stack directory. Each component has a Dockerfile. You need to build the docker-compose file if you are using it for the first time or if you have made changed any Dockerfile or the contents of its build directory.
72
73 .. code:: bash
74
75    $ docker-compose build
76
77
78 3. Builds, (re)creates, starts, and attaches to containers for Elasticsearch, Logstash, Kibana
79
80 .. code:: bash
81
82    $ docker-compose up -d
83
84
85 4. To stop the running containers without removing them
86
87 .. code:: bash
88
89    $ docker-compose stop
90
91
92 Filebeat setup steps:
93 ---------------------
94 Filebeat should be installed as an agent on the servers on which Acumos is running.
95 Add the configuration below to the docker-compose where the Acumos is installed.  
96
97 .. code:: yaml
98
99    filebeat:
100        container_name: filebeat
101        image: <filebeat-image-name>
102        volumes:
103          - <volume-name>:/filebeat-logs
104        environment:
105          - LOGSTASH_HOST=<elk-stack-host-hostname>
106                  - LOGSTASH_PORT=5000
107
108
109 Adding a New Log
110 ----------------
111 Filebeat docker is a customized image that depends on filebeat.yml, a configuration layer. 
112 For adding new log under prospectors of filebeat.yml, need to add log location path as it is in <volume-name>.
113
114 .. code:: yaml
115
116    filebeat.prospectors:
117      - input_type: log
118        paths:
119          - /filebeat-logs/portal-be/*.log
120
121
122 Elastic Stack UI Tour
123 ---------------------
124 According to the `Kibana website <https://www.elastic.co/guide/en/kibana/current/introduction.html>`_, 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.
125 Kibana makes it easy to understand large volumes of data. Its simple, browser-based interface enables you to quickly create queries in real time.
126
127 For more details visit `Kibana User Guide <https://www.elastic.co/guide/en/kibana/5.5/index.html/>`_.
128
129 Site admins have access to Elastic Stack's Kibana Dashboard. Login to the dashboard:
130
131                 .. image:: images/acumos_Sign_In.JPG
132
133 Go to SITE ADMIN -> Monitoring and click on **Login to Dashboard** in the USERS section
134
135                 .. image:: images/acumos_site_admin.jpg
136
137
138 Redirects to Loading Kibana visualization platform
139
140                 .. image:: images/loadingKibana.jpg
141
142
143
144 Acumos Kibana Dashboard Creation
145 --------------------------------
146
147 The Kibana dashboard is used to view all the saved Visualizations.
148
149 To create dashboard click on Create a dashboard or On plus sign show in the search bar.
150
151 .. image:: images/kibana_dashboard_1.jpg
152
153 click on Visit the Visualize app
154
155 .. image:: images/kibana_dashboard_2.jpg
156
157 click on "Create a visualization" or "+"(i.e Plus sign) show in the search bar.
158
159 .. image:: images/kibana_visualization_1.jpg
160
161 Select visualization type. For example click on "Pie".
162
163 .. image:: images/kibana_visualization_2.jpg
164
165 Choose search source as ``logstash-*``
166
167 .. image:: images/kibana_visualization_3.jpg
168
169 Click on Split Slices
170
171 .. image:: images/kibana_visualization_4.jpg
172
173 Select Aggregation as "Terms" and Field as "userAgent.keyword", Click on "Apply changes"
174
175 Note: Elasticsearch aggregations are to extract and process your data.
176
177 .. image:: images/kibana_visualization_5.jpg
178
179 To save this chart click on "Save", Enter a name appropriate name. For example "Acumos User Login".
180  
181 .. image:: images/kibana_visualization_6.jpg
182
183 Click on "Dashboard", On the below screen visualization namely "Acumos User Login"  is appearing. For select this visualization click on "+" (i.e. plus sign) show in the search bar.
184
185 .. image:: images/kibana_dashboard_3.jpg
186
187 Click on "Add" button, to add the visualization.
188
189 .. image:: images/kibana_dashboard_4.jpg
190
191 Select the visualization for example here we have visualization namely "Acumos User Login".
192
193 .. image:: images/kibana_dashboard_6.jpg
194
195 Click on "Save" button. Enter a name appropriate name. For example "Acumos User Login".
196
197 .. image:: images/kibana_dashboard_7.jpg
198
199 Click on "Dashboard", On the below screen created dashboard can be viewed namely "Acumos User Login".
200
201 .. image:: images/kibana_dashboard_8.jpg
202
203