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": 1559285893047, "crit": "INFO", "id": "myprog", "mdc": {"second key":"other value","mykey":"keyval"}, "msg": "Hello world!"}`
  29
  30 Install
  31 -------
  32
  33 Install from PyPi
  34
  35 ```
  36 python3 -m pip install mdclogpy
  37 ```
  38
  39 Install using the source
  40
  41 ```
  42 python3 setup.py install
  43 ```
  44
  45 Usage
  46 -----
  47
  48 The library can be used in two ways shown below.
  49
  50 1) Use the root logger
  51
  52 ```python
  53   import mdclogpy
  54   mdclogpy.error("This is an error log")
  55 ```
  56
  57 2) Create a logger instance
  58
  59 ```python
  60   from mdclogpy import Logger
  61   my_logger = Logger()
  62   my_logger.error("This is an error log")
  63 ```
  64
  65 A program can create several logger instances.
  66
  67
  68 Mapped Diagnostics Context
  69 --------------------------
  70
  71 The MDCs are logger instance specific key-value pairs, which are included to
  72 all log entries written via the logger instance.
  73
  74 By default, the library implements a root logger instance.
  75 MDCs added to the root logger instance are added only to the log entries
  76 written via the root logger instance.
  77
  78
  79 License
  80 -------
  81
  82 Copyright (c) 2019 AT&T Intellectual Property.
  83 Copyright (c) 2018-2019 Nokia.
  84
  85 Licensed under the Apache License, Version 2.0 (the "License");
  86 you may not use this file except in compliance with the License.
  87 You may obtain a copy of the License at
  88
  89     http://www.apache.org/licenses/LICENSE-2.0
  90
  91 Unless required by applicable law or agreed to in writing, software
  92 distributed under the License is distributed on an "AS IS" BASIS,
  93 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  94 See the License for the specific language governing permissions and
  95 limitations under the License.
  96
  97
  98 Unit testing
  99 ------------
 100
 101 To run the unit tests run the following command in the package directory::
 102 `
 103 python3 -m unittest discover
 104 `