add metric annotation instrumentation

.fossa.yml

@@ -10,6 +10,9 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation-annotations'
+    - type: gradle
+      path: ./
+      target: ':instrumentation-annotations-incubator'
     - type: gradle
       path: ./
       target: ':instrumentation-annotations-support'
@@ -214,9 +217,6 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation:opentelemetry-extension-kotlin-1.0:javaagent'
-    - type: gradle
-      path: ./
-      target: ':instrumentation:opentelemetry-instrumentation-annotations-1.16:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:opentelemetry-instrumentation-api:javaagent'
@@ -811,6 +811,15 @@ targets:
     - type: gradle
       path: ./
       target: ':instrumentation:opentelemetry-api:opentelemetry-api-1.52:javaagent'
+    - type: gradle
+      path: ./
+      target: ':instrumentation:opentelemetry-instrumentation-annotations:opentelemetry-instrumentation-annotations-1.16:javaagent'
+    - type: gradle
+      path: ./
+      target: ':instrumentation:opentelemetry-instrumentation-annotations:opentelemetry-instrumentation-annotations-common:javaagent'
+    - type: gradle
+      path: ./
+      target: ':instrumentation:opentelemetry-instrumentation-annotations:opentelemetry-instrumentation-annotations-incubator:javaagent'
     - type: gradle
       path: ./
       target: ':instrumentation:pekko:pekko-actor-1.0:javaagent'

conventions/src/main/kotlin/otel.java-conventions.gradle.kts

@@ -476,6 +476,7 @@ configurations.configureEach {
       substitute(module("io.opentelemetry.instrumentation:opentelemetry-instrumentation-api")).using(project(":instrumentation-api"))
       substitute(module("io.opentelemetry.instrumentation:opentelemetry-instrumentation-api-incubator")).using(project(":instrumentation-api-incubator"))
       substitute(module("io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations")).using(project(":instrumentation-annotations"))
+      substitute(module("io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations-incubator")).using(project(":instrumentation-annotations-incubator"))
       substitute(module("io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations-support")).using(
         project(":instrumentation-annotations-support")
       )

instrumentation-annotations-incubator/build.gradle.kts

@@ -0,0 +1,20 @@
+plugins {
+  id("otel.java-conventions")
+  id("otel.japicmp-conventions")
+  id("otel.publish-conventions")
+
+  id("otel.animalsniffer-conventions")
+}
+
+group = "io.opentelemetry.instrumentation"
+
+dependencies {
+  api("io.opentelemetry:opentelemetry-api")
+}
+
+tasks.test {
+  // This module does not have tests, but has example classes in the test directory. Gradle 9 fails
+  // the build when there are source files in the test directory but no tests to run so we disable
+  // the test task.
+  enabled = false
+}

instrumentation-annotations-incubator/src/main/java/io/opentelemetry/instrumentation/annotations/incubator/Attribute.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations.incubator;
+
+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 or constructor annotated with {@link Timed} or
+ * {@link Counted} should be added as an attribute to the metric.
+ *
+ * <p>`{@link Object#toString()}` will be called on the parameter value to convert it to a String.
+ *
+ * <p>Application developers can use this annotation to signal OpenTelemetry auto-instrumentation
+ * that the attribute should be captured.
+ *
+ * <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.
+ *
+ * <p>Warning: be careful using this because it might cause an explosion of the cardinality on your
+ * metric.
+ */
+@Target(ElementType.PARAMETER)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Attribute {
+
+  /**
+   * 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 name() default "";
+}

instrumentation-annotations-incubator/src/main/java/io/opentelemetry/instrumentation/annotations/incubator/Counted.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations.incubator;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation creates a {@link io.opentelemetry.api.metrics.LongCounter Counter} instrument
+ * recording the number of invocations of the annotated method or constructor.
+ *
+ * <p>By default, the Counter instrument will have the following attributes:
+ *
+ * <ul>
+ *   <li><b>code.namespace:</b> The fully qualified name of the class whose method is invoked.
+ *   <li><b>code.function:</b> The name of the annotated method.
+ *   <li><b>error.type:</b> This is only present if an Exception is thrown, and contains the {@link
+ *       Class#getName name} of the Exception class.
+ * </ul>
+ *
+ * <p>Application developers can use this annotation to signal OpenTelemetry auto-instrumentation
+ * that a Counter metric should be captured.
+ *
+ * <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.
+ */
+@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Counted {
+
+  /**
+   * Name of the Counter metric.
+   *
+   * <p>The name should follow the metric naming rules: <a
+   * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-name-syntax">https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-name-syntax</a>
+   */
+  String name();
+
+  /**
+   * Description of the metric.
+   *
+   * <p>Description strings should follow the metric description rules: <a
+   * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description</a>
+   *
+   * <p>This property will not take effect if the value is not specified.
+   */
+  String description() default "";
+
+  /**
+   * Unit of the metric.
+   *
+   * <p>Unit strings should follow the metric unit rules: <a
+   * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit">https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit</a>
+   *
+   * <p>This property will not take effect if the value is not specified.
+   */
+  String unit() default "{invocation}";
+}

instrumentation-annotations-incubator/src/main/java/io/opentelemetry/instrumentation/annotations/incubator/ReturnValueAttribute.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations.incubator;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation allows for adding the method return value as an attribute to metrics recorded
+ * using the {@link Timed} and {@link Counted} annotations.
+ *
+ * <p>{@link Object#toString()} will be called on the return value to convert it to a String.
+ *
+ * <p>Application developers can use this annotation to signal OpenTelemetry auto-instrumentation
+ * that the attribute should be captured.
+ *
+ * <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.
+ *
+ * <p>Warning: be careful using this because it might cause an explosion of the cardinality on your
+ * metric.
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ReturnValueAttribute {
+
+  /**
+   * Attribute name for the return value.
+   *
+   * <p>The name of the attribute for the return value of the method call.
+   */
+  String value();
+}

instrumentation-annotations-incubator/src/main/java/io/opentelemetry/instrumentation/annotations/incubator/StaticAttribute.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations.incubator;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation allows for adding static attributes to the metrics recorded using {@link Timed}
+ * and {@link Counted} annotations.
+ *
+ * <p>Application developers can use this annotation to signal OpenTelemetry auto-instrumentation
+ * that the static attributes should be captured.
+ *
+ * <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.
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@Repeatable(StaticAttributes.class)
+public @interface StaticAttribute {
+
+  /** Name of the static attribute. */
+  String name();
+
+  /** Value of the static attribute. */
+  String value();
+}

instrumentation-annotations-incubator/src/main/java/io/opentelemetry/instrumentation/annotations/incubator/StaticAttributes.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations.incubator;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation allows for adding static attributes to the metrics recorded using {@link Timed}
+ * and {@link Counted} annotations.
+ *
+ * <p>Application developers can use this annotation to signal OpenTelemetry auto-instrumentation
+ * that the static attributes should be captured.
+ *
+ * <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.
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface StaticAttributes {
+
+  /** Array of {@link StaticAttribute} annotations describing the attributes to capture. */
+  StaticAttribute[] value();
+}

instrumentation-annotations-incubator/src/main/java/io/opentelemetry/instrumentation/annotations/incubator/Timed.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations.incubator;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation creates a {@link io.opentelemetry.api.metrics.DoubleHistogram Histogram}
+ * instrument observing the duration of invocations of the annotated method or constructor.
+ *
+ * <p>By default, the Histogram instrument will have the following attributes:
+ *
+ * <ul>
+ *   <li><b>code.namespace:</b> The fully qualified name of the class whose method is invoked.
+ *   <li><b>code.function:</b> The name of the annotated method.
+ *   <li><b>error.type:</b> This is only present if an Exception is thrown, and contains the {@link
+ *       Class#getName name} of the Exception class.
+ * </ul>
+ *
+ * <p>Application developers can use this annotation to signal OpenTelemetry auto-instrumentation
+ * that the Histogram instrument should be created.
+ *
+ * <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.
+ */
+@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Timed {
+
+  /**
+   * Name of the Histogram metric.
+   *
+   * <p>The name should follow the metric naming rules: <a
+   * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-naming-rule">https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-naming-rule</a>
+   */
+  String name();
+
+  /**
+   * Description for the metric.
+   *
+   * <p>Description strings should follow the metric description rules: <a
+   * href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description">https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description</a>
+   */
+  String description() default "";
+}

instrumentation-annotations-incubator/src/test/java/io/opentelemetry/instrumentation/annotations/incubator/CountedUsageExamples.java

@@ -0,0 +1,16 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations.incubator;
+
+public class CountedUsageExamples {
+
+  @Counted(name = "customizedName")
+  public void method() {}
+
+  @Counted(name = "methodWithAttributes")
+  public void attributes(
+      @Attribute String attribute1, @Attribute(name = "attribute2") long attribute2) {}
+}

instrumentation-annotations-incubator/src/test/java/io/opentelemetry/instrumentation/annotations/incubator/TimedUsageExamples.java

@@ -0,0 +1,16 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations.incubator;
+
+public class TimedUsageExamples {
+
+  @Timed(name = "customizedName")
+  public void method() {}
+
+  @Timed(name = "methodWithAttributes")
+  public void attributes(
+      @Attribute String attribute1, @Attribute(name = "attribute2") long attribute2) {}
+}