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
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97