JAgent
JAgent framework helps you to implement java agents. It has some extra functionality instead of standard Java's API.
Class redefining
By default, java agents don't redefine already loaded classes.
Standard API has method
java.lang.instrument.Instrumentation#redefineClasses(ClassDefinition... definitions)
to redefine them.
But it's impossible to redefine some classes (for example, java.lang.String
) using this method.
JAgent has its own implementation of redefinition logic and allows to redefine all classes.
But make careful with transforming classes from java.*
package because of invalid transformation
can cause strange errors into JVM code (segmentation fault, for example).
Class caching
This feature is under development. See com.devexperts.jagent.CachingClassFileTransformer
.
FrameClassWriter
If you use ASM to code transformation then you can face a problem with frame counting. ClassWriter
has a getCommonSuperClass(String type1, String type2)
method to merge two types to compute stack frame attributes. If one of the types is the one being processed by this ClassWriter
then you will catch LinkageError
or ClassCircularityError
. The cause of this problem is inside this method: ClassWriter
uses ClassLoader#forName(String type)
method to load class of specified type. JAgent has its own implementation of getCommonSuperClass
method based on caching class metadata during transforming. So if you should find superclass of two types and one of them is the one being processed then you have information about it already and you don't need to load it again.
Example:
private final ClassInfoCache ciCache;
@Override
public byte[] transform(ClassLoader loader, String className, Class<?> clazz, ProtectionDomain pd, byte[] classfileBuffer) throws IllegalClassFormatException {
ClassReader cr = new ClassReader(classfileBuffer);
// this visitor exctracts information about class
ClassInfoVisitor ciVisitor = new ClassInfoVisitor();
cr.accept(ciVisitor, 0);
// update cache with information about classes
ciCache.getOrInitClassInfoMap(loader).put(className, ciVisitor.getClassInfo());
// create FrameClassWriter using cache
ClassWriter cw = new FrameClassWriter(loader, ciCache);
...
return cw.toByteArray();
}
Own classloader
JAgent has InnerJarClassLoader
which is used to load transformation code and libraries via custom class loader.
What is it for?
If you have 2 agents that use library XXX with different versions then you have a version conflict.
But it is all right if you load them under different class loaders.
Use InnerJarClassLoader
to load your transformation code and external libraries for it.
See scheme below to understand how to write java agents with this feature:
Fast logging
Every JAgent
instance has a Log
object which is used to write logs efficiently.
You can use JAgent#getLog()
method to get the Log
object for your purposes.
Logs are written according to following format:
2016-02-10T02:48:19.902+0300 <agent_name>: <message>
Sample
You can find sample
module in source code to see how to use JAgent for implementing your own java agent.
Maven
Here is a guide how to create java agents via JAgent with Maven.
If you use InnerJarClassLoader
then you should use 4 modules in your agent code:
- core - contains code that runs transformation and new code for runtime
- transformer - contains transformation logic
- agent - builds agent's jar, no code here
- test - tests for your agent
transformer module
Contains code that is executable in transformation phase.
Should have com.devexperts.jagent:jagent-impl
as dependency.
This code with dependencies is loaded under InnerJarClassLoader
.
com.agent.package.YourJAgentImpl.java
Implementation of JAgent
abstract class. This implementation is used in com.agent.package.AgentRunner
code.
public class YourJAgentImpl extends JAgent {
private YourJAgentImpl(Instrumentation inst, String args, String agentName, String agentVersion, Log log) {
super(inst, agentName, agentVersion, log);
}
public static YourJAgentImpl create(Instrumentation inst, String agentArgs) {
String agentName = JAgentUtil.getImplTitle(YourJAgentImpl.class);
String agentVersion = JAgentUtil.getImplVersion(YourJAgentImpl.class);
Log log = new Log(agentName, Log.Level.DEBUG, null);
YourJAgentImpl agent = new YourJAgentImpl(inst, agentArgs, agentName, agentVersion, log);
agent.addTransformer(...);
...
return agent;
}
}
pom.xml example:
Just contains needful dependencies for transformation.
<dependencies>
<dependency>
<groupId>com.devexperts.jagent</groupId>
<artifactId>jagent-impl</artifactId>
<version>0.2</version>
</dependency>
<dependency>
<groupId>org.ow2.asm</groupId>
<artifactId>asm-all</artifactId>
<version>5.0.4</version>
</dependency>
</dependencies>
core module
Contains code that runs transformation and new code for runtime. All classes from this module will be available via system class loader.
MANIFEST.MF
Configures agent information and permissions.
Premain-Class: com.agent.package.AgentRunner
Can-Redefine-Class: true
Boot-Class-Path: ${agent.artifact.name}.jar
Name: com/agent/package
Implementation-Title: ${agent.artifact.name}
Implementation-Version: ${project.version}
Implementation-Vendor: <your company>
com.agent.package.AgentRunner.java
Runs transformation code via JAgentRunner
.
public class AgentRunner {
public static void premain(String agentArgs, Instrumentation inst) throws Exception {
JAgentRunner.runAgent("com.agent.package.YourJAgentImpl", inst, agentArgs,
// All jars are located into your_agent.jar
InnerJarClassLoader.createForJars("jagent-impl.jar", "transformer.jar", "asm-all.jar"));
}
}
pom.xml example:
Builds jar with specified MANIFEST.MF and uses maven-shade-plugin to get rid of problems with different jagent-api's versions in several java agents.
...
<build>
<!-- Processes resources directory to replace Maven's variables to theirs values -->
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>true</filtering>
</resource>
</resources>
<!-- Builds jar with specified MANIFEST.MF file-->
<plugins>
<plugin>
<artifactId>maven-jar-plugin</artifactId>
<configuration>
<archive>
<addMavenDescriptor>false</addMavenDescriptor>
</archive>
<useDefaultManifestFile>true</useDefaultManifestFile>
</configuration>
</plugin>
<!-- maven-shade-plugin is used for relocating "jagent-api" classes.
It's necessary when you use "jagent-api" in several agents
to get rid of conflict with different "jagent-api" versions. -->
<plugin>
<artifactId>maven-shade-plugin</artifactId>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<artifactSet>
<includes>
<include>com.devexperts.jagent:jagent-api</include>
</includes>
</artifactSet>
<relocations>
<relocation>
<pattern>com.devexperts.jagent.api</pattern>
<shadedPattern>com.agent.package.shaded.com.devexperts.jagent.api</shadedPattern>
</relocation>
</relocations>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>com.devexperts.jagent</groupId>
<artifactId>jagent-api</artifactId>
<version>0.2</version>
</dependency>
</dependencies>
...
agent module
This module contains only pom.xml
to build your_agent.jar
.
pom.xml example:
Unpacks core
classes and adds transformer, jagent-impl and external libraries JARs to your_agent.jar
.
These JARs are loaded via InnerJarClassLoader
.
<build>
<!-- DO NOT RENAME because of "Boot-Class-Path" section in MANIFEST.MF -->
<finalName>${agent.artifact.name}</finalName>
<plugins>
<!-- Firstly, maven-dependency-plugin unpacks "core" module
and copies all other dependencies to its classpath.
Classes from these dependencies will be loaded
via InnerJarClassLoader from "core" module. -->
<plugin>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<id>copy-dependencies</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-dependencies</goal>
</goals>
<configuration>
<excludeArtifactIds>core,jagent-api</excludeArtifactIds>
<outputDirectory>${project.build.outputDirectory}</outputDirectory>
<stripVersion>true</stripVersion>
</configuration>
</execution>
<execution>
<id>unpack-dependencies</id>
<phase>prepare-package</phase>
<goals>
<goal>unpack-dependencies</goal>
</goals>
<configuration>
<includeArtifactIds>core</includeArtifactIds>
<outputDirectory>${project.build.outputDirectory}</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
<!-- Then, maven-jar-plugin builds jar with dependencies and
specified MANIFEST.MF file (contains in "core" module). -->
<plugin>
<artifactId>maven-jar-plugin</artifactId>
<configuration>
<archive>
<addMavenDescriptor>false</addMavenDescriptor>
</archive>
<useDefaultManifestFile>true</useDefaultManifestFile>
</configuration>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>com.agent.package</groupId>
<artifactId>core</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.agent.package</groupId>
<artifactId>transformer</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
test module
Contains tests for your agent. Here is an example for unit testing.
pom.xml example:
Configures maven-surefire-plugin to run tests under yout agent.
...
<plugins>
<!-- maven-dependency-plugin is used to copy your agent into target directory -->
<plugin>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<id>copy-sample-agent</id>
<phase>process-test-classes</phase>
<goals>
<goal>copy</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>com.agent.package</groupId>
<artifactId>your_agent</artifactId>
<version>${project.version}</version>
<outputDirectory>${project.build.directory}</outputDirectory>
<destFileName>${agent.artifact.name}.jar</destFileName>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
<!-- Configure maven-surefire-plugin to use your agent -->
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<argLine>-javaagent:${agent.directory}/${agent.artifact.name}.jar</argLine>
</configuration>
</plugin>
</plugins>
...
Getting support
If you need help, you have a question, or you need further details on how to use JAgent, you can refer to the following resources:
- dxlab research group at Devexperts
- GitHub issues: https://github.com/Devexperts/jagent/issues