README.md

   1 Logging Library with MDC support
   2 ================================
   3
   4 A Golang implementation of a structured logging library with Mapped Diagnostics Context (MDC) support.
   5
   6 Overview
   7 --------
   8
   9 ### Initialization
  10
  11 A new logger instance is created with InitLogger function. Process identity is given as a parameter.
  12
  13 ### Mapped Diagnostics Context
  14
  15 The MDCs are key-value pairs, which are included to all log entries by the library.
  16 The MDC pairs are logger instance specific.
  17
  18 The idea of the MDC is to define values, which stay the same over multiple log writings.
  19 An MDC value set once will appear in all the subsequent logs written with the logger instance.
  20
  21 A logger instance can be shared by several goroutines.
  22 Respectively, also the MDC values of the logger instance are then shared by them.
  23 When sharing of the MDCs is not desired, separate logger instances should be used.
  24
  25 ### Log entry format
  26
  27 Each log entry written the library contains
  28
  29  * Timestamp
  30  * Logger identity
  31  * Log entry severity
  32  * MDC pairs of the logger instance
  33  * Log message text
  34
  35 Currently the library only supports JSON formatted output written to standard out of the process
  36
  37 *Example log output*
  38
  39 `{"ts":1551183682974,"crit":"INFO","id":"myprog","mdc":{"second key":"other value","mykey":"keyval"},"msg":"hello world!"}`
  40
  41 Example
  42 -------
  43
  44 ```go
  45 package main
  46
  47 import (
  48         mdcloggo "gerrit.o-ran-sc.org/r/com/golog"
  49 )
  50
  51 func main() {
  52         logger, _ := mdcloggo.InitLogger("myname")
  53         logger.MdcAdd("mykey", "keyval")
  54     logger.Info("Some test logs")
  55 }
  56 ```
  57
  58 License
  59 -------
  60  Copyright (c) 2019 AT&T Intellectual Property.
  61  Copyright (c) 2018-2019 Nokia.
  62
  63  Licensed under the Apache License, Version 2.0 (the "License");
  64  you may not use this file except in compliance with the License.
  65  You may obtain a copy of the License at
  66
  67      http://www.apache.org/licenses/LICENSE-2.0
  68
  69  Unless required by applicable law or agreed to in writing, software
  70  distributed under the License is distributed on an "AS IS" BASIS,
  71  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  72  See the License for the specific language governing permissions and
  73  limitations under the License.
  74
  75  This source code is part of the near-RT RIC (RAN Intelligent Controller)
  76  platform project (RICP).
  77
  78 CI
  79 --
  80
  81 The Dockerfile in the `ci` directory _only_ runs, when build, the unit tests for the repository.
  82