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