From 5009ae82921126e5c6bc2a813044221fb945c8da Mon Sep 17 00:00:00 2001
From: Lam Tran <lam.tran@commercetools.com>
Date: Mon, 8 Apr 2024 14:49:55 +0200
Subject: [PATCH] Make javadoc consistent across monitoring middlewares (#615)

---
 .../monitoring/datadog/DatadogMiddleware.java  | 18 ++++++++++++++++++
 .../example/DatadogApiRootBuilderTest.java     |  2 +-
 .../opentelemetry/OpenTelemetryMiddleware.java | 10 +++++++++-
 src/main/javadoc/overview.html                 |  8 ++++++++
 4 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/commercetools/commercetools-monitoring-datadog/src/main/java/com/commercetools/monitoring/datadog/DatadogMiddleware.java b/commercetools/commercetools-monitoring-datadog/src/main/java/com/commercetools/monitoring/datadog/DatadogMiddleware.java
index b2a1eec3d65..d77a94d1a5f 100644
--- a/commercetools/commercetools-monitoring-datadog/src/main/java/com/commercetools/monitoring/datadog/DatadogMiddleware.java
+++ b/commercetools/commercetools-monitoring-datadog/src/main/java/com/commercetools/monitoring/datadog/DatadogMiddleware.java
@@ -16,6 +16,24 @@
 import io.vrap.rmf.base.client.ApiHttpResponse;
 import io.vrap.rmf.base.client.http.TelemetryMiddleware;
 
+/**
+ * <p>The DatadogTelemetry middleware can be used to report outgoing request to commercetools to Datadog.
+ * It can be registered as TelemetryMiddleware to the {@link io.vrap.rmf.base.client.ClientBuilder#withTelemetryMiddleware(TelemetryMiddleware) ClientBuilder}
+ * or the ApiRootBuilder.</p>
+ *
+ * {@include.example example.DatadogApiRootBuilderTest#addDatadogTelemetry()}
+ *
+ * The middleware adds the following metrics to Datadog:
+ * <ul>
+ *     <li>commercetools.client.duration: The duration of the request in milliseconds</li>
+ *     <li>commercetools.client.total_requests: The total number of requests</li>
+ *     <li>commercetools.client.error_requests: The total number of requests with a status code greater or equal to 400</li>
+ * </ul>
+ *
+ * <p>The metrics are enriched with the response status code, server address, port and request method.</p>
+ *
+ * <p>See also the <a href="https://github.com/commercetools/commercetools-sdk-java-v2/tree/main/examples/spring-datadog">Spring MVC example application</a> in the examples folder for further details.</p>
+ */
 public class DatadogMiddleware implements TelemetryMiddleware {
 
     private final MetricsApi apiInstance;
diff --git a/commercetools/commercetools-monitoring-datadog/src/test/java/example/DatadogApiRootBuilderTest.java b/commercetools/commercetools-monitoring-datadog/src/test/java/example/DatadogApiRootBuilderTest.java
index 951f9c5301a..758f5ea8a7a 100644
--- a/commercetools/commercetools-monitoring-datadog/src/test/java/example/DatadogApiRootBuilderTest.java
+++ b/commercetools/commercetools-monitoring-datadog/src/test/java/example/DatadogApiRootBuilderTest.java
@@ -12,7 +12,7 @@
 
 public class DatadogApiRootBuilderTest {
 
-    public void addOpenTelemetry() {
+    public void addDatadogTelemetry() {
         ApiHttpClient client = ApiRootBuilder.of()
                 .defaultClient(ServiceRegion.GCP_EUROPE_WEST1.getApiUrl())
                 .withTelemetryMiddleware(new DatadogMiddleware(ApiClient.getDefaultApiClient()))
diff --git a/commercetools/commercetools-monitoring-opentelemetry/src/main/java/com/commercetools/monitoring/opentelemetry/OpenTelemetryMiddleware.java b/commercetools/commercetools-monitoring-opentelemetry/src/main/java/com/commercetools/monitoring/opentelemetry/OpenTelemetryMiddleware.java
index fc831fb9b79..61ec108cb37 100644
--- a/commercetools/commercetools-monitoring-opentelemetry/src/main/java/com/commercetools/monitoring/opentelemetry/OpenTelemetryMiddleware.java
+++ b/commercetools/commercetools-monitoring-opentelemetry/src/main/java/com/commercetools/monitoring/opentelemetry/OpenTelemetryMiddleware.java
@@ -24,8 +24,16 @@
  *
  * {@include.example example.OpenTelemetryApiRootBuilderTest#addOpenTelemetry()}
  *
- * <p>The middleware records a histogram about the request timing in milliseconds. The total number of responses and errors is counted.
+ * The middleware adds the following metrics:
+ *  * <ul>
+ *      <li>commercetools.client.duration: The duration of the request in milliseconds</li>
+ *      <li>commercetools.client.total_requests: The total number of requests</li>
+ *      <li>commercetools.client.error_requests: The total number of requests with a status code greater or equal to 400</li>
+ * *  </ul>
+ *
  * The metrics are enriched with the response status code, server address, port and request method.</p>
+ *
+ * <p>See also the <a href="https://github.com/commercetools/commercetools-sdk-java-v2/tree/main/examples/spring-otel">Spring MVC example application</a> in the examples folder for further details.</p>
  */
 public class OpenTelemetryMiddleware implements TelemetryMiddleware {
     private final LongHistogram histogram;
diff --git a/src/main/javadoc/overview.html b/src/main/javadoc/overview.html
index 7909dc23df9..73feb7831c2 100644
--- a/src/main/javadoc/overview.html
+++ b/src/main/javadoc/overview.html
@@ -111,6 +111,14 @@ <h2>Monitoring</h2>
                 {@link com.commercetools.monitoring.newrelic.NewRelicTelemetryMiddleware NewRelic}
                 {@include.toc com.commercetools.monitoring.newrelic.NewRelicTelemetryMiddleware}
             </li>
+            <li>
+                {@link com.commercetools.monitoring.datadog.DatadogMiddleware Datadog}
+                {@include.toc com.commercetools.monitoring.datadog.DatadogMiddleware}
+            </li>
+            <li>
+                {@link com.commercetools.monitoring.opentelemetry.OpenTelemetryMiddleware OpenTelemetryMiddleware}
+                {@include.toc com.commercetools.monitoring.opentelemetry.OpenTelemetryMiddleware}
+            </li>
         </ol>
     </div>
 </body>