updated User Guide
[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.  As per mentioned in `Acumos Log Standards Wiki <https://wiki.acumos.org/display/OAM/Log+Standards>`_
37
38
39 Elastic Stack Architecture
40 --------------------------
41
42 .. image:: images/elk_stack.png
43
44
45 Elastic Stack Component Goal
46 ----------------------------
47
48 Acumos ELK stack setup has five main components:
49
50 - **Elasticsearch**: Elasticsearch is a distributed open source search engine based on Apache Lucene. Acumos Elasticsearch stores all the logs and metrics of Acumos platform host. 
51 - **Logstash**: Logstash is a data pipeline that helps collect, parse, and analyze a large variety of incoming logs generated across Acumos Platform. 
52 - **Kibana**: Web interface for searching and visualizing logs.
53 - **Filebeat**: Filebeat serves as a log shipping agent, Installed on Acumos platform servers it sends logs to Logstash.
54 - **Metricbeat**: Installed on Acumos platform servers. it periodically collects the metrics from the Acumos platform host operating system which includes running components information  and ships them to elasticsearch. These metrics are used for monitoring.
55
56
57 Elastic Stack Component Versions
58 --------------------------------
59
60 - elasticsearch 5.5.1
61 - kibana:5.5.1
62 - logstash:5.5.1
63 - filebeat:6.0.1
64 - metricbeat:6.2.4
65
66 Elastic Stack Setup
67 -------------------
68 Elastic Stack installation is automated with Docker Compose. Installation is done on a server separate from where Acumos has been installed.
69
70 **Note** We will install components namely Elasticsearch, Logstash and Kibana on a single server, which we will refer to as Acumos ELK stack log collector server. Beat agents namely Filebeat and Metricbeat are installed on Acumos platform host servers.
71
72 Prerequisites
73 -------------
74 `Docker <https://docs.docker.com/>`_ and `Docker Compose <https://docs.docker.com/compose/install/>`_ installed
75
76
77 Steps for first time, clean install 
78 -----
79
80 1. Clone the platform-oam repository 
81
82 .. code:: bash
83
84    $ git clone https://gerrit.acumos.org/r/platform-oam
85
86 2. Create docker volume namely acumos-esdata and acumos-logs if no volumes created earlier.If acumos-esdata and acumos-logs volume already exist on host machine then skip this step.
87    
88 .. code:: bash
89
90    $ docker volume create acumos-esdata
91    $ docker volume create acumos-logs
92    
93 3. The acumos-elk-env.sh file is the environment file for ELK stack. Update variables ELASTICSEARCH_IMAGE , LOGSTASH_IMAGE , KIBANA_IMAGE with the latest release image.
94
95 .. code:: bash
96
97    $ cd elk-stack
98
99    $ vi acumos-elk-env.sh
100    
101
102 4. The docker-compose.yml file as well as component directories are located in the elk-stack directory. Edit docker-compose.yml and make changes to these environment variables (ACUMOS_ELK_JDBC_CONNECTION_STRING, ACUMOS_ELK_JDBC_USERNAME, ACUMOS_ELK_JDBC_PASSWORD) to connect to database instance. Edit elasticsearch.yml and make changes to these environment variables ACUMOS_ELK_ELASTICSEARCH_HOST.
103
104 .. code:: bash
105
106    $ cd elk-stack
107
108    $ vi docker-compose.yml
109    
110
111 5. Starts and attaches to containers for Elasticsearch, Logstash, Kibana
112
113 .. code:: bash
114
115    $ ./docker-compose-elk.sh up -d
116
117
118 6. To stop the running containers without removing them
119
120 .. code:: bash
121
122    $ ./docker-compose-elk.sh stop
123
124 Steps to upgrade 
125 -----
126
127 1. A new version of the base code will need to be pulled from the garret repo.  Before that step make a backup of your platform directory.
128
129 .. code:: bash
130
131    $ git clone https://gerrit.acumos.org/r/platform-oam
132
133 2. Verify that the volumes previously created are present.  If not create the volumes (same as step 2 in clean install):
134
135 .. code:: bash
136
137    $ docker volume create acumos-esdata
138    $ docker volume create acumos-logs
139
140 3. Copy and replace "acumos-elk-env.sh" from your backup ( which can be found out in the location as /elk-stack/acumos-elk-env.sh ). That will have all the previous environment variables.
141
142 Else update the environment variable using below:
143
144 .. code:: bash
145
146    $ cd elk-stack
147
148    $ vi acumos-elk-env.sh
149
150 4. Copy and replace "docker-compose.yml" ( which can be found out in the location as /elk-stack/docker-compose.yml ). Which will have all the previous changes.
151
152 Else update the environment variable using below:
153
154 .. code:: bash
155
156    $ cd elk-stack
157
158    $ vi docker-compose.yml
159
160 5. Starts and attaches to containers for Elasticsearch, Logstash, Kibana
161
162 .. code:: bash
163
164    $ ./docker-compose-elk.sh up -d
165
166
167 6. To stop the running containers without removing them
168
169 .. code:: bash
170
171    $ ./docker-compose-elk.sh stop
172
173    
174 Filebeat setup steps:
175 ---------------------
176 Filebeat should be installed as an agent on the servers on which Acumos is running.
177 Add the configuration below to the docker-compose where the Acumos is installed.  
178
179 .. code:: yaml
180
181    filebeat:
182        container_name: filebeat
183        image: <filebeat-image-name>
184        volumes:
185          - <volume-name>:/filebeat-logs
186        environment:
187          - LOGSTASH_HOST=<elk-stack-host-hostname>
188          - LOGSTASH_PORT=5000
189
190
191 Metricbeat setup steps:
192 -----------------------
193 Metricbeat should be installed as an agent on the servers on which Acumos is running.
194 Add the configuration below to the docker-compose where the Acumos is installed. 
195
196 .. code:: yaml
197
198    metricbeat:
199        image: <metricbeat-image-name>
200        network_mode: host
201        volumes:
202        #Mount the docker, filesystem to enable Metricbeat to monitor the host rather than the Metricbeat container.
203          - /proc:/hostfs/proc:ro
204          - /sys/fs/cgroup:/hostfs/sys/fs/cgroup:ro
205          - /:/hostfs:ro
206          - /var/run:/var/run:rw
207          - /var/run/docker.sock:/var/run/docker.sock
208        command: metricbeat -e -strict.perms=false -system.hostfs=/hostfs
209        environment:
210          - SHIPPER_NAME=DOCKY
211          - ELASTICSEARCH_HOST=<elk-stack-host-hostname>
212          - ELASTICSEARCH_PORT=9200
213          - PROCS=.*
214          - PERIOD=10s
215          - SHIPPER_NAME=super-app
216  
217  
218 Adding a New Log
219 ----------------
220 Filebeat docker is a customized image that depends on filebeat.yml, a configuration layer. 
221 For adding new log under prospectors of filebeat.yml, need to add log location path as it is in <volume-name>.
222
223 .. code:: yaml
224
225    filebeat.prospectors:
226      - input_type: log
227        paths:
228          - /filebeat-logs/portal-be/*.log
229
230
231 Elastic Stack UI Tour
232 ---------------------
233 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.
234 Kibana makes it easy to understand large volumes of data. Its simple, browser-based interface enables you to quickly create queries in real time.
235
236 For more details visit `Kibana User Guide <https://www.elastic.co/guide/en/kibana/5.5/index.html/>`_.
237
238 Site admins have access to Elastic Stack's Kibana Dashboard. Login to the dashboard:
239
240                 .. image:: images/acumos_Sign_In.JPG
241
242 Go to SITE ADMIN -> Monitoring and click on **Login to Dashboard** in the USERS section
243
244                 .. image:: images/acumos_site_admin.jpg
245
246
247 Redirects to Loading Kibana visualization platform
248
249                 .. image:: images/loadingKibana.jpg
250
251
252
253 Acumos Kibana Dashboard Creation
254 --------------------------------
255
256 The Kibana dashboard is used to view all the saved Visualizations.
257
258 To create dashboard click on Create a dashboard or On plus sign show in the search bar.
259
260 .. image:: images/kibana_dashboard_1.jpg
261
262 click on Visit the Visualize app
263
264 .. image:: images/kibana_dashboard_2.jpg
265
266 click on "Create a visualization" or "+"(i.e Plus sign) show in the search bar.
267
268 .. image:: images/kibana_visualization_1.jpg
269
270 Select visualization type. For example click on "Pie".
271
272 .. image:: images/kibana_visualization_2.jpg
273
274 Choose search source as ``logstash-*``
275
276 .. image:: images/kibana_visualization_3.jpg
277
278 Click on Split Slices
279
280 .. image:: images/kibana_visualization_4.jpg
281
282 Select Aggregation as "Terms" and Field as "userAgent.keyword", Click on "Apply changes"
283
284 Note: Elasticsearch aggregations are to extract and process your data.
285
286 .. image:: images/kibana_visualization_5.jpg
287
288 To save this chart click on "Save", Enter a name appropriate name. For example "Acumos User Login".
289  
290 .. image:: images/kibana_visualization_6.jpg
291
292 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.
293
294 .. image:: images/kibana_dashboard_3.jpg
295
296 Click on "Add" button, to add the visualization.
297
298 .. image:: images/kibana_dashboard_4.jpg
299
300 Select the visualization for example here we have visualization namely "Acumos User Login".
301
302 .. image:: images/kibana_dashboard_6.jpg
303
304 Click on "Save" button. Enter a name appropriate name. For example "Acumos User Login".
305
306 .. image:: images/kibana_dashboard_7.jpg
307
308 Click on "Dashboard", On the below screen created dashboard can be viewed namely "Acumos User Login".
309
310 .. image:: images/kibana_dashboard_8.jpg
311
312 Acumos Kibana Dashboard Save
313 ----------------------------
314
315 Click on "Management", On the below screen click on save object.
316
317 .. image:: images/kibana_save_dashboard_1.JPG
318
319
320 Click on "Export Everything" to export the dashboard and "Import" to import the saved dashboard.
321
322 .. image:: images/kibana_save_dashboard_2.JPG
323
324 .. note::
325
326     export/import document should be in JSON format.
327
328 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>`_.