From 834359d29191a8b774455b065707f728445ba112 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 29 Apr 2026 18:39:21 -0700 Subject: [PATCH 01/10] Refactor check-package-names.sh to validate both library and javaagent source sets Extracts a check_source_set function and runs it for both library and javaagent source roots. Previously only library/ was validated. This adds enforcement for javaagent module/package naming and produces explicit allow-lists for the historical exceptions and the no-base-version common modules. --- .github/scripts/check-package-names.sh | 224 ++++++++++++++++++------- 1 file changed, 166 insertions(+), 58 deletions(-) diff --git a/.github/scripts/check-package-names.sh b/.github/scripts/check-package-names.sh index 4f93493da4c0..75e36cfa2425 100755 --- a/.github/scripts/check-package-names.sh +++ b/.github/scripts/check-package-names.sh @@ -1,70 +1,178 @@ #!/bin/bash -e -for dir in $(find instrumentation -name "*.java" | grep library/src/main/java | sed 's#/[^/]*$##' | sort -u); do +if command -v rg > /dev/null 2>&1; then + case "$(uname -s)" in + CYGWIN* | MINGW* | MSYS*) path_separator="//" ;; + *) path_separator="/" ;; + esac - module_name=$(echo "$dir" | sed 's#.*/\([^/]*\)/library/src/main/java[0-9]*/.*#\1#') + source_dirs=$(rg --files --path-separator "$path_separator" instrumentation -g '*.java' \ + | grep -E '/(library|javaagent)/src/main/java[0-9]*/' \ + | sed 's#/[^/]*$##' \ + | sort -u) +else + source_dirs=$(find instrumentation \( -path "*/library/src/main/java*/*.java" -o -path "*/javaagent/src/main/java*/*.java" \) -print \ + | sed 's#/[^/]*$##' \ + | sort -u) +fi - if [[ "$module_name" =~ ^java- ]]; then - continue - fi - if [[ "$module_name" == "jmx-metrics" ]]; then - continue - fi - if [[ "$module_name" == "runtime-telemetry" ]]; then - continue - fi - if [[ "$module_name" == "graphql-java-common-12.0" ]]; then - continue - fi +check_source_set() { + local source_set="$1" + local expected_prefix="$2" - # these are possibly problematic - if [[ "$dir" == "instrumentation/grpc-1.6/library/src/main/java/io/grpc/override" ]]; then - continue - fi - if [[ "$dir" == "instrumentation/lettuce/lettuce-5.1/library/src/main/java/io/lettuce/core/protocol" ]]; then - continue - fi - if [[ "$dir" == "instrumentation/nats/nats-2.17/library/src/main/java/io/nats/client/impl" ]]; then - continue - fi - if [[ "$dir" == "instrumentation/rxjava/rxjava-1.0/library/src/main/java/rx" ]]; then - continue - fi - if [[ "$dir" == "instrumentation/elasticsearch/elasticsearch-rest-7.0/library/src/main/java/org/elasticsearch/client" ]]; then - continue - fi + while IFS= read -r dir; do + if [[ "$dir" != *"/$source_set/src/main/java"* ]]; then + continue + fi - # some common modules don't have any base version (might have a variant instead, ex: javax) - # - jdbc - # - lettuce-common - # - netty-common - # - resources - # - servlet-common - # - servlet-common-javax - if [[ ! "$module_name" =~ [0-9]$ && "$module_name" != "jdbc" && "$module_name" != "lettuce-common" && "$module_name" != "netty-common" && "$module_name" != "resources" && "$module_name" != "servlet-common" && "$module_name" != "servlet-common-javax" ]]; then - echo "module name doesn't have a base version: $dir" - exit 1 - fi + module_path=${dir%%/$source_set/src/main/java*} + module_name=${module_path##*/} - # convention: if module ends with -java (followed by version), remove -java from the package name - simple_module_name=$(echo "$module_name" | sed 's/-[0-9.]*$//' | sed 's/-java$//' | sed 's/-//g') - base_version=$(echo "$module_name" | sed 's/.*-\([0-9.]*\)$/\1/' | sed 's/\./_/g') + if [[ "$module_name" =~ ^java- ]]; then + continue + fi + if [[ "$module_name" == "jmx-metrics" ]]; then + continue + fi + # these are possibly problematic + if [[ "$source_set" == "library" ]]; then + if [[ "$dir" == "instrumentation/grpc-1.6/library/src/main/java/io/grpc/override" ]]; then + continue + fi + if [[ "$dir" == "instrumentation/lettuce/lettuce-5.1/library/src/main/java/io/lettuce/core/protocol" ]]; then + continue + fi + if [[ "$dir" == "instrumentation/nats/nats-2.17/library/src/main/java/io/nats/client/impl" ]]; then + continue + fi + if [[ "$dir" == "instrumentation/rxjava/rxjava-1.0/library/src/main/java/rx" ]]; then + continue + fi + if [[ "$dir" == "instrumentation/elasticsearch/elasticsearch-rest-7.0/library/src/main/java/org/elasticsearch/client" ]]; then + continue + fi + if [[ "$dir" == "instrumentation/servlet/servlet-common/library/src/main/java/io/opentelemetry/instrumentation/servlet/internal" ]]; then + continue + fi + fi - if [[ "$module_name" =~ [0-9]$ ]]; then - expected_package_name="io/opentelemetry/instrumentation/$simple_module_name/v$base_version" - else - expected_package_name="io/opentelemetry/instrumentation/$simple_module_name" - fi + if [[ "$source_set" == "javaagent" ]]; then + # advice packages that must live under the instrumented library's own namespace + case "$dir" in + instrumentation/clickhouse/clickhouse-client-v1-0.5/javaagent/src/main/java/com/clickhouse/client*) continue ;; + instrumentation/finagle-http-23.11/javaagent/src/main/java/com/twitter/finagle*) continue ;; + instrumentation/finagle-http-23.11/javaagent/src/main/java/io/netty/channel*) continue ;; + instrumentation/reactor/reactor-netty/reactor-netty-1.0/javaagent/src/main/java/reactor/netty/http/client*) continue ;; + instrumentation/spring/spring-webmvc/spring-webmvc-3.1/javaagent/src/main/java/org/springframework/web/servlet/v3_1*) continue ;; + instrumentation/spring/spring-webmvc/spring-webmvc-6.0/javaagent/src/main/java/org/springframework/web/servlet/v6_0*) continue ;; + instrumentation/vertx/vertx-redis-client-4.0/javaagent/src/main/java/io/vertx/redis/client/impl*) continue ;; + instrumentation/vertx/vertx-sql-client/vertx-sql-client-common-4.0/javaagent/src/main/java/io/vertx/sqlclient/impl*) continue ;; + esac - package_name=$(echo "$dir" | sed 's#.*/src/main/java[0-9]*/##') + # historical javaagent modules that do not follow the module-name <-> package-name convention + case "$dir" in + instrumentation/akka/akka-actor-fork-join-2.5/javaagent/*) continue ;; + instrumentation/aws-sdk/aws-sdk-1.11/javaagent/src/main/java/io/opentelemetry/instrumentation/awssdk/v1_11) continue ;; + instrumentation/aws-sdk/aws-sdk-2.2/javaagent/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal) continue ;; + instrumentation/internal/internal-application-logger/javaagent/*) continue ;; + instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-annotations/javaagent/*) continue ;; + instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-common/javaagent/*) continue ;; + instrumentation/jaxrs/jaxrs-3.0/jaxrs-3.0-annotations/javaagent/*) continue ;; + instrumentation/jaxrs/jaxrs-3.0/jaxrs-3.0-common/javaagent/*) continue ;; + instrumentation/jaxrs/jaxrs-common/javaagent/*) continue ;; + instrumentation/opentelemetry-api/opentelemetry-api-1.0/javaagent/*) continue ;; + instrumentation/opentelemetry-extension-annotations-1.0/javaagent/*) continue ;; + instrumentation/opentelemetry-instrumentation-annotations-1.16/javaagent/*) continue ;; + instrumentation/opentelemetry-instrumentation-api/javaagent/*) continue ;; + instrumentation/servlet/servlet-common/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/servlet) continue ;; + instrumentation/servlet/servlet-common/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/servlet/snippet) continue ;; + instrumentation/spring/spring-boot-resources/javaagent/*) continue ;; + esac + fi - # deal with differences like module name elasticsearch-rest and package name elasticsearch.rest - expected_package_name_normalized=$(echo "$expected_package_name" | sed 's#/##g') - package_name_normalized=$(echo "$package_name" | sed 's#/##g') + # some common modules don't have any base version (might have a variant instead, ex: javax) + if [[ ! "$module_name" =~ [0-9]$ ]]; then + case "$source_set:$module_name" in + # library: + library:jdbc) ;; + library:lettuce-common) ;; + library:netty-common) ;; + library:oshi) ;; + library:resources) ;; + library:runtime-telemetry) ;; + library:servlet-common) ;; + library:servlet-common-javax) ;; + # javaagent: + javaagent:elasticsearch-transport-common) ;; + javaagent:executors) ;; + javaagent:external-annotations) ;; + javaagent:http-url-connection) ;; + javaagent:internal-application-logger) ;; + javaagent:internal-class-loader) ;; + javaagent:internal-lambda) ;; + javaagent:internal-reflection) ;; + javaagent:internal-url-class-loader) ;; + javaagent:jaxrs-common) ;; + javaagent:jdbc) ;; + javaagent:jetty-common) ;; + javaagent:jsf-common-jakarta) ;; + javaagent:jsf-common-javax) ;; + javaagent:methods) ;; + javaagent:opensearch-rest-common) ;; + javaagent:opentelemetry-instrumentation-api) ;; + javaagent:oshi) ;; + javaagent:payara) ;; + javaagent:quarkus-resteasy-reactive) ;; + javaagent:rmi) ;; + javaagent:runtime-telemetry) ;; + javaagent:servlet-common) ;; + javaagent:spring-boot-resources) ;; + javaagent:spring-cloud-gateway-common) ;; + javaagent:spring-webmvc-common) ;; + javaagent:tomcat-common) ;; + javaagent:tomcat-jdbc) ;; + *) + echo "module name doesn't have a base version: $dir" + exit 1 + ;; + esac + fi - if [[ "$package_name_normalized" != "$expected_package_name_normalized"* ]]; then - echo "ERROR: $dir" - exit 1 - fi + # build expected package name by walking the module name's dash-separated tokens: + # a version token (e.g. "3.0") becomes "/v3_0", any other token becomes "/"; + # the literal token "java" is elided (e.g. graphql-java-20.0 -> graphql/v20_0). + # this also handles multi-version modules like jaxrs-2.0-resteasy-3.1 -> jaxrs/v2_0/resteasy/v3_1. + expected_package_name="$expected_prefix" + IFS='-' read -ra module_parts <<< "$module_name" + for part in "${module_parts[@]}"; do + if [[ "$part" == "java" ]]; then + continue + fi + if [[ "$part" =~ ^[0-9][0-9.]*$ ]]; then + expected_package_name="$expected_package_name/v${part//./_}" + else + expected_package_name="$expected_package_name/$part" + fi + done -done + if [[ "$dir" =~ /src/main/java[0-9]*/(.*)$ ]]; then + package_name=${BASH_REMATCH[1]} + else + echo "ERROR: $dir" + exit 1 + fi + + # deal with differences like module name elasticsearch-rest and package name elasticsearch.rest + expected_package_name_normalized=${expected_package_name//\//} + package_name_normalized=${package_name//\//} + + if [[ "$package_name_normalized" != "$expected_package_name_normalized"* ]]; then + echo "ERROR: $dir" + exit 1 + fi + + done <<< "$source_dirs" +} + +check_source_set "library" "io/opentelemetry/instrumentation" +check_source_set "javaagent" "io/opentelemetry/javaagent/instrumentation" From 10fc49da95eee74c0358992f13826e251264ffad Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 18 May 2026 07:21:33 -0700 Subject: [PATCH 02/10] Update package cleanup plan after merged PRs --- .github/scripts/check-package-names.sh | 5 - package-name-exceptions-plan.md | 211 +++++++++++++++++++++++++ 2 files changed, 211 insertions(+), 5 deletions(-) create mode 100644 package-name-exceptions-plan.md diff --git a/.github/scripts/check-package-names.sh b/.github/scripts/check-package-names.sh index 75e36cfa2425..26bb649782ea 100755 --- a/.github/scripts/check-package-names.sh +++ b/.github/scripts/check-package-names.sh @@ -74,19 +74,14 @@ check_source_set() { instrumentation/akka/akka-actor-fork-join-2.5/javaagent/*) continue ;; instrumentation/aws-sdk/aws-sdk-1.11/javaagent/src/main/java/io/opentelemetry/instrumentation/awssdk/v1_11) continue ;; instrumentation/aws-sdk/aws-sdk-2.2/javaagent/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal) continue ;; - instrumentation/internal/internal-application-logger/javaagent/*) continue ;; instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-annotations/javaagent/*) continue ;; instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-common/javaagent/*) continue ;; instrumentation/jaxrs/jaxrs-3.0/jaxrs-3.0-annotations/javaagent/*) continue ;; instrumentation/jaxrs/jaxrs-3.0/jaxrs-3.0-common/javaagent/*) continue ;; - instrumentation/jaxrs/jaxrs-common/javaagent/*) continue ;; instrumentation/opentelemetry-api/opentelemetry-api-1.0/javaagent/*) continue ;; instrumentation/opentelemetry-extension-annotations-1.0/javaagent/*) continue ;; instrumentation/opentelemetry-instrumentation-annotations-1.16/javaagent/*) continue ;; instrumentation/opentelemetry-instrumentation-api/javaagent/*) continue ;; - instrumentation/servlet/servlet-common/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/servlet) continue ;; - instrumentation/servlet/servlet-common/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/servlet/snippet) continue ;; - instrumentation/spring/spring-boot-resources/javaagent/*) continue ;; esac fi diff --git a/package-name-exceptions-plan.md b/package-name-exceptions-plan.md new file mode 100644 index 000000000000..a53167bb54ee --- /dev/null +++ b/package-name-exceptions-plan.md @@ -0,0 +1,211 @@ +# Package Name Exceptions Cleanup Plan + +Generated on 2026-05-11 from the remaining exceptions in `.github/scripts/check-package-names.sh`. +Updated on 2026-05-13 after PRs 5-8 merged and their historical javaagent exceptions were removed from the checker. +Updated again on 2026-05-13 after PRs 9-12 were implemented and opened as draft PRs. +Updated on 2026-05-14 after PRs 9-12 merged and their historical javaagent exceptions were removed from the checker. +Updated again on 2026-05-14 to plan faster batches: up to 20 changed files per PR, still four PRs per batch. +Updated again on 2026-05-14 to bump the target to up to 40 changed files per PR and plan all remaining historical package renames. +Updated on 2026-05-17 after PRs 15-16 merged, and after deciding to handle Akka/Scala forkjoin as a module-name cleanup instead of a package-only cleanup. +Updated on 2026-05-18 after PRs 13, 18, 20, and 21 merged and their historical package exceptions were removed from the checker. + +## Goal + +Continue reducing package-name checker exceptions in reviewable PRs. Prefer changes where the current package name is only a historical abbreviation and the rename has a small blast radius. Use up to about 40 changed files per package-cleanup PR, while still submitting only four PRs at a time. + +## Quick Audit Summary + +The remaining exceptions fall into four buckets: + +| Bucket | Current signal | Recommendation | +| --- | --- | --- | +| Module-wide skips | `java-*` has 39 files, `jmx-metrics` has 43 files | Do not start here; these need broader naming decisions. | +| Library packages under third-party namespaces | `grpc`, `lettuce`, `nats`, `rxjava` each have 1 file | Leave for later; these are likely compatibility/shim packages. | +| Javaagent advice under instrumented library namespaces | mostly 1 file each | Leave for later; the script already says these must live in the instrumented library namespace. | +| Historical javaagent packages | many one-dir modules remain, usually with one source directory | Best place to keep chipping away. | + +## Completed Cleanups + +These PRs have merged, and their historical javaagent package-name exceptions have been removed from `.github/scripts/check-package-names.sh`: + +- PR 1: `internal-eclipse-osgi-3.6` and `opentelemetry-extension-kotlin-1.0`. +- PR 2: `spark-2.3`. +- PR 3: `external-annotations`. +- PR 4: `hibernate-procedure-call-4.3`. +- PR 5: `elasticsearch-rest-common-5.0`. +- PR 6: `kotlinx-coroutines-flow-1.3`, `liberty-dispatcher-20.0`, and `scala-fork-join-2.8`. +- PR 7: `jaxws-jws-api-1.1`. +- PR 8: `jsf-mojarra-1.2`, `jsf-mojarra-3.0`, `jsf-myfaces-1.2`, and `jsf-myfaces-3.0`. +- PR 9: `elasticsearch-api-client-7.16`. +- PR 10: `elasticsearch-transport-common`. +- PR 11: `opensearch-rest-common`. +- PR 12: `spring-boot-actuator-autoconfigure-2.0`. +- PR 13: `internal-application-logger` and `spring-boot-resources`. +- PR 18: `jaxrs-common`. +- PR 20: `servlet-common` snippet package. +- PR 21: `servlet-common` root helper package. + +PRs 5-8 merged upstream as: + +- #18720: `elasticsearch-rest-common-5.0`. +- #18721: `kotlinx-coroutines-flow-1.3`, `liberty-dispatcher-20.0`, and `scala-fork-join-2.8`. +- #18722: `jaxws-jws-api-1.1`. +- #18723: `jsf-mojarra-1.2`, `jsf-mojarra-3.0`, `jsf-myfaces-1.2`, and `jsf-myfaces-3.0`. + +PRs 9-12 merged upstream as: + +- #18730: `elasticsearch-api-client-7.16`. +- #18731: `elasticsearch-transport-common`. +- #18732: `opensearch-rest-common`. +- #18733: `spring-boot-actuator-autoconfigure-2.0`. + +PRs 15-16 merged upstream as: + +- #18748: `jaxrs-2.0-annotations` and `jaxrs-2.0-common`. +- #18749: `jaxrs-3.0-annotations` and `jaxrs-3.0-common`. + +PRs 13, 18, 20, and 21 merged upstream as: + +- #18746: `internal-application-logger` and `spring-boot-resources`. +- #18776: `jaxrs-common`. +- #18777: `servlet-common` snippet package. +- #18778: `servlet-common` root helper package. + +`external-annotations` still remains in the unversioned-module allowlist as `javaagent:external-annotations`; that is a separate module-name exception, not a historical package exception. + +## PR Creation Notes + +Use draft PRs against upstream `main` for the package-only cleanup batches. These PR branches must be based directly on `upstream/main`, not on `next`, so the PR diffs contain only package moves and dependent import updates. Do not include `.github/scripts/check-package-names.sh` changes in those PRs; checker exception removals stay on the tracking/checker branch and should be updated separately after the package cleanup PRs merge. + +Batch sizing: keep submitting four PRs at a time, but each PR can include up to about 40 changed files when the modules are closely related or the reference spread is easy to audit. Count dependent import updates and test package moves in that limit. Avoid combining package moves that require broad cross-module rewrites just to fill the file budget. The known outlier is the root `servlet-common` helper package move, which likely exceeds 40 changed files because many servlet modules import those helpers; treat that as a dedicated final PR unless a clean split emerges during implementation. + +Preferred PR description for future package cleanup PRs: + +```text +Part of +- https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/18428 +``` + +When splitting several already-implemented package moves into separate PRs: + +1. Keep a local WIP branch or commit that contains the full tested implementation. +2. Recreate each PR branch from `upstream/main`, not `next`. +3. Apply only the module paths for that PR, for example: + +```bash +git switch -C upstream/main +git diff --binary -- | git apply --index +git commit -m "" +git push -u origin --force-with-lease +gh pr create --repo open-telemetry/opentelemetry-java-instrumentation --base main --head trask: --draft --title "" --body "Part of +- https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/18428" +``` + +After pushing or force-pushing, verify that each PR file list contains only the intended module paths and does not include `.github/scripts/check-package-names.sh`: + +```bash +gh pr diff --repo open-telemetry/opentelemetry-java-instrumentation --name-only +``` + +For common-module package moves, search for downstream versioned modules importing the moved helper package. Compile those dependent modules too; the common module's own test can pass while the full smoke-test build fails on stale imports. + +## Open Cleanup PRs + +PR 14 is open as #18747 and PR 17 is open as #18772. Keep `.github/scripts/check-package-names.sh` and checker exception removals on `next` until cleanup PRs merge. + +### PR 14: OpenTelemetry annotation and instrumentation API modules (open #18747) + +Modules: + +- `opentelemetry-extension-annotations-1.0` +- `opentelemetry-instrumentation-api` +- `opentelemetry-instrumentation-annotations-1.16` + +Expected package changes: + +- `io.opentelemetry.javaagent.instrumentation.extensionannotations.v1_0` -> `io.opentelemetry.javaagent.instrumentation.opentelemetry.extension.annotations.v1_0` +- `io.opentelemetry.javaagent.instrumentation.instrumentationapi` -> `io.opentelemetry.javaagent.instrumentation.opentelemetry.instrumentation.api` +- `io.opentelemetry.javaagent.instrumentation.instrumentationannotations.v1_16` -> `io.opentelemetry.javaagent.instrumentation.opentelemetry.instrumentation.annotations.v1_16` + +Notes: + +- Around 30 changed Java files after the dependent Kotlin coroutines import is included. +- Reference audit found only local package declarations/imports for `opentelemetry-extension-annotations-1.0`. +- `opentelemetry-instrumentation-api` has local tests in `src/test` and `src/testOldServerSpan` that must move with the main package. +- Update dependent import(s) in `kotlinx-coroutines-1.0` for instrumentation annotations. +- `opentelemetry-instrumentation-api` still remains in the unversioned-module allowlist unless the module name changes; the PR removes only the broad historical package skip after merge. + +Suggested verification: + +```bash +.github/scripts/check-package-names.sh +./gradlew :instrumentation:opentelemetry-extension-annotations-1.0:javaagent:test :instrumentation:opentelemetry-instrumentation-api:javaagent:test :instrumentation:opentelemetry-instrumentation-annotations-1.16:javaagent:test :instrumentation:kotlinx-coroutines:kotlinx-coroutines-1.0:javaagent:compileJava +``` + +### PR 17: Akka and Scala forkjoin module/package names (open #18772) + +Modules: + +- `akka-actor-fork-join-2.5` -> `akka-actor-forkjoin-2.5` +- `scala-fork-join-2.8` -> `scala-forkjoin-2.8` + +Expected package changes: + +- `io.opentelemetry.javaagent.instrumentation.akkaforkjoin` -> `io.opentelemetry.javaagent.instrumentation.akka.actor.forkjoin.v2_5` +- `io.opentelemetry.javaagent.instrumentation.scala.fork.join.v2_8` -> `io.opentelemetry.javaagent.instrumentation.scala.forkjoin.v2_8` + +Notes: + +- This is intentionally a module-name cleanup, not just a package cleanup: `forkjoin` is a single upstream package/concept in both Akka and Scala. +- Update `settings.gradle.kts`, documentation inventory, instrumentation module names, and dependent Gradle project references. +- Keep `akka-actor` as a compatibility instrumentation alias for the Akka module. + +Suggested verification: + +```bash +.github/scripts/check-package-names.sh +./gradlew :instrumentation:akka:akka-actor-forkjoin-2.5:javaagent:test :instrumentation:scala-forkjoin-2.8:javaagent:test :instrumentation:akka:akka-http-10.0:javaagent:compileTestJava +``` + +### PR 19: OpenTelemetry API package + +Module: + +- `opentelemetry-api-1.0` + +Expected package change: + +- `io.opentelemetry.javaagent.instrumentation.opentelemetryapi` -> `io.opentelemetry.javaagent.instrumentation.opentelemetry.api.v1_0` + +Notes: + +- Around 25 changed Java files. +- Package names may be more compatibility-sensitive or user-facing than pure internal helper modules; keep this as its own PR. + +Suggested verification: + +```bash +.github/scripts/check-package-names.sh +./gradlew :instrumentation:opentelemetry-api:opentelemetry-api-1.0:javaagent:test +``` + +## Do Later + +These are probably not the next easiest wins: + +- `java-*` module skip: the current packages use names like `javahttpclient`, while the checker would expect `http.client` after eliding `java`. This touches 39 files and needs a naming decision. +- `jmx-metrics`: current packages are under `jmx`, while the module says `jmx-metrics`. This touches 43 files and may be user-facing enough to deserve a dedicated PR. +- Library-specific third-party packages: `io.grpc.override`, `io.lettuce.core.protocol`, `io.nats.client.impl`, and `rx` are likely intentional shims or package-private access points. +- Advice-native package exceptions: packages under `com.clickhouse`, `com.twitter`, `io.netty`, `reactor.netty`, `org.springframework`, and `io.vertx` should stay until each one is proven not to need native package placement. +- OpenTelemetry API and Akka/Scala forkjoin package/module renames are planned above; AWS SDK remains deferred. +- Other unversioned module allowlist entries: these need package/module naming decisions beyond a package-only cleanup. + +## Re-Audit Command + +After each PR, run: + +```bash +.github/scripts/check-package-names.sh +``` + +Then look for remaining broad exceptions in `.github/scripts/check-package-names.sh` and prefer candidates where `rg --fixed-strings ` only reports package declarations and local imports. From ed3e8df023299c09eaccf8d6e885e89a25bdd6e1 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 18 May 2026 08:26:10 -0700 Subject: [PATCH 03/10] Plan Java package cleanup --- .github/scripts/check-package-names.sh | 25 ++-- package-name-exceptions-plan.md | 195 ++++++++++++++++++++++++- 2 files changed, 206 insertions(+), 14 deletions(-) diff --git a/.github/scripts/check-package-names.sh b/.github/scripts/check-package-names.sh index 26bb649782ea..d5225b5f048a 100755 --- a/.github/scripts/check-package-names.sh +++ b/.github/scripts/check-package-names.sh @@ -28,9 +28,6 @@ check_source_set() { module_path=${dir%%/$source_set/src/main/java*} module_name=${module_path##*/} - if [[ "$module_name" =~ ^java- ]]; then - continue - fi if [[ "$module_name" == "jmx-metrics" ]]; then continue fi @@ -54,6 +51,12 @@ check_source_set() { if [[ "$dir" == "instrumentation/servlet/servlet-common/library/src/main/java/io/opentelemetry/instrumentation/servlet/internal" ]]; then continue fi + if [[ "$dir" == instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient* ]]; then + continue + fi + if [[ "$dir" == instrumentation/java-http-server/library/src/main/java/io/opentelemetry/instrumentation/javahttpserver* ]]; then + continue + fi fi if [[ "$source_set" == "javaagent" ]]; then @@ -63,6 +66,7 @@ check_source_set() { instrumentation/finagle-http-23.11/javaagent/src/main/java/com/twitter/finagle*) continue ;; instrumentation/finagle-http-23.11/javaagent/src/main/java/io/netty/channel*) continue ;; instrumentation/reactor/reactor-netty/reactor-netty-1.0/javaagent/src/main/java/reactor/netty/http/client*) continue ;; + instrumentation/spring/spring-boot-resources/javaagent/src/main/java/io/opentelemetry/instrumentation/spring/resources) continue ;; instrumentation/spring/spring-webmvc/spring-webmvc-3.1/javaagent/src/main/java/org/springframework/web/servlet/v3_1*) continue ;; instrumentation/spring/spring-webmvc/spring-webmvc-6.0/javaagent/src/main/java/org/springframework/web/servlet/v6_0*) continue ;; instrumentation/vertx/vertx-redis-client-4.0/javaagent/src/main/java/io/vertx/redis/client/impl*) continue ;; @@ -74,6 +78,9 @@ check_source_set() { instrumentation/akka/akka-actor-fork-join-2.5/javaagent/*) continue ;; instrumentation/aws-sdk/aws-sdk-1.11/javaagent/src/main/java/io/opentelemetry/instrumentation/awssdk/v1_11) continue ;; instrumentation/aws-sdk/aws-sdk-2.2/javaagent/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal) continue ;; + instrumentation/java-http-client/javaagent/*) continue ;; + instrumentation/java-http-server/javaagent/*) continue ;; + instrumentation/java-util-logging/javaagent/*) continue ;; instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-annotations/javaagent/*) continue ;; instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-common/javaagent/*) continue ;; instrumentation/jaxrs/jaxrs-3.0/jaxrs-3.0-annotations/javaagent/*) continue ;; @@ -109,11 +116,9 @@ check_source_set() { javaagent:internal-url-class-loader) ;; javaagent:jaxrs-common) ;; javaagent:jdbc) ;; - javaagent:jetty-common) ;; javaagent:jsf-common-jakarta) ;; javaagent:jsf-common-javax) ;; javaagent:methods) ;; - javaagent:opensearch-rest-common) ;; javaagent:opentelemetry-instrumentation-api) ;; javaagent:oshi) ;; javaagent:payara) ;; @@ -124,7 +129,6 @@ check_source_set() { javaagent:spring-boot-resources) ;; javaagent:spring-cloud-gateway-common) ;; javaagent:spring-webmvc-common) ;; - javaagent:tomcat-common) ;; javaagent:tomcat-jdbc) ;; *) echo "module name doesn't have a base version: $dir" @@ -135,12 +139,15 @@ check_source_set() { # build expected package name by walking the module name's dash-separated tokens: # a version token (e.g. "3.0") becomes "/v3_0", any other token becomes "/"; - # the literal token "java" is elided (e.g. graphql-java-20.0 -> graphql/v20_0). + # the literal token "java" is elided except when it is the leading token in java-* modules + # where it identifies a JDK instrumentation (e.g. graphql-java-20.0 -> graphql/v20_0, + # but java-http-client -> java/http/client). # this also handles multi-version modules like jaxrs-2.0-resteasy-3.1 -> jaxrs/v2_0/resteasy/v3_1. expected_package_name="$expected_prefix" IFS='-' read -ra module_parts <<< "$module_name" - for part in "${module_parts[@]}"; do - if [[ "$part" == "java" ]]; then + for i in "${!module_parts[@]}"; do + part=${module_parts[$i]} + if [[ "$part" == "java" && "$i" != 0 ]]; then continue fi if [[ "$part" =~ ^[0-9][0-9.]*$ ]]; then diff --git a/package-name-exceptions-plan.md b/package-name-exceptions-plan.md index a53167bb54ee..50526e48b039 100644 --- a/package-name-exceptions-plan.md +++ b/package-name-exceptions-plan.md @@ -8,6 +8,12 @@ Updated again on 2026-05-14 to plan faster batches: up to 20 changed files per P Updated again on 2026-05-14 to bump the target to up to 40 changed files per PR and plan all remaining historical package renames. Updated on 2026-05-17 after PRs 15-16 merged, and after deciding to handle Akka/Scala forkjoin as a module-name cleanup instead of a package-only cleanup. Updated on 2026-05-18 after PRs 13, 18, 20, and 21 merged and their historical package exceptions were removed from the checker. +Updated again on 2026-05-18 after deciding that leading `java` is meaningful for JDK instrumentation packages. +Updated again on 2026-05-18 after applying #16090's `*-common` module naming convention and planning PRs 23-26. +Updated on 2026-05-19 after PRs 23-24 merged and their unversioned common-module allowances were removed from the checker. +Updated again on 2026-05-19 after deciding app-server/framework module names for Payara, Quarkus RESTEasy Reactive, and Tomcat JDBC. +Updated on 2026-05-22 after documenting how patch-level base versions map to module names. +Updated again on 2026-05-22 after PR 25 merged, Java util logging PR 22 was closed, and app-server/framework PR 27 was split into Payara and Quarkus/Tomcat PRs. ## Goal @@ -19,14 +25,14 @@ The remaining exceptions fall into four buckets: | Bucket | Current signal | Recommendation | | --- | --- | --- | -| Module-wide skips | `java-*` has 39 files, `jmx-metrics` has 43 files | Do not start here; these need broader naming decisions. | +| Module-wide skips | `jmx-metrics` has 43 files | Do not start here; this needs a broader naming decision. | | Library packages under third-party namespaces | `grpc`, `lettuce`, `nats`, `rxjava` each have 1 file | Leave for later; these are likely compatibility/shim packages. | | Javaagent advice under instrumented library namespaces | mostly 1 file each | Leave for later; the script already says these must live in the instrumented library namespace. | | Historical javaagent packages | many one-dir modules remain, usually with one source directory | Best place to keep chipping away. | ## Completed Cleanups -These PRs have merged, and their historical javaagent package-name exceptions have been removed from `.github/scripts/check-package-names.sh`: +These PRs have merged. Remove their historical javaagent package-name exceptions from `.github/scripts/check-package-names.sh` on `next` after the corresponding cleanup lands upstream: - PR 1: `internal-eclipse-osgi-3.6` and `opentelemetry-extension-kotlin-1.0`. - PR 2: `spark-2.3`. @@ -44,6 +50,9 @@ These PRs have merged, and their historical javaagent package-name exceptions ha - PR 18: `jaxrs-common`. - PR 20: `servlet-common` snippet package. - PR 21: `servlet-common` root helper package. +- PR 23: `jetty-common` -> `jetty-common-8.0` and `tomcat-common` -> `tomcat-common-7.0`. +- PR 24: `opensearch-rest-common` -> `opensearch-rest-common-1.0`. +- PR 25: `spring-webmvc-common` -> `spring-webmvc-common-3.1`. PRs 5-8 merged upstream as: @@ -71,7 +80,17 @@ PRs 13, 18, 20, and 21 merged upstream as: - #18777: `servlet-common` snippet package. - #18778: `servlet-common` root helper package. +PRs 23-24 merged upstream as: + +- #18786: `jetty-common` -> `jetty-common-8.0` and `tomcat-common` -> `tomcat-common-7.0`. +- #18787: `opensearch-rest-common` -> `opensearch-rest-common-1.0`. + +PR 25 merged upstream as: + +- #18788: `spring-webmvc-common` -> `spring-webmvc-common-3.1`. + `external-annotations` still remains in the unversioned-module allowlist as `javaagent:external-annotations`; that is a separate module-name exception, not a historical package exception. +`spring-boot-resources` keeps a narrow deprecated compatibility-package exception for `io.opentelemetry.instrumentation.spring.resources`; the replacement javaagent package is already present under `io.opentelemetry.javaagent.instrumentation.spring.boot.resources`. ## PR Creation Notes @@ -111,7 +130,20 @@ For common-module package moves, search for downstream versioned modules importi ## Open Cleanup PRs -PR 14 is open as #18747 and PR 17 is open as #18772. Keep `.github/scripts/check-package-names.sh` and checker exception removals on `next` until cleanup PRs merge. +PR 14 is open as #18747, PR 17 is open as #18772, Payara is open as #18835, and Quarkus/Tomcat JDBC is open as #18838. PR 22 (#18784) was closed without merging. Keep `.github/scripts/check-package-names.sh` and checker exception removals on `next` until cleanup PRs merge. + +For JDK instrumentation modules, keep the leading `java` token in package paths. For example, +`java-util-logging` maps to `io.opentelemetry.javaagent.instrumentation.java.util.logging`, while +embedded `java` tokens in third-party library names are still elided, e.g. `graphql-java-20.0` maps +to `graphql.v20_0`. + +When the actual minimum supported library version is a patch release, use the containing minor +version in the module and package name unless the patch is a meaningful compatibility boundary. For +example, `payara-embedded-web:5.2020.2` maps to `payara-5.2020` and package suffix `v5_2020`, not +`payara-5.2020.2` / `v5_2020_2`, because there is no known compatibility split inside the +`5.2020.x` line. Users should be on the latest patch for a given minor line, and patch-level suffixes +would create noisy module names unless they identify a real boundary such as a muzzle range or +sibling module split. ### PR 14: OpenTelemetry annotation and instrumentation API modules (open #18747) @@ -189,16 +221,169 @@ Suggested verification: ./gradlew :instrumentation:opentelemetry-api:opentelemetry-api-1.0:javaagent:test ``` +### PR 22: Java util logging package (closed #18784, deferred) + +Module: + +- `java-util-logging` + +Expected package change: + +- `io.opentelemetry.javaagent.instrumentation.jul` -> `io.opentelemetry.javaagent.instrumentation.java.util.logging` + +Notes: + +- Javaagent-only package move. +- Keep the module name and instrumentation name `java-util-logging`. +- #18784 was closed without merging. Revisit later if this still looks worth doing after the current module-name cleanups land. + +Suggested verification: + +```bash +.github/scripts/check-package-names.sh +./gradlew :instrumentation:java-util-logging:javaagent:test +``` + +### PR 25: Spring WebMVC common module name (merged #18788) + +Module: + +- `spring-webmvc-common` -> `spring-webmvc-common-3.1` + +Expected package change: + +- `io.opentelemetry.javaagent.instrumentation.spring.webmvc.common` -> `io.opentelemetry.javaagent.instrumentation.spring.webmvc.common.v3_1` + +Notes: + +- This is a #16090 common-module convention cleanup. The common javaagent module compiles against `org.springframework:spring-webmvc:3.1.0.RELEASE` and is shared by `spring-webmvc-3.1` and `spring-webmvc-6.0`. +- Estimated changed files: about 27 in the PR branch, excluding the later checker update on `next`. +- Update `settings.gradle.kts`, dependent Gradle project references, package declarations, and imports. +- Keep the `testing` project path with the module rename, but treat testing package changes under `spring.webmvc.boot` and `spring.webmvc.filter` as a separate public testing API decision unless the audit shows they are private-only. + +Suggested verification: + +```bash +.github/scripts/check-package-names.sh +./gradlew :instrumentation:spring:spring-webmvc:spring-webmvc-common-3.1:javaagent:test :instrumentation:spring:spring-webmvc:spring-webmvc-3.1:javaagent:test :instrumentation:spring:spring-webmvc:spring-webmvc-6.0:javaagent:test +``` + +### PR 28: Spring WebMVC testing package alignment + +Modules: + +- `spring-webmvc-common-3.1` testing packages + +Expected package decision: + +- Move Spring WebMVC common testing helpers to include the `v3_1` package segment that now matches the common module name. +- Preserve public testing API compatibility if these helpers are consumed outside the repository; otherwise treat this as the follow-up requested in #18788's review. + +Notes: + +- This is a follow-up to #18788's review comment asking whether the testing module should add the `v3_1` directory too. +- Audit testing helpers currently under `io.opentelemetry.instrumentation.spring.webmvc.boot` and `io.opentelemetry.instrumentation.spring.webmvc.filter`; decide the exact target packages from their module-local usage before moving files. +- Keep this separate from the already-merged javaagent module rename so the public/private testing API decision is reviewable on its own. + +Suggested verification: + +```bash +.github/scripts/check-package-names.sh +./gradlew :instrumentation:spring:spring-webmvc:spring-webmvc-common-3.1:javaagent:test :instrumentation:spring:spring-webmvc:spring-webmvc-3.1:javaagent:compileTestJava :instrumentation:spring:spring-webmvc:spring-webmvc-6.0:javaagent:compileTestJava +``` + +### PR 26: Spring Cloud Gateway common testing package decision + +Module: + +- `spring-cloud-gateway-common` + +Expected package decision: + +- Keep `spring-cloud-gateway-common` unversioned for the javaagent helper unless a deeper audit finds a direct Spring Cloud Gateway API dependency. +- Decide whether testing packages should move from `io.opentelemetry.instrumentation.spring.gateway.common` to `io.opentelemetry.instrumentation.spring.cloud.gateway.common`. + +Notes: + +- The javaagent helper has no direct Spring Cloud Gateway compile dependency and is shared by WebFlux/WebMVC instrumentations, so #16090 does not obviously require a versioned module name. +- Estimated changed files: about 7 if this is only the testing package rename; more if the audit expands scope beyond testing packages. +- The likely cleanup is only the testing package name, and this may be public testing API. Keep it separate from the module-name PRs above. + +Suggested verification: + +```bash +.github/scripts/check-package-names.sh +./gradlew :instrumentation:spring:spring-cloud-gateway:spring-cloud-gateway-common:javaagent:test :instrumentation:spring:spring-cloud-gateway:spring-cloud-gateway-2.0:javaagent:test :instrumentation:spring:spring-cloud-gateway:spring-cloud-gateway-webmvc-4.3:javaagent:test +``` + +### PR 27a: Payara module name (open #18835) + +Modules: + +- `payara` -> `payara-5.2020` + +Expected package change: + +- `io.opentelemetry.javaagent.instrumentation.payara` -> `io.opentelemetry.javaagent.instrumentation.payara.v5_2020` + +Notes: + +- This module-name cleanup is open as #18835. +- Use `payara-5.2020` because `5.2020.2` is the earliest `5.2020.x` release, the javaagent builds against it, and it contains both `fish.payara.opentracing.OpenTracingService` and `org.apache.catalina.core.StandardWrapper`. Per the patch-floor rule above, use the minor line in the module/package name instead of `payara-5.2020.2`. +- Keep `payara` as the main instrumentation name and add `payara-5.2020` as the versioned alias. + +Suggested verification: + +```bash +.github/scripts/check-package-names.sh +./gradlew generateFossaConfiguration :instrumentation:payara-5.2020:javaagent:test +``` + +### PR 27b: Quarkus RESTEasy Reactive and Tomcat JDBC module names (open #18838) + +Modules: + +- `quarkus-resteasy-reactive` -> `quarkus-resteasy-reactive-1.11` +- `tomcat-jdbc` -> `tomcat-jdbc-8.5` + +Expected package changes: + +- `io.opentelemetry.javaagent.instrumentation.quarkus.resteasy.reactive` -> `io.opentelemetry.javaagent.instrumentation.quarkus.resteasy.reactive.v1_11` +- `io.opentelemetry.javaagent.instrumentation.tomcat.jdbc` -> `io.opentelemetry.javaagent.instrumentation.tomcat.jdbc.v8_5` + +Notes: + +- This module-name cleanup is open as #18838. +- Keep existing instrumentation names as compatibility aliases. For Quarkus RESTEasy Reactive, deprecate the old `quarkus-resteasy-reactive-3.0` suppression key using the repo's `expandDeprecatedNames(...)` convention, and keep the muzzle split across `io.quarkus:quarkus-resteasy-reactive:(,3.9.0)` and `io.quarkus:quarkus-rest:[3.9.0,)`; `3.9` is the artifact rename boundary, not the module's minimum supported version. +- Use `quarkus-resteasy-reactive-1.11` because the artifact starts at `1.11.0` prereleases, the first final is `1.11.0.Final`, the javaagent compiles against `1.11.0.Final`, and the original muzzle range covered all versions of the old artifact. +- Use `tomcat-jdbc-8.5` because the javaagent compiles/tests against `org.apache.tomcat:tomcat-jdbc:8.5.0` and docs list support from `[8.5.0,)`. + +Suggested verification: + +```bash +.github/scripts/check-package-names.sh +./gradlew generateFossaConfiguration :instrumentation:quarkus-resteasy-reactive-1.11:javaagent:test :instrumentation:quarkus-resteasy-reactive-1.11:quarkus-2.0-testing:compileTestJava :instrumentation:quarkus-resteasy-reactive-1.11:quarkus-3.0-testing:compileTestJava :instrumentation:quarkus-resteasy-reactive-1.11:quarkus-3.9-testing:compileTestJava :instrumentation:tomcat:tomcat-jdbc-8.5:javaagent:test :instrumentation:tomcat:tomcat-jdbc-8.5:javaagent:testStableSemconv +``` + ## Do Later These are probably not the next easiest wins: -- `java-*` module skip: the current packages use names like `javahttpclient`, while the checker would expect `http.client` after eliding `java`. This touches 39 files and needs a naming decision. +- `java-http-client` and `java-http-server`: these have published library/testing packages, so package renames need a dedicated public API decision instead of a package-only javaagent cleanup. - `jmx-metrics`: current packages are under `jmx`, while the module says `jmx-metrics`. This touches 43 files and may be user-facing enough to deserve a dedicated PR. - Library-specific third-party packages: `io.grpc.override`, `io.lettuce.core.protocol`, `io.nats.client.impl`, and `rx` are likely intentional shims or package-private access points. - Advice-native package exceptions: packages under `com.clickhouse`, `com.twitter`, `io.netty`, `reactor.netty`, `org.springframework`, and `io.vertx` should stay until each one is proven not to need native package placement. - OpenTelemetry API and Akka/Scala forkjoin package/module renames are planned above; AWS SDK remains deferred. -- Other unversioned module allowlist entries: these need package/module naming decisions beyond a package-only cleanup. +- Remaining unversioned module allowlist entries split into policy buckets: + - JDK/platform modules such as `executors`, `http-url-connection`, `jdbc`, `methods`, `rmi`, and `runtime-telemetry` probably deserve explicit checker allowances instead of version suffixes. + - `internal-*` modules such as `internal-class-loader`, `internal-lambda`, `internal-reflection`, and `internal-url-class-loader` probably deserve explicit checker allowances; version suffixes would be misleading. + - `*-common` modules need case-by-case module naming review: + - Apply #16090's convention: `-common` is for pure utility/abstraction code with no direct library version dependency, `-common-` is for shared code that requires a minimum library version, and `-common-` is for variants such as `javax`. + - `spring-webmvc-common` was completed in PR 25, its testing package follow-up is planned above as PR 28, and the `spring-cloud-gateway-common` testing package decision is planned above as PR 26. `jetty-common`, `tomcat-common`, and `opensearch-rest-common` were completed in PRs 23-24. + - `jaxrs-common`: keep unversioned. The javaagent module has no direct JAX-RS API dependency and acts as cross-generation helper/bootstrap code used by JAX-RS 1.0, 2.0, 3.0, and Quarkus RESTEasy Reactive. Keep it separate from the already version-scoped `jaxrs-2.0-common`, `jaxrs-3.0-common`, `jaxrs-common-2.0`, and `jaxrs-common-3.0` modules. + - `servlet-common`: keep unversioned. This matches #16090's pure abstraction/variant shape: shared code for both `javax.servlet` and `jakarta.servlet`, with `servlet-common-javax` as the variant-specific module. Because it includes published `library` packages, treat any future package changes as public API policy, not package-only cleanup. + - App-server/framework module-name cleanups for `payara`, `quarkus-resteasy-reactive`, and `tomcat-jdbc` are open above as PRs 27a-27b. + - Treat this as a checker-policy cleanup first: document legitimate unversioned javaagent module shapes, then only rename leftovers that are true module-name debt. ## Re-Audit Command From f013ddffe30c3082c0c3c60a1ca01a72e362fb8e Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 26 May 2026 11:24:02 -0700 Subject: [PATCH 04/10] Update package-name cleanup plan after merged PRs --- package-name-exceptions-plan.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/package-name-exceptions-plan.md b/package-name-exceptions-plan.md index 50526e48b039..b653bcbd7854 100644 --- a/package-name-exceptions-plan.md +++ b/package-name-exceptions-plan.md @@ -14,6 +14,7 @@ Updated on 2026-05-19 after PRs 23-24 merged and their unversioned common-module Updated again on 2026-05-19 after deciding app-server/framework module names for Payara, Quarkus RESTEasy Reactive, and Tomcat JDBC. Updated on 2026-05-22 after documenting how patch-level base versions map to module names. Updated again on 2026-05-22 after PR 25 merged, Java util logging PR 22 was closed, and app-server/framework PR 27 was split into Payara and Quarkus/Tomcat PRs. +Updated on 2026-05-26 after PRs 27a, 27b, and the Spring testing-package alignment cleanup merged. ## Goal @@ -130,7 +131,7 @@ For common-module package moves, search for downstream versioned modules importi ## Open Cleanup PRs -PR 14 is open as #18747, PR 17 is open as #18772, Payara is open as #18835, and Quarkus/Tomcat JDBC is open as #18838. PR 22 (#18784) was closed without merging. Keep `.github/scripts/check-package-names.sh` and checker exception removals on `next` until cleanup PRs merge. +PR 14 is open as #18747 and PR 17 is open as #18772. PR 22 (#18784) was closed without merging. Keep `.github/scripts/check-package-names.sh` and checker exception removals on `next` until cleanup PRs merge. For JDK instrumentation modules, keep the leading `java` token in package paths. For example, `java-util-logging` maps to `io.opentelemetry.javaagent.instrumentation.java.util.logging`, while @@ -268,7 +269,7 @@ Suggested verification: ./gradlew :instrumentation:spring:spring-webmvc:spring-webmvc-common-3.1:javaagent:test :instrumentation:spring:spring-webmvc:spring-webmvc-3.1:javaagent:test :instrumentation:spring:spring-webmvc:spring-webmvc-6.0:javaagent:test ``` -### PR 28: Spring WebMVC testing package alignment +### PR 28: Spring WebMVC testing package alignment (merged in #18839) Modules: @@ -283,7 +284,7 @@ Notes: - This is a follow-up to #18788's review comment asking whether the testing module should add the `v3_1` directory too. - Audit testing helpers currently under `io.opentelemetry.instrumentation.spring.webmvc.boot` and `io.opentelemetry.instrumentation.spring.webmvc.filter`; decide the exact target packages from their module-local usage before moving files. -- Keep this separate from the already-merged javaagent module rename so the public/private testing API decision is reviewable on its own. +- This landed together with PR 26 as the combined Spring testing package cleanup in #18839. Suggested verification: @@ -292,7 +293,7 @@ Suggested verification: ./gradlew :instrumentation:spring:spring-webmvc:spring-webmvc-common-3.1:javaagent:test :instrumentation:spring:spring-webmvc:spring-webmvc-3.1:javaagent:compileTestJava :instrumentation:spring:spring-webmvc:spring-webmvc-6.0:javaagent:compileTestJava ``` -### PR 26: Spring Cloud Gateway common testing package decision +### PR 26: Spring Cloud Gateway common testing package decision (merged in #18839) Module: @@ -307,7 +308,8 @@ Notes: - The javaagent helper has no direct Spring Cloud Gateway compile dependency and is shared by WebFlux/WebMVC instrumentations, so #16090 does not obviously require a versioned module name. - Estimated changed files: about 7 if this is only the testing package rename; more if the audit expands scope beyond testing packages. -- The likely cleanup is only the testing package name, and this may be public testing API. Keep it separate from the module-name PRs above. +- The likely cleanup is only the testing package name, and this may be public testing API. +- This landed together with PR 28 as the combined Spring testing package cleanup in #18839. Suggested verification: @@ -316,7 +318,7 @@ Suggested verification: ./gradlew :instrumentation:spring:spring-cloud-gateway:spring-cloud-gateway-common:javaagent:test :instrumentation:spring:spring-cloud-gateway:spring-cloud-gateway-2.0:javaagent:test :instrumentation:spring:spring-cloud-gateway:spring-cloud-gateway-webmvc-4.3:javaagent:test ``` -### PR 27a: Payara module name (open #18835) +### PR 27a: Payara module name (merged #18835) Modules: @@ -328,7 +330,7 @@ Expected package change: Notes: -- This module-name cleanup is open as #18835. +- This module-name cleanup merged as #18835. - Use `payara-5.2020` because `5.2020.2` is the earliest `5.2020.x` release, the javaagent builds against it, and it contains both `fish.payara.opentracing.OpenTracingService` and `org.apache.catalina.core.StandardWrapper`. Per the patch-floor rule above, use the minor line in the module/package name instead of `payara-5.2020.2`. - Keep `payara` as the main instrumentation name and add `payara-5.2020` as the versioned alias. @@ -339,7 +341,7 @@ Suggested verification: ./gradlew generateFossaConfiguration :instrumentation:payara-5.2020:javaagent:test ``` -### PR 27b: Quarkus RESTEasy Reactive and Tomcat JDBC module names (open #18838) +### PR 27b: Quarkus RESTEasy Reactive and Tomcat JDBC module names (merged #18838) Modules: @@ -353,7 +355,7 @@ Expected package changes: Notes: -- This module-name cleanup is open as #18838. +- This module-name cleanup merged as #18838. - Keep existing instrumentation names as compatibility aliases. For Quarkus RESTEasy Reactive, deprecate the old `quarkus-resteasy-reactive-3.0` suppression key using the repo's `expandDeprecatedNames(...)` convention, and keep the muzzle split across `io.quarkus:quarkus-resteasy-reactive:(,3.9.0)` and `io.quarkus:quarkus-rest:[3.9.0,)`; `3.9` is the artifact rename boundary, not the module's minimum supported version. - Use `quarkus-resteasy-reactive-1.11` because the artifact starts at `1.11.0` prereleases, the first final is `1.11.0.Final`, the javaagent compiles against `1.11.0.Final`, and the original muzzle range covered all versions of the old artifact. - Use `tomcat-jdbc-8.5` because the javaagent compiles/tests against `org.apache.tomcat:tomcat-jdbc:8.5.0` and docs list support from `[8.5.0,)`. @@ -382,7 +384,7 @@ These are probably not the next easiest wins: - `spring-webmvc-common` was completed in PR 25, its testing package follow-up is planned above as PR 28, and the `spring-cloud-gateway-common` testing package decision is planned above as PR 26. `jetty-common`, `tomcat-common`, and `opensearch-rest-common` were completed in PRs 23-24. - `jaxrs-common`: keep unversioned. The javaagent module has no direct JAX-RS API dependency and acts as cross-generation helper/bootstrap code used by JAX-RS 1.0, 2.0, 3.0, and Quarkus RESTEasy Reactive. Keep it separate from the already version-scoped `jaxrs-2.0-common`, `jaxrs-3.0-common`, `jaxrs-common-2.0`, and `jaxrs-common-3.0` modules. - `servlet-common`: keep unversioned. This matches #16090's pure abstraction/variant shape: shared code for both `javax.servlet` and `jakarta.servlet`, with `servlet-common-javax` as the variant-specific module. Because it includes published `library` packages, treat any future package changes as public API policy, not package-only cleanup. - - App-server/framework module-name cleanups for `payara`, `quarkus-resteasy-reactive`, and `tomcat-jdbc` are open above as PRs 27a-27b. + - App-server/framework module-name cleanups for `payara`, `quarkus-resteasy-reactive`, and `tomcat-jdbc` were completed in PRs 27a-27b. - Treat this as a checker-policy cleanup first: document legitimate unversioned javaagent module shapes, then only rename leftovers that are true module-name debt. ## Re-Audit Command From e803c69d167e88c3733058dcbc53a073d07aef88 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 26 May 2026 11:27:10 -0700 Subject: [PATCH 05/10] Remove stale unversioned module checker exceptions --- .github/scripts/check-package-names.sh | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.github/scripts/check-package-names.sh b/.github/scripts/check-package-names.sh index d5225b5f048a..be18e10b140e 100755 --- a/.github/scripts/check-package-names.sh +++ b/.github/scripts/check-package-names.sh @@ -121,15 +121,11 @@ check_source_set() { javaagent:methods) ;; javaagent:opentelemetry-instrumentation-api) ;; javaagent:oshi) ;; - javaagent:payara) ;; - javaagent:quarkus-resteasy-reactive) ;; javaagent:rmi) ;; javaagent:runtime-telemetry) ;; javaagent:servlet-common) ;; javaagent:spring-boot-resources) ;; javaagent:spring-cloud-gateway-common) ;; - javaagent:spring-webmvc-common) ;; - javaagent:tomcat-jdbc) ;; *) echo "module name doesn't have a base version: $dir" exit 1 From c0e2f4558ead45f2451cca294df90b1f44193c2b Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 26 May 2026 11:38:13 -0700 Subject: [PATCH 06/10] Plan oshi and elasticsearch-transport-common base-version renames --- package-name-exceptions-plan.md | 56 +++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/package-name-exceptions-plan.md b/package-name-exceptions-plan.md index b653bcbd7854..038d7249dd5c 100644 --- a/package-name-exceptions-plan.md +++ b/package-name-exceptions-plan.md @@ -15,6 +15,7 @@ Updated again on 2026-05-19 after deciding app-server/framework module names for Updated on 2026-05-22 after documenting how patch-level base versions map to module names. Updated again on 2026-05-22 after PR 25 merged, Java util logging PR 22 was closed, and app-server/framework PR 27 was split into Payara and Quarkus/Tomcat PRs. Updated on 2026-05-26 after PRs 27a, 27b, and the Spring testing-package alignment cleanup merged. +Updated again on 2026-05-26 after auditing remaining unversioned-allowlist entries against the documented base-version convention and planning PRs 29-30. ## Goal @@ -367,6 +368,54 @@ Suggested verification: ./gradlew generateFossaConfiguration :instrumentation:quarkus-resteasy-reactive-1.11:javaagent:test :instrumentation:quarkus-resteasy-reactive-1.11:quarkus-2.0-testing:compileTestJava :instrumentation:quarkus-resteasy-reactive-1.11:quarkus-3.0-testing:compileTestJava :instrumentation:quarkus-resteasy-reactive-1.11:quarkus-3.9-testing:compileTestJava :instrumentation:tomcat:tomcat-jdbc-8.5:javaagent:test :instrumentation:tomcat:tomcat-jdbc-8.5:javaagent:testStableSemconv ``` +### PR 29: OSHI module name + +Modules: + +- `oshi` -> `oshi-5.0` + +Expected package changes: + +- `io.opentelemetry.instrumentation.oshi` -> `io.opentelemetry.instrumentation.oshi.v5_0` +- `io.opentelemetry.javaagent.instrumentation.oshi` -> `io.opentelemetry.javaagent.instrumentation.oshi.v5_0` + +Notes: + +- OSHI is a regular third-party library instrumentation with a real minimum version, not a `*-common` abstraction; per the base-version convention in `docs/contributing/writing-instrumentation.md`, the module name should include the major/minor line of the oldest supported library version. +- Javaagent muzzle is `[5.0.0,)` and compiles against `com.github.oshi:oshi-core:5.0.0`; library compiles against `5.3.1` (with a `5.5.0` arm-mac test override). Use `5.0` as the module base version because the javaagent muzzle floor is `5.0.0`. +- Keep `oshi` as the main instrumentation name and add `oshi-5.0` as the versioned alias. +- Update `settings.gradle.kts`, `.fossa.yml`, documentation inventory, and the testing module reference. + +Suggested verification: + +```bash +.github/scripts/check-package-names.sh +./gradlew generateFossaConfiguration :instrumentation:oshi-5.0:javaagent:test :instrumentation:oshi-5.0:library:test +``` + +### PR 30: Elasticsearch transport common module name + +Modules: + +- `elasticsearch-transport-common` -> `elasticsearch-transport-common-5.0` + +Expected package change: + +- `io.opentelemetry.javaagent.instrumentation.elasticsearch.transport.common` -> `io.opentelemetry.javaagent.instrumentation.elasticsearch.transport.common.v5_0` + +Notes: + +- The common javaagent module has a direct `compileOnly("org.elasticsearch.client:transport:5.0.0")` dependency and is shared by `elasticsearch-transport-5.0`, `elasticsearch-transport-5.3`, and `elasticsearch-transport-6.0`; per #16090 this is the `-common-` shape. +- Use `5.0` as the base version because that is the minimum supported version across the sibling modules and matches the common module's own `compileOnly` floor. +- Update `settings.gradle.kts`, sibling module Gradle references, and the testing module path. + +Suggested verification: + +```bash +.github/scripts/check-package-names.sh +./gradlew :instrumentation:elasticsearch:elasticsearch-transport-common-5.0:javaagent:test :instrumentation:elasticsearch:elasticsearch-transport-5.0:javaagent:compileTestJava :instrumentation:elasticsearch:elasticsearch-transport-5.3:javaagent:compileTestJava :instrumentation:elasticsearch:elasticsearch-transport-6.0:javaagent:compileTestJava +``` + ## Do Later These are probably not the next easiest wins: @@ -384,6 +433,13 @@ These are probably not the next easiest wins: - `spring-webmvc-common` was completed in PR 25, its testing package follow-up is planned above as PR 28, and the `spring-cloud-gateway-common` testing package decision is planned above as PR 26. `jetty-common`, `tomcat-common`, and `opensearch-rest-common` were completed in PRs 23-24. - `jaxrs-common`: keep unversioned. The javaagent module has no direct JAX-RS API dependency and acts as cross-generation helper/bootstrap code used by JAX-RS 1.0, 2.0, 3.0, and Quarkus RESTEasy Reactive. Keep it separate from the already version-scoped `jaxrs-2.0-common`, `jaxrs-3.0-common`, `jaxrs-common-2.0`, and `jaxrs-common-3.0` modules. - `servlet-common`: keep unversioned. This matches #16090's pure abstraction/variant shape: shared code for both `javax.servlet` and `jakarta.servlet`, with `servlet-common-javax` as the variant-specific module. Because it includes published `library` packages, treat any future package changes as public API policy, not package-only cleanup. + - `netty-common`: keep unversioned. No direct Netty compile dependency; explicitly listed as the canonical pure-abstraction example in `.github/agents/knowledge/module-naming.md`. Sibling `netty-common-4.0` carries the version-scoped shared code. + - `lettuce-common`: keep unversioned. No direct Lettuce compile dependency; matches the `netty-common` pure-abstraction shape and is shared by `lettuce-5.0` and `lettuce-5.1`. + - `spring-cloud-gateway-common`: keep unversioned. No direct Spring Cloud Gateway compile dependency; shared by `spring-cloud-gateway-2.0`, `spring-cloud-gateway-2.2`, and the gateway webflux/webmvc sibling modules. + - `elasticsearch-transport-common`: rename to `elasticsearch-transport-common-5.0` (planned above as PR 30). It has a direct `org.elasticsearch.client:transport:5.0.0` compile dependency, matching #16090's `-common-` shape. + - Non-common third-party library modules on the unversioned allowlist need module renames: + - `oshi`: rename to `oshi-5.0` (planned above as PR 29). + - `spring-boot-resources`: special case - not a `*-common` module and has no Spring Boot compile dependency (parses `application.yaml`/`bootstrap.yaml` by file convention via `snakeyaml-engine`). Defer until we decide whether a base version is meaningful here; if so, the natural floor is the earliest Spring Boot release whose YAML config layout we still parse. - App-server/framework module-name cleanups for `payara`, `quarkus-resteasy-reactive`, and `tomcat-jdbc` were completed in PRs 27a-27b. - Treat this as a checker-policy cleanup first: document legitimate unversioned javaagent module shapes, then only rename leftovers that are true module-name debt. From 687b65aacf53c119d07513dcadeaf789e06d1de0 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 28 May 2026 07:35:27 -0700 Subject: [PATCH 07/10] Update plan and checker after PRs 29-30 merged as #18854 PR 29 (oshi -> oshi-5.0) and PR 30 (elasticsearch-transport-common -> elasticsearch-transport-common-5.0) landed upstream together as #18854. Remove their now-stale unversioned-module allowlist entries from the checker and mark the corresponding plan sections as merged. --- .github/scripts/check-package-names.sh | 3 --- package-name-exceptions-plan.md | 15 +++++++++++---- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/.github/scripts/check-package-names.sh b/.github/scripts/check-package-names.sh index be18e10b140e..3f32ebf35e32 100755 --- a/.github/scripts/check-package-names.sh +++ b/.github/scripts/check-package-names.sh @@ -99,13 +99,11 @@ check_source_set() { library:jdbc) ;; library:lettuce-common) ;; library:netty-common) ;; - library:oshi) ;; library:resources) ;; library:runtime-telemetry) ;; library:servlet-common) ;; library:servlet-common-javax) ;; # javaagent: - javaagent:elasticsearch-transport-common) ;; javaagent:executors) ;; javaagent:external-annotations) ;; javaagent:http-url-connection) ;; @@ -120,7 +118,6 @@ check_source_set() { javaagent:jsf-common-javax) ;; javaagent:methods) ;; javaagent:opentelemetry-instrumentation-api) ;; - javaagent:oshi) ;; javaagent:rmi) ;; javaagent:runtime-telemetry) ;; javaagent:servlet-common) ;; diff --git a/package-name-exceptions-plan.md b/package-name-exceptions-plan.md index 038d7249dd5c..a527fa2943ff 100644 --- a/package-name-exceptions-plan.md +++ b/package-name-exceptions-plan.md @@ -16,6 +16,7 @@ Updated on 2026-05-22 after documenting how patch-level base versions map to mod Updated again on 2026-05-22 after PR 25 merged, Java util logging PR 22 was closed, and app-server/framework PR 27 was split into Payara and Quarkus/Tomcat PRs. Updated on 2026-05-26 after PRs 27a, 27b, and the Spring testing-package alignment cleanup merged. Updated again on 2026-05-26 after auditing remaining unversioned-allowlist entries against the documented base-version convention and planning PRs 29-30. +Updated on 2026-05-28 after PRs 29 and 30 merged upstream together as #18854 and their `library:oshi`, `javaagent:oshi`, and `javaagent:elasticsearch-transport-common` allowlist entries were removed from the checker. ## Goal @@ -91,6 +92,10 @@ PR 25 merged upstream as: - #18788: `spring-webmvc-common` -> `spring-webmvc-common-3.1`. +PRs 29-30 merged upstream together as: + +- #18854: `oshi` -> `oshi-5.0` and `elasticsearch-transport-common` -> `elasticsearch-transport-common-5.0`. + `external-annotations` still remains in the unversioned-module allowlist as `javaagent:external-annotations`; that is a separate module-name exception, not a historical package exception. `spring-boot-resources` keeps a narrow deprecated compatibility-package exception for `io.opentelemetry.instrumentation.spring.resources`; the replacement javaagent package is already present under `io.opentelemetry.javaagent.instrumentation.spring.boot.resources`. @@ -368,7 +373,7 @@ Suggested verification: ./gradlew generateFossaConfiguration :instrumentation:quarkus-resteasy-reactive-1.11:javaagent:test :instrumentation:quarkus-resteasy-reactive-1.11:quarkus-2.0-testing:compileTestJava :instrumentation:quarkus-resteasy-reactive-1.11:quarkus-3.0-testing:compileTestJava :instrumentation:quarkus-resteasy-reactive-1.11:quarkus-3.9-testing:compileTestJava :instrumentation:tomcat:tomcat-jdbc-8.5:javaagent:test :instrumentation:tomcat:tomcat-jdbc-8.5:javaagent:testStableSemconv ``` -### PR 29: OSHI module name +### PR 29: OSHI module name (merged in #18854) Modules: @@ -385,6 +390,7 @@ Notes: - Javaagent muzzle is `[5.0.0,)` and compiles against `com.github.oshi:oshi-core:5.0.0`; library compiles against `5.3.1` (with a `5.5.0` arm-mac test override). Use `5.0` as the module base version because the javaagent muzzle floor is `5.0.0`. - Keep `oshi` as the main instrumentation name and add `oshi-5.0` as the versioned alias. - Update `settings.gradle.kts`, `.fossa.yml`, documentation inventory, and the testing module reference. +- Landed together with PR 30 as #18854. Suggested verification: @@ -393,7 +399,7 @@ Suggested verification: ./gradlew generateFossaConfiguration :instrumentation:oshi-5.0:javaagent:test :instrumentation:oshi-5.0:library:test ``` -### PR 30: Elasticsearch transport common module name +### PR 30: Elasticsearch transport common module name (merged in #18854) Modules: @@ -408,6 +414,7 @@ Notes: - The common javaagent module has a direct `compileOnly("org.elasticsearch.client:transport:5.0.0")` dependency and is shared by `elasticsearch-transport-5.0`, `elasticsearch-transport-5.3`, and `elasticsearch-transport-6.0`; per #16090 this is the `-common-` shape. - Use `5.0` as the base version because that is the minimum supported version across the sibling modules and matches the common module's own `compileOnly` floor. - Update `settings.gradle.kts`, sibling module Gradle references, and the testing module path. +- Landed together with PR 29 as #18854. Suggested verification: @@ -436,9 +443,9 @@ These are probably not the next easiest wins: - `netty-common`: keep unversioned. No direct Netty compile dependency; explicitly listed as the canonical pure-abstraction example in `.github/agents/knowledge/module-naming.md`. Sibling `netty-common-4.0` carries the version-scoped shared code. - `lettuce-common`: keep unversioned. No direct Lettuce compile dependency; matches the `netty-common` pure-abstraction shape and is shared by `lettuce-5.0` and `lettuce-5.1`. - `spring-cloud-gateway-common`: keep unversioned. No direct Spring Cloud Gateway compile dependency; shared by `spring-cloud-gateway-2.0`, `spring-cloud-gateway-2.2`, and the gateway webflux/webmvc sibling modules. - - `elasticsearch-transport-common`: rename to `elasticsearch-transport-common-5.0` (planned above as PR 30). It has a direct `org.elasticsearch.client:transport:5.0.0` compile dependency, matching #16090's `-common-` shape. + - `elasticsearch-transport-common`: renamed to `elasticsearch-transport-common-5.0` in PR 30 (merged as #18854). It had a direct `org.elasticsearch.client:transport:5.0.0` compile dependency, matching #16090's `-common-` shape. - Non-common third-party library modules on the unversioned allowlist need module renames: - - `oshi`: rename to `oshi-5.0` (planned above as PR 29). + - `oshi`: renamed to `oshi-5.0` in PR 29 (merged as #18854). - `spring-boot-resources`: special case - not a `*-common` module and has no Spring Boot compile dependency (parses `application.yaml`/`bootstrap.yaml` by file convention via `snakeyaml-engine`). Defer until we decide whether a base version is meaningful here; if so, the natural floor is the earliest Spring Boot release whose YAML config layout we still parse. - App-server/framework module-name cleanups for `payara`, `quarkus-resteasy-reactive`, and `tomcat-jdbc` were completed in PRs 27a-27b. - Treat this as a checker-policy cleanup first: document legitimate unversioned javaagent module shapes, then only rename leftovers that are true module-name debt. From 5ffefa5117df25f1c6a10445caa6a06fabfd66cf Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 28 May 2026 08:17:57 -0700 Subject: [PATCH 08/10] Drop wildcard checker exceptions for jaxrs-{2.0,3.0}-{annotations,common} Their package layout already matches the module-name <-> package-name convention (jaxrs/v2_0/annotations, jaxrs/v2_0/common, jaxrs/v3_0/annotations, jaxrs/v3_0/common). Only the digit-suffix module-name guard fails because the version is embedded mid-name, so move them from the historical wildcard case to the no-base-version case where the package layout is still validated. --- .github/scripts/check-package-names.sh | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/.github/scripts/check-package-names.sh b/.github/scripts/check-package-names.sh index 3f32ebf35e32..308cf6dcf0f7 100755 --- a/.github/scripts/check-package-names.sh +++ b/.github/scripts/check-package-names.sh @@ -81,10 +81,6 @@ check_source_set() { instrumentation/java-http-client/javaagent/*) continue ;; instrumentation/java-http-server/javaagent/*) continue ;; instrumentation/java-util-logging/javaagent/*) continue ;; - instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-annotations/javaagent/*) continue ;; - instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-common/javaagent/*) continue ;; - instrumentation/jaxrs/jaxrs-3.0/jaxrs-3.0-annotations/javaagent/*) continue ;; - instrumentation/jaxrs/jaxrs-3.0/jaxrs-3.0-common/javaagent/*) continue ;; instrumentation/opentelemetry-api/opentelemetry-api-1.0/javaagent/*) continue ;; instrumentation/opentelemetry-extension-annotations-1.0/javaagent/*) continue ;; instrumentation/opentelemetry-instrumentation-annotations-1.16/javaagent/*) continue ;; @@ -92,7 +88,9 @@ check_source_set() { esac fi - # some common modules don't have any base version (might have a variant instead, ex: javax) + # modules whose name does not end with a version digit, either because they have no base + # version (e.g. jdbc, netty-common) or because the version is embedded mid-name (e.g. + # jaxrs-2.0-annotations); package layout is still derived from the module name below if [[ ! "$module_name" =~ [0-9]$ ]]; then case "$source_set:$module_name" in # library: @@ -112,6 +110,10 @@ check_source_set() { javaagent:internal-lambda) ;; javaagent:internal-reflection) ;; javaagent:internal-url-class-loader) ;; + javaagent:jaxrs-2.0-annotations) ;; + javaagent:jaxrs-2.0-common) ;; + javaagent:jaxrs-3.0-annotations) ;; + javaagent:jaxrs-3.0-common) ;; javaagent:jaxrs-common) ;; javaagent:jdbc) ;; javaagent:jsf-common-jakarta) ;; From c2bf70e0e7e77e9f0991917d65d2d77c23c73065 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 2 Jun 2026 15:46:09 -0700 Subject: [PATCH 09/10] Update plan and checker after PR 17 merged as #18772 and #18855 PR 17 (akka-actor-fork-join-2.5 -> akka-actor-forkjoin-2.5 and scala-fork-join-2.8 -> scala-forkjoin-2.8) landed upstream as #18772. #18855 moved the servlet-common library internal package from io.opentelemetry.instrumentation.servlet.internal to io.opentelemetry.instrumentation.servlet.common.internal. Remove their now-stale checker carveouts and mark the corresponding plan sections as merged. --- .github/scripts/check-package-names.sh | 4 ---- package-name-exceptions-plan.md | 13 +++++++++++-- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/.github/scripts/check-package-names.sh b/.github/scripts/check-package-names.sh index 308cf6dcf0f7..b713f90f11e4 100755 --- a/.github/scripts/check-package-names.sh +++ b/.github/scripts/check-package-names.sh @@ -48,9 +48,6 @@ check_source_set() { if [[ "$dir" == "instrumentation/elasticsearch/elasticsearch-rest-7.0/library/src/main/java/org/elasticsearch/client" ]]; then continue fi - if [[ "$dir" == "instrumentation/servlet/servlet-common/library/src/main/java/io/opentelemetry/instrumentation/servlet/internal" ]]; then - continue - fi if [[ "$dir" == instrumentation/java-http-client/library/src/main/java/io/opentelemetry/instrumentation/javahttpclient* ]]; then continue fi @@ -75,7 +72,6 @@ check_source_set() { # historical javaagent modules that do not follow the module-name <-> package-name convention case "$dir" in - instrumentation/akka/akka-actor-fork-join-2.5/javaagent/*) continue ;; instrumentation/aws-sdk/aws-sdk-1.11/javaagent/src/main/java/io/opentelemetry/instrumentation/awssdk/v1_11) continue ;; instrumentation/aws-sdk/aws-sdk-2.2/javaagent/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal) continue ;; instrumentation/java-http-client/javaagent/*) continue ;; diff --git a/package-name-exceptions-plan.md b/package-name-exceptions-plan.md index a527fa2943ff..6f985fa5e39f 100644 --- a/package-name-exceptions-plan.md +++ b/package-name-exceptions-plan.md @@ -17,6 +17,7 @@ Updated again on 2026-05-22 after PR 25 merged, Java util logging PR 22 was clos Updated on 2026-05-26 after PRs 27a, 27b, and the Spring testing-package alignment cleanup merged. Updated again on 2026-05-26 after auditing remaining unversioned-allowlist entries against the documented base-version convention and planning PRs 29-30. Updated on 2026-05-28 after PRs 29 and 30 merged upstream together as #18854 and their `library:oshi`, `javaagent:oshi`, and `javaagent:elasticsearch-transport-common` allowlist entries were removed from the checker. +Updated on 2026-06-02 after PR 17 merged upstream as #18772 (Akka/Scala forkjoin module renames), and after #18855 moved the `servlet-common` library internal package; both allowlist entries were removed from the checker. ## Goal @@ -96,6 +97,14 @@ PRs 29-30 merged upstream together as: - #18854: `oshi` -> `oshi-5.0` and `elasticsearch-transport-common` -> `elasticsearch-transport-common-5.0`. +PR 17 merged upstream as: + +- #18772: `akka-actor-fork-join-2.5` -> `akka-actor-forkjoin-2.5` and `scala-fork-join-2.8` -> `scala-forkjoin-2.8`. + +The `servlet-common` library internal package was moved upstream as: + +- #18855: `io.opentelemetry.instrumentation.servlet.internal` -> `io.opentelemetry.instrumentation.servlet.common.internal`. + `external-annotations` still remains in the unversioned-module allowlist as `javaagent:external-annotations`; that is a separate module-name exception, not a historical package exception. `spring-boot-resources` keeps a narrow deprecated compatibility-package exception for `io.opentelemetry.instrumentation.spring.resources`; the replacement javaagent package is already present under `io.opentelemetry.javaagent.instrumentation.spring.boot.resources`. @@ -137,7 +146,7 @@ For common-module package moves, search for downstream versioned modules importi ## Open Cleanup PRs -PR 14 is open as #18747 and PR 17 is open as #18772. PR 22 (#18784) was closed without merging. Keep `.github/scripts/check-package-names.sh` and checker exception removals on `next` until cleanup PRs merge. +PR 14 is open as #18747. PR 22 (#18784) was closed without merging. Keep `.github/scripts/check-package-names.sh` and checker exception removals on `next` until cleanup PRs merge. For JDK instrumentation modules, keep the leading `java` token in package paths. For example, `java-util-logging` maps to `io.opentelemetry.javaagent.instrumentation.java.util.logging`, while @@ -181,7 +190,7 @@ Suggested verification: ./gradlew :instrumentation:opentelemetry-extension-annotations-1.0:javaagent:test :instrumentation:opentelemetry-instrumentation-api:javaagent:test :instrumentation:opentelemetry-instrumentation-annotations-1.16:javaagent:test :instrumentation:kotlinx-coroutines:kotlinx-coroutines-1.0:javaagent:compileJava ``` -### PR 17: Akka and Scala forkjoin module/package names (open #18772) +### PR 17: Akka and Scala forkjoin module/package names (merged #18772) Modules: From 34eca954f1811ba60125d0c345124616bcd404df Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 2 Jun 2026 16:45:01 -0700 Subject: [PATCH 10/10] Defer PR 14 and document self-instrumentation modules in the checker Keep the existing package layout for the four self-instrumentation modules (opentelemetry-api-1.0, opentelemetry-extension-annotations-1.0, opentelemetry-instrumentation-annotations-1.16, opentelemetry-instrumentation-api) instead of renaming them under .opentelemetry.* as PR 14 / #18747 proposed. Promote them in the checker from a generic historical wildcard to a dedicated self-instrumentation case block with a comment explaining why the standard module-name <-> package-name convention does not apply. The javaagent:opentelemetry-instrumentation-api unversioned-module allowlist entry was removed at the same time because the new case block already short-circuits before the unversioned check. --- .github/scripts/check-package-names.sh | 16 +++++++---- package-name-exceptions-plan.md | 39 ++++++++++++++------------ 2 files changed, 32 insertions(+), 23 deletions(-) diff --git a/.github/scripts/check-package-names.sh b/.github/scripts/check-package-names.sh index b713f90f11e4..7b7b542fef2d 100755 --- a/.github/scripts/check-package-names.sh +++ b/.github/scripts/check-package-names.sh @@ -70,6 +70,17 @@ check_source_set() { instrumentation/vertx/vertx-sql-client/vertx-sql-client-common-4.0/javaagent/src/main/java/io/vertx/sqlclient/impl*) continue ;; esac + # self-instrumentation modules: these instrument OpenTelemetry's own code, + # so the standard module-name <-> package-name convention (which treats the + # first dash-separated token as the instrumented library's namespace) does + # not apply; package layout is owned by these modules and reviewed by hand + case "$dir" in + instrumentation/opentelemetry-api/opentelemetry-api-1.0/javaagent/*) continue ;; + instrumentation/opentelemetry-extension-annotations-1.0/javaagent/*) continue ;; + instrumentation/opentelemetry-instrumentation-annotations-1.16/javaagent/*) continue ;; + instrumentation/opentelemetry-instrumentation-api/javaagent/*) continue ;; + esac + # historical javaagent modules that do not follow the module-name <-> package-name convention case "$dir" in instrumentation/aws-sdk/aws-sdk-1.11/javaagent/src/main/java/io/opentelemetry/instrumentation/awssdk/v1_11) continue ;; @@ -77,10 +88,6 @@ check_source_set() { instrumentation/java-http-client/javaagent/*) continue ;; instrumentation/java-http-server/javaagent/*) continue ;; instrumentation/java-util-logging/javaagent/*) continue ;; - instrumentation/opentelemetry-api/opentelemetry-api-1.0/javaagent/*) continue ;; - instrumentation/opentelemetry-extension-annotations-1.0/javaagent/*) continue ;; - instrumentation/opentelemetry-instrumentation-annotations-1.16/javaagent/*) continue ;; - instrumentation/opentelemetry-instrumentation-api/javaagent/*) continue ;; esac fi @@ -115,7 +122,6 @@ check_source_set() { javaagent:jsf-common-jakarta) ;; javaagent:jsf-common-javax) ;; javaagent:methods) ;; - javaagent:opentelemetry-instrumentation-api) ;; javaagent:rmi) ;; javaagent:runtime-telemetry) ;; javaagent:servlet-common) ;; diff --git a/package-name-exceptions-plan.md b/package-name-exceptions-plan.md index 6f985fa5e39f..322a8ecf48b6 100644 --- a/package-name-exceptions-plan.md +++ b/package-name-exceptions-plan.md @@ -18,6 +18,7 @@ Updated on 2026-05-26 after PRs 27a, 27b, and the Spring testing-package alignme Updated again on 2026-05-26 after auditing remaining unversioned-allowlist entries against the documented base-version convention and planning PRs 29-30. Updated on 2026-05-28 after PRs 29 and 30 merged upstream together as #18854 and their `library:oshi`, `javaagent:oshi`, and `javaagent:elasticsearch-transport-common` allowlist entries were removed from the checker. Updated on 2026-06-02 after PR 17 merged upstream as #18772 (Akka/Scala forkjoin module renames), and after #18855 moved the `servlet-common` library internal package; both allowlist entries were removed from the checker. +Updated again on 2026-06-02 after deciding to keep the four self-instrumentation modules' historical packages and document them as self-instrumentation in the checker instead of renaming them (PR 14 / #18747 deferred). ## Goal @@ -146,7 +147,7 @@ For common-module package moves, search for downstream versioned modules importi ## Open Cleanup PRs -PR 14 is open as #18747. PR 22 (#18784) was closed without merging. Keep `.github/scripts/check-package-names.sh` and checker exception removals on `next` until cleanup PRs merge. +PR 14 (#18747) and PR 22 (#18784) were closed without merging. Keep `.github/scripts/check-package-names.sh` and checker exception removals on `next` until cleanup PRs merge. For JDK instrumentation modules, keep the leading `java` token in package paths. For example, `java-util-logging` maps to `io.opentelemetry.javaagent.instrumentation.java.util.logging`, while @@ -161,34 +162,36 @@ example, `payara-embedded-web:5.2020.2` maps to `payara-5.2020` and package suff would create noisy module names unless they identify a real boundary such as a muzzle range or sibling module split. -### PR 14: OpenTelemetry annotation and instrumentation API modules (open #18747) +### PR 14: OpenTelemetry annotation and instrumentation API modules (deferred, #18747 to be closed) Modules: +- `opentelemetry-api-1.0` - `opentelemetry-extension-annotations-1.0` - `opentelemetry-instrumentation-api` - `opentelemetry-instrumentation-annotations-1.16` -Expected package changes: - -- `io.opentelemetry.javaagent.instrumentation.extensionannotations.v1_0` -> `io.opentelemetry.javaagent.instrumentation.opentelemetry.extension.annotations.v1_0` -- `io.opentelemetry.javaagent.instrumentation.instrumentationapi` -> `io.opentelemetry.javaagent.instrumentation.opentelemetry.instrumentation.api` -- `io.opentelemetry.javaagent.instrumentation.instrumentationannotations.v1_16` -> `io.opentelemetry.javaagent.instrumentation.opentelemetry.instrumentation.annotations.v1_16` +Decision: do not rename these packages. The original proposal moved them under +`io.opentelemetry.javaagent.instrumentation.opentelemetry.*`, which adds an +`opentelemetry.opentelemetry` redundancy (and `instrumentation.instrumentation` for the API/annotations +modules) for no real navigation gain. These four are self-instrumentation modules: the agent +instruments OpenTelemetry's own code, so the convention that treats the first dash-separated module +token as the instrumented library's namespace does not meaningfully apply. -Notes: +Keep the existing packages and promote them in the checker from a generic "historical" wildcard to a +dedicated `self-instrumentation modules` case block with a comment that explains why the standard +convention is skipped. Current packages stay as: -- Around 30 changed Java files after the dependent Kotlin coroutines import is included. -- Reference audit found only local package declarations/imports for `opentelemetry-extension-annotations-1.0`. -- `opentelemetry-instrumentation-api` has local tests in `src/test` and `src/testOldServerSpan` that must move with the main package. -- Update dependent import(s) in `kotlinx-coroutines-1.0` for instrumentation annotations. -- `opentelemetry-instrumentation-api` still remains in the unversioned-module allowlist unless the module name changes; the PR removes only the broad historical package skip after merge. +- `opentelemetry-api-1.0` -> `io.opentelemetry.javaagent.instrumentation.opentelemetryapi[.*]` +- `opentelemetry-extension-annotations-1.0` -> `io.opentelemetry.javaagent.instrumentation.extensionannotations.v1_0` +- `opentelemetry-instrumentation-annotations-1.16` -> `io.opentelemetry.javaagent.instrumentation.instrumentationannotations.v1_16` +- `opentelemetry-instrumentation-api` -> `io.opentelemetry.javaagent.instrumentation.instrumentationapi` -Suggested verification: +The `javaagent:opentelemetry-instrumentation-api` unversioned-module allowlist entry was removed at +the same time because the self-instrumentation case block already short-circuits before the +unversioned check. -```bash -.github/scripts/check-package-names.sh -./gradlew :instrumentation:opentelemetry-extension-annotations-1.0:javaagent:test :instrumentation:opentelemetry-instrumentation-api:javaagent:test :instrumentation:opentelemetry-instrumentation-annotations-1.16:javaagent:test :instrumentation:kotlinx-coroutines:kotlinx-coroutines-1.0:javaagent:compileJava -``` +Close #18747 once this lands on `next`. ### PR 17: Akka and Scala forkjoin module/package names (merged #18772)