java.lang.instrument解析

–> go to 总目录

入门博客

Java 从 1.5 开始提供了 java.lang.instrument（doc）包，该包为检测（instrument） Java 程序提供 API，比如用于监控、收集性能信息、诊断问题。通过 java.lang.instrument 实现工具被称为 Java Agent。Java Agent 可以修改类文件的字节码，通常是，在字节码方法插入额外的字节码来完成检测。关于如何使用 java.lang.instrument 包，可以参考 javadoc 的包描述（en, zh）。Java Agent 支持两种方式加载，启动时加载，即在 JVM 程序启动时在命令行指定一个选项来启动代理；启动后加载，这种方式使用从 JDK 1.6 开始提供的 Attach API 来动态加载代理。

一、使用java agent

写一个agent.jar可以分为以下几步

1. 实现 ClassFileTransFormer 类 ----定义class的字节码转化逻辑
2. 实现premain或者domain方法，调用Instrumentation接口，添加定义好的转换逻辑。
3. 制作agent.jar，在MAINIFEST.MF中配置agent.jar的入口信息。
4. 执行agent.jara.
   a. 启动时加载 比如java -javaagent:"proj-premain.jar=hello agent" -cp "target/classes/java/main" com.demo.App
   b. jvm运行时加载，获取目标JVM的对象，执行loadgent动作。

VirtualMachine jvm = VirtualMachine.attach(jvmPid);
 jvm.loadAgent(agentJar, options);
 jvm.detach();

示例的运行，可以参考入门博客中demo。包含两种方式的启动。

二、运行原理

博客

2.1 绕不开的JVM TI

JVMTI是基于事件驱动的，JVM每执行到一定的逻辑就会调用一些事件的回调接口，这些接口可以供开发者扩展自行的逻辑。

ClassFileLoadHook

ClassFileLoadHook 事件。比如我想监听JVM加载某个类的事件，那么我们就可以实现一个回调函数赋给jvmtiEnv的回调方法集合里的ClassFileLoadHook（Class类加载事件），
那么当JVM进行类加载时就会触发回调函数，我们就可以在JVM加载类的时候做一些扩展操作。
比如上面提到的更改这个类的Class文件信息来增强这个类的方法。

agent函数 (Agent_OnLoad、Agent_OnAttach、Agent_OnUnload)

JVMTI运行时，一个JVMTIAgent对应一个jvmtiEnv或者是多个，JVMTIAgent是一个动态库，利用JVMTI暴露出来的接口来进行扩展。

主要有三个函数：

• Agent_OnLoad方法：如果agent是在启动时加载的，那么在JVM启动过程中会执行这个agent里的
• Agent_OnLoad函数（通过-agentlib加载vm参数中）Agent_OnAttach方法：如果agent不是在启动时加载的，而是attach到目标程序上，然后给对应的目标程序发送load命令来加载，则在加载过程中会调用Agent_OnAttach方法
• Agent_OnUnload方法：在agent卸载时调用，要么主动下发卸载命令，要么jvm关闭是触发。

2.2 Instrument的实现

这个没有分析源码，网上找的资料。应该是分析JPLISAgent的源码，有兴趣的可以了解下
回到主题，Instrument 就是一种 JVMTIAgent，它实现了Agent_OnLoad和Agent_OnAttach两个方法，也就是在使用时，Instrument既可以在启动时加载，也可以再运行时加动态加载

• premain启动时加载就是在启动时添加JVM参数：-javaagent:XXXAgent.jar的方式
• agentmain运行时加载是通过JVM的attach机制来实现，通过发送load命令来加载

2.2.1 premain 启动时加载

1. Instrument agent启动时加载会实现Agent_OnLoad方法，具体实现逻辑如下：
   创建并初始化JPLISAgent
2. 监听VMInit事件，在vm初始化完成之后执行下面逻辑
   a. 创建Instrumentation接口的实例，也就是InstrumentationImpl对象
   b. 监听ClassFileLoadHook事件（类加载事件，通过set callback）
   c. 调用InstrumentationImpl类的loadClassAndCallPremain方法，这个方法会调用javaagent的jar包中里的MANIFEST.MF里指定的Premain-Class类的premain方法
3. 解析MANIFEST.MF里的参数，并根据这些参数来设置JPLISAgent里的内容

2.2.2 agentmain 启动时加载

Instrument agent运行时加载会使用Agent_OnAttach方法，会通过JVM的attach机制来请求目标JVM加载对应的agent，过程如下

1. 创建并初始化JPLISAgent
2. 解析javaagent里的MANIFEST.MF里的参数
3. 创建InstrumentationImpl对象
4. 监听ClassFileLoadHook事件
5. 调用InstrumentationImpl类的loadClassAndCallAgentmain方法，这个方法会调用javaagent的jar包中里的MANIFEST.MF里指定的agentmain-Class类的agentmain方法

2.3.3. ClassFileLoadHook回调实现

启动时加载和运行时加载都是监听同一个jvmti事件那就是ClassFileLoadHook，这个是类加载的事件，在读取类文件字节码之后回调用的，这样就可以对字节码进行修改操作。

在类加载时修改类的字节码

在JVM加载类文件时，执行回调，加载Instrument agent，创建Instrumentation接口的实例并且执行premain方法，premain方法中注册自定义的ClassFileTransformer来对字节码文件进行操作，这个就是在加载时进行字节码增强的过程。

修改内存已经存在的类

那么如果java类已经加载完成了，在运行的过程中需要进行字节码增强的时候还可以使用Instrumentation接口的redifineClasses方法，
有兴趣的可以自行研究源码，这里只描述大致过程。
通过执行该方法，在JVM中相当于是创建了一个VM_RedifineClasses的VM_Operation，此时会stop_the_world，具体的执行过程如下：

• 挨个遍历要批量重定义的 jvmtiClassDefinition
• 然后读取新的字节码，如果有关注 ClassFileLoadHook 事件的，还会走对应的 transform 来对新的字节码再做修改字节码解析好，创建一个 klassOop
• 对象对比新老类，并要求如下：

• 父类是同一个实现的接口数也要相同，并且是相同的接口类
• 访问符必须一致
• 字段数和字段名要一致
• 新增的方法必须是 private static/final 的
• 可以删除修改方法
• 对新类做字节码校验
• 合并新老类的常量池
• 如果老类上有断点，那都清除掉
• 对老类做 JIT 去优化
• 对新老方法匹配的方法的 jmethodId 做更新，将老的 jmethodId 更新到新的 method 上
• 新类的常量池的 holer 指向老的类
• 将新类和老类的一些属性做交换，比如常量池，methods，内部类
• 初始化新的 vtable和 itable
• 交换 annotation 的 method、field、paramenter
• 遍历所有当前类的子类，修改他们的 vtable 及 itable

三、sun.instrument 源码分析

下面先介绍核心的类，再说明用法。

这个是在premain和agentmain中如何使用instrument。注意三个方法

1. addTransformer(new Transformer, true) –jdk5
2. retransformClass(Target.class) --JDK6
3. redineClass(new ClassDefintion[] (def)) — jdk5
   这个三个方法就是用来执行转化字节码的

3.1 ClassFileTransFormer 转换器接口

default byte[] transform(ClassLoader loader,String className,Class<?> classBeingRedefined,ProtectionDomain protectionDomain,byte[] classfileBuffer)

参数解析

1. ClassLoader : 被加载类的loader
2. className: 正在加载类的名称
   3.classBeingRedefined: 目标类为A,需要被重定义，被重定义的类记为A1，那么
3. classBeingRedefined: 就代表着A1classFileBuffer当前类的定义
   使用示例:修改com.demo.app的类
   

3.2 TransformerManager

instrument内拥有一个TransformerManager，包含了TransFormer数组。也就是说存在多个TransFormer时，TransFormer会形成一个链。上一个transformer对字节的修改，被传递到下一个transformer。
jdk6支持对本地方法的修改，所以会对分为4类，4类按顺序执行

• 不支持retransform的 TransFormer
• 不支持retransform 的 TransFormerNative
• 支持retransform的 TransFormer
• 支持retransform TransFormerNative

3.3 触发转换的动作

3.3.1 addTransformer(ClassFileTransformer transformer, boolean canRetransform);

在这里插入图片描述

这个函数的作用是，添加到transfomer数组中去。每当有一个类加载时会触发ClassFileLoadHook的回调，
这个回调会执行transfomer链，得到被加工过的字节码—保留在classFileBuffer类，最后被加载进方法区。

3.3.2 redefineClasses(ClassDefinition… definitions)

接受多个类的定义。再经过所transfomer数组（通常不添加）的加工，最后被加载进方法区。
这个方法是来源于jdk5
官方文档用来替换类内不存在任何引用（refrence）的类。往往修改一个类A也会导致相关联的B也要被修改。所以这里参数可以传入多个类。如果被redefine的方法，在栈stack中有了，此时再发生redefine。那么结果是，stack中方法继续执行老的定义，新的调用将会采用redefine后的方法。

3.3.3 retransformed(ClassDefinition… definitions)

这个类在JDK6引入，和redefine类似但更强大。
可以对于已经加载的类（包括被redined的类）进行修改。
当类第一次加载时或者被redefined时，类的字节码byte[] ,会经过transfomer数组的加工。这个函数就是用来重放这个过程，不管内存中的类是否被装换过。
retransformed遵从以下步骤

1. 总是从类最初的定义开始（没有修改过的，原始的）
2. 执行所有canRetransform 为true的transfomer，跳过canRetransform 为false的transfomer。
3. 加载进内存，和redefine一样，存在栈里面的方法改变，对新方法的调用用新定义。

注意
如果所有的transfomer为flase,那么他从最原始的类的定义出发，跳过所有transfomer，得到结果还是最原始的类。
如果内存类已经被修改了，那么会发生原始的类定义替换被修改过的类，相当于还原。参数：ClassDefinition... definitions 需要重新转化的类。

3.3.4 总结一下

只要使用了addTransformer，那么每有类加载的时候，就会触发transfomer链加工。redefine接受一组类的定义，然后触发transfomer的加工，替换进内存里。retransform和redefine类似，从最原始的类定义，开始重放transfomer链接的加工（只重放所有被标记为canRetransform的transfomer）,替换进内存。