Class ByteBuddyAgent
The Byte Buddy agent provides a JVM Instrumentation
in order to allow Byte Buddy the
redefinition of already loaded classes. An agent must normally be specified via the command line via the
javaagent
parameter. As an argument to this parameter, one must specify the location of this agent's jar
file such as for example in
java -javaagent:byte-buddy-agent.jar -jar app.jar
Note: The runtime installation of a Java agent is not possible on all JVMs. See the documentation for
install()
for details on JVMs that are supported out of the box.
Important: This class's name is known to the Byte Buddy main application and must not be altered.
Note: Byte Buddy does not execute code using an java.security.AccessController
. If a security manager
is present, the user of this class is responsible for assuring any required privileges. To read an
Instrumentation
, the net.bytebuddy.agent.getInstrumentation runtime permission is required.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static interface
An agent provider is responsible for handling and providing the jar file of an agent that is being attached.static interface
An attachment provider is responsible for making the Java attachment API available.protected static interface
An attachment evaluator is responsible for deciding if an agent can be attached from the current process.static interface
A process provider is responsible for providing the process id of the current VM. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final String
The manifest property specifying the agent class.private static final String
The naming prefix of all artifacts for an attacher jar.private static final ByteBuddyAgent.AttachmentTypeEvaluator
The attachment type evaluator to be used for determining if an attachment requires an external process.private static final ClassLoader
Representation of the bootstrapClassLoader
.private static final int
The size of the buffer for copying the agent installer file into another jar.private static final String
The manifest property specifying the can redefine property.private static final String
The manifest property specifying the can retransform property.private static final String
The manifest property specifying the can set native method prefix property.private static final File
Represents a failed attempt to self-resolve a jar file location.private static final String
The file extension for a class file.private static final String
The class path argument to specify the class path elements.private static final int
Convenience indices for reading and writing to the buffer to make the code more readable.private static final String
Represents thefile
URL protocol.private static final String
The name of the method for reading the installer's instrumentation.private static final String
The file extension for a jar file.private static final String
The Java property denoting the Java home directory.static final String
Indicates that the agent should not resolve its own code location for a self-attachment.private static final String
The manifest property value for the manifest version.private static final String
The Java property denoting the operating system name.private static final int
Convenience indices for reading and writing to the buffer to make the code more readable.private static final int
The status code expected as a result of a successful attachment.private static final Instrumentation
An indicator variable to express that no instrumentation is available.private static final String
Represents a no-op argument for a dynamic agent attachment. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
The agent provides onlystatic
utility methods and should not be instantiated. -
Method Summary
Modifier and TypeMethodDescriptionstatic void
Attaches the given agent Jar on the target process which must be a virtual machine process.static void
Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach
(File agentJar, String processId, String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach
(File agentJar, String processId, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach
(File agentJar, ByteBuddyAgent.ProcessProvider processProvider) Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach
(File agentJar, ByteBuddyAgent.ProcessProvider processProvider, String argument) Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach
(File agentJar, ByteBuddyAgent.ProcessProvider processProvider, String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach
(File agentJar, ByteBuddyAgent.ProcessProvider processProvider, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attachNative
(File agentLibrary, String processId) Attaches the given agent library on the target process which must be a virtual machine process.static void
attachNative
(File agentLibrary, String processId, String argument) Attaches the given agent library on the target process which must be a virtual machine process.static void
attachNative
(File agentLibrary, String processId, String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent library on the target process which must be a virtual machine process.static void
attachNative
(File agentLibrary, String processId, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent library on the target process which must be a virtual machine process.static void
attachNative
(File agentLibrary, ByteBuddyAgent.ProcessProvider processProvider) Attaches the given agent library on the target process which must be a virtual machine process.static void
attachNative
(File agentLibrary, ByteBuddyAgent.ProcessProvider processProvider, String argument) Attaches the given agent library on the target process which must be a virtual machine process.static void
attachNative
(File agentLibrary, ByteBuddyAgent.ProcessProvider processProvider, String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent library on the target process which must be a virtual machine process.static void
attachNative
(File agentLibrary, ByteBuddyAgent.ProcessProvider processProvider, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent library on the target process which must be a virtual machine process.private static Instrumentation
Performs the actual lookup of theInstrumentation
from an installed Byte Buddy agent and returns the instance, or returnsnull
if not present.private static <T> T
doPrivileged
(PrivilegedAction<T> action) A proxy forjava.security.AccessController#doPrivileged
that is activated if available.static Instrumentation
Looks up theInstrumentation
instance of an installed Byte Buddy agent.static Instrumentation
install()
Installs an agent on the currently running Java virtual machine.static Instrumentation
install
(ByteBuddyAgent.AttachmentProvider attachmentProvider) Installs an agent on the currently running Java virtual machine using the supplied attachment provider.private static void
install
(ByteBuddyAgent.AttachmentProvider attachmentProvider, String processId, String argument, ByteBuddyAgent.AgentProvider agentProvider, boolean isNative) Installs a Java agent on a target VM.static Instrumentation
install
(ByteBuddyAgent.AttachmentProvider attachmentProvider, ByteBuddyAgent.ProcessProvider processProvider) Installs an agent on the currently running Java virtual machine using the supplied attachment provider and process provider.static Instrumentation
install
(ByteBuddyAgent.ProcessProvider processProvider) Installs an agent on the Java virtual machine resolved by the process provider.private static void
installExternal
(ByteBuddyAgent.AttachmentProvider.Accessor.ExternalAttachment externalAttachment, String processId, File agent, boolean isNative, String argument) Installs a Java agent to the current VM via an external process.private static String
Quotes a value if it contains a white space.private static File
Attempts to resolve the location of theAttacher
class for a self-attachment.
-
Field Details
-
LATENT_RESOLVE
Indicates that the agent should not resolve its own code location for a self-attachment.- See Also:
-
AGENT_CLASS_PROPERTY
The manifest property specifying the agent class.- See Also:
-
CAN_REDEFINE_CLASSES_PROPERTY
The manifest property specifying the can redefine property.- See Also:
-
CAN_RETRANSFORM_CLASSES_PROPERTY
The manifest property specifying the can retransform property.- See Also:
-
CAN_SET_NATIVE_METHOD_PREFIX
The manifest property specifying the can set native method prefix property.- See Also:
-
MANIFEST_VERSION_VALUE
The manifest property value for the manifest version.- See Also:
-
BUFFER_SIZE
private static final int BUFFER_SIZEThe size of the buffer for copying the agent installer file into another jar.- See Also:
-
START_INDEX
private static final int START_INDEXConvenience indices for reading and writing to the buffer to make the code more readable.- See Also:
-
END_OF_FILE
private static final int END_OF_FILEConvenience indices for reading and writing to the buffer to make the code more readable.- See Also:
-
SUCCESSFUL_ATTACH
private static final int SUCCESSFUL_ATTACHThe status code expected as a result of a successful attachment.- See Also:
-
BOOTSTRAP_CLASS_LOADER
Representation of the bootstrapClassLoader
. -
WITHOUT_ARGUMENT
Represents a no-op argument for a dynamic agent attachment. -
ATTACHER_FILE_NAME
The naming prefix of all artifacts for an attacher jar.- See Also:
-
CLASS_FILE_EXTENSION
The file extension for a class file.- See Also:
-
JAR_FILE_EXTENSION
The file extension for a jar file.- See Also:
-
CLASS_PATH_ARGUMENT
The class path argument to specify the class path elements.- See Also:
-
JAVA_HOME
The Java property denoting the Java home directory.- See Also:
-
OS_NAME
The Java property denoting the operating system name.- See Also:
-
INSTRUMENTATION_METHOD
The name of the method for reading the installer's instrumentation.- See Also:
-
FILE_PROTOCOL
Represents thefile
URL protocol.- See Also:
-
UNAVAILABLE
An indicator variable to express that no instrumentation is available. -
CANNOT_SELF_RESOLVE
Represents a failed attempt to self-resolve a jar file location. -
ATTACHMENT_TYPE_EVALUATOR
The attachment type evaluator to be used for determining if an attachment requires an external process.
-
-
Constructor Details
-
ByteBuddyAgent
private ByteBuddyAgent()The agent provides onlystatic
utility methods and should not be instantiated.
-
-
Method Details
-
doPrivileged
A proxy forjava.security.AccessController#doPrivileged
that is activated if available.- Type Parameters:
T
- The type of the action's resolved value.- Parameters:
action
- The action to execute from a privileged context.- Returns:
- The action's resolved value.
-
getInstrumentation
Looks up the
Instrumentation
instance of an installed Byte Buddy agent. Note that this method implies reflective lookup and reflective invocation such that the returned value should be cached rather than calling this method several times.Note: This method throws an
IllegalStateException
If the Byte Buddy agent is not properly installed.- Returns:
- The
Instrumentation
instance which is provided by an installed Byte Buddy agent.
-
attach
Attaches the given agent Jar on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an
IllegalStateException
is thrown. The agent is not provided an argument.Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentJar
- The agent jar file.processId
- The target process id.
-
attach
Attaches the given agent Jar on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an
IllegalStateException
is thrown.Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentJar
- The agent jar file.processId
- The target process id.argument
- The argument to provide to the agent.
-
attach
public static void attach(File agentJar, String processId, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent Jar on the target process which must be a virtual machine process. This operation blocks until the attachment is complete. The agent is not provided an argument.
Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentJar
- The agent jar file.processId
- The target process id.attachmentProvider
- The attachment provider to use.
-
attach
public static void attach(File agentJar, String processId, @MaybeNull String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent Jar on the target process which must be a virtual machine process. This operation blocks until the attachment is complete.
Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentJar
- The agent jar file.processId
- The target process id.argument
- The argument to provide to the agent.attachmentProvider
- The attachment provider to use.
-
attach
Attaches the given agent Jar on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an
IllegalStateException
is thrown. The agent is not provided an argument.Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentJar
- The agent jar file.processProvider
- A provider of the target process id.
-
attach
public static void attach(File agentJar, ByteBuddyAgent.ProcessProvider processProvider, @MaybeNull String argument) Attaches the given agent Jar on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an
IllegalStateException
is thrown.Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentJar
- The agent jar file.processProvider
- A provider of the target process id.argument
- The argument to provide to the agent.
-
attach
public static void attach(File agentJar, ByteBuddyAgent.ProcessProvider processProvider, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent Jar on the target process which must be a virtual machine process. This operation blocks until the attachment is complete. The agent is not provided an argument.
Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentJar
- The agent jar file.processProvider
- A provider of the target process id.attachmentProvider
- The attachment provider to use.
-
attach
public static void attach(File agentJar, ByteBuddyAgent.ProcessProvider processProvider, @MaybeNull String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent Jar on the target process which must be a virtual machine process. This operation blocks until the attachment is complete.
Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentJar
- The agent jar file.processProvider
- A provider of the target process id.argument
- The argument to provide to the agent.attachmentProvider
- The attachment provider to use.
-
attachNative
Attaches the given agent library on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an
IllegalStateException
is thrown. The agent is not provided an argument.Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentLibrary
- The agent jar file.processId
- The target process id.
-
attachNative
Attaches the given agent library on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an
IllegalStateException
is thrown.Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentLibrary
- The agent library.processId
- The target process id.argument
- The argument to provide to the agent.
-
attachNative
public static void attachNative(File agentLibrary, String processId, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent library on the target process which must be a virtual machine process. This operation blocks until the attachment is complete. The agent is not provided an argument.
Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentLibrary
- The agent library.processId
- The target process id.attachmentProvider
- The attachment provider to use.
-
attachNative
public static void attachNative(File agentLibrary, String processId, @MaybeNull String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent library on the target process which must be a virtual machine process. This operation blocks until the attachment is complete.
Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentLibrary
- The agent library.processId
- The target process id.argument
- The argument to provide to the agent.attachmentProvider
- The attachment provider to use.
-
attachNative
Attaches the given agent library on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an
IllegalStateException
is thrown. The agent is not provided an argument.Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentLibrary
- The agent library.processProvider
- A provider of the target process id.
-
attachNative
public static void attachNative(File agentLibrary, ByteBuddyAgent.ProcessProvider processProvider, @MaybeNull String argument) Attaches the given agent library on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an
IllegalStateException
is thrown.Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentLibrary
- The agent library.processProvider
- A provider of the target process id.argument
- The argument to provide to the agent.
-
attachNative
public static void attachNative(File agentLibrary, ByteBuddyAgent.ProcessProvider processProvider, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent library on the target process which must be a virtual machine process. This operation blocks until the attachment is complete. The agent is not provided an argument.
Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentLibrary
- The agent library.processProvider
- A provider of the target process id.attachmentProvider
- The attachment provider to use.
-
attachNative
public static void attachNative(File agentLibrary, ByteBuddyAgent.ProcessProvider processProvider, @MaybeNull String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent library on the target process which must be a virtual machine process. This operation blocks until the attachment is complete.
Important: It is only possible to attach to processes that are executed by the same operating system user.
- Parameters:
agentLibrary
- The agent library.processProvider
- A provider of the target process id.argument
- The argument to provide to the agent.attachmentProvider
- The attachment provider to use.
-
install
Installs an agent on the currently running Java virtual machine. Unfortunately, this does not always work. The runtime installation of a Java agent is supported for:
- JVM version 9+: For Java VM of at least version 9, the attachment API was moved
into a module and the runtime installation is possible if the
jdk.attach
module is available to Byte Buddy which is typically only available for VMs shipped with a JDK. - OpenJDK / Oracle JDK / IBM J9 versions 8-: The installation for HotSpot is only
possible when bundled with a JDK and requires a
tools.jar
bundled with the VM which is typically only available for JDK-versions of the JVM. - When running Linux and including the optional junixsocket-native-common depedency, Byte Buddy emulates a Unix socket connection to attach to the target VM.
If an agent cannot be installed, an
IllegalStateException
is thrown.Important: This is a rather computation-heavy operation. Therefore, this operation is not repeated after an agent was successfully installed for the first time. Instead, the previous instrumentation instance is returned. However, invoking this method requires synchronization such that subsequently to an installation,
getInstrumentation()
should be invoked instead.- Returns:
- An instrumentation instance representing the currently running JVM.
- JVM version 9+: For Java VM of at least version 9, the attachment API was moved
into a module and the runtime installation is possible if the
-
install
Installs an agent on the currently running Java virtual machine using the supplied attachment provider.
If an agent cannot be installed, an
IllegalStateException
is thrown.Important: This is a rather computation-heavy operation. Therefore, this operation is not repeated after an agent was successfully installed for the first time. Instead, the previous instrumentation instance is returned. However, invoking this method requires synchronization such that subsequently to an installation,
getInstrumentation()
should be invoked instead.- Parameters:
attachmentProvider
- The attachment provider to use for the installation.- Returns:
- An instrumentation instance representing the currently running JVM.
-
install
Installs an agent on the Java virtual machine resolved by the process provider. Unfortunately, this does not always work. The runtime installation of a Java agent is supported for:
- JVM version 9+: For Java VM of at least version 9, the attachment API was moved
into a module and the runtime installation is possible if the
jdk.attach
module is available to Byte Buddy which is typically only available for VMs shipped with a JDK. - OpenJDK / Oracle JDK / IBM J9 versions 8-: The installation for HotSpot is only
possible when bundled with a JDK and requires a
tools.jar
bundled with the VM which is typically only available for JDK-versions of the JVM. - When running Linux and including the optional junixsocket-native-common depedency, Byte Buddy emulates a Unix socket connection to attach to the target VM.
If an agent cannot be installed, an
IllegalStateException
is thrown.- Parameters:
processProvider
- The provider for the current JVM's process id.- Returns:
- An instrumentation instance representing the currently running JVM.
- JVM version 9+: For Java VM of at least version 9, the attachment API was moved
into a module and the runtime installation is possible if the
-
install
public static Instrumentation install(ByteBuddyAgent.AttachmentProvider attachmentProvider, ByteBuddyAgent.ProcessProvider processProvider) Installs an agent on the currently running Java virtual machine using the supplied attachment provider and process provider.
If an agent cannot be installed, an
IllegalStateException
is thrown.- Parameters:
attachmentProvider
- The attachment provider to use for the installation.processProvider
- The provider for the current JVM's process id.- Returns:
- An instrumentation instance representing the currently running JVM.
-
install
private static void install(ByteBuddyAgent.AttachmentProvider attachmentProvider, String processId, @MaybeNull String argument, ByteBuddyAgent.AgentProvider agentProvider, boolean isNative) Installs a Java agent on a target VM.- Parameters:
attachmentProvider
- The attachment provider to use.processId
- The process id of the target JVM process.argument
- The argument to provide to the agent.agentProvider
- The agent provider for the agent jar or library.isNative
-true
if the agent is native.
-
installExternal
private static void installExternal(ByteBuddyAgent.AttachmentProvider.Accessor.ExternalAttachment externalAttachment, String processId, File agent, boolean isNative, @MaybeNull String argument) throws Exception Installs a Java agent to the current VM via an external process. This is typically required starting with OpenJDK 9 when thejdk.attach.allowAttachSelf
property is set tofalse
what is the default setting.- Parameters:
externalAttachment
- A description of the external attachment.processId
- The process id of the current process.agent
- The Java agent to install.isNative
-true
if the agent is native.argument
- The argument to provide to the agent ornull
if no argument should be supplied.- Throws:
Exception
- If an exception occurs during the attachment or the external process fails the attachment.
-
trySelfResolve
Attempts to resolve the location of theAttacher
class for a self-attachment. Doing so avoids the creation of a temporary jar file.- Returns:
- The self-resolved jar file or
null
if the jar file cannot be located.
-
quote
Quotes a value if it contains a white space.- Parameters:
value
- The value to quote.- Returns:
- The value being quoted if necessary.
-
doGetInstrumentation
Performs the actual lookup of theInstrumentation
from an installed Byte Buddy agent and returns the instance, or returnsnull
if not present.- Returns:
- The Byte Buddy agent's
Instrumentation
instance.
-