or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

agent-attachment.mdagent-installation.mdcross-platform.mdindex.mdvm-operations.md
tile.json

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.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/net.bytebuddy/byte-buddy-agent@1.17.x

To install, run

npx @tessl/cli install tessl/maven-net-bytebuddy--byte-buddy-agent@1.17.0

index.mddocs/

Byte Buddy Agent

The Byte Buddy agent provides convenient APIs for attaching Java agents to local or remote virtual machines. It offers runtime installation capabilities for Java agents without requiring command-line specification, supports multiple JVM implementations including HotSpot and OpenJ9, and provides cross-platform attachment mechanisms through JNA integration.

Package Information

  • Package Name: byte-buddy-agent
  • Package Type: Maven
  • Language: Java
  • Installation:
    • Maven: <dependency><groupId>net.bytebuddy</groupId><artifactId>byte-buddy-agent</artifactId><version>1.17.7</version></dependency>
    • Gradle: implementation 'net.bytebuddy:byte-buddy-agent:1.17.7'

Core Imports

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

For advanced usage:

import net.bytebuddy.agent.ByteBuddyAgent.AttachmentProvider;
import net.bytebuddy.agent.ByteBuddyAgent.ProcessProvider;
import net.bytebuddy.agent.VirtualMachine;
import net.bytebuddy.agent.Installer;

Basic Usage

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

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

// Use instrumentation for runtime class modification
Class<?>[] loadedClasses = instrumentation.getAllLoadedClasses();
boolean canRedefine = instrumentation.isRedefineClassesSupported();

// Attach agent JAR to remote process
File agentJar = new File("my-agent.jar");
String processId = "1234";
ByteBuddyAgent.attach(agentJar, processId);

// Attach agent with arguments
ByteBuddyAgent.attach(agentJar, processId, "agent-arguments");

Architecture

Byte Buddy Agent is built around several key components:

  • ByteBuddyAgent: Main API facade providing high-level agent installation and attachment methods
  • Installer: Agent entry-point class implementing premain/agentmain hooks required by Java agent specification
  • Attachment System: Pluggable providers supporting different JVM attachment mechanisms (tools.jar, modules, JNA)
  • Virtual Machine Abstraction: Cross-platform VM interaction layer supporting HotSpot, OpenJ9, and platform-specific communication protocols
  • Process Management: Process discovery and management utilities for cross-VM operations

This design enables runtime Java agent deployment across different JVM implementations and operating systems while providing a unified API for agent installation and VM attachment.

Capabilities

Agent Installation

Core functionality for installing Java agents on the current JVM at runtime. Provides access to the Instrumentation API for bytecode manipulation and class redefinition.

// Install agent on current JVM
public static Instrumentation install();
public static Instrumentation install(AttachmentProvider attachmentProvider);
public static Instrumentation install(ProcessProvider processProvider);
public static Instrumentation install(AttachmentProvider attachmentProvider, ProcessProvider processProvider);

// Get existing instrumentation instance
public static Instrumentation getInstrumentation();

Agent Installation

Agent Attachment

Remote attachment capabilities for deploying Java agents to other JVM processes. Supports both JAR-based agents and native agent libraries with flexible process targeting.

// Attach JAR agents to remote processes
public static void attach(File agentJar, String processId);
public static void attach(File agentJar, String processId, String argument);
public static void attach(File agentJar, ProcessProvider processProvider);
public static void attach(File agentJar, ProcessProvider processProvider, String argument);

// Attach native agents
public static void attachNative(File agentLibrary, String processId);
public static void attachNative(File agentLibrary, String processId, String argument);

Agent Attachment

Virtual Machine Operations

Low-level virtual machine interaction interface providing direct access to VM operations including property access, agent loading, and management agent control. Used internally by attachment mechanisms and available for advanced use cases.

// VM property access
Properties getSystemProperties() throws IOException;
Properties getAgentProperties() throws IOException;

// Agent loading operations  
void loadAgent(String jarFile) throws IOException;
void loadAgent(String jarFile, String argument) throws IOException;
void loadAgentPath(String path) throws IOException;
void loadAgentLibrary(String library) throws IOException;

// Management operations
void startManagementAgent(Properties properties) throws IOException;
String startLocalManagementAgent() throws IOException;
void detach() throws IOException;

Virtual Machine Operations

Cross-Platform Support

Platform-specific implementations and attachment providers enabling cross-JVM and cross-OS compatibility. Includes support for different attachment mechanisms, process management, and native integrations.

// Attachment provider interface
interface AttachmentProvider {
    Accessor attempt();
}

// Process provider interface  
interface ProcessProvider {
    String resolve();
}

// Pre-configured providers
AttachmentProvider DEFAULT = new Compound(/* multiple providers */);
ProcessProvider.ForCurrentVm INSTANCE = /* current JVM provider */;

Cross-Platform Support