Move instrumentation annotations to this repo
ADD
instrumentation-annotations/build.gradle.kts
+plugins {
+ id("otel.java-conventions")
+ id("otel.publish-conventions")
+
+ id("otel.animalsniffer-conventions")
+}
+
+group = "io.opentelemetry.instrumentation"
+
+dependencies {
+ api("io.opentelemetry:opentelemetry-api")
+}

ADD
instrumentation-annotations/src/main/java/io/opentelemetry/instrumentation/annotations/SpanAttribute.java
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation marks that a parameter of a method annotated by the {@link WithSpan} annotation
+ * should be added as an attribute to the newly created {@link io.opentelemetry.api.trace.Span}.
+ * Using this annotation is equivalent to calling {@code Span.currentSpan().setAttribute(...)}
+ * within the body of the method.
+ *
+ * <p>Application developers can use this annotation to signal OpenTelemetry auto-instrumentation
+ * that a new span attribute should be added to a span created when the parent method is executed.
+ *
+ * <p>If you are a library developer, then probably you should NOT use this annotation, because it
+ * is non-functional without some form of auto-instrumentation.
+ */
+@Target(ElementType.PARAMETER)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface SpanAttribute {
+ /**
+ * Optional name of the attribute.
+ *
+ * <p>If not specified and the code is compiled using the `{@code -parameters}` argument to
+ * `javac`, the parameter name will be used instead. If the parameter name is not available, e.g.,
+ * because the code was not compiled with that flag, the attribute will be ignored.
+ */
+ String value() default "";
+}

ADD
instrumentation-annotations/src/main/java/io/opentelemetry/instrumentation/annotations/WithSpan.java
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations;
+
+import io.opentelemetry.api.trace.SpanKind;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation marks that an execution of this method or constructor should result in a new
+ * {@link io.opentelemetry.api.trace.Span}.
+ *
+ * <p>Application developers can use this annotation to signal OpenTelemetry auto-instrumentation
+ * that a new span should be created whenever marked method is executed.
+ *
+ * <p>If you are a library developer, then probably you should NOT use this annotation, because it
+ * is non-functional without some form of auto-instrumentation.
+ */
+@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface WithSpan {
+ /**
+ * Optional name of the created span.
+ *
+ * <p>If not specified, an appropriate default name should be created by auto-instrumentation.
+ * E.g. {@code "className"."method"}
+ */
+ String value() default "";
+
+ /** Specify the {@link SpanKind} of span to be created. Defaults to {@link SpanKind#INTERNAL}. */
+ SpanKind kind() default SpanKind.INTERNAL;
+}

ADD
instrumentation-annotations/src/main/java/io/opentelemetry/instrumentation/annotations/package-info.java
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * This module contains various annotations that can be used by clients of OpenTelemetry API. They
+ * don't provide any functionality by themselves, but other modules, e.g. OpenTelemetry
+ * auto-instrumentation, can use them to enhance their functionality.
+ *
+ * <p>Note: If you are a library developer, then you should NOT use this module, because it is
+ * useless without some kind of annotation processing, such as bytecode manipulation during runtime.
+ * You cannot guarantee that users of your library will use that in their production system.
+ */
+@ParametersAreNonnullByDefault
+package io.opentelemetry.instrumentation.annotations;
+
+import javax.annotation.ParametersAreNonnullByDefault;

ADD
instrumentation-annotations/src/test/java/io/opentelemetry/instrumentation/annotations/WithSpanUsageExamples.java
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations;
+
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.SpanKind;
+
+/**
+ * This class is not a classical test. It's just a demonstration of possible usages of {@link
+ * WithSpan} annotation together with some explanations. The goal of this class is to serve as an
+ * early detection system for inconvenient API and unintended API breakage.
+ */
+@SuppressWarnings("unused")
+public class WithSpanUsageExamples {
+
+ /**
+ * A new {@link Span} will be created for this method's execution. The span's name will be
+ * automatically generated by OpenTelemetry auto-instrumentation, probably as
+ * "WithSpanUsageExamples.method1".
+ */
+ @WithSpan
+ public void method1() {}
+
+ /** Name of the generated span will be "shinyName". */
+ @WithSpan("shinyName")
+ public void method2() {}
+
+ /**
+ * A {@link Span} with the default name, and a {@link SpanKind} of {@link SpanKind#CONSUMER} will
+ * be created for this method.
+ */
+ @WithSpan(kind = SpanKind.CONSUMER)
+ public void consume() {}
+
+ /**
+ * A {@link Span} with the default name and kind and with default span attributes.
+ *
+ * @param attribute1 A span attribute with the default name of {@code attribute1}.
+ * @param value A span attribute with the name "attribute2".
+ */
+ @WithSpan
+ public void attributes(
+ @SpanAttribute String attribute1, @SpanAttribute("attribute2") long value) {}
+}

MODIFY
settings.gradle.kts
settings.gradle.kts
@@ -110,6 +110,7 @@ include(":instrumentation-api")
include(":instrumentation-api-semconv")
include(":instrumentation-appender-api-internal")
include(":instrumentation-appender-sdk-internal")
+include(":instrumentation-annotations")
include(":instrumentation-api-annotation-support")
// misc

Move instrumentation annotations to this repo (#6248)