add annotations for metrics

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

@@ -0,0 +1,88 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.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.invocations.total}.
+   */
+  String value() default "method.invocations.total";
+
+  /**
+   * 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>
+   */
+  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>
+   */
+  String unit() default "1";
+
+  /**
+   * 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.
+   */
+  String returnValueAttribute() default "";
+}

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

@@ -0,0 +1,36 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.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.
+   */
+  String value() default "";
+}

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

@@ -0,0 +1,88 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.annotations;
+
+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.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.invocations.duration}.
+   */
+  String value() default "method.invocations.duration";
+
+  /**
+   * 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 "1";
+
+  /**
+   * The unit for the instrument.
+   *
+   * <p>Default is millis seconds.
+   */
+  TimeUnit unit() default TimeUnit.MILLISECONDS;
+
+  /**
+   * List of key-value pairs to supply additional attributes.
+   *
+   * <p>Example:
+   *
+   * <pre>
+   * {@literal @}Timed(
+   *     additionalAttributes = {
+   *       "key1", "value1",
+   *       "key2", "value2",
+   * })
+   * </pre>
+   */
+  String[] attributes() 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.
+   */
+  String returnValueAttribute() default "";
+}