docs/developer_info/SO_Admin_Cockpit_User_Guide.rst

   1
   2 SO Admin Cockpit User Guide
   3 ===========================
   4
   5 Introduction
   6 ------------
   7
   8 The SO-Admin-Cockpit component allows a user to have a detailed monitoring view of the Camunda BPMN workflows that have run, or are running, in SO. It provides a frontend UI that allows users to easily go through a workflow’s different calls and drill up/down through the call activities within the workflow. It also provides a search page for filtering specific results. It allows you to filter by start/end time/date, instance id, request id, service name or by the status of a workflow. The component is extremely useful for debugging and testing workflows of any kind, as it delivers an understandable and simple UI which is much easier to follow than large, cumbersome debug log files. Additionally the UI provides a statistics page, based on your current search parameters, that provides the percentages of complete, failed, in progress, pending and unlocked workflows.
   9
  10 (Previous to the Honolulu release of ONAP SO-Admin-Cockpit was named SO-Monitoring, an additional change in the controller is required to change the Host name to SO-Admin-Cockpit, as it remains as SO-Monitoring currently)
  11
  12 Using SO-Admin-Cockpit
  13 ----------------------
  14
  15 In order to make use of SO-Admin-Cockpit currently, you will need to onboard the application in the ONAP portal or access the SO-Admin-Cockpit UI directly. This can be done using the host name “so-admin-cockpit", and the port number, which by default is “30224”. First you need to make sure you can access the ONAP portal, this is done by adding the following to your "hosts" file:
  16
  17 .. code-block:: bash
  18
  19  <onapVmIp> portal.api.simpledemo.onap.org
  20
  21 Replacing <onapVmIp> with the IP of your device hosting your Portal pod within ONAP. Add this to a blank line in your hosts file, usually found in “C:\Windows\System32\drivers\etc” on Windows. Ensure you open the host file as an administrator in order to edit it.
  22
  23 Alternatively you can access SO-Admin-Cockpit directly by simply adding the following line to your "hosts" file:
  24
  25 .. code-block:: bash
  26
  27  <soAdminCockpitVmIp> so-monitoring
  28
  29 Where <soAdminCockpitVmIp> is replaced with the IP of the device hosting your SO-Admin-Cockpit pod.
  30 Then accessing the following link through your browser:
  31
  32 .. code-block:: bash
  33
  34  https://so-monitoring:30224/
  35
  36 Steps to add SO-Admin-Cockpit to the Portal
  37 -------------------------------------------
  38
  39 In Pre-Casablanca releases you will need to expose the so-monitoring service using a Loadbalancer in order to access it, this is simple until there is a NodePort assigned to SO-Monitoring. Use this command to expose the service:
  40
  41 .. code-block:: bash
  42
  43  kubectl expose services so-monitoring --type=LoadBalancer --port 9091 --target-port=9091 --name=so-monitoring-external -n onap
  44
  45 Log into your ONAP Portal as the super user
  46
  47 - Login: demo
  48 - Password: demo123456!
  49
  50 Click “Application Onboarding”, then “Add App” in the top right.
  51 Fill out the required Application Details (Name, URL, REST API URL, Username, Password) as shown here:
  52
  53 -        Application Name: SO-Admin-Cockpit
  54 -        URL: https://so-monitoring:30224
  55 -        Rest API URL: https://so-monitoring:30224
  56 -        Username: demo
  57 -        Password: <PASSWORD>
  58 -        Namespace: SO-Admin-Cockpit
  59
  60 Please note, the <PASSWORD> can be retrieved by logging into the SO-Admin-Cockpit pod and retrieving the environment variables using the following command:
  61
  62 .. code-block:: bash
  63
  64  env | grep SO_COCKPIT
  65
  66 Now simply go to the “Application Catalog” tab on the left of the page, then tick your Monitoring app to enable it. (Whatever you set Application Name as should show up here.) Click the “Home” tab and you should be able to access the Admin Cockpit now.
  67
  68 Searching/Viewing BPMN Workflows
  69 --------------------------------
  70
  71 .. image:: ../images/soAdminCockpitUi.png
  72
  73 In order to find the workflow that you are attempting to monitor you will need at least one of the following values of the service instance: Service Instance ID, Request ID, Service Name or the time/date range in which the workflow started/ended. You can use the filter drop-down boxes to the left of the parameter boxes, i.e. “EQUAL”, “NOT EQUAL” and “LIKE”. Also, you can filter by the status of a workflow, with the status drop-down box, to further filter your results. Simply enter any of these pieces of information into the search page, ensure the start and end date range includes when the workflow would have run and press the search button. Once your results list has been returned you can click on a result to see the workflow in the graphical BPMN viewer.
  74
  75 .. image:: ../images/soAdminCockpitUi2.png
  76
  77 From here you can inspect the different calls and variables throughout the workflow, by using the "Activity Instances" and "Variable Instances" tabs. Clicking on one of the sub process call, within the diagram, to open them in the graphical BPMN viewer (The boxes with a + at the bottom of them are call activities to sub processes. This is how you drill down through a workflow, you can also safely traverse back “up” through the flows with your browser’s back button. The cyan highlighting shows the flow of the path taken by the workflow, and this will go down through each of the sub processes as well.
  78
  79 .. image:: ../images/soAdminCockpitUi3.png
  80
  81 In the BPMN viewer, manipulation of the returned illustrated flow is possible by using the following methods. On the left side of the viewer window there are three symbols for Zooming in/out and fitting the flow to the full window. Along with these controls, the user can left-click and drag to move the flow within the canvas to the user desired position.
  82
  83 SO-Monitoring Service Statistics
  84 --------------------------------
  85
  86 .. image:: ../images/soAdminCockpitStatistics.png
  87
  88 You can see a summary of the status of all of the workflows from one of your search results by clicking on the "Service Statistics" tab, found just above your list of results. Here you can find a percentile breakdown of each workflow's, in the list of results you received, statuses.
  89
  90 Troubleshooting SO-Admin-Cockpit
  91 --------------------------------
  92
  93 The log files for SO-Admin-Cockpit can be found within the SO-Admin-Cockpit pod. They will be located in the “/app/logs/so-admin-cockpit" directory. You will find a debug, error, metric and audit log file here. They each contain differing information, except the debug log file which will contain all of the logging information. Alternatively you can get the logs from the SO-Admin-Cockpit pod itself when using Kubernetes. Using the following command:
  94
  95 .. code-block:: bash
  96
  97  kubectl -n <namespace> logs <soAdminCockpitPodName>
  98
  99 Replacing <namespace> with your environments namespace and <soAdminCockpitPodName> with the full name of your SO-Admin-Cockpit pod. This command will give you some detailed information from the execution of the pod.
 100
 101 CORS (Cross-Origin Resource Sharing) Error
 102 ------------------------------------------
 103
 104 Pre-Dublin SO-Monitoring Components may experience CORS issues.
 105
 106 To check for this error open up the console of the browser you are using. In Mozilla Firefox do this by pressing CTRL + SHIFT + C and then selecting the console. In Google Chrome this is done by CTRL + SHIFT + I and then selecting the console. If an exception relating to CORS is displayed, then this issue must be addressed.
 107
 108 This can be dealt with in two ways. Either using an extension or by disabling CORS in the browser.
 109
 110 - If using Firefox then the CORS Everywhere extension should be used. While if using Chrome the Allow-Control-Allow-Origin should be used.
 111 - To disable the CORS in Chrome, follow this thread (https://stackoverflow.com/questions/3102819/disable-same-origin-policy-in-chrome).
 112
 113 Internal Service Error occurred for operation : GET please check backend  service log. status code: 500
 114 -------------------------------------------------------------------------------------------------------
 115
 116 .. image:: ../images/soAdminCockpitGetError.png
 117
 118 This can be checked by following the below steps:
 119
 120 - Open the developers mode in your browser
 121 - Click on Console
 122 - Check to see if an error occurs similar to the following:
 123
 124 .. code-block:: bash
 125
 126  Error : No serializer found for class org.onap.so.bpmn.core.RollbackData and no properties discovered to create BeanSerializer
 127
 128 This issue could be associated with any one of the objects being used in the BPMN flows, when it's declared as a java object but attempted to be serialized without marking/declaring it as serializable. So the issue must be fixed at the Object level, by ensuring any objects used by the particular BPMN Flow are made serializable.
 129
 130 SO Admin Cockpit App creates a Blank Tab
 131 ----------------------------------------
 132
 133 If when selecting SO Admin Cockpit from the portal a blank tab labeled “SO Admin Cockpit" is returned, then the issue may relate the URL you are using in portal by default.
 134
 135 A fix for this issue is to change “https” to “http” and change the port from “30224” to “30215”, within the browser URL.
 136
 137 For example, using this URL:
 138
 139 .. code-block:: bash
 140
 141  http://portal.api.simpledemo.onap.org:30215/ONAPPORTAL/applicationsHome
 142
 143 Instead of the default URL:
 144
 145 .. code-block:: bash
 146
 147  https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/applicationsHome
 148
 149