pylog/README.md

   1 # ONAP python logging package
   2 - python-package onappylog extend python standard logging library which
   3 could be used in any python project to log MDC(Mapped Diagnostic Contex)
   4 and easy to reload logging at runtime.
   5
   6 -----
   7
   8 ## install package
   9 ```bash
  10   pip install onappylog
  11 ```
  12
  13 ## Usage
  14
  15 ### 1. MDC monkey patch
  16
  17 Import the MDC monkey patch making logRecord to store context in local thread.
  18
  19 ```python
  20    from onaplogging import monkey; monkey.patch_loggingMDC()
  21 ```
  22 Import the MDC format to be used to configure mdc output format.
  23 Please replace your old logging format with mdc format in configuration.
  24
  25
  26 ```python
  27   from onaplogging import mdcformatter
  28 ```
  29 the mdc format  example
  30 ```python
  31 'mdcFormater':{
  32           '()': mdcformatter.MDCFormatter, # Use MDCFormatter instance to convert logging string
  33           'format': '%(mdc)s and other %-style key ', #  Add '%(mdc)s' here.
  34           'mdcfmt':  '{key1} {key2}', # Define your mdc keys here.
  35           'datefmt': '%Y-%m-%d %H:%M:%S'  # date format
  36       }
  37 ```
  38
  39 Import MDC to store context in python file with logger
  40 code.
  41
  42 ```python
  43 from onaplogging.mdcContext import MDC
  44 # add mdc
  45 MDC.put("key1", "value1")
  46 MDC.put("key2", "value2")
  47
  48 # origin code
  49 logger.info("msg")
  50 logger.debug("debug")
  51
  52 ```
  53
  54 ### 2. Reload logging at runtime
  55
  56 It's thread safe to reload logging. If you want to use this feature,
  57 must use yaml file to configure logging.
  58
  59
  60 import the  yaml monkey patch and load logging yaml file
  61
  62 ```python
  63   from onaplogging import monkey,monkey.patch_loggingYaml()
  64   # yaml config
  65   config.yamlConfig(filepath=<yaml filepath>, watchDog=True)
  66 ```
  67
  68 Notice that the watchDog is opening,So your logging could be reloaded at runtime.
  69 if you modify yaml file to change handler、filter or format,
  70 the logger in program will be reloaded to use new configuration.
  71
  72 Set watchDog to **false**, If you don't need to reloaded logging.
  73
  74
  75
  76
  77 Yaml configure exmaple
  78
  79 ```yaml
  80 version: 1
  81
  82 disable_existing_loggers: True
  83
  84 loggers:
  85 vio:
  86     level: DEBUG
  87     handlers: [vioHandler]
  88     propagate: False
  89 handlers:
  90 vioHandler:
  91     class: logging.handlers.RotatingFileHandler
  92     level: DEBUG
  93     filename: /var/log/bt.log
  94     mode: a
  95     maxBytes: 1024*1024*50
  96     backupCount: 10
  97     formatter: mdcFormatter
  98 formatters:
  99   mdcFormatter:
 100     format: "%(asctime)s:[%(name)s] %(created)f %(module)s %(funcName)s %(pathname)s %(process)d %(levelno)s :[ %(threadName)s  %(thread)d]: [%(mdc)s]: [%(filename)s]-[%(lineno)d] [%(levelname)s]:%(message)s"
 101     mdcfmt: "{key1} {key2} {key3} {key4} dwdawdwa "
 102     datefmt: "%Y-%m-%d %H:%M:%S"
 103     (): onaplogging.mdcformatter.MDCFormatter
 104   standard:
 105     format: '%(asctime)s:[%(name)s]:[%(filename)s]-[%(lineno)d]
 106         [%(levelname)s]:%(message)s  '
 107     datefmt: "%Y-%m-%d %H:%M:%S"
 108
 109 ```
 110
 111
 112 ### 3. reference
 113
 114 [What's MDC?](https://logging.apache.org/log4j/2.x/manual/thread-context.html)
 115
 116 [Onap Logging Guidelines](https://wiki.onap.org/pages/viewpage.action?pageId=20087036)
 117
 118 [Python Standard Logging Library](https://docs.python.org/2/library/logging.html)