mdclogpy/README.md

   1 Mdclogpy
   2 ========
   3
   4 Structured logging library with Mapped Diagnostic Context
   5
   6 * Outputs the log entries to standard out in structured format, json currently.
   7 * Severity based filtering.
   8 * Supports Mapped Diagnostic Context (MDC).
   9   Set MDC pairs are automatically added to log entries by the library.
  10
  11
  12 Log entry format
  13 ----------------
  14
  15 Each log entry written with mdclog_write() function contains
  16
  17 * Timestamp
  18 * Logger identity
  19 * Log entry severity
  20 * All existing MDC pairs
  21 * Log message text
  22
  23 Currently the library only supports JSON formatted output written to standard
  24 out of the process.
  25
  26 *Example log output*
  27
  28 `{"ts": 1603103945651, "crit": "ERROR", "id": "test.py", "mdc": {"PID":101,"SYSTEM_NAME": "Cloud-Space", "HOST_NAME": "master", "SERVICE_NAME": "TestApp", "CONTAINER_NAME": "", "POD_NAME": ""}, "msg": "Hello World!"}`
  29
  30
  31 Install
  32 -------
  33
  34 Install from PyPi
  35
  36 ```
  37 python3 -m pip install mdclogpy
  38 ```
  39
  40 Install using the source
  41
  42 ```
  43 python3 setup.py install
  44 ```
  45
  46 Usage
  47 -----
  48
  49 The library can be used in two ways shown below.
  50
  51 1) Use the root logger
  52
  53 ```python
  54   import mdclogpy
  55   mdclogpy.mdclog_format_init(configmap_monitor=True)
  56   mdclogpy.error("This is an error log")
  57 ```
  58
  59 2) Create a logger instance
  60
  61 ```python
  62   from mdclogpy import Logger
  63   my_logger = Logger()
  64   my_logger.mdclog_format_init(configmap_monitor=True)
  65   my_logger.error("This is an error log")
  66 ```
  67
  68 A program can create several logger instances.
  69
  70 mdclog_format_init() Adds the MDC log format with HostName, PodName, ContainerName, ServiceName,PID,CallbackNotifyforLogFieldChange
  71
  72 Pass configmap_monitor = False in mdclog_format_init() function to stop dynamic log level change based on configmap.
  73
  74
  75 Mapped Diagnostics Context
  76 --------------------------
  77
  78 The MDCs are logger instance specific key-value pairs, which are included to
  79 all log entries written via the logger instance.
  80
  81 By default, the library implements a root logger instance.
  82 MDCs added to the root logger instance are added only to the log entries
  83 written via the root logger instance.
  84
  85
  86 License
  87 -------
  88
  89 Copyright (c) 2019 AT&T Intellectual Property.
  90 Copyright (c) 2018-2019 Nokia.
  91
  92 Licensed under the Apache License, Version 2.0 (the "License");
  93 you may not use this file except in compliance with the License.
  94 You may obtain a copy of the License at
  95
  96     http://www.apache.org/licenses/LICENSE-2.0
  97
  98 Unless required by applicable law or agreed to in writing, software
  99 distributed under the License is distributed on an "AS IS" BASIS,
 100 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 101 See the License for the specific language governing permissions and
 102 limitations under the License.
 103
 104 This source code is part of the near-RT RIC (RAN Intelligent Controller)
 105 platform project (RICP).
 106
 107 Unit testing
 108 ------------
 109
 110 To run the unit tests run the following command in the package directory::
 111 `
 112 python3 -m unittest discover
 113 `
 114
 115 CI
 116 --
 117
 118 The ci is done with the `tox` tool. See `tox.ini` file for details.