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-2022 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
  67 - Curl command 2. Change logging level of "logging.level.org.onap.cps" to "DEBUG"
  68
  69 .. note::
  70    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.
  71
  72 .. code-block:: java
  73
  74     curl --location --request POST 'http://{cps-service-name:cps-management-port}/manage/loggers/org.onap.cps' \
  75     --header 'Content-Type: application/json; charset=utf-8' \
  76     --data-raw '{
  77                     "configuredLevel": "DEBUG"
  78                 }'
  79
  80     Response body : HTTP Status 204
  81
  82 - Curl command 3. Verify if log level of "logging.level.org.onap.cps" is changed from 'INFO' to 'DEBUG'
  83
  84 .. code-block:: java
  85
  86     curl --location --request GET 'http://{cps-service-name:cps-management-port}/manage/loggers/org.onap.cps' \
  87     --header 'Content-Type: application/json; charset=utf-8'
  88
  89     Response body : HTTP Status 200
  90
  91     {
  92     "configuredLevel": "DEBUG",
  93     "effectiveLevel": "DEBUG"
  94     }
  95
  96
  97 Location of log files
  98 ---------------------
  99 By default, Spring Boot will only log to the console and will not write log files.
 100
 101 .. image:: images/cps-service-console.JPG
 102   :width: 700
 103   :alt: CPS service console
 104
 105 Measure Execution Time of CPS Service
 106 -------------------------------------
 107
 108 .. note::
 109    Make sure effective log level of "logging.level.org.onap.cps" is 'DEBUG'. This can be verified by executing curl command 3.
 110
 111 Execute CPS service that you want to calculate total elapsed time and log as shown below
 112
 113 .. code-block:: xml
 114
 115    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
 116
 117    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
 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 : CpsAdminPersistenceServiceImpl.getAnchor() with argument[s] = [test42, bookstore] having result = Anchor(name=bookstore, dataspaceName=test42, schemaSetName=bookstore) :: 299 ms
 120
 121    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
 122
 123    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 {
 124     name: bookstore
 125     dataspaceName: test42
 126     schemaSetName: bookstore
 127    },[]> :: 419 ms
 128
 129 .. warning::
 130    Revert logging level of "logging.level.org.onap.cps" to 'INFO' again to prevent unnecessary logging and impacts on performance.
 131
 132 .. Below Label is used by documentation for other CPS components to link here, do not remove even if it gives a warning
 133 .. _cps_common_logging:
 134
 135 Logging & Diagnostics
 136 =====================
 137
 138 General Guidelines
 139 ------------------
 140
 141 CPS-Core logs are sent to `STDOUT` in order to leverage the Kubernetes logging architecture.
 142
 143 These logs are available using the following command:
 144
 145 .. code:: bash
 146
 147     kubectl logs <cps-core-pod>
 148
 149 The default configuration for CPS logs is the INFO level.
 150
 151 This architecture also makes all logs ready to be sent to an Elastic-search Log-stash and Kibana (ELK) stack or similar.
 152
 153 Enabling tracing for all executed sql statements is done by changing hibernate
 154 loggers log level
 155
 156 Logger configuration is provided as a chart resource :
 157
 158     +--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
 159     | cps-component-service-name     | logback.xml location                                                                                                             |
 160     +================================+==================================================================================================================================+
 161     | cps-core                       | `logback.xml <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-core/resources/config/logback.xml>`__        |
 162     +--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
 163     | cps-temporal                   | `logback.xml <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-temporal/resources/config/logback.xml>`__    |
 164     +--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
 165     | ncmp-dmi-plugin                | Not yet applicable to DMI-Plugin                                                                                                 |
 166     +--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
 167
 168 .. Below Label is used by documentation for other CPS components to link here, do not remove even if it gives a warning
 169 .. _cps_common_monitoring:
 170
 171 Monitoring
 172 ==========
 173 Once CPS-Core is deployed, information related to the running instance of the application is available
 174
 175 .. code::
 176
 177     http://<cps-component-service-name>:8081/manage/info/
 178
 179 Health
 180 ------
 181
 182 Cps-Core health status and state can be checked using the following endpoint.
 183 This also includes both the liveliness state and readiness state.
 184
 185 .. code::
 186
 187     http://<cps-component-service-name>:8081/manage/health/
 188
 189 Metrics
 190 -------
 191
 192 Prometheus Metrics can be checked at the following endpoint
 193
 194 .. code::
 195
 196     http://<cps-component-service-name>:8081/manage/prometheus
 197
 198 Naming Validation
 199 -----------------
 200
 201 As part of the Jakarta 3.1.0 release, CPS has added validation to the names of the following components:
 202
 203     - Dataspace names
 204     - Schema Set names
 205     - Anchor names
 206     - Cm-Handle identifiers
 207
 208 The following characters along with spaces are no longer valid for naming of these components.
 209
 210 .. code::
 211
 212     !"#$%&'()*+,./\:;<=>?@[]^`{|}~