Skip to content

Commit 21cbf96

Browse files
Duncan-tree-zhouDuncan-tree-zhou
committed
add metric annotation instrumentation
1 parent cc1c042 commit 21cbf96

File tree

27 files changed

+1711
-2
lines changed

27 files changed

+1711
-2
lines changed

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

+36-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,36 @@
1-
Comparing source compatibility of opentelemetry-instrumentation-annotations-2.5.0-SNAPSHOT.jar against opentelemetry-instrumentation-annotations-2.4.0.jar
2-
No changes.
1+
Comparing source compatibility of against
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.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

+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

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
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.invocation.duration}.
46+
*/
47+
String value() default "";
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 "";
56+
57+
/**
58+
* The unit for the instrument.
59+
*
60+
* <p>Default is milliseconds.
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[] 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+
* <p>Warning: be careful to fill it because it might cause an explosion of the cardinality on
88+
* your metric
89+
*/
90+
String returnValueAttribute() default "";
91+
}

‎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+
}

‎instrumentation/opentelemetry-instrumentation-annotation-counted/README.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Settings for the OpenTelemetry Counted Instrumentation Annotations integration
2+
3+
| Environment variable | Type | Default | Description |
4+
|-----------------------------------------------------------------------------------------| ------ | ------- |-------------------------------------------------------------------------------------|
5+
| `otel.instrumentation.opentelemetry-instrumentation-annotation-counted.exclude-methods` | String | | All methods to be excluded from auto-instrumentation by Counted annotation advices. |

‎instrumentation/opentelemetry-instrumentation-annotation-counted/javaagent/build.gradle.kts

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
plugins {
2+
id("otel.javaagent-instrumentation")
3+
}
4+
5+
// note that muzzle is not run against the current SNAPSHOT instrumentation-annotations, but this is
6+
// ok because the tests are run against the current SNAPSHOT instrumentation-annotations which will
7+
// catch any muzzle issues in SNAPSHOT instrumentation-annotations
8+
9+
muzzle {
10+
pass {
11+
group.set("io.opentelemetry")
12+
module.set("opentelemetry-instrumentation-annotations")
13+
versions.set("(,)")
14+
}
15+
}
16+
17+
dependencies {
18+
compileOnly(project(":instrumentation-annotations-support"))
19+
20+
compileOnly(project(":javaagent-tooling"))
21+
22+
// this instrumentation needs to do similar shading dance as opentelemetry-api-1.0 because
23+
// the @WithSpan annotation references the OpenTelemetry API's SpanKind class
24+
//
25+
// see the comment in opentelemetry-api-1.0.gradle for more details
26+
compileOnly(project(":opentelemetry-instrumentation-annotations-shaded-for-instrumenting", configuration = "shadow"))
27+
28+
// Used by byte-buddy but not brought in as a transitive dependency.
29+
compileOnly("com.google.code.findbugs:annotations")
30+
testCompileOnly("com.google.code.findbugs:annotations")
31+
32+
testImplementation(project(":instrumentation-annotations"))
33+
testImplementation(project(":instrumentation-annotations-support"))
34+
testImplementation("net.bytebuddy:byte-buddy")
35+
}
36+
37+
tasks {
38+
compileTestJava {
39+
options.compilerArgs.add("-parameters")
40+
}
41+
test {
42+
jvmArgs(
43+
"-Dotel.instrumentation.opentelemetry-instrumentation-annotation-counted.exclude-methods=io.opentelemetry.test.annotations.counted.CountedExample[exampleIgnore]"
44+
)
45+
}
46+
}

0 commit comments

Comments
 (0)