docs/developer-guide.rst

   1 ..
   2 .. Copyright (c) 2019 AT&T Intellectual Property.
   3 ..
   4 .. Copyright (c) 2019 Nokia.
   5 ..
   6 ..
   7 .. Licensed under the Creative Commons Attribution 4.0 International
   8 ..
   9 .. Public License (the "License"); you may not use this file except
  10 ..
  11 .. in compliance with the License. You may obtain a copy of the License at
  12 ..
  13 ..
  14 ..     https://creativecommons.org/licenses/by/4.0/
  15 ..
  16 ..
  17 .. Unless required by applicable law or agreed to in writing, documentation
  18 ..
  19 .. distributed under the License is distributed on an "AS IS" BASIS,
  20 ..
  21 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  22 ..
  23 .. See the License for the specific language governing permissions and
  24 ..
  25 .. limitations under the License.
  26 ..
  27 .. This source code is part of the near-RT RIC (RAN Intelligent Controller)
  28 ..
  29 .. platform project (RICP).
  30 ..
  31
  32
  33 Developer Guide
  34 ===============
  35
  36 Clone the pylog git repository
  37 ------------------------------
  38 .. code:: bash
  39
  40  git clone "https://gerrit.o-ran-sc.org/r/com/pylog"
  41
  42
  43 Mapped Diagnostics Context
  44 --------------------------
  45
  46 The MDCs are logger instance specific key-value pairs, which are included to
  47 all log entries written via the logger instance.
  48
  49 By default, the library implements a root logger instance.
  50 MDCs added to the root logger instance are added only to the log entries
  51 written via the root logger instance.
  52
  53 Log entry format
  54 ----------------
  55
  56 Each log entry written with mdclog_write() function contains
  57
  58 * Timestamp
  59 * Logger identity
  60 * Log entry severity
  61 * All existing MDC pairs
  62 * Log message text
  63
  64 Currently the library only supports JSON formatted output written to standard
  65 out of the process.
  66
  67 *Example log output*
  68
  69 `{"ts": 1603103945651, "crit": "ERROR", "id": "test.py", "mdc": {"PID":101,"SYSTEM_NAME": "Cloud-Space", "HOST_NAME": "master", "SERVICE_NAME": "TestApp", "CONTAINER_NAME": "Container-101", "POD_NAME": "POD-101"}, "msg": "Hello World!"}`
  70
  71 Install
  72 -------
  73 Install from PyPi
  74
  75 .. code:: bash
  76
  77  python3 -m pip install mdclogpy
  78
  79 Install using the source
  80
  81 .. code:: bash
  82
  83  python3 setup.py install
  84
  85 Usage
  86 -----
  87
  88 The library can be used in two ways shown below.
  89
  90 1) Use the root logger
  91
  92 .. code:: bash
  93
  94  ```python
  95    import mdclogpy
  96    mdclogpy.mdclog_format_init(configmap_monitor=True)
  97    mdclogpy.error("This is an error log")
  98  ```
  99
 100 2) Create a logger instance
 101
 102 .. code:: bash
 103
 104  ```python
 105    from mdclogpy import Logger
 106    my_logger = Logger()
 107    my_logger.mdclog_format_init(configmap_monitor=True)
 108    my_logger.error("This is an error log")
 109  ```
 110
 111 A program can create several logger instances.
 112
 113 mdclog_format_init() Adds the MDC log format with HostName, PodName, ContainerName, ServiceName,PID,CallbackNotifyforLogFieldChange
 114
 115 Pass configmap_monitor = False in mdclog_format_init() function to stop dynamic log level change based on configmap.
 116
 117 Logging Levels
 118 --------------
 119 .. code:: bash
 120
 121  """Severity levels of the log messages."""
 122      DEBUG = 10
 123      INFO = 20
 124      WARNING = 30
 125      ERROR = 40
 126
 127 Pylog API's
 128 -----------
 129
 130 1. Set current logging level
 131
 132 .. code:: bash
 133
 134  def set_level(self, level: Level):
 135
 136         Keyword arguments:
 137         level -- logging level. Log messages with lower severity will be filtered.
 138
 139 2. Return the current logging level
 140
 141 .. code:: bash
 142
 143  def get_level(self) -> Level:
 144
 145 3. Add a logger specific MDC
 146
 147 .. code:: bash
 148
 149  def add_mdc(self, key: str, value: Value):
 150
 151         Keyword arguments:
 152         key -- MDC key
 153         value -- MDC value
 154
 155 4. Return logger's MDC value with the given key or None
 156
 157 .. code:: bash
 158
 159  def get_mdc(self, key: str) -> Value:
 160
 161 5. Remove logger's MDC with the given key
 162
 163 .. code:: bash
 164
 165  def remove_mdc(self, key: str):
 166
 167 6. Remove all MDCs of the logger instance.
 168
 169 .. code:: bash
 170
 171  def clean_mdc(self):
 172
 173
 174 7. Initialise Logging format:
 175
 176 This api Initialzes mdclog print format using MDC Dictionary by extracting the environment variables in the calling process for “SYSTEM_NAME”, “HOST_NAME”, “SERVICE_NAME”, “CONTAINER_NAME”, “POD_NAME” & “CONFIG_MAP_NAME” mapped to HostName, ServiceName, ContainerName, Podname and Configuration-file-name of the services respectively.
 177
 178
 179 .. code:: bash
 180
 181  def mdclog_format_init(configmap_monitor=False):
 182
 183         Keyword arguments:
 184         configmap_monitor -- Enables/Disables Dynamic log level change based on configmap
 185                           -- Boolean values True/False can be passed as per requirement.
 186
 187
 188
 189 License
 190 -------
 191
 192 Copyright (c) 2019 AT&T Intellectual Property.
 193 Copyright (c) 2018-2019 Nokia.
 194
 195 Licensed under the Apache License, Version 2.0 (the "License");
 196 you may not use this file except in compliance with the License.
 197 You may obtain a copy of the License at
 198
 199     http://www.apache.org/licenses/LICENSE-2.0
 200
 201 Unless required by applicable law or agreed to in writing, software
 202 distributed under the License is distributed on an "AS IS" BASIS,
 203 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 204 See the License for the specific language governing permissions and
 205 limitations under the License.
 206
 207 This source code is part of the near-RT RIC (RAN Intelligent Controller)
 208 platform project (RICP).
 209
 210 Unit testing
 211 ------------
 212
 213 To run the unit tests run the following command in the package directory
 214
 215 .. code:: bash
 216
 217  python3 -m unittest discover
 218