By default, the Counter instrument will have the following attributes: + * + *
Application developers can use this annotation to signal OpenTelemetry auto-instrumentation + * that the Counter instrument should be created. + * + *
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. + * + *
The name should follow the instrument naming rule: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-naming-rule + * + *
The default name is {@code method.invocations.total}. + */ + String value() default "method.invocations.total"; + + /** + * Description of the instrument. + * + *
Description strings should follow the instrument description rules: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description + */ + String description() default ""; + + /** + * Unit of the instrument. + * + *
Unit strings should follow the instrument unit rules: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit + */ + String unit() default "1"; + + /** + * List of key-value pairs to supply additional attributes. + * + *
Example: + * + *
+ * {@literal @}Counted(
+ * additionalAttributes = {
+ * "key1", "value1",
+ * "key2", "value2",
+ * })
+ *
+ */
+ String[] additionalAttributes() default {};
+
+ /**
+ * Attribute name for the return value.
+ *
+ * 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. + * + *
By default, the instrument will not have an attribute with the return value. + */ + String returnValueAttribute() default ""; +} diff --git a/instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/annotations/MetricAttribute.java b/instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/annotations/MetricAttribute.java new file mode 100644 index 000000000000..1843abaadd87 --- /dev/null +++ b/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. + * + *
Application developers can use this annotation to signal OpenTelemetry auto-instrumentation + * that the attribute should be created. + * + *
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. + * + *
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 ""; +} diff --git a/instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/annotations/Timed.java b/instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/annotations/Timed.java new file mode 100644 index 000000000000..58b72818e3f5 --- /dev/null +++ b/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. + * + *
By default, the Histogram instrument will have the following attributes: + * + *
Application developers can use this annotation to signal OpenTelemetry auto-instrumentation + * that the Histogram instrument should be created. + * + *
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. + * + *
The name should follow the instrument naming rule: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-naming-rule + * + *
The default name is {@code method.invocations.duration}. + */ + String value() default "method.invocations.duration"; + + /** + * Description for the instrument. + * + *
Description strings should follow the instrument description rules: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description + */ + String description() default "1"; + + /** + * The unit for the instrument. + * + *
Default is millis seconds. + */ + TimeUnit unit() default TimeUnit.MILLISECONDS; + + /** + * List of key-value pairs to supply additional attributes. + * + *
Example: + * + *
+ * {@literal @}Timed(
+ * additionalAttributes = {
+ * "key1", "value1",
+ * "key2", "value2",
+ * })
+ *
+ */
+ String[] attributes() default {};
+
+ /**
+ * Attribute name for the return value.
+ *
+ * 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. + * + *
By default, the instrument will not have an attribute with the return value. + */ + String returnValueAttribute() default ""; +}