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": 1559285893047, "crit": "INFO", "id": "myprog", "mdc": {"second key":"other value","mykey":"keyval"}, "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.error("This is an error log")
  97  ```
  98
  99 2) Create a logger instance
 100
 101 .. code:: bash
 102
 103  ```python
 104    from mdclogpy import Logger
 105    my_logger = Logger()
 106    my_logger.error("This is an error log")
 107  ```
 108
 109 A program can create several logger instances.
 110
 111 Logging Levels
 112 --------------
 113 .. code:: bash
 114
 115  """Severity levels of the log messages."""
 116      DEBUG = 10
 117      INFO = 20
 118      WARNING = 30
 119      ERROR = 40
 120
 121 Pylog API's
 122 -----------
 123
 124 1. Set current logging level
 125
 126 .. code:: bash
 127
 128  def set_level(self, level: Level):
 129
 130         Keyword arguments:
 131         level -- logging level. Log messages with lower severity will be filtered.
 132
 133 2. Return the current logging level
 134
 135 .. code:: bash
 136
 137  def get_level(self) -> Level:
 138
 139 3. Add a logger specific MDC
 140
 141 .. code:: bash
 142
 143  def add_mdc(self, key: str, value: Value):
 144
 145         Keyword arguments:
 146         key -- MDC key
 147         value -- MDC value
 148
 149 4. Return logger's MDC value with the given key or None
 150
 151 .. code:: bash
 152
 153  def get_mdc(self, key: str) -> Value:
 154
 155 5. Remove logger's MDC with the given key
 156
 157 .. code:: bash
 158
 159  def remove_mdc(self, key: str):
 160
 161 6. Remove all MDCs of the logger instance.
 162
 163 .. code:: bash
 164
 165  def clean_mdc(self):
 166
 167
 168 License
 169 -------
 170
 171 Copyright (c) 2019 AT&T Intellectual Property.
 172 Copyright (c) 2018-2019 Nokia.
 173
 174 Licensed under the Apache License, Version 2.0 (the "License");
 175 you may not use this file except in compliance with the License.
 176 You may obtain a copy of the License at
 177
 178     http://www.apache.org/licenses/LICENSE-2.0
 179
 180 Unless required by applicable law or agreed to in writing, software
 181 distributed under the License is distributed on an "AS IS" BASIS,
 182 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 183 See the License for the specific language governing permissions and
 184 limitations under the License.
 185
 186 This source code is part of the near-RT RIC (RAN Intelligent Controller)
 187 platform project (RICP).
 188
 189 Unit testing
 190 ------------
 191
 192 To run the unit tests run the following command in the package directory
 193
 194 .. code:: bash
 195
 196  python3 -m unittest discover
 197