Logging (not tracing)

Logging from C

Gerrit repo: https://gerrit.o-ran-sc.org/r/admin/repos/com/log

RIC provides a C library for logging: mdclog. The library implements thread-local MDC management and formatting of the logs into the correct JSON format.

Logging from Go

The native Golang version of RIC logging library is in Gerrit: https://gerrit.o-ran-sc.org/r/admin/repos/com/golog

The Go version of the library works like the C version, except that the MDC values are not thread but logger instance specific. The mdclog C library can also be used from Go, but note that the thread-local MDCs do not work with Go goroutines. An example of how to use the mdclog C library from Go is shown below.

package main
 
/*
#cgo CFLAGS: -I/usr/local/include
#cgo LDFLAGS: -lmdclog
#
#include <mdclog/mdclog.h>
void my_log_write(mdclog_severity_t severity, const char *msg) {

   mdclog_write(severity, "%s", msg);
}
*/
import "C"
import "fmt"
 
func mylog(severity C.mdclog_severity_t, msg string) {

    C.my_log_write(severity, C.CString(msg))
}
 
func main() {

      C.mdclog_mdc_add(C.CString("Weather"), C.CString("Sunny"))
   C.mdclog_mdc_add(C.CString("Temperature"), C.CString("15.5"))
   mylog(C.MDCLOG_INFO, fmt.Sprintf("Weather report log"))
}

Logging from Python

Gerrit repo: https://gerrit.o-ran-sc.org/r/admin/repos/com/pylog  You can also install the python library using pip: python3 -m pip install mdclogpy

RIC provides a Python library for logging: mdclogpy. The Python version of the library works like the Golang version, i.e. the MDC values are logger instance specific.

MDC (Mapped Diagnostic Context)

MDC is a list of key-value pairs the RIC components can define to be included in their logs. It is currently rarely used in RIC.

MDC keyMDC value (type, range, list of values, format, ...)DescriptionComponents using the MDCComments
Weather

Possible values: sunny, cloudy, rainy, snowy

Weather type included in every log made by the Weather Manager.Weather Manager xAppThis is an example.
TemperatureValue range from -100.0 to 100.0 with one decimal. Example: 15.5Temperature (Celsius degrees) included in every log made by the Weather Manager.Weather Manager xAppThis is an example.
timeyyyy-MM-dd HH:mm:ss.SSSHuman readable timestamp. Note that the timezone can be derived from comparing this value against the ts millisecond timestamp in the same log entry.E2 Manager

Example:

{"crit":"INFO","ts":1560266556006,"id":"E2Manager","msg":"#rmrCgoApi.Init - RMR router has been initiated","mdc":{"time":"2019-06-11 15:22:36.006"}}







Severity Levels

The following severity levels are used in RIC:

  • DEBUG - information useful for debugging
  • INFO - informational message related to normal operation
  • WARNING - indication of a potential error
  • ERROR - error condition

Fields in the log entry

  • ts – Timestamp, number of milliseconds since Unix Epoch (i.e. 1970-01-01 00:00:00 +0000 (UTC)), set by the logging library
  • crit – Severity level of the log, given by the application process: DEBUG, INFO, WARNING, ERROR
  • id – the name of the process, set by the logging library
  • msg – log message given by the application process
  • mdc – a list of key value pairs, both strings, unique key names, given by the application process

The logging library writes the logs to stdout. Each log entry is one line. All line feed characters, as well as non-printable characters, are replaced with a space by the logging library. In addition, characters having a special meaning in the output format are escaped by the logging library. The logging library supports only JSON format, only. Having named fields is flexible from post-processing point of view and, as we might have new requirements from the applications in later releases, allows us to easily add, remove or modify the fields to the logs in the future, if needed. If other formats are needed, we can add them as configurable options in the future versions. The format of each field (e.g. timestamp) can also be made configurable in the future versions of the logging library, if needed. No separate “markers”, which are defined in the ONAP specification (https://wiki.onap.org/pages/viewpage.action?pageId=28378955#ONAPApplicationLoggingSpecificationv1.2(Casablanca)), are supported. Reasoning is that this is a tracing concept and needs to be covered by a tracing solution such as OpenTracing. It will cover the functionality of having specific ENTRY, EXIT, INVOKE etc marked logs. In the following examples, the process has logged an INFO log with message “This is an example log” and with two key-value pairs "key1"="value1" and "key2"="value with a space". The one-line log has been divided into several lines for readability.

JSON

{
    "ts": 1550045469,
    "crit": "INFO",
    "id": "applicationABC",
    "msg": "This is an example log",
"mdc":
{
    "key1": "value1",
    "key2": "value with a space"
}
}

CSV (proposal for future development)

With a comma as a separator in this example. The separator could be made configurable.

1550045469,
INFO,
applicationABC,
This is an example log,
key1=value1 key2=value with a space

Key-value pairs (proposal for future development)

With a colon as a separator in this example. The separator could be made configurable.

timestamp=1550045469:
severity=INFO:
logger=applicationABC:
message=This is an example log:
key1=value1:
key2=value with a space