feat: provided-style extensions and manifest-libs by jbachorik · Pull Request #791 · btraceio/btrace

jbachorik · 2026-01-13T16:21:12Z

Summary

This PR introduces provided-style extensions and fat agent deployment for BTrace, enabling application class tracing without classpath pollution and single-JAR deployment for distributed environments.

Features

Provided-Style Extensions

Application class tracing without classpath injection - Access classes loaded by application classloader through reflection
Runtime class discovery - ClassLoadingUtil loads classes from application context at trace time
Safe method handles - MethodHandleCache provides efficient, cached reflective access
Manifest-driven library management - New declarative approach replaces error-prone libs= parameter

Embedded Extensions & Fat Agent

Single-JAR deployment - Bundle agent + extensions into one JAR for Spark/Hadoop/Kubernetes
ClassDataLoader - Runtime loading of impl classes from .classdata resources
EmbeddedExtensionRepository - Discovers extensions from JAR manifest
Gradle Plugin (org.openjdk.btrace.fat-agent) - Auto-discovers extensions, supports project/maven/file sources
Maven Plugin (btrace-maven-plugin) - Equivalent functionality for Maven users

Bug Fixes

Bootstrap classloader NPE in Main and EmbeddedExtensionRepository
Probe listing after disconnect and test isolation
Thread retransform after startup scripts for early hooks
Java 8 compatibility (List.of → Collections.emptyList)

Documentation

Document	Description
Fat Agent Plugin Architecture	Single-JAR deployment design
Provided-Style Extensions	API on bootstrap, impl via TCCL
Migration Guide	Migrating from deprecated libs/profiles
Extension Development Guide	Building extensions
Gradle Plugin README	Both extension and fat-agent plugins

Example Extensions

btrace-spark - Trace Spark job lifecycle
btrace-hadoop - Trace Hadoop file operations

Usage

Fat Agent (Gradle)

plugins { id 'org.openjdk.btrace.fat-agent' }
btraceFatAgent {
    embedExtensions {
        project(':btrace-metrics')
        maven('io.btrace:btrace-statsd:2.3.0')
    }
}

Fat Agent (Maven)

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

Breaking Changes

libs= and profiles= deprecated (removal planned N+2)

🤖 Generated with Claude Code

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:

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.
Review Locally: Clone the repository and check out the branch locally. This allows you to review the changes using your preferred tools and environment.
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.
Automated Tools: Use automated code review tools and linters to catch common issues and enforce coding standards.
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.

…ibs deprecation; provided-style helpers; examples; tests\n\n- agent: manifest-driven libs (flagged), centralized classpath append with dedup + diagnostics; deprecate libs (debug log); add single-jar system CL escape hatch; test knob scoped to manifest-libs\n- client: pass-through of btrace.* props to agent using $ system props\n- extension: add ClassLoadingUtil and MethodHandleCache for provided-style extensions\n- examples: add btrace-extensions/examples/{btrace-spark,btrace-hadoop} with README\n- docs: research + provided-style guide + migration + examples index; README deprecation note\n- tests: add ManifestLibsTests; gradle knob for btrace.test.skipLibs\n\nBREAKING CHANGE: libs/profiles deprecated with planned removal after N+2; prefer extensions

- Proactively retransform java.lang.Thread after startup scripts load - Move initExtensions() after transformer is installed - Add delay in RuntimeTest to allow traced app output after ready marker 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…ation - Add disconnecting flag to RemoteClient for immediate probe visibility - Skip loadAgent when agent already running (check btrace.port) - Add try-finally cleanup in tests to prevent port conflicts 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

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

btrace-agent/src/main/java/org/openjdk/btrace/agent/AgentManifestLibs.java

Copilot · 2026-01-13T16:35:32Z

btrace-agent/src/main/java/org/openjdk/btrace/agent/AgentManifestLibs.java

+    Manifest mf = readManifest(anchor);
+    if (mf == null) {
+      if (log.isDebugEnabled()) log.debug("No manifest found for agent; skipping manifest libs");
+      return new ResolvedLibs(List.of(), List.of());


The code uses List.of() which was introduced in Java 9, but the project targets Java 8. This will cause a compilation error. Use Collections.emptyList() or Arrays.asList() instead for Java 8 compatibility.

@copilot open a new pull request to apply changes based on this feedback

btrace-extension/src/main/java/org/openjdk/btrace/extension/util/ClassLoadingUtil.java

btrace-agent/src/main/java/org/openjdk/btrace/agent/Main.java

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot · 2026-01-13T16:37:28Z

@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.

…il/ClassLoadingUtil.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot · 2026-01-13T16:37:32Z

@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 · 2026-01-13T16:37:45Z

@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.

…usion Co-authored-by: jbachorik <738413+jbachorik@users.noreply.github.com>

… compatibility Co-authored-by: jbachorik <738413+jbachorik@users.noreply.github.com>

- Add ExtensionConfigurator interface for environment-aware probe selection - Add ProbeConfiguration and RuntimeEnvironment classes - Add ClassDataLoader for loading .classdata resources (dd-trace pattern) - Add EmbeddedExtensionRepository for discovering embedded extensions - Extend ExtensionDescriptorDTO with embedded, resourceBasePath, configuratorClass, bundledProbes fields - Register EmbeddedExtensionRepository in ExtensionLoader (lowest priority) - Handle embedded extensions in ExtensionLoaderImpl via ClassDataLoader 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- gradle: BTraceFatAgentPlugin with auto-discovery, project/maven/file sources - maven: btrace-maven-plugin with fat-agent goal (Gradle-built module) - fix: bootstrap classloader NPE in Main and EmbeddedExtensionRepository - docs: fat-agent-plugin architecture, getting started, migration guide 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

btrace-maven-plugin/src/main/java/org/openjdk/btrace/maven/FatAgentMojo.java

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add Zip Slip protection in FatAgentMojo (path traversal prevention) - Add extension ID validation to prevent path traversal attacks - Add bytecode validation in ClassDataLoader (magic number check) - Add class name validation for services and configurators - Validate ProbeConfiguration.setOutput() throws on invalid values - Improve ClassFilter documentation for sensitive method filtering - Add AgentManifestLibsTest (27 tests) - Add BTraceFatAgentPluginTest using Gradle TestKit (10 tests) - Add FatAgentMojoTest (26 tests) - Add SecurityValidationTest (17 tests) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

...e-extension/src/main/java/org/openjdk/btrace/extension/impl/EmbeddedExtensionRepository.java

jbachorik added the AI AI-generated code label Jan 13, 2026

reviewabot bot approved these changes Jan 13, 2026

View reviewed changes

jbachorik changed the title ~~fix(agent,client,tests): probe listing after disconnect and test isolation~~ feat: manifest-libs, provided-style extensions, permission removal, and fixes Jan 13, 2026

jbachorik changed the title ~~feat: manifest-libs, provided-style extensions, permission removal, and fixes~~ feat: provided-style extensions and manifest-libs Jan 13, 2026

jbachorik and others added 3 commits January 13, 2026 17:29

jbachorik force-pushed the jb/configurations branch from f5dd242 to 0062717 Compare January 13, 2026 16:29

jbachorik requested a review from Copilot January 13, 2026 16:29

Copilot started reviewing on behalf of jbachorik January 13, 2026 16:30 View session

Copilot AI reviewed Jan 13, 2026

View reviewed changes

Update btrace-agent/src/main/java/org/openjdk/btrace/agent/Main.java

ea9c8e9

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI mentioned this pull request Jan 13, 2026

fix(agent): replace List.of() with Collections.emptyList() for Java 8 compatibility #792

Merged

Update btrace-extension/src/main/java/org/openjdk/btrace/extension/ut…

807f457

…il/ClassLoadingUtil.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI mentioned this pull request Jan 13, 2026

fix(agent): replace List.of() with Collections.emptyList() for Java 8 compatibility #793

Merged

Copilot AI mentioned this pull request Jan 13, 2026

Rename ClassLoadingUtil.load(String, Object) to loadFromContext #794

Merged

Copilot AI and others added 4 commits January 14, 2026 09:55

Rename load(String, Object) to loadFromContext to avoid overload conf…

cd3ef50

…usion Co-authored-by: jbachorik <738413+jbachorik@users.noreply.github.com>

fix(agent): replace List.of() with Collections.emptyList() for Java 8…

a62169b

… compatibility Co-authored-by: jbachorik <738413+jbachorik@users.noreply.github.com>

github-advanced-security bot found potential problems Jan 16, 2026

View reviewed changes

jbachorik and others added 2 commits January 19, 2026 16:11

fix(instr): exclude JDK 25 Thread accessor methods from instrumentation

555d1e6

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

github-advanced-security bot found potential problems Jan 22, 2026

View reviewed changes

...e-extension/src/main/java/org/openjdk/btrace/extension/impl/EmbeddedExtensionRepository.java Dismissed Show dismissed Hide dismissed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: provided-style extensions and manifest-libs#791

feat: provided-style extensions and manifest-libs#791
jbachorik wants to merge 11 commits intodevelopfrom
jb/configurations

jbachorik commented Jan 13, 2026 •

edited

Loading

Uh oh!

reviewabot bot left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Jan 13, 2026

Uh oh!

jbachorik Jan 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Jan 13, 2026

Uh oh!

Copilot AI commented Jan 13, 2026

Uh oh!

Copilot AI commented Jan 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

jbachorik commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Features

Provided-Style Extensions

Embedded Extensions & Fat Agent

Bug Fixes

Documentation

Example Extensions

Usage

Fat Agent (Gradle)

Fat Agent (Maven)

Breaking Changes

Uh oh!

reviewabot bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

jbachorik Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Jan 13, 2026

Uh oh!

Copilot AI commented Jan 13, 2026

Uh oh!

Copilot AI commented Jan 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jbachorik commented Jan 13, 2026 •

edited

Loading