Skip to content

Commit 95f0f0d

Browse files
Duncan-tree-zhouDuncan-tree-zhou
committed
add metric annotation instrumentation
1 parent 98d0c3d commit 95f0f0d

File tree

16 files changed

+1076
-2
lines changed

16 files changed

+1076
-2
lines changed

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ out/
4848

4949
# Others #
5050
##########
51+
instrumentation/opentelemetry-instrumentation-annotations-1.16/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/instrumentationannotations/annotations/
5152
/logs/*
5253
/bin
5354
/out

‎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[] additionalAttributes()
29+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String description()
30+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String returnValueAttribute()
31+
+++ NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String 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

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
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.invocation.count}.
45+
*/
46+
String value() default "";
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+
* <p>This property would not take effect if the value is not specified.
55+
*/
56+
String description() default "";
57+
58+
/**
59+
* Unit of the instrument.
60+
*
61+
* <p>Unit strings should follow the instrument unit rules: <a
62+
* 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>
63+
*
64+
* <p>This property would not take effect if the value is not specified.
65+
*/
66+
String unit() default "{invocation}";
67+
68+
/**
69+
* List of key-value pairs to supply additional attributes.
70+
*
71+
* <p>Example:
72+
*
73+
* <pre>
74+
* {@literal @}Counted(
75+
* additionalAttributes = {
76+
* "key1", "value1",
77+
* "key2", "value2",
78+
* })
79+
* </pre>
80+
*/
81+
String[] additionalAttributes() default {};
82+
83+
/**
84+
* Attribute name for the return value.
85+
*
86+
* <p>The name of the attribute for the return value of the method call. {@link Object#toString()}
87+
* will be called on the return value to convert it to a String.
88+
*
89+
* <p>By default, the instrument will not have an attribute with the return value.
90+
*
91+
* <p>Warning: be careful to fill it because it might cause an explosion of the cardinality on
92+
* your metric
93+
*/
94+
String returnValueAttribute() default "";
95+
}

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

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

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

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
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.LongHistogram Histogram} instrument
15+
* observing the duration of invocations of the annotated method or constructor.
16+
*
17+
* <p>By default, the Histogram 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" of 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 Histogram 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 Timed {
37+
38+
/**
39+
* Name of the Histogram 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.invocation.duration}.
45+
*/
46+
String value() default "";
47+
48+
/**
49+
* Description for 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+
* The unit for the instrument.
58+
*
59+
* <p>Default is seconds.
60+
*/
61+
String unit() default "s";
62+
63+
/**
64+
* List of key-value pairs to supply additional attributes.
65+
*
66+
* <p>Example:
67+
*
68+
* <pre>
69+
* {@literal @}Timed(
70+
* additionalAttributes = {
71+
* "key1", "value1",
72+
* "key2", "value2",
73+
* })
74+
* </pre>
75+
*/
76+
String[] additionalAttributes() default {};
77+
78+
/**
79+
* Attribute name for the return value.
80+
*
81+
* <p>The name of the attribute for the return value of the method call. {@link Object#toString()}
82+
* will be called on the return value to convert it to a String.
83+
*
84+
* <p>By default, the instrument will not have an attribute with the return value.
85+
*
86+
* <p>Warning: be careful to fill it because it might cause an explosion of the cardinality on
87+
* your metric
88+
*/
89+
String returnValueAttribute() default "";
90+
}

‎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)