aboutsummaryrefslogtreecommitdiffstats
path: root/openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main
diff options
context:
space:
mode:
Diffstat (limited to 'openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main')
-rw-r--r--openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/AuditData.java10
-rw-r--r--openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/ContextData.java5
-rw-r--r--openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/Logger.java16
-rw-r--r--openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/LoggerFactory.java22
-rw-r--r--openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/MetricsData.java248
-rw-r--r--openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/annotations/Metrics.java27
-rw-r--r--openecomp-be/lib/openecomp-sdc-logging-lib/openecomp-sdc-logging-api/src/main/java/org/openecomp/sdc/logging/api/package-info.java38
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