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::
  34
  35    <pattern>
  36        {
  37          "logTimeStamp" : "%timestamp", // 2022-01-28 18:39:17.768
  38          "logLevel": "%level",   // DEBUG
  39          "principalId": "%userId",    // cpsuser
  40          "serviceName": "${springAppName}",  // cps-application
  41          "message":"%message",  // Execution time ...
  42          "processId": "${PID}", //11128
  43          "threadName": "%thread", //tp1901272535-29
  44          "class": "%logger{40}", .// o.onap.cps.aop.CpsLoggingAspectService
  45        }
  46    </pattern>
  47
  48 Change logging level
  49 --------------------
  50
  51 - Curl command 1. Check current log level of "logging.level.org.onap.cps" if it is set to it's default value (INFO)
  52
  53 .. code-block:: bash
  54
  55     curl --location --request GET 'http://{cps-service-name:cps-port}/actuator/loggers/org.onap.cps' \
  56     --header 'Content-Type: application/json; charset=utf-8'
  57
  58     Response body : HTTP Status 200
  59
  60     {
  61         "configuredLevel": "INFO",
  62         "effectiveLevel": "INFO"
  63     }
  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:: bash
  72
  73     curl --location --request POST 'http://{cps-service-name:cps-port}/actuator/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:: bash
  84
  85     curl --location --request GET 'http://{cps-service-name:cps-port}/actuator/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
  96 Location of log files
  97 ---------------------
  98 By default, Spring Boot will only log to the console and will not write log files.
  99
 100 .. image:: _static/cps-service-console.JPG
 101   :width: 700
 102   :alt: CPS service console
 103
 104 Measure Execution Time of CPS Service
 105 -------------------------------------
 106
 107 .. note::
 108    Make sure effective log level of "logging.level.org.onap.cps" is 'DEBUG'. This can be verified by executing curl command 3.
 109
 110 Execute CPS service that you want to calculate total elapsed time and log as shown below
 111
 112 .. code-block::
 113
 114    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
 115
 116    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
 117
 118    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
 119
 120    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
 121
 122    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 {
 123     name: bookstore
 124     dataspaceName: test42
 125     schemaSetName: bookstore
 126    },[]> :: 419 ms
 127
 128 .. warning::
 129    Revert logging level of "logging.level.org.onap.cps" to 'INFO' again to prevent unnecessary logging and impacts on performance.
 130
 131 .. Below Label is used by documentation for other CPS components to link here, do not remove even if it gives a warning
 132 .. _cps_common_logging:
 133
 134 Logging & Diagnostics
 135 =====================
 136
 137 General Guidelines
 138 ------------------
 139
 140 CPS-Core logs are sent to `STDOUT` in order to leverage the Kubernetes logging architecture.
 141
 142 These logs are available using the following command:
 143
 144 .. code:: bash
 145
 146     kubectl logs <cps-core-pod>
 147
 148 The default configuration for CPS logs is the INFO level.
 149
 150 This architecture also makes all logs ready to be sent to an Elastic-search Log-stash and Kibana (ELK) stack or similar.
 151
 152 Enabling tracing for all executed sql statements is done by changing hibernate
 153 loggers log level
 154
 155 Logger configuration is provided as a chart resource :
 156
 157     +--------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
 158     | cps-component-service-name     | logback.xml location                                                                                                                          |
 159     +================================+===============================================================================================================================================+
 160     | cps-core                       | `logback-spring.xml <https://github.com/onap/oom/blob/master/kubernetes/cps/components/cps-core/resources/config/logback-spring.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>:8080/actuator/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>:8080/actuator/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>:8080/actuator/prometheus
 194
 195 Hazelcast
 196 ---------
 197
 198 Hazelcast cluster state and health check can be seen using the below endpoints
 199
 200 .. code::
 201
 202     http://<cps-component-service-name>:<member-port>/hazelcast/health
 203     http://<cps-component-service-name>:<member-port>/hazelcast/rest/management/cluster/state
 204
 205 See also : :ref:`cps_common_distributed_datastructures`
 206
 207 Naming Validation
 208 -----------------
 209
 210 As part of the Kohn 3.1.0 release, CPS has added validation to the names of the following components:
 211
 212     - Dataspace names
 213     - Schema Set names
 214     - Anchor names
 215     - Cm-Handle identifiers
 216
 217 The following characters along with spaces are no longer valid for naming of these components.
 218
 219 .. code::
 220
 221     !"#$%&'()*+,./\:;<=>?@[]^`{|}~