Add @SpanAttribute annotation for adding attributes to spans created through instrumentation (#3168)

* Add WithSpanAttribute annotation for adding attributes to spans created through instrumentation

* Fix warning on invalid parameter due to suspected name mismatch

* Add javadoc comment about formal parameter names

* Address PR comments, change name to SpanAttribute

* Reference Span.currentSpan().setAttribute() in the javadocs

* Fix Javadoc copypasta based on PR feedback

* Add @since to javadoc on SpanAttribute

* Bump javadoc since to version 1.4

extensions/annotations/src/main/java/io/opentelemetry/extension/annotations/SpanAttribute.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.extension.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 the OpenTelemetry auto-instrumentation agent, or some other annotation
+ * processor.
+ *
+ * @see <a href="https://github.com/open-telemetry/opentelemetry-java-instrumentation">OpenTelemetry
+ *     OpenTelemetry Instrumentation for Java</a>
+ * @since 1.4.0
+ */
+@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 "";
+}

extensions/annotations/src/main/java/io/opentelemetry/extension/annotations/WithSpan.java

@@ -22,8 +22,8 @@ import java.lang.annotation.Target;
  * is non-functional without the OpenTelemetry auto-instrumentation agent, or some other annotation
  * processor.
  *
- * @see <a href="https://github.com/open-telemetry/opentelemetry-auto-instr-java">OpenTelemetry
- *     Auto-Instrumentation</a>
+ * @see <a href="https://github.com/open-telemetry/opentelemetry-java-instrumentation">OpenTelemetry
+ *     OpenTelemetry Instrumentation for Java</a>
  */
 @Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
 @Retention(RetentionPolicy.RUNTIME)

extensions/annotations/src/test/java/io/opentelemetry/extension/annotations/WithSpanUsageExamples.java

@@ -34,4 +34,14 @@ public class WithSpanUsageExamples {
    */
   @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) {}
 }