add metric annotation instrumentation

.gitignore

@@ -48,6 +48,7 @@ out/
 
 # Others #
 ##########
+instrumentation/opentelemetry-instrumentation-annotations-1.16/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/instrumentationannotations/annotations/
 /logs/*
 /bin
 /out

docs/apidiffs/current_vs_latest/opentelemetry-instrumentation-annotations.txt

@@ -1,2 +1,36 @@
 Comparing source compatibility of  against 
-No changes.
++++  NEW ANNOTATION: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.annotations.Counted  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW INTERFACE: java.lang.annotation.Annotation
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String[] additionalAttributes()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String description()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String returnValueAttribute()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String unit()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String value()
+	+++  NEW ANNOTATION: java.lang.annotation.Target
+		+++  NEW ELEMENT: value=java.lang.annotation.ElementType.METHOD,java.lang.annotation.ElementType.CONSTRUCTOR (+)
+	+++  NEW ANNOTATION: java.lang.annotation.Retention
+		+++  NEW ELEMENT: value=java.lang.annotation.RetentionPolicy.RUNTIME (+)
++++  NEW ANNOTATION: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.annotations.MetricAttribute  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW INTERFACE: java.lang.annotation.Annotation
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String value()
+	+++  NEW ANNOTATION: java.lang.annotation.Target
+		+++  NEW ELEMENT: value=java.lang.annotation.ElementType.PARAMETER (+)
+	+++  NEW ANNOTATION: java.lang.annotation.Retention
+		+++  NEW ELEMENT: value=java.lang.annotation.RetentionPolicy.RUNTIME (+)
++++  NEW ANNOTATION: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.annotations.Timed  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW INTERFACE: java.lang.annotation.Annotation
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String[] additionalAttributes()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String description()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String returnValueAttribute()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String unit()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String value()
+	+++  NEW ANNOTATION: java.lang.annotation.Target
+		+++  NEW ELEMENT: value=java.lang.annotation.ElementType.METHOD,java.lang.annotation.ElementType.CONSTRUCTOR (+)
+	+++  NEW ANNOTATION: java.lang.annotation.Retention
+		+++  NEW ELEMENT: value=java.lang.annotation.RetentionPolicy.RUNTIME (+)

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

@@ -0,0 +1,95 @@
+/*
+ * 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 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, or "new" if the annotation is on a
+ *       constructor.
+ *   <li><b>exception.type:</b> This is only present if an Exception is thrown, and contains the
+ *       {@link Class#getCanonicalName() canonical name} of the Exception.
+ * </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>
+   *
+   * <p>The default name is {@code method.invocation.count}.
+   */
+  String value() default "";
+
+  /**
+   * 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}";
+
+  /**
+   * List of key-value pairs to supply additional attributes.
+   *
+   * <p>Example:
+   *
+   * <pre>
+   * {@literal @}Counted(
+   *     additionalAttributes = {
+   *       "key1", "value1",
+   *       "key2", "value2",
+   * })
+   * </pre>
+   */
+  String[] additionalAttributes() default {};
+
+  /**
+   * Attribute name for the return value.
+   *
+   * <p>The name of the attribute for the return value of the method call. {@link Object#toString()}
+   * will be called on the return value to convert it to a String.
+   *
+   * <p>By default, the instrument will not have an attribute with the return value.
+   *
+   * <p>Warning: be careful to fill it because it might cause an explosion of the cardinality on
+   * your metric
+   */
+  String returnValueAttribute() default "";
+}

instrumentation-annotations/src/main/java/io/opentelemetry/instrumentation/annotations/MetricAttribute.java

@@ -0,0 +1,39 @@
+/*
+ * 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 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.
+ */
+@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.
+   *
+   * <p>Warning: be careful to fill it because it might cause an explosion of the cardinality on
+   * your metric
+   */
+  String value() default "";
+}

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

@@ -0,0 +1,90 @@
+/*
+ * 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 creates a {@link io.opentelemetry.api.metrics.LongHistogram 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, or "new" of the annotation is on a
+ *       constructor.
+ *   <li><b>exception.type:</b> This is only present if an Exception is thrown, and contains the
+ *       {@link Class#getCanonicalName canonical name} of the Exception.
+ * </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>
+   *
+   * <p>The default name is {@code method.invocation.duration}.
+   */
+  String value() default "";
+
+  /**
+   * 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.
+   */
+  String unit() default "s";
+
+  /**
+   * List of key-value pairs to supply additional attributes.
+   *
+   * <p>Example:
+   *
+   * <pre>
+   * {@literal @}Timed(
+   *     additionalAttributes = {
+   *       "key1", "value1",
+   *       "key2", "value2",
+   * })
+   * </pre>
+   */
+  String[] additionalAttributes() default {};
+
+  /**
+   * Attribute name for the return value.
+   *
+   * <p>The name of the attribute for the return value of the method call. {@link Object#toString()}
+   * will be called on the return value to convert it to a String.
+   *
+   * <p>By default, the instrument will not have an attribute with the return value.
+   *
+   * <p>Warning: be careful to fill it because it might cause an explosion of the cardinality on
+   * your metric
+   */
+  String returnValueAttribute() default "";
+}

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

@@ -0,0 +1,19 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations;
+
+public class CountedUsageExamples {
+
+  @Counted()
+  public void method1() {}
+
+  @Counted("customizedName")
+  public void method2() {}
+
+  @Counted
+  public void attributes(
+      @MetricAttribute String attribute1, @MetricAttribute("attribute2") long attribute2) {}
+}

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

@@ -0,0 +1,19 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.annotations;
+
+public class TimedUsageExamples {
+
+  @Timed()
+  public void method1() {}
+
+  @Timed("customizedName")
+  public void method2() {}
+
+  @Timed
+  public void attributes(
+      @MetricAttribute String attribute1, @MetricAttribute("attribute2") long attribute2) {}
+}