Skip to content

Commit 9acc107

Browse files
trasktrask
committed
More classLoaderMatcher normalization
1 parent 3d445a9 commit 9acc107

20 files changed

Lines changed: 92 additions & 68 deletions

File tree

‎.github/agents/knowledge/javaagent-module-patterns.md‎

Lines changed: 47 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -90,10 +90,39 @@ For multi-class checks, and for negated exclusions, add a version comment **abov
9090
name string**.
9191

9292
- **Positive floor class** in `hasClassesNamed(...)`: use `// added in X.Y`.
93+
When the landmark class comes from a different artifact than the instrumentation's usual
94+
library module, choose the form based on what the comment is documenting:
95+
- If the version boundary is for that different artifact itself, use
96+
`// added in groupId:artifactId X.Y`.
97+
- If the comment is documenting the main library-module boundary or an optional-component
98+
presence condition that happens via a different artifact, use
99+
`// added in X.Y (via groupId:artifactId A.B)`.
100+
- For `javax.servlet:javax.servlet-api` and `jakarta.servlet:jakarta.servlet-api`, use the
101+
shorthand `Servlet` instead of the full Maven coordinate, for example `// added in Servlet
102+
5.0` or `// added in X.Y (via Servlet 5.0)`.
93103
- **Positive ceiling class** in `hasClassesNamed(...)`: use `// removed in Y.Z`.
104+
When the landmark class comes from a different artifact than the instrumentation's usual
105+
library module, choose the form based on what the comment is documenting:
106+
- If the version boundary is for that different artifact itself, use
107+
`// removed in groupId:artifactId Y.Z`.
108+
- If the comment is documenting the main library-module boundary through a class that is
109+
supplied by a different artifact, use `// removed in Y.Z (via groupId:artifactId A.B)`.
110+
- For `javax.servlet:javax.servlet-api` and `jakarta.servlet:jakarta.servlet-api`, use the
111+
shorthand `Servlet` instead of the full Maven coordinate, for example `// removed in Servlet
112+
5.0` or `// removed in Y.Z (via Servlet 5.0)`.
94113
- **Negated exclusion class** in `not(hasClassesNamed(...))` or
95114
`.and(not(hasClassesNamed(...)))`: use `// added in Y.Z`, because that class's first
96115
appearance is what starts excluding `Y.Z+`.
116+
When the landmark class comes from a different artifact than the instrumentation's usual
117+
library module, choose the form based on what the comment is documenting:
118+
- If the excluded range begins when that different artifact appears, use
119+
`// added in groupId:artifactId Y.Z`.
120+
- If the excluded range is described in terms of the main library-module version but the
121+
landmark class is supplied by a different artifact, use
122+
`// added in Y.Z (via groupId:artifactId A.B)`.
123+
- For `javax.servlet:javax.servlet-api` and `jakarta.servlet:jakarta.servlet-api`, use the
124+
shorthand `Servlet` instead of the full Maven coordinate, for example `// added in Servlet
125+
5.0` or `// added in Y.Z (via Servlet 5.0)`.
97126

98127
You may add brief parenthetical context, but only when it adds interesting, non-duplicative
99128
signal beyond the version role itself, for example native instrumentation notes, backport
@@ -195,9 +224,9 @@ public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
195224
```java
196225
@Override
197226
public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
198-
// added in azure-core 1.53
227+
// added in 1.53
199228
return hasClassesNamed("com.azure.core.util.LibraryTelemetryOptions")
200-
// added in azure-core-tracing-opentelemetry 1.0.0-beta.47
229+
// added in com.azure:azure-core-tracing-opentelemetry 1.0.0-beta.47
201230
.and(not(hasClassesNamed("com.azure.core.tracing.opentelemetry.OpenTelemetryTracer")));
202231
}
203232
```
@@ -218,11 +247,24 @@ public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
218247
comment above the statement or expression. When matchers are chained, place each version
219248
comment directly above its class name string.
220249
- Positive floor class → `// added in X.Y`, optionally with brief, non-duplicative context
221-
such as `renamed from javax` or `backported to 2.12.3`.
250+
such as `renamed from javax` or `backported to 2.12.3`. For a landmark class from a
251+
different artifact, use `// added in groupId:artifactId X.Y` when the boundary is for that
252+
artifact, or `// added in X.Y (via groupId:artifactId A.B)` when the boundary or presence
253+
condition is for the main library module. For `javax.servlet:javax.servlet-api` and
254+
`jakarta.servlet:jakarta.servlet-api`, use `Servlet` instead of the full Maven coordinate.
222255
- Positive ceiling class → `// removed in Y.Z`, optionally with brief, non-duplicative
223-
context such as `replaced by jakarta variant` or `moved to internal.async`.
256+
context such as `replaced by jakarta variant` or `moved to internal.async`. For a landmark
257+
class from a different artifact, use `// removed in groupId:artifactId Y.Z` when the
258+
boundary is for that artifact, or `// removed in Y.Z (via groupId:artifactId A.B)` when the
259+
boundary is for the main library module. For `javax.servlet:javax.servlet-api` and
260+
`jakarta.servlet:jakarta.servlet-api`, use `Servlet` instead of the full Maven coordinate.
224261
- Negated exclusion class → `// added in Y.Z`, optionally with brief, non-duplicative
225-
context such as `native OTel support` or `shaded into core module`.
262+
context such as `native OTel support` or `shaded into core module`. For a landmark class
263+
from a different artifact, use `// added in groupId:artifactId Y.Z` when the excluded range
264+
is driven by that artifact, or `// added in Y.Z (via groupId:artifactId A.B)` when the
265+
excluded range is described in terms of the main library module. For
266+
`javax.servlet:javax.servlet-api` and `jakarta.servlet:jakarta.servlet-api`, use `Servlet`
267+
instead of the full Maven coordinate.
226268
- Single positive class serving as both floor and ceiling → include both boundaries, for
227269
example `// added in X.Y, removed in Y.Z`.
228270
Do not use `// added in` for a **positive** ceiling class, because the upper bound depends on

‎instrumentation/akka/akka-http-10.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/akkahttp/server/AkkaHttpServerInstrumentationModule.java‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,7 @@ public String getModuleGroup() {
2929

3030
@Override
3131
public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
32-
// in GraphInterpreterInstrumentation we instrument a class that belongs to akka-streams, make
33-
// sure this runs only when akka-http is present to avoid muzzle failures
32+
// added in 10.0.0
3433
return hasClassesNamed("akka.http.scaladsl.HttpExt");
3534
}
3635

‎instrumentation/aws-sdk/aws-sdk-2.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/awssdk/v2_2/LambdaInstrumentationModule.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ public LambdaInstrumentationModule() {
2626
public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
2727
return hasClassesNamed(
2828
"software.amazon.awssdk.services.lambda.model.InvokeRequest",
29+
// added in software.amazon.awssdk:json-utils 2.17.0
2930
"software.amazon.awssdk.protocols.jsoncore.JsonNode");
3031
}
3132

‎instrumentation/azure-core/azure-core-1.14/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/azurecore/v1_14/AzureSdkInstrumentationModule.java‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,11 +46,11 @@ public List<String> exposedClassNames() {
4646

4747
@Override
4848
public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
49-
// added in azure-core 1.14.0
49+
// added in 1.14.0
5050
return hasClassesNamed("com.azure.core.util.tracing.Tracer")
51-
// added in azure-core 1.19.0
51+
// added in 1.19.0
5252
.and(not(hasClassesNamed("com.azure.core.util.tracing.StartSpanOptions")))
53-
// added in azure-core-tracing-opentelemetry 1.0.0-beta.47 (native OTel support)
53+
// added in com.azure:azure-core-tracing-opentelemetry 1.0.0-beta.47 (native OTel support)
5454
.and(not(hasClassesNamed("com.azure.core.tracing.opentelemetry.OpenTelemetryTracer")));
5555
}
5656

‎instrumentation/azure-core/azure-core-1.19/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/azurecore/v1_19/AzureSdkInstrumentationModule.java‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -46,19 +46,12 @@ public List<String> exposedClassNames() {
4646

4747
@Override
4848
public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
49-
return hasClassesNamed(
50-
// added in azure-core 1.19
51-
"com.azure.core.util.tracing.StartSpanOptions")
52-
.and(
53-
not(
54-
hasClassesNamed(
55-
// added in azure-core-tracing-opentelemetry 1.0.0-beta.47 (native OTel support)
56-
"com.azure.core.tracing.opentelemetry.OpenTelemetryTracer")))
57-
.and(
58-
not(
59-
hasClassesNamed(
60-
// added in azure-core 1.36
61-
"com.azure.core.util.tracing.TracerProvider")));
49+
// added in 1.19
50+
return hasClassesNamed("com.azure.core.util.tracing.StartSpanOptions")
51+
// added in 1.36
52+
.and(not(hasClassesNamed("com.azure.core.util.tracing.TracerProvider")))
53+
// added in com.azure:azure-core-tracing-opentelemetry 1.0.0-beta.47 (native OTel support)
54+
.and(not(hasClassesNamed("com.azure.core.tracing.opentelemetry.OpenTelemetryTracer")));
6255
}
6356

6457
@Override

‎instrumentation/azure-core/azure-core-1.36/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/azurecore/v1_36/AzureSdkInstrumentationModule.java‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -48,19 +48,12 @@ public List<String> exposedClassNames() {
4848

4949
@Override
5050
public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
51-
return hasClassesNamed(
52-
// added in azure-core 1.36
53-
"com.azure.core.util.tracing.TracerProvider")
54-
.and(
55-
not(
56-
hasClassesNamed(
57-
// added in azure-core 1.53
58-
"com.azure.core.util.LibraryTelemetryOptions")))
59-
.and(
60-
not(
61-
hasClassesNamed(
62-
// added in azure-core-tracing-opentelemetry 1.0.0-beta.47 (native OTel support)
63-
"com.azure.core.tracing.opentelemetry.OpenTelemetryTracer")));
51+
// added in 1.36
52+
return hasClassesNamed("com.azure.core.util.tracing.TracerProvider")
53+
// added in 1.53
54+
.and(not(hasClassesNamed("com.azure.core.util.LibraryTelemetryOptions")))
55+
// added in com.azure:azure-core-tracing-opentelemetry 1.0.0-beta.47 (native OTel support)
56+
.and(not(hasClassesNamed("com.azure.core.tracing.opentelemetry.OpenTelemetryTracer")));
6457
}
6558

6659
@Override

‎instrumentation/azure-core/azure-core-1.53/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/azurecore/v1_53/AzureSdkInstrumentationModule.java‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -48,14 +48,10 @@ public List<String> exposedClassNames() {
4848

4949
@Override
5050
public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
51-
return hasClassesNamed(
52-
// added in azure-core 1.53
53-
"com.azure.core.util.LibraryTelemetryOptions")
54-
.and(
55-
not(
56-
hasClassesNamed(
57-
// added in azure-core-tracing-opentelemetry 1.0.0-beta.47 (native OTel support)
58-
"com.azure.core.tracing.opentelemetry.OpenTelemetryTracer")));
51+
// added in 1.53
52+
return hasClassesNamed("com.azure.core.util.LibraryTelemetryOptions")
53+
// added in com.azure:azure-core-tracing-opentelemetry 1.0.0-beta.47 (native OTel support)
54+
.and(not(hasClassesNamed("com.azure.core.tracing.opentelemetry.OpenTelemetryTracer")));
5955
}
6056

6157
@Override

‎instrumentation/couchbase/couchbase-3.1.6/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/couchbase/v3_1_6/CouchbaseInstrumentationModule.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@ public CouchbaseInstrumentationModule() {
2323

2424
@Override
2525
public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
26-
// added in java-client 3.1.6 (core-io 2.1.6)
26+
// added in 3.1.6 (via com.couchbase.client:core-io 2.1.6)
2727
return hasClassesNamed("com.couchbase.client.core.endpoint.EventingEndpoint")
28-
// added in java-client 3.2.0 (core-io 2.2.0)
28+
// added in 3.2.0 (via com.couchbase.client:core-io 2.2.0)
2929
.and(not(hasClassesNamed("com.couchbase.client.core.cnc.RequestSpan$StatusCode")));
3030
}
3131

‎instrumentation/couchbase/couchbase-3.1/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/couchbase/v3_1/CouchbaseInstrumentationModule.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@ public CouchbaseInstrumentationModule() {
2323

2424
@Override
2525
public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
26-
// introduced in java-client 3.1.0 (core-io 2.1.0)
26+
// added in 3.1.0 (via com.couchbase.client:core-io 2.1.0)
2727
return hasClassesNamed("com.couchbase.client.core.cnc.TracingIdentifiers")
28-
// introduced in java-client 3.1.6 (core-io 2.1.6)
28+
// added in 3.1.6 (via com.couchbase.client:core-io 2.1.6)
2929
.and(not(hasClassesNamed("com.couchbase.client.core.endpoint.EventingEndpoint")));
3030
}
3131

‎instrumentation/couchbase/couchbase-3.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/couchbase/v3_2/CouchbaseInstrumentationModule.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@ public CouchbaseInstrumentationModule() {
2323

2424
@Override
2525
public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
26-
// added in java-client 3.2.0 (core-io 2.2.0)
26+
// added in 3.2.0 (via com.couchbase.client:core-io 2.2.0)
2727
return hasClassesNamed("com.couchbase.client.core.cnc.RequestSpan$StatusCode")
28-
// removed in java-client 3.4.0 (core-io 2.4.0)
28+
// removed in 3.4.0 (via com.couchbase.client:core-io 2.4.0)
2929
.and(
3030
not(
3131
hasClassesNamed(

0 commit comments

Comments
 (0)