Table of Contents

...

Original AT&T ONAP Logging guidelines (pre amsterdam release) - for historical reference only: https://wiki.onap.org/download/attachments/1015849/ONAP%20application%20logging%20guidelines.pdf?api=v2

The Acumos logging specification follows this document at https://wiki.acumos.org/display/OAM/Log+Standards

...

The library and aop wrapper are written in Java and will work for Clojure (thanks to a discussion with Shwetank that reminded my me of languages that compile to bytecode) and Scala as well. see: https://git.onap.org/logging-analytics/tree/reference

...

For the casablanca release there the logging specification has been updated and finalized as of June 2018. Implementation of this specification is required but the method of implementation is optional based on each team's level of possible engagement.

...

Use a spring based Aspect library that emits Markers automatically around function calls and retrofit your code to log via Luke's SLF4J for internal log messages.

LoggingWithAOP 16339021

Logging Library Location and Use

...

By selection of a logging provider such as Logback or Log4j, typically via the classpath.
By way of a provider configuration document, typically logback.xml or log4j.xml. See Providers 16339021.

SLF4J

SLF4J is a logging facade, and a humble masterpiece. It combines what's common to all major, modern Java logging providers into a single interface. This decouples the caller from the provider, and encourages the use of what's universal, familiar and proven.

...

Logback is the most commonly used provider. It is generally configured by an XML document named logback.xml. See Configuration 16339021.

See HELM template https://git.onap.org/logging-analytics/tree/reference/provider/helm/logback

...

Log4j 2.X is somewhat less common than Logback, but equivalent. It is generally configured by an XML document named log4j.xml. See Configuration 16339021.

Log4j 1.X

Strongly discouraged from Beijing onwards, since 1.X is EOL, and since it does not support escaping, so its output may not be machine-readable. See https://logging.apache.org/log4j/1.2/.

...

It isn't the aim of this document to reiterate Best Practices, so advice here is general:

Use a logger logging facade such as SLF4J or EELF.
Write log messages in English.
Write meaningful messages. Consider what will be useful to consumers of logger output.
Log at the appropriate level. Be aware of the volume of logs that will be produced.
Safeguard the information in exceptions, and ensure it is never lost.
Use errorcodes error codes to characterise characterize exceptions.
Log in a machine-readable format. See Conventions.
Log for analytics as well as troubleshooting.

...

See https://www.slf4j.org/api/org/slf4j/Logger.html and https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout for their origins and use.

Logger Name

This indicates the origin of a log name of the logger that logged the message.

It is confusingly named, and since in Java logging it is normally given as a class or package name, it's more often referred to as the logger "class" or "package"In Java it is convention to name the logger after the class or package using that logger.

In Java, report the class or package name.
In Python, the class or source filename.

...

Think carefully about the information you report at each loglevellog level. The default log level is INFO.

Some loggers define non-standard levels, like FINE, FINER, WARNING, SEVERE, FATAL or CRITICAL. Use these judiciously, or avoid them.

Message

The freetext free text payload of a log event.

This is the most important item of information in most log messages. See General 16339021 guidelines.

Internationalization

...

Code Block

language	java

if (logger.isDebugEnabled()) {
    logger.debug("But this WILL hurt: " + costlyToSerialize);
}

Parameterized logging is preferable.

Context

MDCs

A Mapped Diagnostic Context (MDC) allows an arbitrary string-valued attribute to be attached to a Java thread via a ThreadLocal variable. The MDC's value is then emitted with each message logged by that thread. The set of MDCs associated with a log message is serialized as unordered name-value pairs (see Text Output 16339021).

A good discussion of MDCs can be found at https://logback.qos.ch/manual/mdc.html.

...

Pipe Order	Name	Type	Description	Moved MDC to standard attribute	Required? Y/N/C (C= context dependent) N = not required L=Library provided	Historical	Acumos ref	Code References
1	LogTimestamp	log system	use %d field - see %d{"yyyy-MM-dd'T'HH:mm:ss.SSSXXX",UTC}		L
2	EntryTimestamp	MDC	if part of an ENTRY marker log		C
3	InvokeTimestamp	MDC	if part of an INVOKE marker log		C
4	RequestID	MDC	UUID to track the processing of each client request across all the ONAP components involved in its processing		Y			In general https://git.onap.org/logging-analytics/tree/reference/logging-slf4j-demo/src/test/java/org/onap/logging/ref/slf4j/demo/component/AbstractComponentTest.java
5	InvocationID	MDC	UUID correlates log entries relating to a single invocation of a single component In the case of an asynchronous request, the InvocationID should come from the original request		Y
6	InstanceID	MDC	UUID to differentiate between multiple instances of the same (named) log writing service/application		Y	was InstanceUUID
7	ServiceInstanceID	MDC			C
8	thread	log system	use %thread field		L
9	ServiceName		The service inside the partner doing the call - includes API name		Y
10	PartnerName	unauthenticated = The part of the URI specifying the agent that the caller used to make the call to the component that is logging the message. authenticated = userid	PartnerName	unauthenticated = The part of the URI specifying the agent that the caller used to make the call to the component that is logging the message. authenticated = userid If an authenticated API, then log the userid Otherwise, if the HTTP header "X-ONAP-PartnerName" was provided, then log that (note: this was a direction that we seemed to be going but never completed) Otherwise, if the HTTP header "User-Agent" was provided, then log that Otherwise, log "UNKNOWN" (since the field is currently required, something must be in it)			Y		user
11	StatusCode		This field indicates the high level status of the request - one of (COMPLETE, ERROR, INPROGRESS)		Y			20180807: expand from 2 fields to add "INPROGRESS" addresses Chris Lott question on https://wiki.acumos.org/display/OAM/Log+Standards
12	ResponseCode		This field contains application-specific error codes.		Y
13	ResponseDesc		This field contains a human readable description of the ResponseCode		Y
14	level		%level		L
15	Severity		Logging level by default aligned with the reported log level - one of INFO/TRACE/DEBUG/WARN/ERROR/FATAL		Y		level (but numbers)
16	ServerIPAddress				C
17	ElapsedTime				C
18	ServerFQDN		The VM FQDN if the server is virtualized. Otherwise the host name of the logging component.		Y
19	ClientIPAddress		This field contains the requesting remote client application’s IP address if known. Otherwise empty.		Y
20	VirtualServerName				C
21	ContextName				C
22	TargetEntity		The name of the ONAP component or sub-component, or external entity, at which the operation activities captured in this metrics log record is invoked.		C
23	TargetServiceName		The name of the API or operation activities invoked (name on the remote/target application) at the TargetEntity.		C
24	TargetElement		VNF/PNF context dependent - on CRUD operations of VNF/PNFs The IDs that need to be covered with the above Attributes are - VNF_ID OR VNFC_ID : (Unique identifier for a VNF asset that is being instantiated or that would generate an alarms) - VSERVER_ID OR VM_ID (or vmid): (Unique identified for a virtual server or virtual machine on which a Control Loop action is usually taken on, or that is installed as part of instantiation flow) - PNF : (What is the Unique identifier used within ONAP)		C
25	User	MDC	User - used for %X{user}		C
26	p_logger	log system	The name of the class doing the logging (in my case the ApplicationController – close to the targetservicename but at the class granular level - this field is %logger		L
27	p_mdc	log system	allows forward compatability with ELK indexers that read all MDCs in a single field - while maintaining separate MDCs above. The key/value pairs all in one pipe field (will have some duplications currently with MDC’s that are in their own pipe – but allows us to expand the MDC list – replaces customvalue1-3 older fields - this field is %mdc		L
28	p_message	log system	The marker labels INVOKE, ENTRY, EXIT – and later will also include DEBUG, AUDIT, METRICS, ERROR when we go to 1 log file - this field is %marker		L
	~~RootException~~	~~log system~~	~~%rootException - Dublin spec only~~		L
29	p_marker	log system	The marker labels INVOKE, ENTRY, EXIT – and later will also include DEBUG, AUDIT, METRICS, ERROR when we go to 1 log file - this field is %marker		L

...

Used as valuable URI - to annnote invoke marker

Review in terms of Marker 16339021 - INVOKE - possiblly add INVOKE-return - to filter reporting

...

Note there are 3 tabs (see p_mak in logback.xml) delimiting the MARKERS (ENTRY and EXIT) at the end of each line

<property name="p_mak" value="%replace(%replace(%marker){'\t', '\\\\t'}){'\n','\\\\n'}"/>

Code Block

language	java
theme	Midnight

2018-07-05T20:21:34.794Z	http-nio-8080-exec-2	INFO	org.onap.demo.logging.ApplicationService	InstanceID=ede7dd52-91e8-45ce-9406-fbafd17a7d4c, RequestID=f9d8bb0f-4b4b-4700-9853-d3b79d861c5b, ServiceName=/logging-demo/rest/health/health, InvocationID=8f4c1f1d-5b32-4981-b658-e5992f28e6c8, InvokeTimestamp=2018-07-05T20:21:26.617Z, PartnerName=, ClientIPAddress=0:0:0:0:0:0:0:1, ServerFQDN=localhost			ENTRY	
2018-07-05T20:22:09.268Z	http-nio-8080-exec-2	INFO	org.onap.demo.logging.ApplicationService	ResponseCode=, InstanceID=ede7dd52-91e8-45ce-9406-fbafd17a7d4c, RequestID=f9d8bb0f-4b4b-4700-9853-d3b79d861c5b, ServiceName=/logging-demo/rest/health/health, ResponseDescription=, InvocationID=8f4c1f1d-5b32-4981-b658-e5992f28e6c8, Severity=, InvokeTimestamp=2018-07-05T20:21:26.617Z, PartnerName=, ClientIPAddress=0:0:0:0:0:0:0:1, ServerFQDN=localhost, StatusCode=			EXIT

...

This should accompany INVOKE when the invocation is synchronous.

...

SLF4J:

Code Block

language	java
title	SLF4J
linenumbers	true

public static final Marker INVOKE_SYNCHRONOUS;
static {
    INVOKE_SYNCHRONOUS = MarkerFactory.getMarker("INVOKE");
    INVOKE_SYNCHRONOUS.add(MarkerFactory.getMarker("SYNCHRONOUS"));
}
// ...

// Generate and report invocation ID. 

final String invocationID = UUID.randomUUID().toString();
MDC.put(MDC_INVOCATION_ID, invocationID);
try {
    logger.debug(INVOKE_SYNCHRONOUS, "Invoking synchronously ... ");
}
finally {
    MDC.remove(MDC_INVOCATION_ID);
}

// Pass invocationID as HTTP X-InvocationID header.

callDownstreamSystem(invocationID, ... );

EELF example of SYNCHRONOUS reporting, without changing published APIs.

...

Error Codes

Errorcodes Error codes are reported as MDCs.

TODO: add to table

Exceptions should be accompanied by an errrorcodeerror code. Typically this is achieved by incorporating errorcodes error codes into your exception hierarchy and error handling. ONAP components generally do not share this kind of code, though EELF defines a marker interface (meaning it has no methods) EELFResolvableErrorEnum.

A common convention is for errorcodes error codes to have two components:

A prefix, which identifies the origin of the error.
A suffix, which identifies the kind of error.

...

Logs on each filebeat docker container sidecar - /var/log/onap

Excerpt

New ONAP Component Checklist

Add this procedure to the Project Proposal Template

By following a few simple rules:

Your component's output will be indexed automatically.
Analytics will be able to trace invocation through your component.

Obligations fall into two categories:

Conventions regarding configuration, line format and output.
Ensuring the propagation of contextual information.

You must:

Choose a Logging provider and/or EELF. Decisions, decisions.
Create a configuration file based on an existing archetype. See

...

16339021.
Read your configuration file when your components initialize logging.
Write logs to a standard location so that they can be shipped by Filebeat for indexing. See

...

16339021.
Report transaction state:
1. Retrieve, default and propagate RequestID. See

...

1. 16339021.
2. At each invocation of one ONAP component by another:
  1. Initialize and propagate InvocationID. See

...

1. 1. 16339021.
  2. Report INVOKE and SYNCHRONOUS markers in caller.
  3. Report ENTRY and EXIT markers in recipient.
Write useful logs!

They are unordered.

What's New

(Including what WILL be new in v1.2 / R2).

...

Versions Compared

Old Version 117

New Version Current

Key

Logging Library Location and Use

SLF4J

Log4j 1.X

Logger Name

Message

Internationalization

Context

MDCs

SLF4J:

Error Codes

Logs on each filebeat docker container sidecar - /var/log/onap

New ONAP Component Checklist

What's New

Page Comparison

Versions Compared

Old Version 117

New Version Current

Key

Logging Library Location and Use

SLF4J

Log4j 1.X

Logger Name

Message

Internationalization

Context

MDCs

SLF4J:

Error Codes

Logs on each filebeat docker container sidecar - /var/log/onap

New ONAP Component Checklist

What's New