Versions Compared

Old Version 10

changes.mady.by.user Prudence Au

Saved on

compared with

New Version Current

changes.mady.by.user Toine Siebelink

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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 

...

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 71831758).

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

...

Pipe OrderNameTypeGroupDescription

Required?

Y/N/C

(C= context dependent)

N = not required

L=Library provided


Notes

Code References

1LogTimestamplog system
use %d field - see %d{"yyyy-MM-dd'T'HH:mm:ss.SSSXXX",UTC}L

2EntryTimestampMDC
if part of an ENTRY marker logC

3InvokeTimestampMDC
if part of an INVOKE marker logC

4

RequestID
(pau)do we need to update this to TransactionID as per LOG-232 (discussed back in 20180426)?

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

5InvocationIDMDC

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 

YSee the comment section of the v1.2 spec spec on July 23, 2019
6InstanceIDMDC

An unique ID to differentiate between multiple instances of the same (named) log writing service/application.  For example, either the Kubernetes pod ID or UUID can be used for this field.

YWas InstanceUUID
7ServiceInstanceIDMDC
An unique identifier of a newly instantiated network service instance.C

8threadlog system
use %thread fieldL

9ServiceNameMDC

The service inside the partner doing the call - includes API name

Y

10PartnerNameMDC

The identification of the entity that made the request being served.  For a serving API that is authenticating the request, this should be the authenticated username or equivalent (e.g. an attuid or a mechid)

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

  1. If an authenticated API, then log the userid
  2. 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)
  3. Otherwise, if the HTTP header "X-FromAppId" was provided, then log that
  4. Otherwise, if the HTTP header "User-Agent" was provided, then log that
  5. Otherwise, log "UNKNOWN" (since the field is currently required, something must be in it)
YSee the comment section of the v1.2 spec spec on August 6, 2019
11StatusCodeMDC

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

12ResponseCodeMDC

This field contains application-specific error codes.

In the case where 

Y



13ResponseDesc

This field contains a human readable description of the ResponseCode

Y



14level

%levelL

15SeverityMDC

Logging level by default aligned with the reported log level - one of INFO/TRACE/DEBUG/WARN/ERROR/FATAL

Y

16ServerIPAddress


C

17ElapsedTime


C

18ServerFQDNMDC

The VM FQDN if the server is virtualized. Otherwise the host name of the logging component.

Y



19ClientIPAddressMDC

This field contains the requesting remote client application’s IP address if known. Otherwise empty.

Y



20VirtualServerName


C

ServerFQDN supercedes VirtualServerName as mentioned in the comment section of the v1.2 spec on July 3, 2019.

Jira Legacy
serverSystem Jira
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyLOG-1163


21ContextName


CThe logging enhancement team could not find any definition for this field and it was agreed to leave out the description for this field.  See comment section of the v1.2 spec on July 23, 2019.
22TargetEntityMDC

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

23TargetServiceNameMDC

The name  of the API or operation activities invoked (name on the remote/target application) at the TargetEntity.  

C

24TargetElementMDC

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

25UserMDC
User - used for %X{user}  C

26p_loggerlog 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 %loggerL

27p_mdclog 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

28p_messagelog system
Standard attribute - defined in logback.xml - Message - used for %msg%L


RootExceptionlog system
%rootException - Dublin spec onlyL

29p_markerlog 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 %markerL

...

Discussion: roll all 3 fqdn, hostname or ip into one field - do we ever need two of the 3 fields concurrently?

Dave Williamson We seem to cover well what to put in this field in bare metal and virtualized environments, but I think we have not managed to come to closure as to what we should put in containerized environments.  I would suggest that in all environments we simply ask that whatever "hostname" reports be logged in this field.

  •  TODO: Verify what is also available from a filebeat agent when it exists

...

Used as valuable URI - to annnote invoke marker

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

...

Retention

Types of EELF Logs

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:

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

You must:

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

...

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

...

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

...

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

...

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

 They are unordered. 

What's New

TBD

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

...