docs/developer-guide.rst

   1 ..\r
   2 .. Copyright (c) 2019 AT&T Intellectual Property.\r
   3 ..\r
   4 .. Copyright (c) 2019 Nokia.\r
   5 ..\r
   6 ..\r
   7 .. Licensed under the Creative Commons Attribution 4.0 International\r
   8 ..\r
   9 .. Public License (the "License"); you may not use this file except\r
  10 ..\r
  11 .. in compliance with the License. You may obtain a copy of the License at\r
  12 ..\r
  13 ..\r
  14 ..     https://creativecommons.org/licenses/by/4.0/\r
  15 ..\r
  16 ..\r
  17 .. Unless required by applicable law or agreed to in writing, documentation\r
  18 ..\r
  19 .. distributed under the License is distributed on an "AS IS" BASIS,\r
  20 ..\r
  21 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  22 ..\r
  23 .. See the License for the specific language governing permissions and\r
  24 ..\r
  25 .. limitations under the License.\r
  26 ..\r
  27 .. This source code is part of the near-RT RIC (RAN Intelligent Controller) platform project (RICP).\r
  28 ..\r
  29 \r
  30 Developer Guide\r
  31 ===============\r
  32 \r
  33 Clone the golog git repository\r
  34 --------------------------------------\r
  35 .. code:: bash\r
  36 \r
  37  git clone "https://gerrit.o-ran-sc.org/r/com/golog"\r
  38 \r
  39 Initialization\r
  40 --------------\r
  41 \r
  42 A new logger instance is created with InitLogger function. Process identity is given as a parameter.\r
  43 \r
  44 Mapped Diagnostics Context\r
  45 --------------------------\r
  46 \r
  47 The MDCs are key-value pairs, which are included to all log entries by the library.\r
  48 The MDC pairs are logger instance specific.\r
  49 \r
  50 The idea of the MDC is to define values, which stay the same over multiple log writings.\r
  51 An MDC value set once will appear in all the subsequent logs written with the logger instance.\r
  52 \r
  53 A logger instance can be shared by several goroutines.\r
  54 Respectively, also the MDC values of the logger instance are then shared by them.\r
  55 When sharing of the MDCs is not desired, separate logger instances should be used.\r
  56 \r
  57 Log entry format\r
  58 ----------------\r
  59 \r
  60 Each log entry written the library contains\r
  61 \r
  62  * Timestamp\r
  63  * Logger identity\r
  64  * Log entry severity\r
  65  * MDC pairs of the logger instance\r
  66  * Log message text\r
  67 \r
  68 Currently the library only supports JSON formatted output written to standard out of the process\r
  69 \r
  70 *Example log output*\r
  71 \r
  72 `{"ts":1551183682974,"crit":"INFO","id":"myprog","mdc":{"second key":"other value","mykey":"keyval"},"msg":"hello world!"}`\r
  73 \r
  74  `{"ts":1602081593063,"crit":"INFO","id":"myapp","mdc":{"PID":"21587","POD_NAME":"tta-app-5565fc4d6f-ppfl8","CONTAINER_NAME":"tta-app","SERVICE_NAME":"TEST_APP","HOST_NAME":"master-an","SYSTEM_NAME":"CloudSpace-0"},"msg":"This is an example log"}`\r
  75 \r
  76 Example\r
  77 -------\r
  78 \r
  79 .. code:: bash\r
  80 \r
  81  package main\r
  82 \r
  83  import (\r
  84         mdcloggo "gerrit.o-ran-sc.org/r/com/golog"\r
  85  )\r
  86 \r
  87  func main() {\r
  88     logFileMonitor := 0;\r
  89     logger, _ := mdcloggo.InitLogger("myname")\r
  90     if(logger.Mdclog_format_initialize(logFileMonitor)!=0) {\r
  91         logger.Error("UnSuccessful Format Initialize")\r
  92     }\r
  93     logger.MdcAdd("mykey", "keyval")\r
  94     logger.Info("Some test logs")\r
  95  } \r
  96 \r
  97 Logging Levels\r
  98 --------------\r
  99 \r
 100 .. code:: bash\r
 101 \r
 102  // ERR is an error level log entry.\r
 103    ERR Level = 1\r
 104  // WARN is a warning level log entry.\r
 105    WARN Level = 2\r
 106  // INFO is an info level log entry.\r
 107    INFO Level = 3\r
 108  // DEBUG is a debug level log entry.\r
 109    DEBUG Level = 4\r
 110 \r
 111 Golog API's\r
 112 -----------\r
 113 \r
 114 1. LevelSet sets the current logging level.\r
 115 \r
 116 .. code:: bash\r
 117 \r
 118  func (l *MdcLogger) LevelSet(level Level) \r
 119 \r
 120 \r
 121 2. LevelGet returns the current logging level.\r
 122 \r
 123 .. code:: bash\r
 124 \r
 125  func (l *MdcLogger) LevelGet() Level\r
 126 \r
 127 3. MdcAdd adds a new MDC key value pair to the logger.\r
 128 \r
 129 .. code:: bash\r
 130 \r
 131  func (l *MdcLogger) MdcAdd(key string, value string)\r
 132 \r
 133 4. MdcRemove removes an MDC key from the logger.\r
 134 \r
 135 .. code:: bash\r
 136 \r
 137  func (l *MdcLogger) MdcRemove(key string)\r
 138 \r
 139 5. MdcGet gets the value of an MDC from the logger.\r
 140 \r
 141 .. code:: bash\r
 142 \r
 143  func (l *MdcLogger) MdcGet(key string) (string, bool)\r
 144 \r
 145 Description: The function returns the value string and a boolean which tells if the key was found or not.\r
 146 \r
 147 6. MdcClean removes all MDC keys from the logger.\r
 148 \r
 149 .. code:: bash\r
 150 \r
 151  func (l *MdcLogger) MdcClean()\r
 152 \r
 153 7. Mdclog_format_initialize Adds the MDC log format with HostName, PodName, ContainerName, ServiceName,PID,CallbackNotifyforLogFieldChange\r
 154 \r
 155 .. code:: bash\r
 156 \r
 157  func (l *MdcLogger) Mdclog_format_initialize(log_change_monitor int) (int)\r
 158 \r
 159 Description:  This api Initialzes mdclog print format using MDC Array by extracting the environment variables in the calling process for "SYSTEM_NAME", "HOST_NAME", "SERVICE_NAME", "CONTAINER_NAME", "POD_NAME" & "CONFIG_MAP_NAME"  mapped to HostName, ServiceName, ContainerName, Podname and Configuration-file-name of the services respectively.\r
 160 \r
 161   Note: In K8s/Docker Containers the environment variables are declared in the Helm charts.\r
 162 \r
 163   Refer xAPP developer guide for more information about how to define Helm chart.\r