| Table of Contents |
|---|
...
This document proposes conventions you can follow to generate conformant, indexable logging output from your component.
Supported Languages
Java (including Scala and Clojure - because they compile to the same bytecode) and Python are supported, but conventions may be implemented by other technologies like GO.
Java
The library and aop wrapper are written in Java and will work for Clojure (thanks to a discussion with Shwetank that reminded me of languages that compile to bytecode) and Scala as well. see: https://git.onap.org/logging-analytics/tree/reference
Clojure
See the java libraries
Scala
see the java libraries
Python
How to Log
ONAP prescribes conventions. The use of certain APIs and providers is recommended, but they are not mandatory. Most components log via EELF or SLF4J to a provider like Logback or Log4j.
Logging Specification Compliance
TBU
| Info | ||||||||
|---|---|---|---|---|---|---|---|---|
For the casablanca release 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. High Level the changes are introduction of MDC's (key/value pairs like requestID=...) and Markers (labels like ENTRY/EXIT) The ELK stack (indexes and dashboards) is focused on the new specification in Casablanca - if time permits we will have a migration path and/or support for both the older Amsterdam/Beijing release and Casablanca -
|
Level 0: Log specification unchanged
Just keep your code as-is and commit to migrating to the the MDC and Marker focused specification for Dublin - logs will be the older format for now
Level 1: Log specification compliance via local project changes, library or wrapper
Continue to use your own library/wrapper if you have one like in SDC and AAI, change individual source files.
Level 2: Log specification compliance via SLF4J supplied logging-analytics library
Use Luke's SLF4J library directly as wrapper for MDCs and Markers by calling the library from within each function.
Level 3: Log specification compliance via AOP library over SLF4J supplied logging-analytics library
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.
Logging Library Location and Use
see https://git.onap.org/logging-analytics/tree/reference/logging-slf4j
and usage ONAP Development#DeveloperUseoftheLoggingLibrary ONAP Development#KubernetesDevOps and Logging User Guide#LoggingDevOps
see Spring AOP example (minimal changes to existing code base) WIP in
| Jira Legacy | ||||||
|---|---|---|---|---|---|---|
|
EELF
EELF is the Event and Error Logging Framework, described at https://github.com/att/EELF.
EELF abstracts your choice of logging provider, and decorates the familiar Logger contracts with features like:
- Localization.
- Error codes.
- Generated wiki documentation.
- Separate audit, metrics,
securityerror and debug logs.
EELF is a facade, so logging output is configured in two ways:
- 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.
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.
EELF also logs via SLF4J's abstractions as the default provider.
Providers
Logging providers are normally enabled by their presence in the classpath. This means the decision may have been made for you, in some cases implicitly by dependencies. If you have a strong preference then you can change providers, but since the implementation is typically abstracted behind EELF or SLF4J, it may not be worth the effort.
Logback
Logback is the most commonly used provider. It is generally configured by an XML document named logback.xml. See Configuration.
See HELM template https://git.onap.org/logging-analytics/tree/reference/provider/helm/logback
Log4j 2.X
Log4j 2.X is somewhat less common than Logback, but equivalent. It is generally configured by an XML document named log4j.xml. See Configuration.
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/.
...
How to Log
ONAP prescribes conventions. The use of certain APIs and providers is recommended, but they are not mandatory. Most components log via EELF or SLF4J to a provider like Logback or Log4j.
Logging Specification Compliance
Logging Library Location and Use
What to Log
The purpose of logging is to capture diagnostic information.
...
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 | ||||
|---|---|---|---|---|
| ||||
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 |
...