Plan Java package cleanup

Author: trask

.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
@@ -51,6 +48,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
@@ -60,6 +63,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 ;;
@@ -71,6 +75,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 ;;
@@ -106,11 +113,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) ;;
@@ -121,7 +126,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"
@@ -132,12 +136,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 "/<token>";
-    # 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

package-name-exceptions-plan.md

@@ -8,6 +8,11 @@ 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.
 
 ## Goal
 
@@ -19,7 +24,7 @@ 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. |
@@ -44,6 +49,8 @@ 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`.
 
 PRs 5-8 merged upstream as:
 
@@ -71,7 +78,13 @@ 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`.
+
 `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 +124,18 @@ 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, PR 22 is open as #18784, and PR 25 is open as #18788. 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 instead of including the patch. 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`. Users should be on the latest patch for a given minor line, and
+patch-level suffixes would create noisy module names without a meaningful compatibility boundary.
 
 ### PR 14: OpenTelemetry annotation and instrumentation API modules (open #18747)
 
@@ -189,16 +213,124 @@ Suggested verification:
 ./gradlew :instrumentation:opentelemetry-api:opentelemetry-api-1.0:javaagent:test
 ```
 
+### PR 22: Java util logging package
+
+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`.
+
+Suggested verification:
+
+```bash
+.github/scripts/check-package-names.sh
+./gradlew :instrumentation:java-util-logging:javaagent:test
+```
+
+### PR 25: Spring WebMVC common module name
+
+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 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 27: App-server and framework module names
+
+Modules:
+
+- `payara` -> `payara-5.2020`
+- `quarkus-resteasy-reactive` -> `quarkus-resteasy-reactive-1.11`
+- `tomcat-jdbc` -> `tomcat-jdbc-8.5`
+
+Expected package changes:
+
+- `io.opentelemetry.javaagent.instrumentation.payara` -> `io.opentelemetry.javaagent.instrumentation.payara.v5_2020`
+- `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:
+
+- These are module-name cleanups, not just package moves. Update `settings.gradle.kts`, instrumentation inventory/docs, FOSSA config, Gradle project references, package declarations, imports, and checker allowlist entries after merge.
+- Keep existing instrumentation names as compatibility aliases. For Quarkus RESTEasy Reactive, 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 `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`.
+- 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 :instrumentation:payara-5.2020:javaagent:test :instrumentation:quarkus-resteasy-reactive-1.11:javaagent:test :instrumentation:tomcat:tomcat-jdbc-8.5: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.
+- `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: `<library>-common` is for pure utility/abstraction code with no direct library version dependency, `<library>-common-<major.minor>` is for shared code that requires a minimum library version, and `<library>-common-<variant>` is for variants such as `javax`.
+    - `spring-webmvc-common` and the `spring-cloud-gateway-common` testing package decision are planned above as PRs 25-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 planned above as PR 27.
+  - 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