Update Elastic Stack instructions 70/1170/6
authorAimee Ukasick <aimeeu.opensource@gmail.com>
Fri, 2 Mar 2018 20:19:27 +0000 (14:19 -0600)
committerAimee Ukasick <aimeeu.opensource@gmail.com>
Fri, 9 Mar 2018 19:06:55 +0000 (13:06 -0600)
Move content into User's Guide
Rename files
Update developer's guide
Removed Kong instructions

Issue: ACUMOS-299

Change-Id: I239ef06b364bb37561934e5d201ba4effc5f16ac
Signed-off-by: Aimee Ukasick <aimeeu.opensource@gmail.com>
Signed-off-by: Amit Mishra <AM00474504@techmahindra.com>
23 files changed:
docs/Developer_Guide.rst [deleted file]
docs/developer-guide.rst [moved from docs/User_Guide.rst with 61% similarity]
docs/images/acumosSiteAdmin.jpg [new file with mode: 0644]
docs/images/acumos_Sign_In.JPG [new file with mode: 0644]
docs/images/acumos_elk_flow.jpg [new file with mode: 0644]
docs/images/acumos_site_admin.jpg [new file with mode: 0644]
docs/images/kibana_dashboard_1.jpg [new file with mode: 0644]
docs/images/kibana_dashboard_2.jpg [new file with mode: 0644]
docs/images/kibana_dashboard_3.jpg [new file with mode: 0644]
docs/images/kibana_dashboard_4.jpg [new file with mode: 0644]
docs/images/kibana_dashboard_5.jpg [new file with mode: 0644]
docs/images/kibana_dashboard_6.jpg [new file with mode: 0644]
docs/images/kibana_dashboard_7.jpg [new file with mode: 0644]
docs/images/kibana_dashboard_8.jpg [new file with mode: 0644]
docs/images/kibana_visualization_1.jpg [new file with mode: 0644]
docs/images/kibana_visualization_2.jpg [new file with mode: 0644]
docs/images/kibana_visualization_3.jpg [new file with mode: 0644]
docs/images/kibana_visualization_4.jpg [new file with mode: 0644]
docs/images/kibana_visualization_5.jpg [new file with mode: 0644]
docs/images/kibana_visualization_6.jpg [new file with mode: 0644]
docs/images/loadingKibana.jpg [new file with mode: 0644]
docs/index.rst
docs/user-guide.rst [new file with mode: 0644]

diff --git a/docs/Developer_Guide.rst b/docs/Developer_Guide.rst
deleted file mode 100644 (file)
index 8170d6e..0000000
+++ /dev/null
@@ -1,57 +0,0 @@
-.. ===============LICENSE_START=======================================================
-.. Acumos
-.. ===================================================================================
-.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
-.. ===================================================================================
-.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
-.. under the Creative Commons Attribution 4.0 International License (the "License");
-.. you may not use this file except in compliance with the License.
-.. You may obtain a copy of the License at
-..  
-..      http://creativecommons.org/licenses/by/4.0
-..  
-.. This file is distributed on an "AS IS" BASIS,
-.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-.. See the License for the specific language governing permissions and
-.. limitations under the License.
-.. ===============LICENSE_END=========================================================
-=================
-Developer's Guide
-=================
-
-Acumos ELK stack for log analytics
-===================================
-This guide that describes how to use the Acumos ELK Stack.
-
-1. Introduction
----------------
-One of the functions of Operations, Administration, and Management (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. 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. 
-
-       1.1 What is Acumos ELK Stack?
-               OAM are the processes, activities, tools, and standards involved with operating, administering, managing and maintaining any system. Collecting Logs of all the micro-services involved can reveal about the system that can mitigate potential risks. There are many ways we can collect logs that are generated via the micro-services. One of them is ELK stack. 
-               ELK stands for, E- Elasticsearch L- Logstash K-Kibana           
-        Note: Filebeats( a lightweight log shipping tools is also used to ship the logs to the servers)
-
-       1.2 Target Users
-               This guide is targeted towards the open source user community that who have access of super site admin.
-  
-       1.3 Assumptions
-               All the module should follow Acumos Log Standards.
-
-       1.4 ELK-Stack - Backend Architecture
-               .. image:: images/elk_stack.png
-
-
-2. ELK-Stack User Interface A Tour
-----------------------------------
-Site admin having access to ELK stack Login to dashboard:
-
-.. image:: images/acumosSiteAdminUntitled.png
-
-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.
-Kibana makes it easy to understand large volumes of data. Its simple, browser-based interface enables you to quickly create queries in real time.
-
-For more details visit `Kibana User Guide <https://www.elastic.co/guide/en/kibana/current/index.html/>`_.
-
-
-.. image:: images/loadingKibanaCapture.PNG
similarity index 61%
rename from docs/User_Guide.rst
rename to docs/developer-guide.rst
index 744e5f5..78b0448 100644 (file)
 .. See the License for the specific language governing permissions and
 .. limitations under the License.
 .. ===============LICENSE_END=========================================================
-=======================
-Platform OAM User Guide
-=======================
+===================================================================
+Operations, Administration, and Management (OA&M) Developer's Guide
+===================================================================
+
+
+The OA&M project is for the processes, activities, tools, and standards involved with operating, administering, managing and maintaining the Acumos platform. The project uses Docker, Docker Compose, shell scripts, and third-party tools such as the Kong API and Elastic Stack. 
+
+Jira: `https://jira.acumos.org <https://jira.acumos.org>`_   project name: platform-oam
+Gerrit:  git clone https://gerrit.acumos.org/r/platform-oam
+
+
+
 
-The Platform OA&M component is not accessed directly by end users.
-Please see the `Acumos Portal MarketPlace Users Guide <http://docs.acumos.org/>`_.  
diff --git a/docs/images/acumosSiteAdmin.jpg b/docs/images/acumosSiteAdmin.jpg
new file mode 100644 (file)
index 0000000..8a4b1e8
Binary files /dev/null and b/docs/images/acumosSiteAdmin.jpg differ
diff --git a/docs/images/acumos_Sign_In.JPG b/docs/images/acumos_Sign_In.JPG
new file mode 100644 (file)
index 0000000..5085116
Binary files /dev/null and b/docs/images/acumos_Sign_In.JPG differ
diff --git a/docs/images/acumos_elk_flow.jpg b/docs/images/acumos_elk_flow.jpg
new file mode 100644 (file)
index 0000000..a49e050
Binary files /dev/null and b/docs/images/acumos_elk_flow.jpg differ
diff --git a/docs/images/acumos_site_admin.jpg b/docs/images/acumos_site_admin.jpg
new file mode 100644 (file)
index 0000000..deccbc8
Binary files /dev/null and b/docs/images/acumos_site_admin.jpg differ
diff --git a/docs/images/kibana_dashboard_1.jpg b/docs/images/kibana_dashboard_1.jpg
new file mode 100644 (file)
index 0000000..cb8dde1
Binary files /dev/null and b/docs/images/kibana_dashboard_1.jpg differ
diff --git a/docs/images/kibana_dashboard_2.jpg b/docs/images/kibana_dashboard_2.jpg
new file mode 100644 (file)
index 0000000..0228152
Binary files /dev/null and b/docs/images/kibana_dashboard_2.jpg differ
diff --git a/docs/images/kibana_dashboard_3.jpg b/docs/images/kibana_dashboard_3.jpg
new file mode 100644 (file)
index 0000000..bb3c5f5
Binary files /dev/null and b/docs/images/kibana_dashboard_3.jpg differ
diff --git a/docs/images/kibana_dashboard_4.jpg b/docs/images/kibana_dashboard_4.jpg
new file mode 100644 (file)
index 0000000..b041838
Binary files /dev/null and b/docs/images/kibana_dashboard_4.jpg differ
diff --git a/docs/images/kibana_dashboard_5.jpg b/docs/images/kibana_dashboard_5.jpg
new file mode 100644 (file)
index 0000000..ca52bf1
Binary files /dev/null and b/docs/images/kibana_dashboard_5.jpg differ
diff --git a/docs/images/kibana_dashboard_6.jpg b/docs/images/kibana_dashboard_6.jpg
new file mode 100644 (file)
index 0000000..34d0b7a
Binary files /dev/null and b/docs/images/kibana_dashboard_6.jpg differ
diff --git a/docs/images/kibana_dashboard_7.jpg b/docs/images/kibana_dashboard_7.jpg
new file mode 100644 (file)
index 0000000..5c64473
Binary files /dev/null and b/docs/images/kibana_dashboard_7.jpg differ
diff --git a/docs/images/kibana_dashboard_8.jpg b/docs/images/kibana_dashboard_8.jpg
new file mode 100644 (file)
index 0000000..47ee853
Binary files /dev/null and b/docs/images/kibana_dashboard_8.jpg differ
diff --git a/docs/images/kibana_visualization_1.jpg b/docs/images/kibana_visualization_1.jpg
new file mode 100644 (file)
index 0000000..159e625
Binary files /dev/null and b/docs/images/kibana_visualization_1.jpg differ
diff --git a/docs/images/kibana_visualization_2.jpg b/docs/images/kibana_visualization_2.jpg
new file mode 100644 (file)
index 0000000..2c8f73f
Binary files /dev/null and b/docs/images/kibana_visualization_2.jpg differ
diff --git a/docs/images/kibana_visualization_3.jpg b/docs/images/kibana_visualization_3.jpg
new file mode 100644 (file)
index 0000000..2391d73
Binary files /dev/null and b/docs/images/kibana_visualization_3.jpg differ
diff --git a/docs/images/kibana_visualization_4.jpg b/docs/images/kibana_visualization_4.jpg
new file mode 100644 (file)
index 0000000..be60a36
Binary files /dev/null and b/docs/images/kibana_visualization_4.jpg differ
diff --git a/docs/images/kibana_visualization_5.jpg b/docs/images/kibana_visualization_5.jpg
new file mode 100644 (file)
index 0000000..1d785c9
Binary files /dev/null and b/docs/images/kibana_visualization_5.jpg differ
diff --git a/docs/images/kibana_visualization_6.jpg b/docs/images/kibana_visualization_6.jpg
new file mode 100644 (file)
index 0000000..bc0d3e7
Binary files /dev/null and b/docs/images/kibana_visualization_6.jpg differ
diff --git a/docs/images/loadingKibana.jpg b/docs/images/loadingKibana.jpg
new file mode 100644 (file)
index 0000000..c4f8bf0
Binary files /dev/null and b/docs/images/loadingKibana.jpg differ
index a91a87b..e1ddb38 100644 (file)
@@ -23,7 +23,7 @@ Acumos Platform Operations, Administration, and Management (OA&M) Documentation
        :maxdepth: 2
 
        release-notes
-       Developer_Guide
-       User_Guide
+       developer-guide       
+       user-guide
 
 * :ref:`search`
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
new file mode 100644 (file)
index 0000000..4da6c8f
--- /dev/null
@@ -0,0 +1,205 @@
+.. ===============LICENSE_START=======================================================
+.. Acumos
+.. ===================================================================================
+.. Copyright (C) 2017-2018 AT&T Intellectual Property & Tech Mahindra. All rights reserved.
+.. ===================================================================================
+.. This Acumos documentation file is distributed by AT&T and Tech Mahindra
+.. under the Creative Commons Attribution 4.0 International License (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..  
+..      http://creativecommons.org/licenses/by/4.0
+..  
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+=====================================================================
+Platform Operations, Administration, and Management (OA&M) User Guide
+=====================================================================
+
+Operations, Administration and Management/Maintenance are the processes, activities, tools, and standards involved with operating, administering, managing and maintaining any system. 
+
+Acumos Elastic Stack for Log Analytics
+======================================
+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).
+
+Target users
+------------
+Acumos Platform super admins
+
+
+Assumptions
+-----------
+All the modules are following the Acumos Logging Guidelines
+
+
+Elastic Stack architecture
+--------------------------
+.. image:: images/elk_stack.png
+
+Elastic Stack component versions
+--------------------------------
+
+- elasticsearch 5.5.1
+- kibana:5.5.1
+- logstash:5.5.1
+- filebeat:6.0.1
+
+Elastic Stack setup 
+-------------------
+Elastic Stack installation is automated with Docker Compose. Installation is done on a server separate from where Acumos has been installed. 
+
+Prerequisites
+-------------
+`Docker <https://docs.docker.com/>`_ and `Docker Compose <https://docs.docker.com/compose/install/>`_ installed
+
+
+Steps
+-----
+
+1. Clone the platform-oam repository 
+
+.. code-block:: bash
+   
+   $ git clone https://gerrit.acumos.org/r/platform-oam
+   
+
+2. 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.
+
+.. code-block:: bash
+       
+   $ docker-compose build  
+   
+       
+3. Builds, (re)creates, starts, and attaches to containers for Elasticsearch, Logstash, Kibana
+
+.. code-block:: bash
+       
+   $ docker-compose up -d      
+                               
+                
+4. To stop the running containers without removing them 
+
+.. code-block:: bash   
+
+   $ docker-compose stop   
+               
+
+Filebeat setup steps:
+---------------------
+Filebeat should be installed as an agent on the servers on which Acumos is running.
+Add the configuration below to the docker-compose where the Acumos is installed.  
+
+.. code-block:: yaml
+
+   filebeat:
+       container_name: filebeat           
+       image: <filebeat-image-name>       
+       volumes:
+         - <volume-name>:/filebeat-logs
+       environment:
+         - LOGSTASH_HOST=<elk-stack-host-hostname>
+                - LOGSTASH_PORT=5000
+
+
+Adding new log:
+---------------
+Filebeat docker is a customized image that depends on filebeat.yml, a configuration layer. 
+For adding new log under prospectors of filebeat.yml, need to add log location path as it is in <volume-name>.
+
+.. code-block:: yaml
+
+   filebeat.prospectors:
+     - input_type: log
+       paths:
+         - /filebeat-logs/portal-be/*.log
+         
+
+Elastic Stack user interface tour
+---------------------------------
+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.
+Kibana makes it easy to understand large volumes of data. Its simple, browser-based interface enables you to quickly create queries in real time.
+
+For more details visit `Kibana User Guide <https://www.elastic.co/guide/en/kibana/5.5/index.html/>`_.
+
+Site admins have access to Elastic Stack's Kibana Dashboard. Login to the dashboard:
+
+For accessing Acumos elk stack login via Acumos Platform Website. 
+               .. image:: images/acumos_Sign_In.jpg
+
+               
+               
+Go to SITE ADMIN monitoring users and click on to Login to Dashboard
+
+               .. image:: images/acumos_site_admin.jpg 
+
+               
+
+Redirects to Loading Kibana visualization platform
+
+               .. image:: images/loadingKibana.jpg
+
+
+
+Acumos Kibana dashboard creation steps
+------------------------------------
+Kibana dashboard used to view all the saved visualizations. 
+
+To create dashboard click on Create a dashboard or On plus sign show in the search bar.
+
+
+.. image:: images/kibana_dashboard_1.jpg                                  
+
+click on "visit the Visualize app."
+
+.. image:: images/kibana_dashboard_2.jpg
+
+click on "Create new a visualization" or "+"(i.e Plus sign) show in the search bar.
+
+.. image:: images/kibana_visualization_1.jpg
+
+Select visualization type. For example click on "Pie".
+
+.. image:: images/kibana_visualization_2.jpg
+
+Choose search source as "logstash-*"
+
+.. image:: images/kibana_visualization_3.jpg
+
+Click on "Split Slices"
+
+.. image:: images/kibana_visualization_4.jpg
+
+Select Aggregation as "Terms" and Field as "userAgent.keyword", Click on "Apply changes"
+
+Note: Elasticsearch aggregations are to extract and process your data. 
+
+.. image:: images/kibana_visualization_5.jpg
+
+To save this chart click on "Save", Enter a name appropriate name. For example "Acumos User Login".
+.. image:: images/kibana_visualization_6.jpg
+
+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.
+
+.. image:: images/kibana_dashboard_3.jpg
+
+Click on "Add" button, to add the visualization.
+
+.. image:: images/kibana_dashboard_4.jpg
+
+Select the visualization for example here we have visualization namely "Acumos User Login".
+
+.. image:: images/kibana_dashboard_6.jpg
+
+Click on "Save" button. Enter a name appropriate name. For example "Acumos User Login".
+
+.. image:: images/kibana_dashboard_7.jpg
+
+Click on "Dashboard", On the below screen created dashboard can be viewed namely "Acumos User Login".
+
+.. image:: images/kibana_dashboard_8.jpg
+
+