tessl/maven-net-bytebuddy--byte-buddy-agent

Byte Buddy Agent is a Java instrumentation agent library that provides convenient APIs for attaching Java agents to local or remote virtual machines.

—

Pending

Overview

Eval results

Files

Agent Installation

Name: tessl/maven-net-bytebuddy--byte-buddy-agent
Author: tessl

Core functionality for installing Java agents on the current JVM at runtime, providing access to the Instrumentation API for bytecode manipulation and class redefinition without requiring command-line agent specification.

Capabilities

Runtime Agent Installation

Install a Byte Buddy agent on the currently running JVM to enable runtime bytecode instrumentation. The agent provides access to the Java Instrumentation API for class redefinition and transformation.

/**
 * Installs an agent on the currently running Java virtual machine using the default attachment provider.
 * @return An instrumentation instance representing the currently running JVM
 * @throws IllegalStateException If the agent cannot be installed
 */
public static Instrumentation install();

/**
 * Installs an agent using the supplied attachment provider.
 * @param attachmentProvider The attachment provider to use for the installation
 * @return An instrumentation instance representing the currently running JVM
 * @throws IllegalStateException If the agent cannot be installed
 */
public static Instrumentation install(AttachmentProvider attachmentProvider);

/**
 * Installs an agent on the Java virtual machine resolved by the process provider.
 * @param processProvider The provider for the current JVM's process id
 * @return An instrumentation instance representing the currently running JVM
 * @throws IllegalStateException If the agent cannot be installed
 */
public static Instrumentation install(ProcessProvider processProvider);

/**
 * Installs an agent using the supplied attachment provider and process provider.
 * @param attachmentProvider The attachment provider to use for the installation
 * @param processProvider The provider for the current JVM's process id
 * @return An instrumentation instance representing the currently running JVM
 * @throws IllegalStateException If the agent cannot be installed
 */
public static synchronized Instrumentation install(AttachmentProvider attachmentProvider, ProcessProvider processProvider);

Instrumentation Access

Retrieve the Instrumentation instance from an already installed Byte Buddy agent. This method provides access to the JVM's instrumentation capabilities without reinstalling the agent.

/**
 * Looks up the Instrumentation instance of an installed Byte Buddy agent.
 * @return The Instrumentation instance provided by an installed Byte Buddy agent
 * @throws IllegalStateException If the Byte Buddy agent is not properly installed
 */
public static Instrumentation getInstrumentation();

Agent Hook Methods (Installer Class)

These methods are called by the JVM when the agent is loaded. They are part of the Java agent specification and should not be called directly by user code. These methods are located in the Installer class, not ByteBuddyAgent.

/**
 * Allows the installation of this agent via a command line argument.
 * @param arguments The unused agent arguments
 * @param instrumentation The instrumentation instance
 */
public static void premain(String arguments, Instrumentation instrumentation);

/**
 * Allows the installation of this agent via the attach API.
 * @param arguments The unused agent arguments  
 * @param instrumentation The instrumentation instance
 */
public static void agentmain(String arguments, Instrumentation instrumentation);

Usage Examples

Basic Installation

import net.bytebuddy.agent.ByteBuddyAgent;
import java.lang.instrument.Instrumentation;

// Install agent and get instrumentation
Instrumentation instrumentation = ByteBuddyAgent.install();

// Use instrumentation capabilities
Class<?>[] loadedClasses = instrumentation.getAllLoadedClasses();
boolean canRedefine = instrumentation.isRedefineClassesSupported();
boolean canRetransform = instrumentation.isRetransformClassesSupported();

System.out.println("Loaded classes: " + loadedClasses.length);
System.out.println("Can redefine: " + canRedefine);
System.out.println("Can retransform: " + canRetransform);

Custom Attachment Provider

import net.bytebuddy.agent.ByteBuddyAgent;
import net.bytebuddy.agent.ByteBuddyAgent.AttachmentProvider;

// Use a specific attachment provider
AttachmentProvider provider = AttachmentProvider.ForModularizedVm.INSTANCE;
Instrumentation instrumentation = ByteBuddyAgent.install(provider);

// Or use compound provider with custom strategy
AttachmentProvider customProvider = new AttachmentProvider.Compound(
    AttachmentProvider.ForModularizedVm.INSTANCE,
    AttachmentProvider.ForJ9Vm.INSTANCE
);
instrumentation = ByteBuddyAgent.install(customProvider);

Safe Installation Check

import net.bytebuddy.agent.ByteBuddyAgent;
import java.lang.instrument.Instrumentation;

try {
    // Try to get existing instrumentation first
    Instrumentation instrumentation = ByteBuddyAgent.getInstrumentation();
    System.out.println("Agent already installed");
} catch (IllegalStateException e) {
    // Install agent if not already present
    System.out.println("Installing agent...");
    Instrumentation instrumentation = ByteBuddyAgent.install();
    System.out.println("Agent installed successfully");
}

JVM Compatibility

The runtime installation of a Java agent is supported for:

Java 9+: Uses the jdk.attach module when available (typically JDK distributions)
Java 8 and earlier: Requires tools.jar from JDK installations (HotSpot, OpenJDK, IBM J9)
Linux systems: Optional JNA-based Unix socket emulation when JDK attachment is unavailable
All platforms: Automatic fallback through multiple attachment provider strategies

Important Notes

Computation-heavy operation: Installation is expensive and cached after first success
Synchronization required: Installation method is synchronized to prevent race conditions
Security permissions: Requires net.bytebuddy.agent.getInstrumentation runtime permission when security manager is active
JDK requirement: Most attachment mechanisms require JDK (not JRE) distributions
Same-user limitation: Can only attach to processes running under the same operating system user

Install with Tessl CLI

npx tessl i tessl/maven-net-bytebuddy--byte-buddy-agent

docs

agent-attachment.md

agent-installation.md

tessl/maven-net-bytebuddy--byte-buddy-agent