docs/specs/logging_enablement.rst

   1 ..
   2  This work is licensed under a Creative Commons Attribution 4.0
   3  International License.
   4
   5 =================
   6 Multi-Vim logging
   7 =================
   8
   9 The purpose of logging is to generate machine-readable, indexable output logs
  10 and support to trace
  11 requests through sub-component, it need to ship logs to logging enhancement
  12 project a centralized
  13 logging analysis system capturing diagnostic information.
  14
  15
  16
  17 Problem Description
  18 ===================
  19
  20 So far the logging of multi-vim is not able to support customer configuration,
  21 handler context specific logging like
  22 MDC[MDC_Document]_, also it dose't propagate transaction-ID in REST headers
  23 which is critical to tracing request.
  24 There are 4 python containers in oom project need to configure filebeat
  25 container for shipping logs.
  26
  27 .. [MDC_Document] https://wiki.onap.org/display/DW/ONAP+Application+Logging+Guidelines+v1.1#ONAPApplicationLoggingGuidelinesv1.1-MDCs
  28
  29 In addition the current logging is very difficult to understand behavior
  30 and performance.
  31
  32
  33 Proposed Change
  34 ===============
  35
  36 The proposed change will include three parts.
  37
  38 Filebeat container
  39 ------------------
  40
  41 Logging architecture[Log_Architecture]_ use Filebeat collects logs from
  42 multi-vim containers and ships them to the
  43 centralized logging stack. To enable this feature it need to add Filebeat
  44 container in multi-vim pod that was
  45 deployed by OOM, as well Yaml file will be used to configure Filebeat.
  46
  47 .. [Log_Architecture] https://wiki.onap.org/display/DW/Logging+Architecture
  48
  49 Tracing ID
  50 ----------
  51
  52 ONAP logging uses a global unique "RequestID"[RequestID_Document]_ in logging
  53 to track the processing of each request
  54 across all the components, multi-vim will receive this id from http header
  55 by vary "X-TransactionID", then record it
  56 in logs.
  57 Meanwhile single component should generate a InvocationID that records the
  58 relationship between RequestID
  59 and InvocationID for proper tracing. So Mulit-vim will set unique InvocationID
  60 for each single request,also output it in logs.
  61
  62 .. [RequestID_Document] https://wiki.onap.org/pages/viewpage.action?pageId=20087036#ONAPApplicationLoggingGuidelinesv1.2(Beijing)-MDC-RequestID
  63
  64
  65 python AOP logging library
  66 --------------------------
  67
  68 Currently logging enhancement project just has java AOP logging library, For
  69 multi-vim which based on python need
  70 a python version. The basic feature of AOP logging library could provide
  71 customer configuration include retention
  72 policy、output location、text output format、message level and so on, support
  73 MDC context specific logging, able to
  74 change configuration at runtime, and make logging quite fast.
  75
  76 Supporting Python3 version
  77 -------------------------
  78 Right now, this library only has be used in Python2 version. Python2 will not been
  79 maintained after 2020, besides part of ONAP project have used python3 version.
  80 It's be better to support Python2 and Python3 version
  81
  82
  83 Markers
  84 -------
  85 Markers can be used to characterize log entries. They allow message that has
  86 a specific meaning to be cheaply and easily identified in logger output, without
  87 inherently unreliable schemes like scanning for magic strings in the text of each
  88 log message.
  89 Onap logging requires the emission of markers reporting entry, exit and invocation
  90 as the execution if requests pass between ONAP components. This information is used
  91 to generate a call graph.
  92 Useful and commonplace, See https://stackoverflow.com/questions/4165558/best-practices-for-using-markers-in-slf4j-logback
  93
  94
  95 colored terminal output
  96 -----------------------
  97 As we known, in log4j coloring is supported. It would be better to render logging messages in colors.
  98 Bash colors refer: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
  99
 100 The standard colors(nosupport windows) list as below:
 101 +---------------------+-------------------------+------------------------+
 102 | **Text color**      | **Hightlight color**    |  **Text Attribute**    |
 103 +=====================+==================================================+
 104 |  Black              |   Black                 |   Normal               |
 105 +---------------------+--------------------------------------------------+
 106 |  Red                |   Red                   |   Bold                 |
 107 +---------------------+--------------------------------------------------+
 108 |  Green              |   Green                 |   Underline            |
 109 +---------------------+--------------------------------------------------+
 110 |  Yellow             |   Yellow                |   Blink                |
 111 +------------------------------------------------------------------------+
 112 |  Blue               |   Blue                  |   Invert               |
 113 +------------------------------------------------------------------------+
 114 |  Purple             |   Purple                |   Hide                 |
 115 +------------------------------------------------------------------------+
 116 |  Cyan               |   Cyan                  |                        |
 117 +------------------------------------------------------------------------+
 118 |  White              |   White                 |                        |
 119 +------------------------------------------------------------------------+
 120
 121
 122 Test
 123 ====
 124
 125 #. Unit tests with tox
 126 #. CSIT tests, verify marker label in logging message