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