[Tracing Framework] Add proper API annotations (opensearch-project#9706)

Signed-off-by: Andriy Redko <[email protected]> Signed-off-by: Ivan Brusic <[email protected]>
brusic · Sep 25, 2023 · 6f688e0 · 6f688e0
1 parent 084e854
commit 6f688e0
Show file tree

Hide file tree

Showing 34 changed files with 120 additions and 14 deletions.
diff --git a/libs/telemetry/build.gradle b/libs/telemetry/build.gradle
@@ -10,6 +10,8 @@
  */
 
 dependencies {
+  api project(':libs:opensearch-common')
+
   testImplementation "com.carrotsearch.randomizedtesting:randomizedtesting-runner:${versions.randomizedrunner}"
   testImplementation "junit:junit:${versions.junit}"
   testImplementation "org.hamcrest:hamcrest:${versions.hamcrest}"

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/Telemetry.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/Telemetry.java
@@ -8,14 +8,16 @@
 
 package org.opensearch.telemetry;
 
+import org.opensearch.common.annotation.ExperimentalApi;
 import org.opensearch.telemetry.metrics.MetricsTelemetry;
 import org.opensearch.telemetry.tracing.TracingTelemetry;
 
 /**
  * Interface defining telemetry
  *
- * @opensearch.internal
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public interface Telemetry {
 
     /**

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/metrics/MetricsTelemetry.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/metrics/MetricsTelemetry.java
@@ -8,9 +8,14 @@
 
 package org.opensearch.telemetry.metrics;
 
+import org.opensearch.common.annotation.ExperimentalApi;
+
 /**
  * Interface for metrics telemetry providers
+  *
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public interface MetricsTelemetry {
 
 }
diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/AbstractSpan.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/AbstractSpan.java
@@ -8,11 +8,14 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.InternalApi;
+
 /**
  * Base span
  *
  * @opensearch.internal
  */
+@InternalApi
 public abstract class AbstractSpan implements Span {
 
     /**

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/DefaultScopedSpan.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/DefaultScopedSpan.java
@@ -8,13 +8,16 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.InternalApi;
+
 import java.util.Objects;
 
 /**
  * Default implementation of Scope
  *
  * @opensearch.internal
  */
+@InternalApi
 final class DefaultScopedSpan implements ScopedSpan {
 
     private final Span span;
@@ -73,7 +76,7 @@ public void close() {
 
     /**
      * Returns span.
-     * @return
+     * @return the span associated with this scope
      */
     Span getSpan() {
         return span;

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/DefaultSpanScope.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/DefaultSpanScope.java
@@ -8,12 +8,17 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.InternalApi;
+
 import java.util.Objects;
 
 /**
  * Default implementation for {@link SpanScope}
+ *
+ * @opensearch.internal
  */
-public class DefaultSpanScope implements SpanScope {
+@InternalApi
+class DefaultSpanScope implements SpanScope {
     private final Span span;
     private final SpanScope previousSpanScope;
     private static final ThreadLocal<SpanScope> spanScopeThreadLocal = new ThreadLocal<>();

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/DefaultTracer.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/DefaultTracer.java
@@ -8,6 +8,7 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.InternalApi;
 import org.opensearch.telemetry.tracing.attributes.Attributes;
 
 import java.io.Closeable;
@@ -23,6 +24,7 @@
  *
  *  @opensearch.internal
  */
+@InternalApi
 class DefaultTracer implements Tracer {
     static final String THREAD_NAME = "th_name";
 
@@ -77,6 +79,7 @@ private Span getCurrentSpanInternal() {
         return tracerContextStorage.get(TracerContextStorage.CURRENT_SPAN);
     }
 
+    @Override
     public SpanContext getCurrentSpan() {
         final Span currentSpan = tracerContextStorage.get(TracerContextStorage.CURRENT_SPAN);
         return (currentSpan == null) ? null : new SpanContext(currentSpan);

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/ScopedSpan.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/ScopedSpan.java
@@ -8,12 +8,16 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.ExperimentalApi;
 import org.opensearch.telemetry.tracing.noop.NoopScopedSpan;
 
 /**
  * An auto-closeable that represents scoped span.
  * It provides interface for all the span operations.
+ *
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public interface ScopedSpan extends AutoCloseable {
     /**
      * No-op Scope implementation

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/Span.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/Span.java
@@ -8,13 +8,16 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.ExperimentalApi;
+
 /**
  * An interface that represents a tracing span.
  * Spans are created by the Tracer.startSpan method.
  * Span must be ended by calling SpanScope.close which internally calls Span's endSpan.
  *
- * @opensearch.internal
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public interface Span {
 
     /**

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/SpanContext.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/SpanContext.java
@@ -8,10 +8,15 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.ExperimentalApi;
+
 /**
  * Wrapped Span will be exposed to the code outside of tracing package for sharing the {@link Span} without having access to
  * its properties.
+ *
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public final class SpanContext {
     private final Span span;
 

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/SpanCreationContext.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/SpanCreationContext.java
@@ -8,11 +8,15 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.ExperimentalApi;
 import org.opensearch.telemetry.tracing.attributes.Attributes;
 
 /**
  * Context for span details.
+ *
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public final class SpanCreationContext {
     private final String spanName;
     private final Attributes attributes;

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/SpanReference.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/SpanReference.java
@@ -8,11 +8,14 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.InternalApi;
+
 /**
  * Wrapper class to hold reference of Span
  *
  * @opensearch.internal
  */
+@InternalApi
 final class SpanReference {
 
     private Span span;

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/SpanScope.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/SpanScope.java
@@ -8,11 +8,15 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.ExperimentalApi;
 import org.opensearch.telemetry.tracing.noop.NoopSpanScope;
 
 /**
  * An auto-closeable that represents scope of the span.
+ *
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public interface SpanScope extends AutoCloseable {
 
     /**

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/Tracer.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/Tracer.java
@@ -8,6 +8,7 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.ExperimentalApi;
 import org.opensearch.telemetry.tracing.attributes.Attributes;
 import org.opensearch.telemetry.tracing.http.HttpTracer;
 
@@ -18,7 +19,10 @@
  * It automatically handles the context propagation between threads, tasks, nodes etc.
  *
  * All methods on the Tracer object are multi-thread safe.
+ *
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public interface Tracer extends HttpTracer, Closeable {
     /**
      * Starts the {@link Span} with given {@link SpanCreationContext}

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/TracerContextStorage.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/TracerContextStorage.java
@@ -8,13 +8,16 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.InternalApi;
+
 /**
  * Storage interface used for storing tracing context
  * @param <K> key type
  * @param <V> value type
  *
  * @opensearch.internal
  */
+@InternalApi
 public interface TracerContextStorage<K, V> {
     /**
      * Key for storing current span

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/TracingContextPropagator.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/TracingContextPropagator.java
@@ -8,6 +8,8 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.ExperimentalApi;
+
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
@@ -16,8 +18,9 @@
 /**
  * Interface defining the tracing related context propagation
  *
- * @opensearch.internal
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public interface TracingContextPropagator {
 
     /**

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/TracingTelemetry.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/TracingTelemetry.java
@@ -8,15 +8,17 @@
 
 package org.opensearch.telemetry.tracing;
 
+import org.opensearch.common.annotation.ExperimentalApi;
 import org.opensearch.telemetry.tracing.attributes.Attributes;
 
 import java.io.Closeable;
 
 /**
  * Interface for tracing telemetry providers
  *
- * @opensearch.internal
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public interface TracingTelemetry extends Closeable {
 
     /**

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/attributes/Attributes.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/attributes/Attributes.java
@@ -8,14 +8,19 @@
 
 package org.opensearch.telemetry.tracing.attributes;
 
+import org.opensearch.common.annotation.ExperimentalApi;
+
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Objects;
 
 /**
  * Class to create attributes for a span.
+ *
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public class Attributes {
     private final Map<String, Object> attributesMap;
     /**

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/attributes/package-info.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/attributes/package-info.java
@@ -7,6 +7,6 @@
  */
 
 /**
- * Contains No-op implementations
+ * Contains attributes management
  */
 package org.opensearch.telemetry.tracing.attributes;
diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/http/HttpTracer.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/http/HttpTracer.java
@@ -8,6 +8,7 @@
 
 package org.opensearch.telemetry.tracing.http;
 
+import org.opensearch.common.annotation.ExperimentalApi;
 import org.opensearch.telemetry.tracing.Span;
 import org.opensearch.telemetry.tracing.attributes.Attributes;
 
@@ -19,7 +20,10 @@
  * from the HttpRequest header and propagate the span accordingly.
  *
  * All methods on the Tracer object are multi-thread safe.
+ *
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public interface HttpTracer {
     /**
      * Start the span with propagating the tracing info from the HttpRequest header.

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/noop/NoopScopedSpan.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/noop/NoopScopedSpan.java
@@ -8,13 +8,15 @@
 
 package org.opensearch.telemetry.tracing.noop;
 
+import org.opensearch.common.annotation.InternalApi;
 import org.opensearch.telemetry.tracing.ScopedSpan;
 
 /**
  * No-op implementation of SpanScope
  *
  * @opensearch.internal
  */
+@InternalApi
 public final class NoopScopedSpan implements ScopedSpan {
 
     /**

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/noop/NoopSpan.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/noop/NoopSpan.java
@@ -8,11 +8,15 @@
 
 package org.opensearch.telemetry.tracing.noop;
 
+import org.opensearch.common.annotation.InternalApi;
 import org.opensearch.telemetry.tracing.Span;
 
 /**
  * No-op implementation of {@link org.opensearch.telemetry.tracing.Span}
+ *
+ * @opensearch.internal
  */
+@InternalApi
 public class NoopSpan implements Span {
 
     /**

diff --git a/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/noop/NoopSpanScope.java b/libs/telemetry/src/main/java/org/opensearch/telemetry/tracing/noop/NoopSpanScope.java
@@ -8,12 +8,16 @@
 
 package org.opensearch.telemetry.tracing.noop;
 
+import org.opensearch.common.annotation.InternalApi;
 import org.opensearch.telemetry.tracing.Span;
 import org.opensearch.telemetry.tracing.SpanScope;
 
 /**
  * No-op implementation of {@link SpanScope}
+ *
+ * @opensearch.internal
  */
+@InternalApi
 public class NoopSpanScope implements SpanScope {
     /**
      * Constructor.