opensearch-project · dblock · Sep 5, 2023 · Sep 1, 2023
@@ -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}"

@@ -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 {
 
     /**

@@ -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 {
 
 }
@@ -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 {
 
     /**

@@ -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;

@@ -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<>();

@@ -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);

@@ -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

@@ -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 {
 
     /**

@@ -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;
 

@@ -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;

@@ -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;

@@ -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 {
 
     /**

@@ -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}

@@ -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

@@ -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 {
 
     /**

@@ -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 {
 
     /**

@@ -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;
     /**

@@ -7,6 +7,6 @@
  */
 
 /**
- * Contains No-op implementations
+ * Contains attributes management
  */
 package org.opensearch.telemetry.tracing.attributes;
@@ -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.

@@ -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 {
 
     /**

@@ -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 {
 
     /**

@@ -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.