docs/admin-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright (C) 2021 Nordix Foundation
   4
   5 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
   6 .. _adminGuide:
   7
   8
   9 CPS Admin Guide
  10 ###############
  11
  12 .. toctree::
  13    :maxdepth: 1
  14
  15 Logging Configuration
  16 =====================
  17
  18 .. note::
  19    Default logging level of "logging.level.org.onap.cps" is set to "INFO".
  20
  21 .. code-block:: bash
  22
  23    logging:
  24     level:
  25         org:
  26             springframework: INFO
  27             onap:
  28                 cps: INFO
  29
  30 CPS Log pattern
  31 ---------------
  32
  33 .. code-block:: java
  34
  35    <pattern>
  36            {
  37              "timestamp" : "%timestamp", // 2022-01-28 18:39:17.768
  38              "severity": "%level",   // DEBUG
  39              "service": "${springAppName}",  // cps-application
  40              "trace": "${TraceId}", // e17da1571e518c59
  41              "span": "${SpanId}", // e17da1571e518c59
  42              "pid": "${PID}", //11128
  43              "thread": "%thread", //tp1901272535-29
  44              "class": "%logger{40}", .// o.onap.cps.aop.CpsLoggingAspectService
  45              "rest": "%message" // Execution time ...
  46            }
  47    </pattern>
  48
  49 Change logging level
  50 --------------------
  51
  52 - Curl command 1. Check current log level of "logging.level.org.onap.cps" if it is set to it's default value (INFO)
  53
  54 .. code-block:: java
  55
  56     curl --location --request GET 'http://{cps-service-name:cps-management-port}/manage/loggers/org.onap.cps' \
  57     --header 'Content-Type: application/json; charset=utf-8'
  58
  59     Response body : HTTP Status 200
  60
  61     {
  62         "configuredLevel": "INFO",
  63         "effectiveLevel": "INFO"
  64     }
  65
  66 - Curl command 2. Change logging level of "logging.level.org.onap.cps" to "DEBUG"
  67
  68 .. note::
  69    Below-mentioned endpoint  will change the log level at runtime. After executing the curl command "effectiveLevel" will set and applied immediately without restarting CPS service.
  70
  71 .. code-block:: java
  72
  73     curl --location --request POST 'http://{cps-service-name:cps-management-port}/manage/loggers/org.onap.cps' \
  74     --header 'Content-Type: application/json; charset=utf-8' \
  75     --data-raw '{
  76                     "configuredLevel": "DEBUG"
  77                 }'
  78
  79     Response body : HTTP Status 204
  80
  81 - Curl command 3. Verify if log level of "logging.level.org.onap.cps" is changed from 'INFO' to 'DEBUG'
  82
  83 .. code-block:: java
  84
  85     curl --location --request GET 'http://{cps-service-name:cps-management-port}/manage/loggers/org.onap.cps' \
  86     --header 'Content-Type: application/json; charset=utf-8'
  87
  88     Response body : HTTP Status 200
  89
  90     {
  91     "configuredLevel": "DEBUG",
  92     "effectiveLevel": "DEBUG"
  93     }
  94
  95 Location of log files
  96 ---------------------
  97 By default, Spring Boot will only log to the console and will not write log files.
  98
  99 .. image:: images/cps-service-console.JPG
 100   :width: 700
 101   :alt: CPS service console
 102
 103 Measure Execution Time of CPS Service
 104 -------------------------------------
 105
 106 .. note::
 107    Make sure effective log level of "logging.level.org.onap.cps" is 'DEBUG'. This can be verified by executing curl command 3.
 108
 109 Execute CPS service that you want to calculate total elapsed time and log as shown below
 110
 111 .. code-block:: xml
 112
 113    2022-01-28 18:39:17.679 DEBUG [cps-application,e17da1571e518c59,e17da1571e518c59] 11128 --- [tp1901272535-29] o.onap.cps.aop.CpsLoggingAspectService   : Execution time of : DataspaceRepository.getByName() with argument[s] = [test42] having result = org.onap.cps.spi.entities.DataspaceEntity@68ded236 :: 205 ms
 114
 115    2022-01-28 18:39:17.726 DEBUG [cps-application,e17da1571e518c59,e17da1571e518c59] 11128 --- [tp1901272535-29] o.onap.cps.aop.CpsLoggingAspectService   : Execution time of : AnchorRepository.getByDataspaceAndName() with argument[s] = [org.onap.cps.spi.entities.DataspaceEntity@68ded236, bookstore] having result = org.onap.cps.spi.entities.AnchorEntity@71c47fb1 :: 46 ms
 116
 117    2022-01-28 18:39:17.768 DEBUG [cps-application,e17da1571e518c59,e17da1571e518c59] 11128 --- [tp1901272535-29] o.onap.cps.aop.CpsLoggingAspectService   : Execution time of : CpsAdminPersistenceServiceImpl.getAnchor() with argument[s] = [test42, bookstore] having result = Anchor(name=bookstore, dataspaceName=test42, schemaSetName=bookstore) :: 299 ms
 118
 119    2022-01-28 18:39:17.768 DEBUG [cps-application,e17da1571e518c59,e17da1571e518c59] 11128 --- [tp1901272535-29] o.onap.cps.aop.CpsLoggingAspectService   : Execution time of : CpsAdminServiceImpl.getAnchor() with argument[s] = [test42, bookstore] having result = Anchor(name=bookstore, dataspaceName=test42, schemaSetName=bookstore) :: 305 ms
 120
 121    2022-01-28 18:39:17.843 DEBUG [cps-application,e17da1571e518c59,e17da1571e518c59] 11128 --- [tp1901272535-29] o.onap.cps.aop.CpsLoggingAspectService   : Execution time of : AdminRestController.getAnchor() with argument[s] = [test42, bookstore] having result = <200 OK OK,class AnchorDetails {
 122     name: bookstore
 123     dataspaceName: test42
 124     schemaSetName: bookstore
 125    },[]> :: 419 ms
 126
 127 .. warning::
 128    Revert logging level of "logging.level.org.onap.cps" to 'INFO' again to prevent unnecessary logging and impacts on performance.
 129
 130 .. Below Label is used by documentation for other CPS components to link here, do not remove even if it gives a warning
 131 .. _cps_common_logging:
 132
 133 Logging & Diagnostics
 134 =====================
 135
 136 General Guidelines
 137 ------------------
 138 CPS-Core logs are sent to `STDOUT` in order to leverage the Kubernetes logging architecture.
 139
 140 These logs are available using the following command:
 141
 142 .. code:: bash
 143
 144     kubectl logs <cps-core-pod>
 145
 146 The default configuration for CPS logs is the INFO level.
 147
 148 This architecture also makes all logs ready to be sent to an Elastic-search Log-stash and Kibana (ELK) stack or similar.
 149
 150 Enabling tracing for all executed sql statements is done by changing hibernate
 151 loggers log level
 152
 153 Logger configuration is provided as a chart resource :
 154
 155     +--------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
 156     | cps-component-service-name     | logback.xml location                                                                                                            |
 157     +================================+=================================================================================================================================+
 158     | cps-core                       | `logback.xml <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-core/resources/config/logback.xml>`_        |
 159     +--------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
 160     | cps-temporal                   | `logback.xml <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-temporal/resources/config/logback.xml>`_    |
 161     +--------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
 162     | ncmp-dmi-plugin                | Not yet applicable to DMI-Plugin                                                                                                |
 163     +--------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
 164
 165 .. Below Label is used by documentation for other CPS components to link here, do not remove even if it gives a warning
 166 .. _cps_common_monitoring:
 167
 168 Monitoring
 169 ==========
 170 Once CPS-Core is deployed, information related to the running instance of the application is available
 171
 172 .. code::
 173
 174     http://<cps-component-service-name>:8081/manage/info/
 175
 176 Health
 177 ------
 178
 179 Cps-Core health status and state can be checked using the following endpoint.
 180 This also includes both the liveliness state and readiness state.
 181
 182 .. code::
 183
 184     http://<cps-component-service-name>:8081/manage/health/
 185
 186 Metrics
 187 -------
 188
 189 Prometheus Metrics can be checked at the following endpoint
 190
 191 .. code::
 192
 193     http://<cps-component-service-name>:8081/manage/prometheus