diff options
Diffstat (limited to 'reference/logging-slf4j')
10 files changed, 1762 insertions, 0 deletions
diff --git a/reference/logging-slf4j/README.md b/reference/logging-slf4j/README.md new file mode 100644 index 0000000..2796a21 --- /dev/null +++ b/reference/logging-slf4j/README.md @@ -0,0 +1,50 @@ +# README - slf4j-reference + +This project gives an example of ONAP-compliant logging using SLF4J logging. + +## Adapter + +In ```org.onap.logging.ref.slf4j```, there are TWO classes: +1. ```org.onap.logging.ref.slf4j.ONAPLogConstants```, providing declarations of standard ONAP Markers, MDCs and HTTP headers. +2. ```org.onap.logging.ref.slf4j.ONAPLogAdapter```, providing a lightweight, compliant implementation of the ONAP logging spec. + +The adapter provides: +1. A loosely-coupled SLF4j logging wrapper: + * To be used for logging ONAP ```entry```, ```exit``` and ```invoke``` behavior. + * Devolving all *application* logging to the component, via the regular SLF4J ```Logger``` facade. +2. Customization options: + * *Cheap*, by way of bean properties. This is suited to most Use Cases. + * *Sophisticated*: + * By OPTIONALLY implementing one of a number of adapters: + * ```RequestAdapter``` to read incoming headers. + * ```ServiceDescriptor``` for reporting attributes of the current service. + * ```ResponseDescriptor``` for reporting outcomes. + * ```RequestBuilder``` for setting southbound request headers. + * By OPTIONALLY overriding methods like ```ONAPLogAdapter#setMDCs(RequestAdapter)```. + +Note that: +* The adapter implementation uses static inner classes in order to fit in a single source file. This was an objective. + +## WAR + +Building produces a simple (spring-boot](https://projects.spring.io/spring-boot/) example WAR, which can be launched from this directory with: + +```bash +$ java -war target/*war +``` + +The example WAR in ```logging-slf4j-demo``` publishes four web services: +1. ```services/alpha``` +2. ```services/beta``` +3. ```services/gamma``` +4. ```services/delta``` + +... each of which can invoke the others. + +The purpose of the WAR is to demonstrate minimalist ONAP-compliant logging for web components, but a secondary purpose is to demonstrate that the call graph can be generated for a (mostly) representative set of interacting REST services. + +## Tests + +Tests for: +1. Code in the (potentially) reusable ``common`` package. +2. Validating that emitted logs can be used to generate an unambiguous call graph. diff --git a/reference/logging-slf4j/pom.xml b/reference/logging-slf4j/pom.xml new file mode 100644 index 0000000..9cc9d4b --- /dev/null +++ b/reference/logging-slf4j/pom.xml @@ -0,0 +1,91 @@ +<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId>org.onap.logging-analytics</groupId> + <artifactId>logging-reference</artifactId> + <version>1.2.0-SNAPSHOT</version> + <relativePath>..</relativePath> + </parent> + <artifactId>logging-slf4j</artifactId> + <name>logging-slf4j</name> + <packaging>jar</packaging> + <version>1.2.0-SNAPSHOT</version> + + <dependencies> + <!-- Exported dependencies. --> + <dependency> + <groupId>org.slf4j</groupId> + <artifactId>slf4j-api</artifactId> + </dependency> + <!-- Provided dependencies. --> + <dependency> + <groupId>javax.servlet</groupId> + <artifactId>javax.servlet-api</artifactId> + <scope>provided</scope> + </dependency> + <!-- Test dependencies. --> + <dependency> + <groupId>ch.qos.logback</groupId> + <artifactId>logback-classic</artifactId> + <scope>test</scope> + </dependency> + <dependency> + <groupId>org.springframework</groupId> + <artifactId>spring-test</artifactId> + <scope>test</scope> + </dependency> + <dependency> + <groupId>org.testng</groupId> + <artifactId>testng</artifactId> + <scope>test</scope> + </dependency> + <dependency> + <groupId>org.hamcrest</groupId> + <artifactId>hamcrest-all</artifactId> + <scope>test</scope> + </dependency> + </dependencies> + + <dependencyManagement> + <dependencies> + <dependency> + <groupId>org.slf4j</groupId> + <artifactId>slf4j-api</artifactId> + <version>1.7.25</version> + </dependency> + <dependency> + <groupId>javax.servlet</groupId> + <artifactId>javax.servlet-api</artifactId> + <version>3.1.0</version> + <scope>provided</scope> + </dependency> + <dependency> + <groupId>ch.qos.logback</groupId> + <artifactId>logback-classic</artifactId> + <version>1.2.3</version> + </dependency> + <dependency> + <groupId>org.testng</groupId> + <artifactId>testng</artifactId> + <version>6.8.5</version> + <exclusions> + <exclusion> + <groupId>junit</groupId> + <artifactId>junit</artifactId> + </exclusion> + </exclusions> + </dependency> + <dependency> + <groupId>org.hamcrest</groupId> + <artifactId>hamcrest-all</artifactId> + <version>1.3</version> + </dependency> + <dependency> + <groupId>org.springframework</groupId> + <artifactId>spring-test</artifactId> + <version>5.0.5.RELEASE</version> + </dependency> + </dependencies> + </dependencyManagement> + +</project> diff --git a/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogAdapter.java b/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogAdapter.java new file mode 100644 index 0000000..50693cb --- /dev/null +++ b/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogAdapter.java @@ -0,0 +1,611 @@ +/** + * ============LICENSE_START======================================================= + * org.onap.logging + * ================================================================================ + * Copyright © 2018 Amdocs + * All rights reserved. + * ================================================================================ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * ============LICENSE_END========================================================= + */ + +package org.onap.logging.ref.slf4j; + +import java.time.LocalDateTime; +import java.util.UUID; + +import javax.servlet.http.HttpServletRequest; + +import org.slf4j.Logger; +import org.slf4j.MDC; +import org.slf4j.Marker; +import org.slf4j.event.Level; + +/** + * Extensible adapter for cheaply meeting ONAP logging obligations using + * an SLF4J facade. + * + * <p>This can be used with any SLF4J-compatible logging provider, with + * appropriate provider configuration.</p> + * + * <p>The basics are that: + * <ul> + * <li>{@link #entering} sets all MDCs.</li> + * <li>{@link #exiting} unsets all MDCs *and* logs response information.</li> + * <li>{@link #invoke} logs and returns a UUID to passed during invocation, + * and optionally sets these for you on your downstream request by way of + * an adapter.</li> + * <li>Call {@link #getServiceDescriptor()} and its setters to set service-related MDCs.</li> + * <li>Call {@link #getResponseDescriptor()} and its setters to set response-related MDCs.</li> + * </ul> + * </p> + * + * <p>Minimal usage is: + * <ol> + * <li>#entering(RequestAdapter)</li> + * <li>#invoke, #invoke, ...</li> + * <li>#getResponse + setters (or #setResponse)</li> + * <li>#exiting</li> + * </ol> + * </p> + * + * <p> ... if you're happy for service information to be automatically derived as follows: + * <ul> + * <li><tt>ServiceName</tt> - from <tt>HttpServletRequest#getRequestURI()</tt></li> + * <li><tt>InstanceUUID</tt> - classloader-scope UUID.</li> + * </ul> + * </p> + * + * <p>... and if those defaults don't suit, then you can override using properties on + * {@link #getServiceDescriptor()}, or by injecting your own adapter using + * {@link #setServiceDescriptor(ServiceDescriptor)}, or by overriding + * a <tt>protected</tt> methods like{@link #setEnteringMDCs}.</p> + * + * <p>For everything else: + * <ul> + * <li>The underlying SLF4J {@link Logger} can be retrieved using {@link #unwrap}. + * Use this or create your own using the usual SLF4J factor.</li> + * <li>Set whatever MDCs you like.</li> + * <li>Log whatever else you like.</li> + * </ul> + * </p> + */ +public class ONAPLogAdapter { + + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // + // Constants. + // + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + /** String constant for messages <tt>ENTERING</tt>, <tt>EXITING</tt>, etc. */ + private static final String EMPTY_MESSAGE = ""; + + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // + // Fields. + // + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + /** Automatic UUID, overrideable per adapter or per invocation. */ + private static UUID sInstanceUUID = UUID.randomUUID(); + + /** Logger delegate. */ + private Logger mLogger; + + /** Overrideable descriptor for the service doing the logging. */ + private ServiceDescriptor mServiceDescriptor = new ServiceDescriptor(); + + /** Overrideable descriptor for the response returned by the service doing the logging. */ + private ResponseDescriptor mResponseDescriptor = new ResponseDescriptor(); + + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // + // Constructors. + // + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + /** + * Construct adapter. + * + * @param logger non-null logger. + */ + public ONAPLogAdapter(final Logger logger) { + this.mLogger = checkNotNull(logger); + } + + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // + // Public methods. + // + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + /** + * Get logger. + * + * @return unwrapped logger. + */ + public Logger unwrap() { + return this.mLogger; + } + + /** + * Report <tt>ENTERING</tt> marker. + * + * @param request non-null incoming request (wrapper). + * @return this. + */ + public ONAPLogAdapter entering(final RequestAdapter request) { + + checkNotNull(request); + + // Default the service name. + + this.setEnteringMDCs(request); + this.mLogger.info(ONAPLogConstants.Markers.ENTRY, EMPTY_MESSAGE); + + return this; + } + + /** + * Report <tt>ENTERING</tt> marker. + * + * @param request non-null incoming request. + * @return this. + */ + public ONAPLogAdapter entering(final HttpServletRequest request) { + return this.entering(new HttpServletRequestAdapter(checkNotNull(request))); + } + + /** + * Report <tt>EXITING</tt> marker. + * + * @return this. + */ + public ONAPLogAdapter exiting() { + try { + this.mResponseDescriptor.setMDCs(); + this.mLogger.info(ONAPLogConstants.Markers.EXIT, EMPTY_MESSAGE); + } + finally { + MDC.clear(); + } + return this; + } + + /** + * Report pending invocation with <tt>INVOKE</tt> marker. + * + * <p>If you call this variant, then YOU are assuming responsibility for + * setting the requisite ONAP headers.</p> + * + * @param sync whether synchronous. + * @return invocation ID to be passed with invocation. + */ + public UUID invoke(final ONAPLogConstants.InvocationMode sync) { + + final UUID invocationID = UUID.randomUUID(); + + // Derive SYNC/ASYNC marker. + + final Marker marker = (sync == null) ? ONAPLogConstants.Markers.INVOKE : sync.getMarker(); + + // Log INVOKE*, with the invocationID as the message body. + // (We didn't really want this kind of behavior in the standard, + // but is it worse than new, single-message MDC?) + + this.mLogger.info(marker, "{}", invocationID); + return invocationID; + } + + /** + * Report pending invocation with <tt>INVOKE</tt> marker, + * setting standard ONAP logging headers automatically. + * + * @param builder request builder, for setting headers. + * @param sync whether synchronous, nullable. + * @return invocation ID to be passed with invocation. + */ + public UUID invoke(final RequestBuilder builder, + final ONAPLogConstants.InvocationMode sync) { + + // Sync can be defaulted. Builder cannot. + + checkNotNull(builder); + + // Log INVOKE, and retain invocation ID for header + return. + + final UUID invocationID = this.invoke(sync); + + // Set standard HTTP headers on (southbound request) builder. + + builder.setHeader(ONAPLogConstants.Headers.REQUEST_ID, + defaultToEmpty(MDC.get(ONAPLogConstants.MDCs.REQUEST_ID))); + builder.setHeader(ONAPLogConstants.Headers.INVOCATION_ID, + defaultToEmpty(invocationID)); + builder.setHeader(ONAPLogConstants.Headers.PARTNER_NAME, + defaultToEmpty(MDC.get(ONAPLogConstants.MDCs.PARTNER_NAME))); + + return invocationID; + } + + /** + * Report vanilla <tt>INVOKE</tt> marker. + * + * @param builder builder for downstream requests, if you want the + * standard ONAP headers to be added automatically. + * @return invocation ID to be passed with invocation. + */ + public UUID invoke(final RequestBuilder builder) { + return this.invoke(builder, (ONAPLogConstants.InvocationMode)null); + } + + /** + * Get descriptor, for overriding service details. + * @return non-null descriptor. + */ + public ServiceDescriptor getServiceDescriptor() { + return checkNotNull(this.mServiceDescriptor); + } + + /** + * Override {@link ServiceDescriptor}. + * @param d non-null override. + * @return this. + */ + public ONAPLogAdapter setServiceDescriptor(final ServiceDescriptor d) { + this.mServiceDescriptor = checkNotNull(d); + return this; + } + + /** + * Get descriptor, for setting response details. + * @return non-null descriptor. + */ + public ResponseDescriptor getResponseDescriptor() { + return checkNotNull(this.mResponseDescriptor); + } + + /** + * Override {@link ResponseDescriptor}. + * @param d non-null override. + * @return this. + */ + public ONAPLogAdapter setResponseDescriptor(final ResponseDescriptor d) { + this.mResponseDescriptor = checkNotNull(d); + return this; + } + + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // + // Protected methods. + // + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + /** + * Set MDCs that persist for the duration of an invocation. + * + * <p>It would be better to roll this into {@link #entering}, like + * with {@link #exiting}. Then it would be easier to do, but it + * would mean more work. </p> + * + * @param request incoming HTTP request. + * @return this. + */ + protected ONAPLogAdapter setEnteringMDCs(final RequestAdapter<?> request) { + + // Extract MDC values from standard HTTP headers. + + final String requestID = defaultToUUID(request.getHeader(ONAPLogConstants.Headers.REQUEST_ID)); + final String invocationID = defaultToUUID(request.getHeader(ONAPLogConstants.Headers.INVOCATION_ID)); + final String partnerName = defaultToEmpty(request.getHeader(ONAPLogConstants.Headers.PARTNER_NAME)); + + // Set standard MDCs. Override this entire method if you want to set + // others, OR set them BEFORE or AFTER the invocation of #entering, + // depending on where you need them to appear, OR extend the + // ServiceDescriptor to add them. + + MDC.put(ONAPLogConstants.MDCs.INVOKE_TIMESTAMP, LocalDateTime.now().toString()); + MDC.put(ONAPLogConstants.MDCs.REQUEST_ID, requestID); + MDC.put(ONAPLogConstants.MDCs.INVOCATION_ID, invocationID); + MDC.put(ONAPLogConstants.MDCs.PARTNER_NAME, partnerName); + MDC.put(ONAPLogConstants.MDCs.CLIENT_IP_ADDRESS, defaultToEmpty(request.getClientAddress())); + MDC.put(ONAPLogConstants.MDCs.SERVER_FQDN, defaultToEmpty(request.getServerAddress())); + + // Delegate to the service adapter, for service-related DMCs. + + this.mServiceDescriptor.setMDCs(); + + // Default the service name to the requestURI, in the event that + // no value has been provided. + + if (MDC.get(ONAPLogConstants.MDCs.SERVICE_NAME) == null) { + MDC.put(ONAPLogConstants.MDCs.SERVICE_NAME, request.getRequestURI()); + } + + return this; + } + + /** + * Dependency-free nullcheck. + * + * @param in to be checked. + * @param <T> argument (and return) type. + * @return input arg. + */ + protected static <T> T checkNotNull(final T in) { + if (in == null) { + throw new NullPointerException(); + } + return in; + } + + /** + * Dependency-free string default. + * + * @param in to be filtered. + * @return input string or null. + */ + protected static String defaultToEmpty(final Object in) { + if (in == null) { + return ""; + } + return in.toString(); + } + + /** + * Dependency-free string default. + * + * @param in to be filtered. + * @return input string or null. + */ + protected static String defaultToUUID(final String in) { + if (in == null) { + return UUID.randomUUID().toString(); + } + return in; + } + + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // + // Inner classes. + // + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + /** + * Extensible descriptor for reporting service details. + * + * <p>In most cases extension isn't required. </p> + */ + public static class ServiceDescriptor { + + /** <tt>ServiceName</tt>. */ + protected String mName; + + /** <tt>InstanceUUID</tt>. */ + protected String mUUID = sInstanceUUID.toString(); + + /** + * Set name. + * @param name <tt>ServiceName</tt>. + * @return this. + */ + public ServiceDescriptor setServiceName(final String name) { + this.mName = name; + return this; + } + + /** + * Set name. + * @param uuid <tt>InstanceUUID</tt>. + * @return this. + */ + public ServiceDescriptor setServiceUUID(final String uuid) { + this.mUUID = uuid; + return this; + } + + /** + * Set MDCs. Once set they remain set until everything is cleared. + */ + protected void setMDCs() { + MDC.put(ONAPLogConstants.MDCs.SERVICE_NAME, defaultToEmpty(this.mName)); + MDC.put(ONAPLogConstants.MDCs.INSTANCE_UUID, defaultToEmpty(this.mUUID)); + } + } + + /** + * Response is different in that response MDCs are normally only + * reported once, for a single log message. (But there's no method + * for clearing them, because this is only expected to be called + * during <tt>#exiting</tt>.) + */ + public static class ResponseDescriptor { + + /** Response errorcode. */ + protected String mCode; + + /** Response description. */ + protected String mDescription; + + /** Response severity. */ + protected Level mSeverity; + + /** Response status, of {<tt>COMPLETED</tt>, <tt>ERROR</tt>}. */ + protected ONAPLogConstants.ResponseStatus mStatus; + + /** + * Setter. + * + * @param code response (error) code. + * @return this. + */ + public ResponseDescriptor setResponseCode(final String code) { + this.mCode = code; + return this; + } + + /** + * Setter. + * + * @param description response description. + * @return this. + */ + public ResponseDescriptor setResponseDescription(final String description) { + this.mDescription = description; + return this; + } + + /** + * Setter. + * + * @param severity response outcome severity. + * @return this. + */ + public ResponseDescriptor setResponseSeverity(final Level severity) { + this.mSeverity = severity; + return this; + } + + /** + * Setter. + * + * @param status response overall status. + * @return this. + */ + public ResponseDescriptor setResponseStatus(final ONAPLogConstants.ResponseStatus status) { + this.mStatus = status; + return this; + } + + /** + * Overrideable method to set MDCs based on property values. + */ + protected void setMDCs() { + MDC.put(ONAPLogConstants.MDCs.RESPONSE_CODE, defaultToEmpty(this.mCode)); + MDC.put(ONAPLogConstants.MDCs.RESPONSE_DESCRIPTION, defaultToEmpty(this.mDescription)); + MDC.put(ONAPLogConstants.MDCs.RESPONSE_SEVERITY, defaultToEmpty(this.mSeverity)); + MDC.put(ONAPLogConstants.MDCs.RESPONSE_STATUS_CODE, defaultToEmpty(this.mStatus)); + } + } + + /** + * Adapter for reading information from an incoming HTTP request. + * + * <p>Incoming is generally easy, because in most cases you'll be able to + * get your hands on the <tt>HttpServletRequest</tt>.</p> + * + * <p>Perhaps should be generalized to refer to constants instead of + * requiring the implementation of specific methods.</p> + * + * @param <T> type, for chaining. + */ + public interface RequestAdapter<T extends RequestAdapter> { + + /** + * Get header by name. + * @param name header name. + * @return header value, or null. + */ + String getHeader(String name); + + /** + * Get client address. + * @return address, if available. + */ + String getClientAddress(); + + /** + * Get server address. + * @return address, if available. + */ + String getServerAddress(); + + /** + * Get default service name, from service URI. + * @return service name default. + */ + String getRequestURI(); + } + + /** + * Default {@link RequestBuilder} impl for {@link HttpServletRequest}, which + * will should available for most incoming REST requests. + */ + public static class HttpServletRequestAdapter implements RequestAdapter<HttpServletRequestAdapter> { + + /** Wrapped HTTP request. */ + private final HttpServletRequest mRequest; + + /** + * Construct adapter for HTTP request. + * @param request to be wrapped; + */ + public HttpServletRequestAdapter(final HttpServletRequest request) { + this.mRequest = checkNotNull(request); + } + + /** + * {@inheritDoc} + */ + @Override + public String getHeader(final String name) { + return this.mRequest.getHeader(name); + } + + /** + * {@inheritDoc} + */ + @Override + public String getClientAddress() { + return this.mRequest.getRemoteAddr(); + } + + /** + * {@inheritDoc} + */ + @Override + public String getServerAddress() { + return this.mRequest.getServerName(); + } + + /** + * {@inheritDoc} + */ + @Override + public String getRequestURI() { + return this.mRequest.getRequestURI(); + } + } + + /** + * Header builder, which (unlike {@link RequestAdapter} will tend to + * vary a lot from caller to caller, since they each get to choose their + * own REST (or HTTP, or whatever) client APIs. + * + * <p>No default implementation, because there's no HTTP client that's + * sufficiently ubiquitous to warrant incurring a mandatory dependency.</p> + * + * @param <T> type, for chaining. + */ + public interface RequestBuilder<T extends RequestBuilder> { + + /** + * Set HTTP header. + * @param name header name. + * @param value header value. + * @return this. + */ + T setHeader(String name, String value); + } +} diff --git a/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogConstants.java b/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogConstants.java new file mode 100644 index 0000000..744f99f --- /dev/null +++ b/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/ONAPLogConstants.java @@ -0,0 +1,253 @@ +/** + * ============LICENSE_START======================================================= + * org.onap.logging + * ================================================================================ + * Copyright © 2018 Amdocs + * All rights reserved. + * ================================================================================ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * ============LICENSE_END========================================================= + */ + +package org.onap.logging.ref.slf4j; + +import org.slf4j.Marker; +import org.slf4j.MarkerFactory; + +/** + * Constants for standard ONAP headers, MDCs, etc. + * + * <p>See <tt>package-info.java</tt>.</p> + */ +public final class ONAPLogConstants { + + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // + // Constructors. + // + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + /** + * Hide and forbid construction. + */ + private ONAPLogConstants() { + throw new UnsupportedOperationException(); + } + + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // + // Inner classes. + // + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + /** + * Marker constants. + */ + public static final class Markers { + + /** Marker reporting invocation. */ + public static final Marker INVOKE = MarkerFactory.getMarker("INVOKE"); + + /** Marker reporting synchronous invocation. */ + public static final Marker INVOKE_SYNCHRONOUS = build("INVOKE", "SYNCHRONOUS"); + + /** Marker reporting asynchronous invocation. */ + public static final Marker INVOKE_ASYNCHRONOUS = build("INVOKE", "ASYNCHRONOUS"); + + /** Marker reporting entry into a component. */ + public static final Marker ENTRY = MarkerFactory.getMarker("ENTRY"); + + /** Marker reporting exit from a component. */ + public static final Marker EXIT = MarkerFactory.getMarker("EXIT"); + + /** + * Build nested, detached marker. + * @param m1 top token. + * @param m2 sub-token. + * @return detached Marker. + */ + private static Marker build(final String m1, final String m2) { + final Marker marker = MarkerFactory.getDetachedMarker(m1); + marker.add(MarkerFactory.getDetachedMarker(m2)); + return marker; + } + + /** + * Hide and forbid construction. + */ + private Markers() { + throw new UnsupportedOperationException(); + } + } + + /** + * MDC name constants. + */ + public static final class MDCs { + + // Tracing. //////////////////////////////////////////////////////////// + + /** MDC correlating messages for an invocation. */ + public static final String INVOCATION_ID = "InvocationID"; + + /** MDC correlating messages for a logical transaction. */ + public static final String REQUEST_ID = "RequestID"; + + /** MDC recording calling service. */ + public static final String PARTNER_NAME = "PartnerName"; + + /** MDC recording current service. */ + public static final String SERVICE_NAME = "ServiceName"; + + /** MDC recording target service. */ + public static final String TARGET_SERVICE_NAME = "TargetServiceName"; + + /** MDC recording current service instance. */ + public static final String INSTANCE_UUID = "InstanceUUID"; + + // Network. //////////////////////////////////////////////////////////// + + /** MDC recording caller address. */ + public static final String CLIENT_IP_ADDRESS = "ClientIPAddress"; + + /** MDC recording server address. */ + public static final String SERVER_FQDN = "ServerFQDN"; + + /** + * MDC recording timestamp at the start of the current request, + * with the same scope as {@link #REQUEST_ID}. + * + * <p>Open issues: + * <ul> + * <ul>Easily confused with {@link #INVOKE_TIMESTAMP}.</ul> + * <ul>No mechanism for propagation between components, e.g. via HTTP headers.</ul> + * <ul>Whatever mechanism we define, it's going to be costly.</ul> + * </ul> + * </p> + * */ + public static final String ENTRY_TIMESTAMP = "EntryTimestamp"; + + /** MDC recording timestamp at the start of the current invocation. */ + public static final String INVOKE_TIMESTAMP = "InvokeTimestamp"; + + // Outcomes. /////////////////////////////////////////////////////////// + + /** MDC reporting outcome code. */ + public static final String RESPONSE_CODE = "ResponseCode"; + + /** MDC reporting outcome description. */ + public static final String RESPONSE_DESCRIPTION = "ResponseDescription"; + + /** MDC reporting outcome error level. */ + public static final String RESPONSE_SEVERITY = "Severity"; + + /** MDC reporting outcome error level. */ + public static final String RESPONSE_STATUS_CODE = "StatusCode"; + + // Unsorted. /////////////////////////////////////////////////////////// + + /** + * Hide and forbid construction. + */ + private MDCs() { + throw new UnsupportedOperationException(); + } + } + + /** + * Header name constants. + */ + public static final class Headers { + + /** HTTP <tt>X-ONAP-RequestID</tt> header. */ + public static final String REQUEST_ID = "X-ONAP-RequestID"; + + /** HTTP <tt>X-ONAP-InvocationID</tt> header. */ + public static final String INVOCATION_ID = "X-ONAP-InvocationID"; + + /** HTTP <tt>X-ONAP-PartnerName</tt> header. */ + public static final String PARTNER_NAME = "X-ONAP-PartnerName"; + + /** + * Hide and forbid construction. + */ + private Headers() { + throw new UnsupportedOperationException(); + } + } + + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + // + // Enums. + // + //////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + + /** + * Response success or not, for setting <tt>StatusCode</tt>. + */ + public enum ResponseStatus { + + /** Success. */ + COMPLETED, + + /** Not. */ + ERROR, + } + + /** + * Synchronous or asynchronous execution, for setting invocation marker. + */ + public enum InvocationMode { + + /** Synchronous, blocking. */ + SYNCHRONOUS("SYNCHRONOUS", Markers.INVOKE_SYNCHRONOUS), + + /** Asynchronous, non-blocking. */ + ASYNCHRONOUS("ASYNCHRONOUS", Markers.INVOKE_ASYNCHRONOUS); + + /** Enum value. */ + private String mString; + + /** Corresponding marker. */ + private Marker mMarker; + + /** + * Construct enum. + * + * @param s enum value. + * @param m corresponding Marker. + */ + InvocationMode(final String s, final Marker m) { + this.mString = s; + this.mMarker = m; + } + + /** + * Get Marker for enum. + * + * @return Marker. + */ + public Marker getMarker() { + return this.mMarker; + } + + /** + * {@inheritDoc} + */ + @Override + public String toString() { + return this.mString; + } + } + +} diff --git a/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/package-info.java b/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/package-info.java new file mode 100644 index 0000000..d9a6247 --- /dev/null +++ b/reference/logging-slf4j/src/main/java/org/onap/logging/ref/slf4j/package-info.java @@ -0,0 +1,32 @@ +/** + * ============LICENSE_START======================================================= + * org.onap.logging + * ================================================================================ + * Copyright © 2018 Amdocs + * All rights reserved. + * ================================================================================ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * ============LICENSE_END========================================================= + */ + +package org.onap.logging.ref.slf4j; + +/** + * <p>Code in here has potential application outside this reference + * example, and accordingly: + * <ul> + * <li>Packaged in <tt>common</tt>.</li> + * <li>Has minimal dependencies.</li> + * </ul> + * </p> + */
\ No newline at end of file diff --git a/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterOutputTest.java b/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterOutputTest.java new file mode 100644 index 0000000..bab74bb --- /dev/null +++ b/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterOutputTest.java @@ -0,0 +1,162 @@ +/** + * ============LICENSE_START======================================================= + * org.onap.logging + * ================================================================================ + * Copyright © 2018 Amdocs + * All rights reserved. + * ================================================================================ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * ============LICENSE_END========================================================= + */ + +package org.onap.logging.ref.slf4j; + +import java.io.BufferedReader; +import java.io.File; +import java.io.FileReader; +import java.nio.file.Files; +import java.util.ArrayList; +import java.util.List; +import java.util.UUID; + +import javax.xml.bind.DatatypeConverter; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.slf4j.MDC; +import org.springframework.mock.web.MockHttpServletRequest; +import org.testng.annotations.AfterSuite; +import org.testng.annotations.BeforeSuite; +import org.testng.annotations.Test; + +import static org.hamcrest.MatcherAssert.assertThat; +import static org.hamcrest.core.Is.is; +import static org.hamcrest.core.IsNot.not; +import static org.hamcrest.core.IsNull.notNullValue; +import static org.hamcrest.core.StringContains.containsString; +import static org.hamcrest.number.OrderingComparison.greaterThan; + +/** + * Smoketest output, though the embedded configuration isn't necessarily + * canonical. + * + * <p>There are more comprehensive tests in the <tt>logging-slf4j-demo</tt> + * project.</p> + */ +public class ONAPLogAdapterOutputTest { + + /** Temporary directory into which logfiles are written. */ + private static File sDir; + + @BeforeSuite + public static void setUp() throws Exception { + sDir = Files.createTempDirectory(ONAPLogAdapterOutputTest.class.getName()).toFile(); + System.getProperties().setProperty("SLF4J_OUTPUT_DIRECTORY", sDir.getAbsolutePath()); + LoggerFactory.getLogger(ONAPLogAdapterOutputTest.class).info("Starting."); + } + + @AfterSuite + public static void tearDown() throws Exception { + LoggerFactory.getLogger(ONAPLogAdapterOutputTest.class).info("Ending."); + Thread.sleep(1000L); + if (sDir != null) { + System.err.println("Should be deleting [" + sDir.getAbsolutePath() + "]..."); + } + } + + @Test + public void testOutput() throws Exception { + + assertThat(sDir, notNullValue()); + assertThat(sDir.isDirectory(), is(true)); + + final String uuid = UUID.randomUUID().toString(); + final String errorcode = UUID.randomUUID().toString(); + final Logger logger = LoggerFactory.getLogger(ONAPLogAdapterOutputTest.class); + + try { + MDC.put("uuid", uuid); + final ONAPLogAdapter adapter = new ONAPLogAdapter(logger); + final ONAPLogAdapter.HttpServletRequestAdapter http + = new ONAPLogAdapter.HttpServletRequestAdapter(new MockHttpServletRequest()); + adapter.entering(http); + adapter.unwrap().warn("a_warning"); + try { + throw new Exception("errorcode=" + errorcode); + } + catch (final Exception e) { + adapter.unwrap().error("an_error", e); + } + + Thread.sleep(1000L); + } + finally { + MDC.clear(); + } + + final List<String> lines = new ArrayList<>(); + for (final File f : sDir.listFiles()) { + try (BufferedReader reader = new BufferedReader(new FileReader(f))) { + String line; + while ((line = reader.readLine()) != null) { + if (line.contains(uuid)) { + lines.add(line); + } + } + } + } + + assertThat(lines.size(), is(3)); + + assertThat(lines.get(0), containsString("ENTRY")); + final String [] line0 = lines.get(0).split("\t", -1); + assertThat(line0.length, is(9)); + DatatypeConverter.parseDateTime(line0[0]); + assertThat(line0[1].trim().length(), greaterThan(1)); + assertThat(line0[2], is("INFO")); + assertThat(line0[3], is(this.getClass().getName())); + assertThat(line0[4], containsString("uuid=" + uuid)); + assertThat(line0[5], is("")); + assertThat(line0[6], is("")); + assertThat(line0[7], is("ENTRY")); + System.err.println(lines.get(0)); + + assertThat(lines.get(1), not(containsString("ENTRY"))); + assertThat(lines.get(1), containsString("a_warning")); + final String [] line1 = lines.get(1).split("\t", -1); + assertThat(line1.length, is(9)); + DatatypeConverter.parseDateTime(line1[0]); + assertThat(line1[1].trim().length(), greaterThan(1)); + assertThat(line1[2], is("WARN")); + assertThat(line1[3], is(this.getClass().getName())); + assertThat(line1[4], containsString("uuid=" + uuid)); + assertThat(line1[5], is("a_warning")); + assertThat(line1[6], is("")); + assertThat(line1[7], is("")); + System.err.println(lines.get(1)); + + assertThat(lines.get(2), not(containsString("ENTRY"))); + assertThat(lines.get(2), containsString("an_error")); + final String [] line2 = lines.get(2).split("\t", -1); + assertThat(line2.length, is(9)); + DatatypeConverter.parseDateTime(line2[0]); + assertThat(line2[1].trim().length(), greaterThan(1)); + assertThat(line2[2], is("ERROR")); + assertThat(line2[3], is(this.getClass().getName())); + assertThat(line2[4], containsString("uuid=" + uuid)); + assertThat(line2[5], is("an_error")); + assertThat(line2[6], containsString("errorcode=" + errorcode)); + assertThat(line2[7], is("")); + System.err.println(lines.get(2)); + } +} diff --git a/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterTest.java b/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterTest.java new file mode 100644 index 0000000..ad22603 --- /dev/null +++ b/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogAdapterTest.java @@ -0,0 +1,387 @@ +/** + * ============LICENSE_START======================================================= + * org.onap.logging + * ================================================================================ + * Copyright © 2018 Amdocs + * All rights reserved. + * ================================================================================ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * ============LICENSE_END========================================================= + */ + +package org.onap.logging.ref.slf4j; + +import java.util.HashMap; +import java.util.Map; +import java.util.UUID; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.slf4j.MDC; +import org.slf4j.event.Level; +import org.springframework.mock.web.MockHttpServletRequest; +import org.testng.Assert; +import org.testng.annotations.AfterMethod; +import org.testng.annotations.Test; + +import static org.hamcrest.MatcherAssert.assertThat; +import static org.hamcrest.core.Is.is; +import static org.hamcrest.core.IsNot.not; +import static org.hamcrest.core.IsNull.notNullValue; +import static org.hamcrest.core.IsNull.nullValue; +import static org.hamcrest.core.IsSame.sameInstance; + +/** + * Tests for {@link ONAPLogAdapter}. + */ +public class ONAPLogAdapterTest { + + /** + * Ensure that MDCs are cleared after each testcase. + */ + @AfterMethod + public void resetMDCs() { + MDC.clear(); + } + + /** + * Test nullcheck. + */ + @Test + public void testCheckNotNull() { + + ONAPLogAdapter.checkNotNull(""); + + try { + ONAPLogAdapter.checkNotNull(null); + Assert.fail("Should throw NullPointerException"); + } + catch (final NullPointerException e) { + + } + } + + /** + * Test defaulting of nulls. + */ + @Test + public void testDefaultToEmpty() { + assertThat(ONAPLogAdapter.defaultToEmpty("123"), is("123")); + assertThat(ONAPLogAdapter.defaultToEmpty(Integer.valueOf(1984)), is("1984")); + assertThat(ONAPLogAdapter.defaultToEmpty(null), is("")); + } + + /** + * Test defaulting of nulls. + */ + @Test + public void testDefaultToUUID() { + assertThat(ONAPLogAdapter.defaultToUUID("123"), is("123")); + UUID.fromString(ONAPLogAdapter.defaultToUUID(null)); + } + + /** + * Test ENTERING. + */ + @Test + public void testEntering() { + + final Logger logger = LoggerFactory.getLogger(this.getClass()); + final ONAPLogAdapter adapter = new ONAPLogAdapter(logger); + final MockHttpServletRequest http = new MockHttpServletRequest(); + http.setRequestURI("uri123"); + http.setServerName("local123"); + http.setRemoteAddr("remote123"); + http.addHeader("X-ONAP-RequestID", "request123"); + http.addHeader("X-ONAP-InvocationID", "invocation123"); + http.addHeader("X-ONAP-PartnerName", "partner123"); + + try { + adapter.getServiceDescriptor().setServiceName("uri123"); + adapter.entering(http); + final Map<String, String> mdcs = MDC.getCopyOfContextMap(); + assertThat(mdcs.get("RequestID"), is("request123")); + assertThat(mdcs.get("InvocationID"), is("invocation123")); + assertThat(mdcs.get("PartnerName"), is("partner123")); + assertThat(mdcs.get("ServiceName"), is("uri123")); + assertThat(mdcs.get("ServerFQDN"), is("local123")); + assertThat(mdcs.get("ClientIPAddress"), is("remote123")); + } + finally { + MDC.clear(); + } + } + + @Test + public void testSetServiceDescriptor() { + final ONAPLogAdapter.ServiceDescriptor override = new ONAPLogAdapter.ServiceDescriptor(); + final Logger logger = LoggerFactory.getLogger(this.getClass()); + final ONAPLogAdapter adapter = new ONAPLogAdapter(logger); + final ONAPLogAdapter.ServiceDescriptor before = adapter.getServiceDescriptor(); + adapter.setServiceDescriptor(override); + final ONAPLogAdapter.ServiceDescriptor after = adapter.getServiceDescriptor(); + assertThat(after, not(sameInstance(before))); + assertThat(after, is(override)); + } + + @Test + public void testSetResponseDescriptor() { + final ONAPLogAdapter.ResponseDescriptor override = new ONAPLogAdapter.ResponseDescriptor(); + final Logger logger = LoggerFactory.getLogger(this.getClass()); + final ONAPLogAdapter adapter = new ONAPLogAdapter(logger); + final ONAPLogAdapter.ResponseDescriptor before = adapter.getResponseDescriptor(); + adapter.setResponseDescriptor(override); + final ONAPLogAdapter.ResponseDescriptor after = adapter.getResponseDescriptor(); + assertThat(after, not(sameInstance(before))); + assertThat(after, is(override)); + } + + @Test + public void testUnwrap() { + final Logger logger = LoggerFactory.getLogger(this.getClass()); + final ONAPLogAdapter adapter = new ONAPLogAdapter(logger); + assertThat(adapter.unwrap(), is(logger)); + } + + /** + * Test EXITING. + */ + @Test + public void testExiting() { + + final Logger logger = LoggerFactory.getLogger(this.getClass()); + final ONAPLogAdapter adapter = new ONAPLogAdapter(logger); + + try { + MDC.put("somekey", "somevalue"); + assertThat(MDC.get("somekey"), is("somevalue")); + adapter.exiting(); + assertThat(MDC.get("somekey"), nullValue()); + } + finally { + MDC.clear(); + } + } + + /** + * Test INVOKE. + */ + @Test + public void testInvokeSyncAsyncNull() { + + final Logger logger = LoggerFactory.getLogger(this.getClass()); + final ONAPLogAdapter adapter = new ONAPLogAdapter(logger); + + final UUID syncUUID = adapter.invoke(ONAPLogConstants.InvocationMode.SYNCHRONOUS); + assertThat(syncUUID, notNullValue()); + + final UUID asyncUUID = adapter.invoke(ONAPLogConstants.InvocationMode.SYNCHRONOUS); + assertThat(asyncUUID, notNullValue()); + + final UUID agnosticUUID = adapter.invoke((ONAPLogConstants.InvocationMode)null); + assertThat(agnosticUUID, notNullValue()); + + } + + /** + * Test INVOKE, with RequestAdapter. + */ + @Test + public void testInvokeWithAdapter() throws Exception { + + final Logger logger = LoggerFactory.getLogger(this.getClass()); + final ONAPLogAdapter adapter = new ONAPLogAdapter(logger); + + final Map<String, String> headers = new HashMap<>(); + final ONAPLogAdapter.RequestBuilder builder = new ONAPLogAdapter.RequestBuilder<ONAPLogAdapter.RequestBuilder>() { + @Override + public ONAPLogAdapter.RequestBuilder setHeader(final String name, final String value) { + headers.put(name, value); + return this; + } + }; + + try { + final UUID uuid = adapter.invoke(builder, ONAPLogConstants.InvocationMode.SYNCHRONOUS); + assertThat(uuid, notNullValue()); + assertThat(headers.get(ONAPLogConstants.Headers.INVOCATION_ID), is(uuid.toString())); + assertThat(headers.containsKey(ONAPLogConstants.Headers.PARTNER_NAME), is(true)); + assertThat(headers.containsKey(ONAPLogConstants.Headers.REQUEST_ID), is(true)); + } + finally { + MDC.clear(); + } + } + + /** + * Test INVOKE, with RequestAdapter. + */ + @Test + public void testInvokeWithAdapterAndNull() throws Exception { + + final Logger logger = LoggerFactory.getLogger(this.getClass()); + final ONAPLogAdapter adapter = new ONAPLogAdapter(logger); + + final Map<String, String> headers = new HashMap<>(); + final ONAPLogAdapter.RequestBuilder builder = new ONAPLogAdapter.RequestBuilder<ONAPLogAdapter.RequestBuilder>() { + @Override + public ONAPLogAdapter.RequestBuilder setHeader(final String name, final String value) { + headers.put(name, value); + return this; + } + }; + + try { + final UUID uuid = adapter.invoke(builder); + assertThat(uuid, notNullValue()); + assertThat(headers.get(ONAPLogConstants.Headers.INVOCATION_ID), is(uuid.toString())); + assertThat(headers.containsKey(ONAPLogConstants.Headers.PARTNER_NAME), is(true)); + assertThat(headers.containsKey(ONAPLogConstants.Headers.REQUEST_ID), is(true)); + } + finally { + MDC.clear(); + } + } + + @Test + public void testHttpServletRequestAdapter() { + + final UUID uuid = UUID.randomUUID(); + final MockHttpServletRequest request = new MockHttpServletRequest(); + request.addHeader("uuid", uuid.toString()); + request.setRequestURI("/ctx0"); + request.setServerName("srv0"); + + final ONAPLogAdapter.HttpServletRequestAdapter adapter + = new ONAPLogAdapter.HttpServletRequestAdapter(request); + assertThat(adapter.getHeader("uuid"), is(uuid.toString())); + assertThat(adapter.getRequestURI(), is("/ctx0")); + assertThat(adapter.getServerAddress(), is("srv0")); + } + + @Test + public void testServiceDescriptor() { + final String uuid = UUID.randomUUID().toString(); + + final ONAPLogAdapter.ServiceDescriptor adapter + = new ONAPLogAdapter.ServiceDescriptor(); + adapter.setServiceUUID(uuid); + adapter.setServiceName("name0"); + + assertThat(MDC.get(ONAPLogConstants.MDCs.SERVICE_NAME), nullValue()); + assertThat(MDC.get(ONAPLogConstants.MDCs.INSTANCE_UUID), nullValue()); + + adapter.setMDCs(); + + assertThat(MDC.get(ONAPLogConstants.MDCs.SERVICE_NAME), is("name0")); + assertThat(MDC.get(ONAPLogConstants.MDCs.INSTANCE_UUID), is(uuid)); + } + + @Test + public void testResponseDescriptor() { + final String uuid = UUID.randomUUID().toString(); + + final ONAPLogAdapter.ResponseDescriptor adapter + = new ONAPLogAdapter.ResponseDescriptor(); + adapter.setResponseCode("code0"); + adapter.setResponseDescription("desc0"); + adapter.setResponseSeverity(Level.INFO); + adapter.setResponseStatus(ONAPLogConstants.ResponseStatus.COMPLETED); + + assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_CODE), nullValue()); + assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_DESCRIPTION), nullValue()); + assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_SEVERITY), nullValue()); + assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_STATUS_CODE), nullValue()); + + adapter.setMDCs(); + + assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_CODE), is("code0")); + assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_DESCRIPTION), is("desc0")); + assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_SEVERITY), is("INFO")); + assertThat(MDC.get(ONAPLogConstants.MDCs.RESPONSE_STATUS_CODE), is("COMPLETED")); + } + + /** + * Exercise the contract, for a caller that's happy to have their + * service name automatically derived. (This validates nothing + * and achieves nothing; it's just to provide an example of minimal usage). + */ + @Test + public void testContract() { + + // Note no wrapper around HttpServletRequest, which will work for + // most invocations (since they come via HTTP), but otherwise + // can implement your own RequestAdapter. + + final Logger logger = LoggerFactory.getLogger(this.getClass()); + final ONAPLogAdapter adapter = new ONAPLogAdapter(logger); + final MockHttpServletRequest http = new MockHttpServletRequest(); + + // Immediately log ENTERING marker, with global MDCs. + + adapter.entering(http); + try { + + // Generate (and log) an invocationID, then use it to + // invoke another component. + + final RESTClient client = new RESTClient(); // implements ONAPLogAdapter.RequestBuilder<RESTClient>. + adapter.invoke(client, ONAPLogConstants.InvocationMode.SYNCHRONOUS); + final RESTRequest request = null; // TODO: build real request. + final RESTResponse response = client.execute(request); // TODO: handle real response. + + // Set response details prior to #exiting. + // (Obviously there'd be errorhandling, etc. IRL). + + adapter.getResponseDescriptor() + .setResponseCode((String)null) + .setResponseSeverity(Level.INFO) + .setResponseStatus(ONAPLogConstants.ResponseStatus.COMPLETED); + } + finally { + + // Return, logging EXIT marker, with response MDCs. + + adapter.exiting(); + } + } + + /** + * Dummy class, for example code. + */ + static class RESTClient implements ONAPLogAdapter.RequestBuilder<RESTClient> { + + @Override + public RESTClient setHeader(final String name, final String value) { + return null; + } + + RESTResponse execute(RESTRequest request) { + return null; + } + } + + /** + * Dummy class, for example code. + */ + static class RESTRequest { + + } + + /** + * Dummy class, for example code. + */ + static class RESTResponse { + + } +} diff --git a/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogConstantsTest.java b/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogConstantsTest.java new file mode 100644 index 0000000..f6642f9 --- /dev/null +++ b/reference/logging-slf4j/src/test/java/org/onap/logging/ref/slf4j/ONAPLogConstantsTest.java @@ -0,0 +1,133 @@ +/** + * ============LICENSE_START======================================================= + * org.onap.logging + * ================================================================================ + * Copyright © 2018 Amdocs + * All rights reserved. + * ================================================================================ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * ============LICENSE_END========================================================= + */ + +package org.onap.logging.ref.slf4j; + +import java.lang.reflect.Constructor; +import java.lang.reflect.InvocationTargetException; + +import org.testng.Assert; +import org.testng.annotations.Test; + +import static org.hamcrest.MatcherAssert.assertThat; +import static org.hamcrest.core.Is.is; +import static org.hamcrest.core.IsInstanceOf.instanceOf; + +/** + * Tests for {@link ONAPLogConstants}. + */ +public class ONAPLogConstantsTest { + + @Test + public void testConstructors() throws Exception { + assertInaccessibleConstructor(ONAPLogConstants.class); + assertInaccessibleConstructor(ONAPLogConstants.MDCs.class); + assertInaccessibleConstructor(ONAPLogConstants.Markers.class); + assertInaccessibleConstructor(ONAPLogConstants.Headers.class); + } + + @Test + public void testConstructorUnsupported() throws Exception { + try { + Constructor<?> c = ONAPLogConstants.class.getDeclaredConstructors()[0]; + c.setAccessible(true); + c.newInstance(); + Assert.fail("Should fail for hidden constructor."); + } + catch (final InvocationTargetException e) { + assertThat(e.getCause(), instanceOf(UnsupportedOperationException.class)); + } + } + + @Test + public void testHeaders() { + assertThat(ONAPLogConstants.Headers.REQUEST_ID, is("X-ONAP-RequestID")); + assertThat(ONAPLogConstants.Headers.INVOCATION_ID, is("X-ONAP-InvocationID")); + assertThat(ONAPLogConstants.Headers.PARTNER_NAME, is("X-ONAP-PartnerName")); + } + + @Test + public void testMarkers() { + assertThat(ONAPLogConstants.Markers.ENTRY.toString(), is("ENTRY")); + assertThat(ONAPLogConstants.Markers.EXIT.toString(), is("EXIT")); + assertThat(ONAPLogConstants.Markers.INVOKE.toString(), is("INVOKE")); + assertThat(ONAPLogConstants.Markers.INVOKE_ASYNCHRONOUS.toString(), is("INVOKE [ ASYNCHRONOUS ]")); + assertThat(ONAPLogConstants.Markers.INVOKE_SYNCHRONOUS.toString(), is("INVOKE [ SYNCHRONOUS ]")); + } + + @Test + public void testInvocationMode() { + assertThat(ONAPLogConstants.InvocationMode.SYNCHRONOUS.getMarker(), + is(ONAPLogConstants.Markers.INVOKE_SYNCHRONOUS)); + assertThat(ONAPLogConstants.InvocationMode.ASYNCHRONOUS.getMarker(), + is(ONAPLogConstants.Markers.INVOKE_ASYNCHRONOUS)); + } + + @Test + public void testInvocationModeToString() { + assertThat(ONAPLogConstants.InvocationMode.SYNCHRONOUS.toString(), + is("SYNCHRONOUS")); + } + + @Test + public void testResponseStatus() { + assertThat(ONAPLogConstants.ResponseStatus.COMPLETED.toString(), is("COMPLETED")); + assertThat(ONAPLogConstants.ResponseStatus.ERROR.toString(), is("ERROR")); + } + + @Test + public void testMDCs() { + + assertThat(ONAPLogConstants.MDCs.CLIENT_IP_ADDRESS.toString(), is("ClientIPAddress")); + assertThat(ONAPLogConstants.MDCs.SERVER_FQDN.toString(), is("ServerFQDN")); + + assertThat(ONAPLogConstants.MDCs.ENTRY_TIMESTAMP.toString(), is("EntryTimestamp")); + assertThat(ONAPLogConstants.MDCs.INVOKE_TIMESTAMP.toString(), is("InvokeTimestamp")); + + assertThat(ONAPLogConstants.MDCs.REQUEST_ID.toString(), is("RequestID")); + assertThat(ONAPLogConstants.MDCs.INVOCATION_ID.toString(), is("InvocationID")); + assertThat(ONAPLogConstants.MDCs.PARTNER_NAME.toString(), is("PartnerName")); + assertThat(ONAPLogConstants.MDCs.INSTANCE_UUID.toString(), is("InstanceUUID")); + assertThat(ONAPLogConstants.MDCs.SERVICE_NAME.toString(), is("ServiceName")); + assertThat(ONAPLogConstants.MDCs.TARGET_SERVICE_NAME.toString(), is("TargetServiceName")); + + } + + static void assertInaccessibleConstructor(final Class<?> c) throws Exception { + try { + c.getDeclaredConstructors()[0].newInstance(); + Assert.fail("Should fail for hidden constructor."); + } + catch (final IllegalAccessException e) { + + } + + try { + final Constructor<?> constructor = c.getDeclaredConstructors()[0]; + constructor.setAccessible(true); + constructor.newInstance(); + Assert.fail("Should fail even when invoked."); + } + catch (final InvocationTargetException e) { + assertThat(e.getCause(), instanceOf(UnsupportedOperationException.class)); + } + } +} diff --git a/reference/logging-slf4j/src/test/java/testng.xml b/reference/logging-slf4j/src/test/java/testng.xml new file mode 100644 index 0000000..7b31c26 --- /dev/null +++ b/reference/logging-slf4j/src/test/java/testng.xml @@ -0,0 +1,8 @@ +<!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd"> +<suite name="org.onap.logging.ref.slf4j" verbose="9" thread-count="1" parallel="methods"> + <test name="all" thread-count="1" enabled="true"> + <packages> + <package name="org.onap.logging.ref.slf4j.*"/> + </packages> + </test> +</suite>
\ No newline at end of file diff --git a/reference/logging-slf4j/src/test/resources/logback.xml b/reference/logging-slf4j/src/test/resources/logback.xml new file mode 100644 index 0000000..554d712 --- /dev/null +++ b/reference/logging-slf4j/src/test/resources/logback.xml @@ -0,0 +1,35 @@ +<configuration> + + <property name="p_tim" value="%d{"yyyy-MM-dd'T'HH:mm:ss.SSSXXX", UTC}"/> + <property name="p_lvl" value="%level"/> + <property name="p_log" value="%logger"/> + <property name="p_mdc" value="%replace(%replace(%mdc){'\t','\\\\t'}){'\n', '\\\\n'}"/> + <property name="p_msg" value="%replace(%replace(%msg){'\t', '\\\\t'}){'\n','\\\\n'}"/> + <property name="p_exc" value="%replace(%replace(%rootException){'\t', '\\\\t'}){'\n','\\\\n'}"/> + <property name="p_mak" value="%replace(%replace(%marker){'\t', '\\\\t'}){'\n','\\\\n'}"/> + <property name="p_thr" value="%thread"/> + <property name="pattern" value="%nopexception${p_tim}\t${p_thr}\t${p_lvl}\t${p_log}\t${p_mdc}\t${p_msg}\t${p_exc}\t${p_mak}\t%n"/> + + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <encoder> + <pattern>${pattern}</pattern> + </encoder> + </appender> + + <appender name="FILE" class="ch.qos.logback.core.FileAppender"> + <file>${SLF4J_OUTPUT_DIRECTORY}/output.log</file> + <encoder> + <pattern>${pattern}</pattern> + </encoder> + </appender> + + <logger level="debug" name="org.onap.logging.ref.slf4j" additivity="false"> + <appender-ref ref="STDOUT" /> + <appender-ref ref="FILE" /> + </logger> + + <root level="error"> + <appender-ref ref="STDOUT" /> + </root> + +</configuration> |