diff options
Diffstat (limited to 'openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main')
7 files changed, 303 insertions, 63 deletions
diff --git a/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/AuditData.java b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/AuditData.java index ecf795b2d5..b7c4e0d78f 100644 --- a/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/AuditData.java +++ b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/AuditData.java @@ -17,19 +17,15 @@ package org.openecomp.sdc.logging.api; /** - * Builder to populate audit data for logging according to - * <a href="https://wiki.onap.org/download/attachments/1015849/ONAP%20application%20logging%20guidelines.pdf?api=v2> - * ONAP application logging guidelines</a>. This includes only data known to an application, and not otherwise available - * to the logging framework. + * Builder to populate <i>audit</i> data. This includes only data known to an application, and not otherwise available + * to the logging framework. As opposed, for example, to local runtime, host address, etc. * * @author KATYR, evitaliy * @since February 15, 2018 */ public class AuditData { - // A concrete implementation interface was chosen over an interface to enable to gracefully add new fields without - // affecting client code. Also, the builder can be implemented differently if needed, without affecting client code. - // For instance, it may delegate the population and instantiation to a service provider. + // don't inherit from MetricsData because it has a very different meaning private final long startTime; private final long endTime; diff --git a/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/ContextData.java b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/ContextData.java index ea777d5907..43f0143774 100644 --- a/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/ContextData.java +++ b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/ContextData.java @@ -17,8 +17,9 @@ package org.openecomp.sdc.logging.api; /** - * Builder to populate logging context data. This includes only data known to an application, and not otherwise - * available to the logging framework. + * Builder to populate logging <i>context</i> data, i.e. data that should be available to any log writing event + * throughout an application. This includes only data known at some point to the application (e.g. at an API call), + * and not otherwise available to the logging framework (e.g. information about local runtime, machine, etc.). * * @author evitaliy * @since Mar 22, 2018 diff --git a/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/Logger.java b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/Logger.java index d02e99f9a2..d100a2d7f9 100644 --- a/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/Logger.java +++ b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/Logger.java @@ -31,16 +31,16 @@ public interface Logger { boolean isMetricsEnabled(); + void metrics(MetricsData data); + + /** + * Kept for backward compatibility. + * + * @deprecated will be removed soon, {@link #metrics(MetricsData)} must be used instead + */ + @Deprecated void metrics(String msg); - void metrics(String msg, Object arg); - - void metrics(String msg, Object arg1, Object arg2); - - void metrics(String msg, Object... arguments); - - void metrics(String msg, Throwable t); - boolean isAuditEnabled(); void audit(AuditData data); diff --git a/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/LoggerFactory.java b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/LoggerFactory.java index 399fd3717e..1f3df8bcc0 100644 --- a/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/LoggerFactory.java +++ b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/LoggerFactory.java @@ -16,9 +16,8 @@ package org.openecomp.sdc.logging.api; -import org.openecomp.sdc.logging.spi.LoggerCreationService; - import java.util.Objects; +import org.openecomp.sdc.logging.spi.LoggerCreationService; /** * <a>Factory to hide a concrete, framework-specific implementation of logger creation.</a> @@ -69,27 +68,12 @@ public class LoggerFactory { } @Override - public void metrics(String msg) { + public void metrics(MetricsData msg) { // no-op } @Override - public void metrics(String msg, Object arg) { - // no-op - } - - @Override - public void metrics(String msg, Object arg1, Object arg2) { - // no-op - } - - @Override - public void metrics(String msg, Object... arguments) { - // no-op - } - - @Override - public void metrics(String msg, Throwable t) { + public void metrics(String msg) { // no-op } diff --git a/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/MetricsData.java b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/MetricsData.java new file mode 100644 index 0000000000..c44ab42efa --- /dev/null +++ b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/MetricsData.java @@ -0,0 +1,248 @@ +/* + * Copyright © 2016-2018 European Support Limited + * + * 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. + */ + +package org.openecomp.sdc.logging.api; + +/** + * Builder to populate <i>metrics</i> data. This includes only data known to an application, and not otherwise available + * to the logging framework. + * + * @author evitaliy + * @since 26 Mar 2018 + */ +public class MetricsData { + + // don't inherit from AuditData because it has a very different meaning + + private final long startTime; + private final long endTime; + private final StatusCode statusCode; + private final String responseCode; + private final String responseDescription; + private final String clientIpAddress; + private final String targetVirtualEntity; + private final String targetEntity; + + private MetricsData(final MetricsDataBuilder builder) { + this.startTime = builder.startTime; + this.endTime = builder.endTime; + this.statusCode = builder.statusCode; + this.responseCode = builder.responseCode; + this.responseDescription = builder.responseDescription; + this.clientIpAddress = builder.clientIpAddress; + this.targetEntity = builder.targetEntity; + this.targetVirtualEntity = builder.targetVirtualEntity; + } + + /** + * Begin timestamp of an API invocation. + * + * @return timestamp + */ + public long getStartTime() { + return startTime; + } + + /** + * End timestamp of an API invocation. + * + * @return timestamp + */ + public long getEndTime() { + return endTime; + } + + /** + * Result status of an API invocation. + * + * @return protocol and application agnostic status code + */ + public StatusCode getStatusCode() { + return statusCode; + } + + /** + * Application/protocol specific response status of an API invocation. + * + * @return response code + */ + public String getResponseCode() { + return responseCode; + } + + /** + * Application/protocol specific response in a human-friendly way. + * + * @return human-friendly response description + */ + public String getResponseDescription() { + return responseDescription; + } + + /** + * IP address of the invoking client when available. + * + * @return IP address + */ + public String getClientIpAddress() { + return clientIpAddress; + } + + /** + * External entity invoked by the local system. + * + * @return identifier of an external entity (system, component, sub-component) + */ + public String getTargetEntity() { + return targetEntity; + } + + /** + * External API invoked by the local system. + * + * @return name of an external API + */ + public String getTargetVirtualEntity() { + return targetVirtualEntity; + } + + @Override + public String toString() { + return "AuditData{startTime=" + startTime + ", endTime=" + endTime + ", statusCode=" + statusCode + + ", responseCode=" + responseCode + ", responseDescription=" + responseDescription + + ", clientIpAddress=" + clientIpAddress + '}'; + } + + public static MetricsDataBuilder builder() { + return new MetricsDataBuilder(); + } + + /** + * Fluent API for building metrics data. + */ + public static class MetricsDataBuilder { + + private long startTime; + private long endTime; + private StatusCode statusCode; + private String responseCode; + private String responseDescription; + private String clientIpAddress; + private String targetEntity; + private String targetVirtualEntity; + + MetricsDataBuilder() { /* package-private default constructor to hide the public one */ } + + /** + * Begin timestamp of an activity being audited. + * + * @param startTime local timestamp, usually received from {@link System#currentTimeMillis()} + * @return this builder for fluent API + */ + public MetricsDataBuilder startTime(final long startTime) { + this.startTime = startTime; + return this; + } + + /** + * End timestamp of an activity being audited. + * + * @param endTime local timestamp, usually received from {@link System#currentTimeMillis()} + * @return this builder for fluent API + */ + public MetricsDataBuilder endTime(final long endTime) { + this.endTime = endTime; + return this; + } + + /** + * Indicate whether an invocation was successful. It is up the the application to decide if a particular result + * must be treated as a success or a failure. + * + * @param statusCode invocation status success/failure + * @return this builder for fluent API + */ + public MetricsDataBuilder statusCode(final StatusCode statusCode) { + this.statusCode = statusCode; + return this; + } + + /** + * Application/protocol specific response code. For a Web API, it is likely a standard HTTP response code. + * + * @param responseCode response code that depends on application and invocation protocol + * @return this builder for fluent API + */ + public MetricsDataBuilder responseCode(final String responseCode) { + this.responseCode = responseCode; + return this; + } + + /** + * Response description that explains {@link #responseCode(String)} in a human-friendly way. For a Web API, it + * is likely to be a standard HTTP response phrase. + * + * @param responseDescription human-friendly response description + * @return this builder for fluent API + */ + public MetricsDataBuilder responseDescription(final String responseDescription) { + this.responseDescription = responseDescription; + return this; + } + + /** + * IP address of an invoking client. + * + * @param clientIpAddress IP address + * @return this builder for fluent API + */ + public MetricsDataBuilder clientIpAddress(final String clientIpAddress) { + this.clientIpAddress = clientIpAddress; + return this; + } + + /** + * External entity at which the operation is invoked. + * + * @param targetEntity external entity identifier + * @return this builder for fluent API + */ + public MetricsDataBuilder targetEntity(String targetEntity) { + this.targetEntity = targetEntity; + return this; + } + + /** + * Name of the API or operation activities invoked at the external entity. + * + * @param targetVirtualEntity invoked external API + * @return this builder for fluent API + */ + public MetricsDataBuilder targetVirtualEntity(String targetVirtualEntity) { + this.targetVirtualEntity = targetVirtualEntity; + return this; + } + + /** + * Create an instance of {@link MetricsData}. + * + * @return a populated instance of audit data + */ + public MetricsData build() { + return new MetricsData(this); + } + } +} diff --git a/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/annotations/Metrics.java b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/annotations/Metrics.java deleted file mode 100644 index 2be7eac01c..0000000000 --- a/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/annotations/Metrics.java +++ /dev/null @@ -1,27 +0,0 @@ -/* - * Copyright © 2016-2017 European Support Limited - * - * 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. - */ - -package org.openecomp.sdc.logging.api.annotations; - -/** - * Indicates a method whose execution time should be measured and logged as required for Open OPENECOMP metrics. - * - * @author evitaliy - * @since 27/07/2016. - */ - -public @interface Metrics { -} diff --git a/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/package-info.java b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/package-info.java new file mode 100644 index 0000000000..a8ecad0c55 --- /dev/null +++ b/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/package-info.java @@ -0,0 +1,38 @@ +/* + * Copyright © 2016-2018 European Support Limited + * + * 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. + */ + +/** + * <p>Client-visible API for logging, implemented according to + * <a href="https://wiki.onap.org/download/attachments/1015849/ONAP%20application%20logging%20guidelines.pdf?api=v2"> + * ONAP application logging guidelines</a>. The actual implementation is delegated to a service provider bound through + * the <a href="https://docs.oracle.com/javase/tutorial/ext/basics/spi.html">Java SPI</a> mechanism. The provider must + * implement {@link org.openecomp.sdc.logging.spi.LoggingServiceProvider}.</p> + * <p>The logging API collects the following types of data:</p> + * <ol> + * <li>Context that must be propagated throughout the application, and available at any point for debug and error + * reporting.</li> + * <li>Audit data, reflecting the invocation of a local, usually REST, API.</li> + * <li>Metrics data, reflecting the invocation of a remote API by current system (component).</li> + * </ol> + * <p>The construction of all three types of data follows the same pattern for consistency. The builder pattern has + * been chosen over an interface to enable to gracefully add new fields without affecting the client code. Also, the + * builder can be implemented differently if needed, also without affecting client code. For instance, it may delegate + * the instantiation and population of a data object to the service provider.</p> + * + * @author evitaliy + * @since 26 Mar 2018 + */ +package org.openecomp.sdc.logging.api;
\ No newline at end of file |