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