add metric annotation instrumentation

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

@@ -469,6 +469,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,13 @@
+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")
+}

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>exception.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 Counter 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 Counted {
+
+  /**
+   * Name of the Counter instrument.
+   *
+   * <p>The name should follow the instrument naming rule: <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 value();
+
+  /**
+   * Description of the instrument.
+   *
+   * <p>Description strings should follow the instrument 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 would not take effect if the value is not specified.
+   */
+  String description() default "";
+
+  /**
+   * Unit of the instrument.
+   *
+   * <p>Unit strings should follow the instrument 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 would not take effect if the value is not specified.
+   */
+  String unit() default "{invocation}";
+}

instrumentation-annotations-incubator/src/main/java/io/opentelemetry/instrumentation/annotations/incubator/MetricAttribute.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 marks that a parameter of a method or constructor annotated with {@link Timed} or
+ * {@link Counted} should be added as an attribute to the instrument.
+ *
+ * <p>Application developers can use this annotation to signal OpenTelemetry auto-instrumentation
+ * that the attribute 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.
+ *
+ * <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 MetricAttribute {
+
+  /**
+   * 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 "";
+}

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

@@ -0,0 +1,38 @@
+/*
+ * 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 method return value as attribute 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 attribute 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.
+ *
+ * <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 MetricAttributeForReturnValue {
+
+  /**
+   * Attribute name for the return value.
+   *
+   * <p>The name of the attribute for the return value of the method call. {@link Object#toString()}
+   * may be called on the return value to convert it to a String.
+   */
+  String value();
+}

instrumentation-annotations-incubator/src/main/java/io/opentelemetry/instrumentation/annotations/incubator/StaticMetricAttribute.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 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 attribute 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)
+@Retention(RetentionPolicy.RUNTIME)
+@Repeatable(StaticMetricAttributes.class)
+public @interface StaticMetricAttribute {
+
+  /** Name of the attribute. */
+  String name();
+
+  /** Value of the attribute. */
+  String value();
+}

instrumentation-annotations-incubator/src/main/java/io/opentelemetry/instrumentation/annotations/incubator/StaticMetricAttributes.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 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 attribute 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)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface StaticMetricAttributes {
+
+  /** Array of {@link StaticMetricAttribute} annotations describing the added attributes. */
+  StaticMetricAttribute[] value();
+}

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

@@ -0,0 +1,60 @@
+/*
+ * 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;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * 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>exception.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 instrument.
+   *
+   * <p>The name should follow the instrument naming rule: <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 value();
+
+  /**
+   * Description for the instrument.
+   *
+   * <p>Description strings should follow the instrument 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 "";
+
+  /**
+   * The unit for the instrument.
+   *
+   * <p>Default is seconds.
+   */
+  TimeUnit unit() default TimeUnit.SECONDS;
+}

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("customizedName")
+  public void method() {}
+
+  @Counted("methodWithAttributes")
+  public void attributes(
+      @MetricAttribute String attribute1, @MetricAttribute("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("customizedName")
+  public void method() {}
+
+  @Timed("methodWithAttributes")
+  public void attributes(
+      @MetricAttribute String attribute1, @MetricAttribute("attribute2") long attribute2) {}
+}

instrumentation-annotations-support/src/main/java/io/opentelemetry/instrumentation/api/annotation/support/MethodBinder.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.annotation.support;
+
+import io.opentelemetry.api.common.AttributesBuilder;
+import java.lang.reflect.Method;
+import java.util.function.BiConsumer;
+import javax.annotation.Nullable;
+
+/** Helper class for binding method parameters and return value to attributes. */
+public final class MethodBinder {
+
+  /** Create binding for method return value. */
+  @Nullable
+  public static BiConsumer<AttributesBuilder, Object> bindReturnValue(
+      Method method, String attributeName) {
+    Class<?> returnType = method.getReturnType();
+    if (returnType == void.class) {
+      return null;
+    }
+    AttributeBinding binding = AttributeBindingFactory.createBinding(attributeName, returnType);
+    return binding::apply;
+  }
+
+  /** Create binding for method parameters. */
+  @Nullable
+  public static BiConsumer<AttributesBuilder, Object[]> bindParameters(
+      Method method, ParameterAttributeNamesExtractor parameterAttributeNamesExtractor) {
+    AttributeBindings bindings = AttributeBindings.bind(method, parameterAttributeNamesExtractor);
+    if (bindings.isEmpty()) {
+      return null;
+    }
+    return bindings::apply;
+  }
+
+  private MethodBinder() {}
+}

instrumentation-annotations-support/src/main/java/io/opentelemetry/instrumentation/api/annotation/support/async/AsyncOperationEndHandler.java

@@ -0,0 +1,15 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.annotation.support.async;
+
+import io.opentelemetry.context.Context;
+import javax.annotation.Nullable;
+
+/** Callback that is called when async computation completes. */
+public interface AsyncOperationEndHandler<REQUEST, RESPONSE> {
+  void handle(
+      Context context, REQUEST request, @Nullable RESPONSE response, @Nullable Throwable error);
+}