Java Agent入门实战（一）-Instrumentation介绍与使用

学会Java Agent你能做什么？

• 自动添加getter/setter方法的工具lombok就使用了这一技术
• btrace、Arthas和housemd等动态诊断工具也是用了instrument技术
• Intellij idea 的 HotSwap、Jrebel 等也是该技术的实现之一
• pinpoint、skywalking、newrelic、听云的 APM 产品等都基于 Instrumentation 实现

Java Instrumentation 简介

来源：网易有道词典-专业释义-计算机科学技术

Instrumentation: 在计算机科学技术中的英文释义是插桩、植入。

instrument: 仪器（仪器是指用以检出、测量、观察、计算各物理量、物质成分、物性参数等的器具或设备。）

动态 Instrumentation 是 Java SE 5 的新特性，它在 java.lang.instrument 包中，它把 Java 的 instrument 功能从本地代码中释放出来，使其可以用 Java 代码的方式解决问题。使用 Instrumentation，开发者可以构建一个独立于应用程序的代理程序（Agent），用来监测和协助运行在 JVM 上的程序，甚至可以替换和修改某些类的定义。有了这样的功能，开发者就可以实现更为灵活的虚拟机监控和 Java的 类操作了，这样的特性实际上提供了一种虚拟机级别支持的 AOP方式，使得开发者无需对原有应用做任何修改，就可以实现类的动态修改和增强

java.lang.instrument 包被赋予了更强大的功能：启动后的 监测、本地代码（native code）监测，以及动态改变 classpath 等等。这些改变，意味着 Java 具有了更强的动态控制与解释能力，它使得 Java 语言变得更加灵活多变。

在 Java SE6 里面，最大的改变是能够植入代码到运行时的JVM 程序。在 Java SE 5 中，Instrument 要求在运行前利用命令行参数或者系统参数来设置代理类，在实际的运行之中，虚拟机在初始化之时（在绝大多数的 Java 类库被载入之前），instrumentation 的设置已经启动，并在虚拟机中设置了回调函数，检测特定类的加载情况，并完成实际工作。但是在实际的很多的情况下，我们没有办法在虚拟机启动之时就为其设定代理，这样实际上限制了 instrument 的应用。而 Java SE 6 的新特性改变了这种情况，通过 Java Tool API 中的 attach 方式，我们可以很方便地在运行过程中动态地设置加载代理类，以达到 instrumentation 的目的。

另外，对 native method 的 Instrumentation 也是 Java SE 6 的一个崭新的功能，这使以前无法完成的功能，可以在 Java SE 6 中通过对 native method 接口的 Instrumentation，通过一个或者一系列的 prefix 添加而得以完成。

Java SE 6 里的 Instrumentation 也增加了动态添加 class path 的功能。这些新的功能，都使得 java.lang.instrument 包的功能更加丰富，使得 Java 语言更加强大。

java.lang.instrument包的具体实现，依赖于 JVMTI（Java Virtual Machine Tool Interface）这是一套由 Java 虚拟机提供的，为 JVM 相关工具提供的本地编程接口集合。JVMTI 是从 Java SE 5 开始引入，JVMTI 提供了一套“代理”程序机制，可以支持第三方工具程序以代理的方式连接和访问 JVM，并利用 JVMTI 提供的编程接口，完成很多跟 JVM 相关的功能。事实上，java.lang.instrument 包的实现，也就是基于这种机制的

在 Instrumentation 的实现当中，存在一个 JVMTI 的代理程序，通过调用 JVMTI 当中与Java 类相关的函数，来完成对 Java 类的动态操作。

除了 Instrumentation 功能外，JVMTI 还在虚拟机内存管理，线程控制，方法和变量操作等等方面提供了大量可用的函数。关于 JVMTI 的详细信息，可以参考 Java SE 6 JVM TI文档

Java Instrumentation 的基本用法

在java中如何实现 Instrumentation 呢，简单来说有以下几步

1. 创建一个普通的类，内含静态方法premain(),这个方法名是java agent内定的方法名，它总会在main函数之前执行

package cn.jpsite.learning.javaagent01;
import java.lang.instrument.Instrumentation;
public class JpAgent {
    public static void premain(String agentArgs, Instrumentation instrumentation)  {
        /*转换发生在 premain 函数执行之后，main 函数执行之前，这时每装载一个类，transform 方法就会执行一次，看看是否需要转换，
        所以，在 transform（Transformer 类中）方法中，程序用 className.equals("TransClass") 来判断当前的类是否需要转换。*/
        // 方式一：
        System.out.println("我是两个参数的 Java Agent premain");
    }
    public static void premain(String agentArgs){
        System.out.println("我是一个参数的 Java Agent premain");
    }
}

1. 如上有2个premain()方法，当1个参数和2个参数的premain()的方法同事存在的时候，premain(String agentArgs)将被忽略
2. 在resource目录下新建META-INF/MANIFEST.MF文件，内容如下:

Manifest-Version: 1.0
Premain-Class: cn.jpsite.learning.javaagent01.JpAgent
Can-Redefine-Classes: true
Can-Retransform-Classes: true

1. 以上内容可以通过Maven的org.apache.maven.plugins和maven-assembly-plugin插件配合完成，在mvn install的时候生成MANIFEST.MF文件内容
2. 目录结构是这样的
   

4.对当前工程执行mvn clean install 打包，生成了jpAgent.jar文件 5. 新建一个maven工程example01，内含Main.java、Dog.java，并最终打包成example01-1.0-SNAPSHOT.jarpublic class Dog { public String say() { return "dog"; } }public class Main { public static void main(String[] args) { System.out.println("夜太黑"); System.out.println("----"+new Dog().say()); } }6. 执行 jpAgent.jar 需要通过 -javaagent 参数来指定Java代理包， > -javaagent 这个参数的个数是不限的，可以指定多个，会按指定的先后顺序执行，执行完各个 agent 后，才会执行主程序的 main 方法。

```
// 为了执行方便，把jar文件放在同一层级目录下
java -javaagent:jpAgent.jar -cp example01-1.0-SNAPSHOT.jar  cn.jpsite.learning.Main
```
其中`example01-1.0-SNAPSHOT.jar`的`Main()`方法只是简单的输出2行内容，通过agent代理后多输出了一段内容。

C:\Users\jiangpeng\Desktop\learning>java-jauaagent:jpAgent.jar-cpexample01-10-SNAPSHOT.jar cn.jpsite.learning.Main
袋吴票个参数的 Java agent prenain
-dog

addTransformer方法

对 Java 类文件的操作，可以理解为对一个 byte 数组的操作（将类文件的二进制字节流读入一个 byte 数组）。开发者可以在 interface ClassFileTransformer的 transform 方法（通过 classfileBuffer 参数）中得到，操作并最终返回一个类的定义（一个 byte 数组），接下来演示下transform 转换类的用法，采用简单的类文件替换方式。

1. 新建JpClassFileTransformerDemo.java 实现 ClassFileTransformer接口，getBytesFromFile() 方法根据文件名读入二进制字符流，而 ClassFileTransformer 当中的 transform 方法则完成了类定义的替换。

import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.lang.instrument.ClassFileTransformer;
import java.lang.instrument.IllegalClassFormatException;
import java.security.ProtectionDomain;
public class JpClassFileTransformerDemo implements ClassFileTransformer {
    @Override
    public byte[] transform(ClassLoader loader, String className, Class<?> classBeingRedefined,
                            ProtectionDomain protectionDomain, byte[] classfileBuffer) throws IllegalClassFormatException {
        System.out.println("loader className: " + className);
        if (!className.equalsIgnoreCase("cn/jpsite/learning/Dog")) {
            return null;
        }
        return getBytesFromFile("D:\\learning\\Dog.class");
    }
    public static byte[] getBytesFromFile(String fileName) {
        File file = new File(fileName);
        try (InputStream is = new FileInputStream(file)) {
            // precondition
            long length = file.length();
            byte[] bytes = new byte[(int) length];
            // Read in the bytes
            int offset = 0;
            int numRead = 0;
            while (offset < bytes.length
                    && (numRead = is.read(bytes, offset, bytes.length - offset)) >= 0) {
                offset += numRead;
            }
            if (offset < bytes.length) {
                throw new IOException("Could not completely read file "
                        + file.getName());
            }
            is.close();
            return bytes;
        } catch (Exception e) {
            System.out.println("error occurs in _ClassTransformer!"
                    + e.getClass().getName());
            return null;
        }
    }
}

1. JpAgent.java 增加

instrumentation.addTransformer(new JpClassFileTransformerDemo());内容

2. 如下,重新打包

public class JpAgent {
    public static void premain(String agentArgs, Instrumentation instrumentation)  {
        /*转换发生在 premain 函数执行之后，main 函数执行之前，这时每装载一个类，transform 方法就会执行一次，看看是否需要转换，
        所以，在 transform（Transformer 类中）方法中，程序用 className.equals("TransClass") 来判断当前的类是否需要转换。*/
        // 方式一：
       instrumentation.addTransformer(new JpClassFileTransformerDemo());
        System.out.println("我是两个参数的 Java Agent premain");
    }
    public static void premain(String agentArgs){
        System.out.println("我是一个参数的 Java Agent premain");
    }

1. 此时我们去修改之前的example01工程中的Dog.java, 把say()方法返回的字符串"dog"改为"cat", 然后编译成.class文件，

getBytesFromFile("D:\\learning\\Dog.class")

2. 就是读取修改后的class文件。
3. 执行

java -javaagent:jpAgent.jar -cp example01-1.0-SNAPSHOT.jar cn.jpsite.learning.Main

3. 查看结果如下：

D:\learning>jaua -javaagent:jpAgent.jar -cp example01-1.0-SNAPSHOT.jar  cn.ipsite.learning.Main 
我是两个参数的 Jaua Agent premain
loader className:jaua/lang/invoke/MethodHandleImpl loader className:iava/lang/invoke/MethodHandleImpl$1 loader className:iava/lang/invoke/MethodHandleImpl$2 loader className:java/util/function/Function
loaderclassNane:iava/lang/inyoke/MethodHandleImol53 loader className:java/lang/invoke/MethodHandleImpl$4 loader className: iava/lang/ClassUalue
loader className:jaua/lang/ClassUalue$Entry
loader className: iava/lang/ClassUalueSIdentity loader className:iava/lang/ClassUalue$Uersion
loaderclassName:iava/lang/inyoke/MemberNameSFactory loader className:jaua/lang/invoke/MethodHandleStatics loader className:iava/lang/invoke/MethodHandleStatics$1 loader className:sun/misc/PostUMInitHook
loader className: sun/usagetracker/UsageTrackerClient
loader className:jaua/util/concurrent/atomic/AtomicBoolean Loader className: sun/usagetracker/UsageTrackerClient$1 loader className:sun/usagetracker/UsageTrackerClient$4 loader className: sun/usagetracker/UsageTrackerClient$2 loader className:jaua/lang/ProcessEnuironment
loader className:jaua/lang/ProcessEnvironment$NameComparator loader className:jaua/lang/ProcessEnvironment$EntryComparator loader className:java/util/Collections$UnmodifiableMap
loader className:jaua/lang/ProcessEnuironment$CheckedEntrySet Loader className: jaua/util/HashMap$EntrySet
loader className:jaua/lang/ProcessEnvironment$CheckedEntrySet$1 loader className: iava/util/HashMapSEntryIterator loader className:java/util/HashMap$HashIterator
loader className:java/lang/ProcessEnuironment$CheckedEntry loader className:sun/usagetracker/UsageTrackerClient$3 loader className:jaua/io/FileOutputStream$1 loader className:sun/launcher/LauncherHelper loader className:cn/ipsite/learning/Main
loader className:sun/launcher/LauncherHelper$FXHelper loaderclassName:.java/lang/Uoid夜太黑
loader className:cn/jpsite/learning/Dog ---cat
loader className: iava/lang/shutdown loader className:java/lang/ShutdownSLock

转换发生在 premain 函数执行之后，main 函数执行完成之前，这时每装载一个类，transform 方法就会执行一次，看看是否需要转换，所以，在 transform方法中，这里用了 className.equals("cn/jpsite/learning/Dog") 来判断当前的类是否需要转换。

除了用 addTransformer 的方式，Instrumentation 当中还有另外一个方法“redefineClasses”来实现 premain 当中指定的转换。用法类似，如下：

ClassDefinition def = new ClassDefinition(Dog.class, Objects.requireNonNull(JpClassFileTransformerDemo
                .getBytesFromFile("D:\\learning\\Dog.class")));
instrumentation.redefineClasses(new ClassDefinition[] { def });

扩展阅读

Java虚拟机参数分析平台

java.lang.instrument api doc

Java SE 6 JVM TI文档

Java SE 8 docJava Attach API

JavaAgent源码分析

Java探针-Java Agent技术-阿里面试题

自己实现一个Native方法的调用

自己实现一个Native方法的调用2