feat: provided-style extensions and manifest-libs

[jbachorik]

Rationale

BTrace has historically relied on libs=<profile> and $BTRACE_HOME/btrace-libs/<profile>/{boot,system}/*.jar to make application APIs (Spark, Hadoop, Kafka, …) visible to probes. That model has three structural problems:

• Classpath pollution. Profile JARs are appended to the bootstrap and system class loaders, which is highly privileged, conflicts with application shading, and cannot be isolated per probe.
• Fragile packaging. Resolution is heuristic (hardcoded agent-JAR name, URL string slicing, per-OS quirks). Renaming, JPMS, or non-filesystem deployments break it.
• Doesn't ship. Spark drivers/executors, Hadoop containers, and Kubernetes pods don't have a shared $BTRACE_HOME with a matching profile layout. Users end up with custom init containers, sidecars, or wrapper scripts just to deliver one extra JAR.

This PR introduces two complementary mechanisms to fix this: provided-style extensions (APIs on bootstrap, implementation reflective and isolated) and fat agents (a single JAR containing the agent plus embedded extensions, built via a Gradle or Maven plugin).

Usability Improvements

• Single-JAR deployment. java -javaagent:btrace-agent-fat.jar is now enough for Spark/Hadoop/K8s — no $BTRACE_HOME, no profile directory, no sidecars.
• No more classpath injection. Provided-style extensions keep only minimal API types on bootstrap; the impl lives in an isolated extension class loader and resolves app types via TCCL. Application shading and version conflicts stop being BTrace's problem.
• Build-time tooling. New Gradle plugins (org.openjdk.btrace.extension, org.openjdk.btrace.fat-agent) and a btrace-maven-plugin handle API/impl split, manifest metadata, permission scanning, relocations, and multi-project auto-discovery.
• Declarative, manifest-driven libs. The legacy libs= heuristic is replaced by explicit manifest attributes (BTrace-Boot-Libs, BTrace-System-Libs, BTrace-Embedded-Extensions) with deduplication, validation, and diagnostics.
• Helpers for writing adapters. ClassLoadingUtil (TCCL, service loading, scoped context) and MethodHandleCache (cached reflective handles) remove most of the boilerplate from reflective probes.
• Working examples. btrace-extensions/examples/btrace-spark and btrace-extensions/examples/btrace-hadoop demonstrate the pattern end-to-end.

Quick Start

1. Build a fat agent with Gradle

plugins {
    id 'org.openjdk.btrace.fat-agent' version "${btraceVersion}"
}

btraceFatAgent {
    baseName = 'my-btrace-agent'
    embedExtensions {
        project(':my-spark-extension')              // multi-project
        maven('io.btrace:btrace-metrics:2.3.0')     // external
    }
}

./gradlew fatAgentJar
# -> build/libs/my-btrace-agent.jar

2. Attach it

java -javaagent:/path/to/my-btrace-agent.jar=debug=true,port=2020 -jar your-app.jar

Embedded extensions are discovered automatically from the JAR manifest — no $BTRACE_HOME required.

3. (Optional) Write a provided-style extension

API module (ships to bootstrap, pure interfaces / value types):

public interface SparkApi {
    void onJobStart(Object jobStartEvent);
}

Impl module (isolated class loader, reflective against app classes):

public final class SparkApiImpl implements SparkApi {
    private final MethodHandleCache mh = new MethodHandleCache();

    public void onJobStart(Object evt) {
        ClassLoadingUtil.withDefiningLoader(evt, () -> {
            Class<?> cls = ClassLoadingUtil.loadFromContext(
                "org.apache.spark.scheduler.SparkListenerJobStart", evt);
            int jobId = (int) mh.findVirtual(cls, "jobId", int.class).invoke(evt);
            // emit metrics / logs...
            return null;
        });
    }
}

See docs/architecture/provided-style-extensions.md and docs/architecture/migrating-from-libs-profiles.md for the full walk-through.

Maven equivalent

<plugin>
  <groupId>org.openjdk.btrace</groupId>
  <artifactId>btrace-maven-plugin</artifactId>
  <configuration>
    <extensions>
      <extension>io.btrace:btrace-metrics:${btrace.version}</extension>
    </extensions>
  </configuration>
</plugin>

Drawbacks and Remaining Issues

• No hot-reload for embedded extensions. Updating an extension in a fat agent requires rebuilding the JAR and restarting the target JVM.
• Larger artifact. A fat agent is strictly bigger than the minimal agent; users who ship BTrace through a managed $BTRACE_HOME don't benefit from embedding.
• More boilerplate than profiles. Provided-style requires an explicit API/impl split and reflective adapters. It's a deliberate trade-off (isolation + portability) but the migration cost from existing profile-based setups is real — the migration guide documents it but cannot eliminate it.
• Reflective cost at the hot path. Even with MethodHandleCache, an adapter call is more expensive than a direct invocation. Most tracing workloads won't notice, but very high-frequency probes should be profiled.
• libs= / profiles= still accepted. They are deprecated and log a warning; planned removal is N+2 minor releases. Until then, both code paths coexist and users can mix them (not recommended).
• Escape hatch kept for now. -Dbtrace.system.appendJar=/abs/path/lib.jar (requires -Dbtrace.trusted=true) exists for cases where immediate migration is impossible. It's restricted to BTRACE_HOME by default and is explicitly discouraged — expect it to be removed together with libs=.
• Fat-agent plugin API surface. The Gradle/Maven plugins are new; DSL and task names may still shift before the first stable release cut.

Documentation

Document	Description
Provided-Style Extensions	API on bootstrap, impl via TCCL
Fat Agent Plugin Architecture	Single-JAR deployment design
Migrating from libs/profiles	Step-by-step migration guide
Extension Development Guide	Building extensions from scratch
Gradle Plugin README	Extension + fat-agent plugins

Breaking Changes

• libs= and profiles= are deprecated. Planned removal: N+2 minor releases. A runtime warning is emitted on use.

🤖 Generated with Claude Code

---

This change is

[reviewabot]

It looks like the pull request diff is too large to be displayed directly on GitHub. Here are some general recommendations for handling large pull requests:

1. Break Down the PR: Try to break down the pull request into smaller, more manageable chunks. This makes it easier to review and ensures that each part can be thoroughly checked.

2. Review Locally: Clone the repository and check out the branch locally. This allows you to review the changes using your preferred tools and environment.

3. Focus on Key Areas: Identify and focus on the key areas of the code that are most critical or have the highest impact. This can help prioritize the review process.

4. Automated Tools: Use automated code review tools and linters to catch common issues and enforce coding standards.

5. Collaborate with the Team: If possible, involve multiple reviewers to share the workload and get different perspectives on the changes.

If you can provide a smaller subset of the changes or specific files that need review, I'd be happy to help with a more detailed review.

[Copilot]

Pull request overview

This PR introduces provided-style extensions and manifest-driven library loading to enable tracing application-specific classes without polluting the application classpath. The core innovation is using reflection and object hand-off patterns to access application classes at runtime, keeping BTrace isolated.

Changes:

• New extension utilities (ClassLoadingUtil, MethodHandleCache) for runtime class resolution and reflective method access
• Manifest-driven library path resolution (AgentManifestLibs) with security restrictions to BTRACE_HOME
• Refactored agent classpath processing with deduplication and better error handling
• Example extensions for Spark and Hadoop demonstrating the provided-style pattern
• Comprehensive architecture documentation and migration guides
• Deprecation of libs/profiles mechanism with escape hatch for edge cases

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
settings.gradle	Added example extension modules (btrace-spark, btrace-hadoop)
integration-tests/src/test/java/tests/RuntimeTest.java	Fixed debug flag insertion and added timing delays for test stability
integration-tests/src/test/java/tests/ManifestLibsTests.java	New test suite for manifest-libs feature
integration-tests/src/test/java/tests/BTraceFunctionalTests.java	Improved unattended test with better synchronization and cleanup
integration-tests/build.gradle	Added test property for skipping preconfigured libs
docs/examples/README.md	Guide for building and configuring provided-style extension examples
docs/architecture/provided-style-extensions.md	Comprehensive guide on provided-style extension pattern
docs/architecture/migrating-from-libs-profiles.md	Migration guide from deprecated libs/profiles to extensions
docs/architecture/agent-manifest-libs.md	Design document for manifest-driven library loading
compile.log	Build artifact that should not be committed
btrace-extensions/examples/btrace-spark/*	Example Spark extension with API and provided-style implementation
btrace-extensions/examples/btrace-hadoop/*	Example Hadoop extension with API and provided-style implementation
btrace-extension/src/main/java/org/openjdk/btrace/extension/util/MethodHandleCache.java	Cache for reflective method handles to reduce lookup overhead
btrace-extension/src/main/java/org/openjdk/btrace/extension/util/ClassLoadingUtil.java	Helper utilities for TCCL-based class loading and service discovery
btrace-client/src/main/java/org/openjdk/btrace/client/Main.java	Removed exit hooks for list-only operations to prevent unintended probe removal
btrace-client/src/main/java/org/openjdk/btrace/client/Client.java	Added agent-already-running detection and system property pass-through
btrace-agent/src/main/java/org/openjdk/btrace/agent/RemoteClient.java	Improved disconnect handling with disconnecting flag
btrace-agent/src/main/java/org/openjdk/btrace/agent/Main.java	Refactored classpath processing with manifest support, deduplication, and escape hatch for single-jar injection
btrace-agent/src/main/java/org/openjdk/btrace/agent/AgentManifestLibs.java	New utility for manifest-driven library resolution with security checks
README.md	Added deprecation notice for libs/profiles with migration guidance

[Copilot]

@jbachorik I've opened a new pull request, #792, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

@jbachorik I've opened a new pull request, #793, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

@jbachorik I've opened a new pull request, #794, to work on those changes. Once the pull request is ready, I'll request review from you.

[jbachorik]

ReDoS in EmbeddedExtensionRepository.isValidClassName — fixed in dbd3964

Addresses the CodeQL ReDoS alert (js/redos, alert #15) on the class-name validation pattern.

The regex had three ambiguities the engine could explore:

1. Inner char class [a-zA-Z0-9_$]* inside the .-group and the $-group both allowed $
2. The outer (\$[a-zA-Z_][a-zA-Z0-9_$]*)* group also started with $
3. All three repetitions were standard (backtracking) *

On an input like A$A$A$A…! (trailing mismatch) this produced exponential partition searching before failing.

Fix: switch the three repetitions to possessive quantifiers (*+). Each commit is final, so the engine cannot re-partition $-separated tail segments. Match semantics are preserved for every accepted and rejected input in SecurityValidationTest > Class name validation (valid / invalid / special-chars / code-injection / null-and-empty — all green).

Stress-check: A$A × 30 + ! now rejects in ~0 ms instead of hanging.

Items 1–5 of the earlier review (unused Enumeration import, redundant homeStr null check, three zip-slip sites in FatAgentMojo) were already addressed in prior commits on this branch.

[Copilot]

Pull request overview

Copilot reviewed 54 out of 55 changed files in this pull request and generated 12 comments.

[jbachorik]

Review-fix commits pushed

Addressed 17 of 23 accepted findings from the muse chorus review (session review-20260421-095158), in two commits:

• 84576bfa — fix: address review findings in PR feat: provided-style extensions and manifest-libs #791 (7 files, 15 findings)
• 21c59452 — docs: document ordering and null-classloader contracts (2 files, 2 findings)

Highlights

• Main.java: bootstrap/system jar append failures now log at warn; Thread.class retransform failure warns; explicit warn when both deprecated libs= and manifest-libs are in use; FIXME marker on loadBundledProbes() placeholder; comment clarifying Thread-class retransform ordering is intentional.
• ClassDataLoader.findClass: IOException cause is preserved when converting to ClassNotFoundException.
• MethodHandleCache: negative cache removed — failed lookups no longer permanently poison the cache.
• FatAgentMojo.createJar: Files.walk() now in try-with-resources.
• AgentManifestLibs: skip/validation log levels upgraded (DEBUG → INFO / WARN) so operators see non-existent / invalid entries.
• EmbeddedExtensionRepository.readManifestIndex: iterates all BTrace-Embedded-Extensions manifests instead of returning on first match; dedupes extension IDs and warns on duplicates. Null-classloader handling now explicit via BOOTSTRAP_SENTINEL + isBootstrap flag.
• ClassFilter: expanded rationale comment for JDK-25 Thread-method exclusions — kept getUncaughtExceptionHandler in the exclusion set because probes on the getter could re-enter the dispatcher path.

Verification

• ./gradlew :btrace-agent:compileJava :btrace-extension:compileJava :btrace-instr:compileJava :btrace-maven-plugin:compileJava — green
• ./gradlew spotlessCheck — green
• Unit tests: 930/930 pass (920 module + 10 gradle-plugin), 0 failures, 0 errors

Deferred for follow-up

6 findings were not addressed in these commits because they need architectural or design decisions best handled separately:

1. ClassDataLoader.java:98 — add ProtectionDomain/CodeSource on defineClass. Planner concertato recommended deferring: post-JDK 17 removal of SecurityManager makes a correct ProtectionDomain non-trivial.
2. FatAgentMojo.java:~6055 — extract duplicated isValidExtensionId logic. Needs a module-boundary decision (new btrace-plugin-common vs. intentional duplication).
3. FatAgentMojoTest.java:189 — replace "no-behavior-assertion" tests with concrete assertions.
4. SecurityValidationTest.java:3392 — replace mock-based bytecode magic test with a real ClassDataLoader integration test.
5. BTraceFatAgentPluginTest.java:~5117 — test duplication (phantom line numbers — requires locating the actual duplicated test code).
6. BTraceFatAgentPlugin.groovy:~4722 — unify Gradle and Maven plugin extension-staging logic. Planner concertato flagged as out of scope for this PR.

The user also dismissed two earlier findings with explicit rationale: ClassDataLoader double-check-lock (intentional lockfree fast path) and ClassDataLoader:2468 concurrency (assumed harmless race, to be validated).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Copilot reviewed 54 out of 55 changed files in this pull request and generated 4 comments.

[Copilot]

debugBTrace inserts -v at index 4, which places it between -cp and the eventsClassPath value. That changes the command to ... Loader -cp -v <eventsClassPath> ..., so -v is interpreted as the classpath value and breaks argument parsing. Insert -v immediately after the main class (org.openjdk.btrace.boot.Loader) instead (same position as the previous conditional element).

[jbachorik]

Addressed in commit 6295796. Counting the list literal: index 0=javaHome+"/bin/java", 1=-cp, 2=cp, 3=org.openjdk.btrace.boot.Loader, 4=-cp. argVals.add(4, "-v") inserts at index 4, shifting the existing -cp to index 5 — so -v lands immediately after the Loader main class and before the -cp/eventsClassPath pair, exactly as the reviewer requested. Argument parsing is no longer broken.

[Copilot]

These system property values are appended into a comma-separated agentArgs string without any escaping. If any value contains a comma (notably file paths on some systems), it will be split into multiple agent arguments and silently misconfigure the agent. Consider rejecting/escaping commas in values (or switching to a mechanism that doesn't use comma as a delimiter for these pass-through properties).

Suggested change

	if (manifestLibs != null && !manifestLibs.isEmpty()) {
	agentArgs += "," + "$btrace.feature.manifestLibs" + "=" + manifestLibs;
	}
	if (sysAppendJar != null && !sysAppendJar.isEmpty()) {
	agentArgs += "," + "$btrace.system.appendJar" + "=" + sysAppendJar;
	}
	if (allowExternalLibs != null && !allowExternalLibs.isEmpty()) {
	agentArgs += "," + "$btrace.allowExternalLibs" + "=" + allowExternalLibs;
	}
	if (testSkipLibs != null && !testSkipLibs.isEmpty()) {
	if (manifestLibs != null && !manifestLibs.isEmpty()) {
	if (manifestLibs.indexOf(',') >= 0) {
	throw new IllegalArgumentException(
	"System property btrace.feature.manifestLibs must not contain ','");
	}
	agentArgs += "," + "$btrace.feature.manifestLibs" + "=" + manifestLibs;
	}
	if (sysAppendJar != null && !sysAppendJar.isEmpty()) {
	if (sysAppendJar.indexOf(',') >= 0) {
	throw new IllegalArgumentException(
	"System property btrace.system.appendJar must not contain ','");
	}
	agentArgs += "," + "$btrace.system.appendJar" + "=" + sysAppendJar;
	}
	if (allowExternalLibs != null && !allowExternalLibs.isEmpty()) {
	if (allowExternalLibs.indexOf(',') >= 0) {
	throw new IllegalArgumentException(
	"System property btrace.allowExternalLibs must not contain ','");
	}
	agentArgs += "," + "$btrace.allowExternalLibs" + "=" + allowExternalLibs;
	}
	if (testSkipLibs != null && !testSkipLibs.isEmpty()) {
	if (testSkipLibs.indexOf(',') >= 0) {
	throw new IllegalArgumentException(
	"System property btrace.test.skipLibs must not contain ','");
	}

[jbachorik]

Addressed — Agent arg string uses ',' as delimiter; a stray comma in any pass-through property silently splits into extra args. Fail-fast with IllegalArgumentException is the minimally invasive fix that surfaces the misconfiguration rather than letting the agent read a mangled property.

[Copilot]

The anchor in this link contains an embedded space (entrye xit), which will break the Markdown link target. Fix the anchor text to match the actual section id in QuickReference (and keep it space-free).

[jbachorik]

Addressed — QuickReference.md has a section ### Pattern 1: Method Entry/Exit Timing which GitHub slugifies to pattern-1-method-entryexit-timing; the current README anchor contains a stray space (entrye xit) that will never match.

[Copilot]

This subproject sets sourceCompatibility/targetCompatibility to Java 11, while the repo-wide build defaults (via common.gradle) compile modules for Java 8. If this plugin is meant to be consumed by Java-8 users, compiling it to 11 will be a compatibility break; if it intentionally requires 11, it should be clearly isolated from the Java-8 toolchain assumptions and documented. Please align the target level with the repo convention or explicitly justify/enforce the higher requirement.

[jbachorik]

Intentional and isolated. The Maven Plugin API 3.9.x (declared at build.gradle:18-20) itself requires Java 11+ at runtime — downstream consumers who can run Maven 3.9 already have a Java-11 toolchain. The rest of the BTrace agent/client/runtime retains sourceCompatibility = 8 in common.gradle; only this subproject bumps to 11 because it is a Maven plugin, not a component shipped into target JVMs. No Java-8 user of the BTrace agent is affected.

[Copilot]

Pull request overview

Copilot reviewed 54 out of 55 changed files in this pull request and generated no new comments.