e53e2401799f12ce2ffdce1116879d640fa1a9a4
[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 - metricbeat:6.2.4
52
53 Elastic Stack Setup
54 -------------------
55 Elastic Stack installation is automated with Docker Compose. Installation is done on a server separate from where Acumos has been installed.
56
57 Prerequisites
58 -------------
59 `Docker <https://docs.docker.com/>`_ and `Docker Compose <https://docs.docker.com/compose/install/>`_ installed
60
61
62 Steps
63 -----
64
65 1. Clone the platform-oam repository 
66
67 .. code:: bash
68
69    $ git clone https://gerrit.acumos.org/r/platform-oam
70
71 2. Create docker volume namely acumos-esdata
72    
73 .. code:: bash
74
75    $ docker volume create acumos-esdata
76
77
78 3. 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.
79
80 .. code:: bash
81
82    $ ./docker-compose-elk.sh build
83
84
85 4. Builds, (re)creates, starts, and attaches to containers for Elasticsearch, Logstash, Kibana
86
87 .. code:: bash
88
89    $ ./docker-compose-elk.sh up -d
90
91
92 5. To stop the running containers without removing them
93
94 .. code:: bash
95
96    $ ./docker-compose-elk.sh stop
97
98
99 Filebeat setup steps:
100 ---------------------
101 Filebeat should be installed as an agent on the servers on which Acumos is running.
102 Add the configuration below to the docker-compose where the Acumos is installed.  
103
104 .. code:: yaml
105
106    filebeat:
107        container_name: filebeat
108        image: <filebeat-image-name>
109        volumes:
110          - <volume-name>:/filebeat-logs
111        environment:
112          - LOGSTASH_HOST=<elk-stack-host-hostname>
113                  - LOGSTASH_PORT=5000
114
115
116 Metricbeat setup steps:
117 -----------------------
118 Metricbeat should be installed as an agent on the servers on which Acumos is running.
119 Add the configuration below to the docker-compose where the Acumos is installed. 
120
121 .. code:: yaml
122
123    metricbeat:
124        image: <metricbeat-image-name>
125        network_mode: host
126        volumes:
127        #Mount the docker, filesystem to enable Metricbeat to monitor the host rather than the Metricbeat container.
128          - /proc:/hostfs/proc:ro
129          - /sys/fs/cgroup:/hostfs/sys/fs/cgroup:ro
130          - /:/hostfs:ro
131          - /var/run:/var/run:rw
132          - /var/run/docker.sock:/var/run/docker.sock
133        command: metricbeat -e -strict.perms=false -system.hostfs=/hostfs
134        environment:
135          - SHIPPER_NAME=DOCKY
136          - ELASTICSEARCH_HOST=<elk-stack-host-hostname>
137          - ELASTICSEARCH_PORT=9200
138          - PROCS=.*
139          - PERIOD=10s
140          - SHIPPER_NAME=super-app
141  
142  
143 Adding a New Log
144 ----------------
145 Filebeat docker is a customized image that depends on filebeat.yml, a configuration layer. 
146 For adding new log under prospectors of filebeat.yml, need to add log location path as it is in <volume-name>.
147
148 .. code:: yaml
149
150    filebeat.prospectors:
151      - input_type: log
152        paths:
153          - /filebeat-logs/portal-be/*.log
154
155
156 Elastic Stack UI Tour
157 ---------------------
158 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.
159 Kibana makes it easy to understand large volumes of data. Its simple, browser-based interface enables you to quickly create queries in real time.
160
161 For more details visit `Kibana User Guide <https://www.elastic.co/guide/en/kibana/5.5/index.html/>`_.
162
163 Site admins have access to Elastic Stack's Kibana Dashboard. Login to the dashboard:
164
165                 .. image:: images/acumos_Sign_In.JPG
166
167 Go to SITE ADMIN -> Monitoring and click on **Login to Dashboard** in the USERS section
168
169                 .. image:: images/acumos_site_admin.jpg
170
171
172 Redirects to Loading Kibana visualization platform
173
174                 .. image:: images/loadingKibana.jpg
175
176
177
178 Acumos Kibana Dashboard Creation
179 --------------------------------
180
181 The Kibana dashboard is used to view all the saved Visualizations.
182
183 To create dashboard click on Create a dashboard or On plus sign show in the search bar.
184
185 .. image:: images/kibana_dashboard_1.jpg
186
187 click on Visit the Visualize app
188
189 .. image:: images/kibana_dashboard_2.jpg
190
191 click on "Create a visualization" or "+"(i.e Plus sign) show in the search bar.
192
193 .. image:: images/kibana_visualization_1.jpg
194
195 Select visualization type. For example click on "Pie".
196
197 .. image:: images/kibana_visualization_2.jpg
198
199 Choose search source as ``logstash-*``
200
201 .. image:: images/kibana_visualization_3.jpg
202
203 Click on Split Slices
204
205 .. image:: images/kibana_visualization_4.jpg
206
207 Select Aggregation as "Terms" and Field as "userAgent.keyword", Click on "Apply changes"
208
209 Note: Elasticsearch aggregations are to extract and process your data.
210
211 .. image:: images/kibana_visualization_5.jpg
212
213 To save this chart click on "Save", Enter a name appropriate name. For example "Acumos User Login".
214  
215 .. image:: images/kibana_visualization_6.jpg
216
217 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.
218
219 .. image:: images/kibana_dashboard_3.jpg
220
221 Click on "Add" button, to add the visualization.
222
223 .. image:: images/kibana_dashboard_4.jpg
224
225 Select the visualization for example here we have visualization namely "Acumos User Login".
226
227 .. image:: images/kibana_dashboard_6.jpg
228
229 Click on "Save" button. Enter a name appropriate name. For example "Acumos User Login".
230
231 .. image:: images/kibana_dashboard_7.jpg
232
233 Click on "Dashboard", On the below screen created dashboard can be viewed namely "Acumos User Login".
234
235 .. image:: images/kibana_dashboard_8.jpg
236
237 Acumos Kibana Dashboard Save
238 ----------------------------
239
240 Click on "Management", On the below screen click on save object.
241
242 .. image:: images/kibana_save_dashboard_1.JPG
243
244
245 Click on "Export Everything" to export the dashboard and "Import" to import the saved dashboard.
246
247 .. image:: images/kibana_save_dashboard_2.JPG
248
249 .. note::
250
251     export/import document should be in JSON format.
252
253 An example JSON file that can be used to import a Dashboard is available in the platform-oam repo, `elk-stack directory <https://gerrit.acumos.org/r/gitweb?p=platform-oam.git;a=tree;f=elk-stack;hb=refs/heads/master>`_.