Skip to content

Commit 8b4e6d2

Browse files
Duncan-tree-zhouDuncan-tree-zhou
committed
add metric annotation instrumentation
1 parent 851cfb2 commit 8b4e6d2

File tree

8 files changed

+513
-1
lines changed

8 files changed

+513
-1
lines changed

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

+35-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,36 @@
11
Comparing source compatibility of against
2-
No changes.
2+
+++ NEW ANNOTATION: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.annotations.Counted (not serializable)
3+
+++ CLASS FILE FORMAT VERSION: 52.0 <- n.a.
4+
+++ NEW INTERFACE: java.lang.annotation.Annotation
5+
+++ NEW SUPERCLASS: java.lang.Object
6+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String[] additionalAttributes()
7+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String description()
8+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String returnValueAttribute()
9+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String unit()
10+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String value()
11+
+++ NEW ANNOTATION: java.lang.annotation.Target
12+
+++ NEW ELEMENT: value=java.lang.annotation.ElementType.METHOD,java.lang.annotation.ElementType.CONSTRUCTOR (+)
13+
+++ NEW ANNOTATION: java.lang.annotation.Retention
14+
+++ NEW ELEMENT: value=java.lang.annotation.RetentionPolicy.RUNTIME (+)
15+
+++ NEW ANNOTATION: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.annotations.MetricAttribute (not serializable)
16+
+++ CLASS FILE FORMAT VERSION: 52.0 <- n.a.
17+
+++ NEW INTERFACE: java.lang.annotation.Annotation
18+
+++ NEW SUPERCLASS: java.lang.Object
19+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String value()
20+
+++ NEW ANNOTATION: java.lang.annotation.Target
21+
+++ NEW ELEMENT: value=java.lang.annotation.ElementType.PARAMETER (+)
22+
+++ NEW ANNOTATION: java.lang.annotation.Retention
23+
+++ NEW ELEMENT: value=java.lang.annotation.RetentionPolicy.RUNTIME (+)
24+
+++ NEW ANNOTATION: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.annotations.Timed (not serializable)
25+
+++ CLASS FILE FORMAT VERSION: 52.0 <- n.a.
26+
+++ NEW INTERFACE: java.lang.annotation.Annotation
27+
+++ NEW SUPERCLASS: java.lang.Object
28+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String[] attributes()
29+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String description()
30+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String returnValueAttribute()
31+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.util.concurrent.TimeUnit unit()
32+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String value()
33+
+++ NEW ANNOTATION: java.lang.annotation.Target
34+
+++ NEW ELEMENT: value=java.lang.annotation.ElementType.METHOD,java.lang.annotation.ElementType.CONSTRUCTOR (+)
35+
+++ NEW ANNOTATION: java.lang.annotation.Retention
36+
+++ NEW ELEMENT: value=java.lang.annotation.RetentionPolicy.RUNTIME (+)

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

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
/*
2+
* Copyright The OpenTelemetry Authors
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package io.opentelemetry.instrumentation.annotations;
7+
8+
import java.lang.annotation.ElementType;
9+
import java.lang.annotation.Retention;
10+
import java.lang.annotation.RetentionPolicy;
11+
import java.lang.annotation.Target;
12+
13+
/**
14+
* This annotation creates a {@link io.opentelemetry.api.metrics.LongCounter Counter} instrument
15+
* recording the number of invocations of the annotated method or constructor.
16+
*
17+
* <p>By default, the Counter instrument will have the following attributes:
18+
*
19+
* <ul>
20+
* <li><b>code.namespace:</b> The fully qualified name of the class whose method is invoked.
21+
* <li><b>code.function:</b> The name of the annotated method, or "new" if the annotation is on a
22+
* constructor.
23+
* <li><b>exception.type:</b> This is only present if an Exception is thrown, and contains the
24+
* {@link Class#getCanonicalName() canonical name} of the Exception.
25+
* </ul>
26+
*
27+
* <p>Application developers can use this annotation to signal OpenTelemetry auto-instrumentation
28+
* that the Counter instrument should be created.
29+
*
30+
* <p>If you are a library developer, then probably you should NOT use this annotation, because it
31+
* is non-functional without the OpenTelemetry auto-instrumentation agent, or some other annotation
32+
* processor.
33+
*/
34+
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
35+
@Retention(RetentionPolicy.RUNTIME)
36+
public @interface Counted {
37+
38+
/**
39+
* Name of the Counter instrument.
40+
*
41+
* <p>The name should follow the instrument naming rule: <a
42+
* 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>
43+
*
44+
* <p>The default name is {@code method.invocations.total}.
45+
*/
46+
String value() default "method.invocations.total";
47+
48+
/**
49+
* Description of the instrument.
50+
*
51+
* <p>Description strings should follow the instrument description rules: <a
52+
* 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>
53+
*/
54+
String description() default "";
55+
56+
/**
57+
* Unit of the instrument.
58+
*
59+
* <p>Unit strings should follow the instrument unit rules: <a
60+
* 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>
61+
*/
62+
String unit() default "1";
63+
64+
/**
65+
* List of key-value pairs to supply additional attributes.
66+
*
67+
* <p>Example:
68+
*
69+
* <pre>
70+
* {@literal @}Counted(
71+
* additionalAttributes = {
72+
* "key1", "value1",
73+
* "key2", "value2",
74+
* })
75+
* </pre>
76+
*/
77+
String[] additionalAttributes() default {};
78+
79+
/**
80+
* Attribute name for the return value.
81+
*
82+
* <p>The name of the attribute for the return value of the method call. {@link Object#toString()}
83+
* will be called on the return value to convert it to a String.
84+
*
85+
* <p>By default, the instrument will not have an attribute with the return value.
86+
*/
87+
String returnValueAttribute() default "";
88+
}

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

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/*
2+
* Copyright The OpenTelemetry Authors
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package io.opentelemetry.instrumentation.annotations;
7+
8+
import java.lang.annotation.ElementType;
9+
import java.lang.annotation.Retention;
10+
import java.lang.annotation.RetentionPolicy;
11+
import java.lang.annotation.Target;
12+
13+
/**
14+
* This annotation marks that a parameter of a method or constructor annotated with {@link Timed} or
15+
* {@link Counted} should be added as an attribute to the instrument.
16+
*
17+
* <p>Application developers can use this annotation to signal OpenTelemetry auto-instrumentation
18+
* that the attribute should be created.
19+
*
20+
* <p>If you are a library developer, then probably you should NOT use this annotation, because it
21+
* is non-functional without the OpenTelemetry auto-instrumentation agent, or some other annotation
22+
* processor.
23+
*/
24+
@Target(ElementType.PARAMETER)
25+
@Retention(RetentionPolicy.RUNTIME)
26+
public @interface MetricAttribute {
27+
28+
/**
29+
* Optional name of the attribute.
30+
*
31+
* <p>If not specified and the code is compiled using the `{@code -parameters}` argument to
32+
* `javac`, the parameter name will be used instead. If the parameter name is not available, e.g.,
33+
* because the code was not compiled with that flag, the attribute will be ignored.
34+
*/
35+
String value() default "";
36+
}

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

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
/*
2+
* Copyright The OpenTelemetry Authors
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package io.opentelemetry.instrumentation.annotations;
7+
8+
import java.lang.annotation.ElementType;
9+
import java.lang.annotation.Retention;
10+
import java.lang.annotation.RetentionPolicy;
11+
import java.lang.annotation.Target;
12+
import java.util.concurrent.TimeUnit;
13+
14+
/**
15+
* This annotation creates a {@link io.opentelemetry.api.metrics.LongHistogram Histogram} instrument
16+
* observing the duration of invocations of the annotated method or constructor.
17+
*
18+
* <p>By default, the Histogram instrument will have the following attributes:
19+
*
20+
* <ul>
21+
* <li><b>code.namespace:</b> The fully qualified name of the class whose method is invoked.
22+
* <li><b>code.function:</b> The name of the annotated method, or "new" of the annotation is on a
23+
* constructor.
24+
* <li><b>exception.type:</b> This is only present if an Exception is thrown, and contains the
25+
* {@link Class#getCanonicalName canonical name} of the Exception.
26+
* </ul>
27+
*
28+
* <p>Application developers can use this annotation to signal OpenTelemetry auto-instrumentation
29+
* that the Histogram instrument should be created.
30+
*
31+
* <p>If you are a library developer, then probably you should NOT use this annotation, because it
32+
* is non-functional without the OpenTelemetry auto-instrumentation agent, or some other annotation
33+
* processor.
34+
*/
35+
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
36+
@Retention(RetentionPolicy.RUNTIME)
37+
public @interface Timed {
38+
39+
/**
40+
* Name of the Histogram instrument.
41+
*
42+
* <p>The name should follow the instrument naming rule: <a
43+
* 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>
44+
*
45+
* <p>The default name is {@code method.invocations.duration}.
46+
*/
47+
String value() default "method.invocations.duration";
48+
49+
/**
50+
* Description for the instrument.
51+
*
52+
* <p>Description strings should follow the instrument description rules: <a
53+
* 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>
54+
*/
55+
String description() default "1";
56+
57+
/**
58+
* The unit for the instrument.
59+
*
60+
* <p>Default is millis seconds.
61+
*/
62+
TimeUnit unit() default TimeUnit.MILLISECONDS;
63+
64+
/**
65+
* List of key-value pairs to supply additional attributes.
66+
*
67+
* <p>Example:
68+
*
69+
* <pre>
70+
* {@literal @}Timed(
71+
* additionalAttributes = {
72+
* "key1", "value1",
73+
* "key2", "value2",
74+
* })
75+
* </pre>
76+
*/
77+
String[] attributes() default {};
78+
79+
/**
80+
* Attribute name for the return value.
81+
*
82+
* <p>The name of the attribute for the return value of the method call. {@link Object#toString()}
83+
* will be called on the return value to convert it to a String.
84+
*
85+
* <p>By default, the instrument will not have an attribute with the return value.
86+
*/
87+
String returnValueAttribute() default "";
88+
}

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

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
/*
2+
* Copyright The OpenTelemetry Authors
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package io.opentelemetry.instrumentation.annotations;
7+
8+
public class CountedUsageExamples {
9+
10+
@Counted()
11+
public void method1() {}
12+
13+
@Counted("customizedName")
14+
public void method2() {}
15+
16+
@Counted
17+
public void attributes(
18+
@MetricAttribute String attribute1, @MetricAttribute("attribute2") long attribute2) {}
19+
}

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

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
/*
2+
* Copyright The OpenTelemetry Authors
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package io.opentelemetry.instrumentation.annotations;
7+
8+
public class TimedUsageExamples {
9+
10+
@Timed()
11+
public void method1() {}
12+
13+
@Timed("customizedName")
14+
public void method2() {}
15+
16+
@Timed
17+
public void attributes(
18+
@MetricAttribute String attribute1, @MetricAttribute("attribute2") long attribute2) {}
19+
}

0 commit comments

Comments
 (0)