Created by Lx.
JVM TOOL INTERFACE / SINCE JAVA SE 5 / JSR-163

深入 JVM 的 原生探针.

JVMTI 是 JVM 暴露给工具与 Agent 的原生接口。它允许你在 JVM 进程内部订阅事件、读取运行时状态,并在受控边界内改变程序的执行方式。调试器、Profiler 与 APM 的底层,都站在这层接口之上。

In-process agent Event-driven C / C++ ABI Hot attach
JSR-163 / STANDARD EVENT → CALLBACK jvmtiEnv* / C ABI
jvmti://agent/session
live
00.012[load] Agent_OnLoad → GetEnv(JVMTI_VERSION_1_2)
00.018[caps] AddCapabilities ok · class hook / method trace
00.031[event] VMInit phase=LIVE · subscribed=3
00.044[class] Ljava/lang/Object; prepared
00.057[class] Ldemo/Demo; prepared · loader=bootstrap
00.082[trace] Demo.main() entry · depth=1
00.084[trace] Worker.run() entry · task=task-0
00.101[trace] Worker.run() exit · elapsed=17.4ms
00.102[jvmti] waiting for events
streaming events = 3 env 0x00007f3a
01
In-process · 同进程

Agent 以本地库形式被加载进目标 JVM,没有外部网络代理。

02
Event-first · 事件驱动

由 VM 主动回调 Agent,按能力授权、按需订阅。

03
Native ABI · C 函数表

通过 jvmti.h 与 jvmtiEnv 访问虚拟机内部。

01CONCEPT

概念与坐标

JVMTI 是什么?

如果 JVM 是一个持续运转的黑盒,JVMTI 就是在盒壁上开出的受控观测窗口:它不替代 JVM,也不属于 Java 业务 API,而是让原生工具能够在 VM 的关键路径上接收事件、查询状态,并按能力边界修改执行。

Definition / 定义

JVMTI 是一套由 JVM 实现的原生工具接口,让 Agent 在进程内观测、查询并有限度地改变 Java 程序。

它以 C/C++ 头文件 jvmti.h 的形式提供,通过 jvmtiEnv 函数表调用。Agent 不需要启动新的进程,也不依赖网络协议;它和 JVM 共享同一个地址空间,因此能拿到线程、栈帧、类、对象与 GC 等最贴近运行时的事实。

JavaVM->GetEnv(vm, (void**)&jvmti, JVMTI_VERSION_1_2); JSR-163 Java SE 5+
Position in the stack / 体系坐标

调试、剖析与 Java Agent,最终都落在这张图上

不同工具选择不同抽象层,但越往下,看到的事实越原生,也需要承担越多的兼容性与性能责任。

native protocol java api
01工具层
IDE 调试器IntelliJ IDEA · Eclipse
性能剖析器JProfiler · async-profiler
诊断 / APM AgentArthas · SkyWalking
02接口层
JDI + JDWPJava Debug Interface / wire protocol
JVMTIC/C++ 函数表 + 事件回调
Instrumentationpremain / agentmain · retransform
03VM 内部
JVM Debug Agent接收 JDWP,翻译为 JVMTI 调用
Native Agent直接持有 jvmtiEnv
Agent 支持层Attach / redefine / class hook
JVM · HOTSPOT 类加载 · 解释器 / JIT · 线程 · 堆与 GC · Monitor · JNI JVMTI implementation
JDI 通过 JDWP 与目标 VM 内的调试 Agent 通信 Instrumentation 是 Java 层入口,底层依赖 VM 的 Agent 支持 JNI 是互操作接口,提供对象访问能力,但不是事件接口
Why it exists / 诞生背景

把“调试”与“剖析”两套接口,收束成一套 VM 级标准。

Java 5 之前,调试主要依赖 JVMDI,性能分析依赖 JVMPI。两套接口目标重叠、实现成本高,事件与能力模型也不统一。JSR-163 将它们合并为 JVMTI,在 Java SE 5 中随 JVMDI / JVMPI 的退场一起登场。

2 → 1 / ONE INTERFACE
统一事件模型 能力授权 原生 Agent
Evolution / 演进时间线
JDK 1.2 — 1.4

双接口时代

JVMDI 负责调试,JVMPI 负责性能剖析,各自维护。

2003

JSR-163 启动

Java Platform Profiling Architecture 推动接口统一。

2004

JVMTI 随 Java 5 发布

统一调试与剖析能力,旧接口被标记为过时并逐步移除。

NOW

动态与生产化

Attach、retransform、采样与低开销 Agent 成为主流。

注意:JVMTI 不是 JVMPI 的“改名版”,而是重新设计的事件 + 能力 + 函数表模型。新 Agent 应当只面向 JVMTI 编写。

Smallest handle / 最小入口C · GetEnv
JavaVM *vm = ...;                    /* 由 Agent_OnLoad / Agent_OnAttach 传入 */
jvmtiEnv *jvmti = NULL;

jint rc = (*vm)->GetEnv(vm, (void **)&jvmti, JVMTI_VERSION_1_2);
if (rc != JNI_OK) {
    return JNI_ERR;                  /* 版本不匹配或当前 VM 不支持 */
}

/* 此后所有 JVMTI 调用都通过 jvmti 函数表完成 */
jvmtiError err = (*jvmti)->SetEventNotificationMode(
    jvmti, JVMTI_ENABLE, JVMTI_EVENT_CLASS_PREPARE, NULL);
02ARCHITECTURE

架构与工作原理

一个进程内的
双向契约。

Agent 不是“外挂进程”,而是被加载进 JVM 的原生库。它通过 jvmtiEnv 向下调用 VM,通过注册的 C 回调向上接收事件;能力机制则决定这条通路能走多远。

AGENTnative library
FUNCTION TABLE / IN-PROCESS
JNIEnv event callback Allocate / Deallocate JVMTI_ERROR_*
jvmtiEnvC FUNCTION TABLE
VERSION 1.2
事件上行 · VM → Agent
调用下行 · Agent → VM
JVMruntime services
SELECTED / 当前节点

GetEnv · 取得函数表

Agent 通过 JavaVM 的 GetEnv 取得 jvmtiEnv,并在此协商 JVMTI 版本。jvmtiEnv 是一张 C 函数表,后续所有查询、能力申请与事件控制都从这里发起。

JavaVMjvmtiEnv版本协商
PHASE / 相位

启动期与 Live 期不同

JVM 启动时执行 Agent_OnLoad;Attach 进来时执行 Agent_OnAttach,此时 VM 已处于 Live 期。用 GetPhase 判断当前相位,不要假设 main 还没执行。

THREAD / 线程

回调线程由 VM 决定

不同事件可能在不同线程上回调。不要在回调中假设线程身份,也不要阻塞、加长锁或执行慢 I/O;把数据复制到无锁队列,交给独立线程处理。

ERROR / 错误

每个 jvmtiError 都要检查

JVMTI 函数返回 jvmtiError,而不是抛异常。用 GetErrorName 记录可读错误名;能力未申请、相位不对、对象失效都会以错误码出现。

01 / LOADSTARTUP

Agent_OnLoad

启动参数进入 JVM,解析 options;调用 GetEnv 获取 jvmtiEnv。返回 JNI_ERR 会中止启动。

02 / WIREONLOAD

申请能力 · 注册回调

AddCapabilities → SetEventCallbacks → SetEventNotificationMode,搭好事件管道。

03 / LIVERUNTIME

事件回调 · 查询

VM 按订阅推送事件;Agent 读取栈、类、对象与时间信息。Attach 场景从这里进入。

04 / EXITUNLOAD

Agent_OnUnload

关闭事件、flush 数据、释放环境。VM 异常退出时不能依赖它完成关键落盘。

03EVENTS

事件模型

VM 主动讲述,
Agent 决定听什么。

JVMTI 的核心不是轮询,而是事件订阅 + 回调。你先声明能力、注册回调,再按事件粒度打开通知;VM 在对应时机调用你的 C 函数。事件越靠近执行核心,信息越细,开销也越高。

01 / HAPPEN 运行时状态变化

类被准备、方法进入、异常抛出、GC 开始。

02 / CHECK VM 匹配订阅

该事件是否启用?是否满足线程或对象过滤?

03 / CALLBACK 调用注册的 C 函数

回调在 VM 选定的线程上执行,参数携带现场。

04 / HANDLE 查询、缓冲、上报

快速拷贝最小事实,异步处理,避免阻塞 VM。

Event Category 触发时机 所需能力 典型用途
VMInit VM JVM 初始化完成,即将调用 main 方法之前。 无需额外能力 初始化 Agent 上下文、采样器与启动计时。
VMDeath VM JVM 即将结束,main 已退出并完成大部分关闭流程。 无需额外能力 flush 缓冲区、输出最终统计、关闭后端连接。
ClassPrepare CLASS 类已完成准备,字段与方法结构可用。 无需额外能力 读取类签名、预注册断点、建立方法索引。
ClassFileLoadHook CLASS 类文件字节进入 VM 前后,可返回修改后的字节。 can_generate_all_class_hook_events 字节码增强、探针注入、覆盖率与安全扫描。
ClassUnload CLASS 类被卸载,通常与类加载器不可达相关。 无需额外能力 诊断类加载器泄漏、观测热部署残留。
ThreadStart THREAD Java 线程开始执行,线程对象已创建。 无需额外能力 建立线程上下文、采样器注册、命名与标签。
ThreadEnd THREAD Java 线程终止,线程即将消失。 无需额外能力 清理线程本地数据,输出线程级汇总。
MethodEntry METHOD 进入 Java 方法时,在方法体执行前。 can_generate_method_entry_events 调用链追踪、方法计时;高频,需谨慎启用。
MethodExit METHOD Java 方法返回或异常退出方法体时。 can_generate_method_exit_events 与 MethodEntry 配对计算耗时与调用深度。
Exception DEBUG 异常对象被创建并抛出时。 can_generate_exception_events 异常热点、首次异常捕获、调试器断点。
ExceptionCatch DEBUG 异常即将被某个 catch 块捕获时。 can_generate_exception_events 异常处理路径分析、静默异常排查。
Breakpoint DEBUG 执行到 SetBreakpoint 设置的位置。 can_generate_breakpoint_events 调试器源码级断点、暂停与检查状态。
SingleStep DEBUG 线程执行到下一条字节码指令,且单步已开启。 can_generate_single_step_events 单步调试、指令级执行观察。
GarbageCollectionStart / Finish MEMORY GC 开始与结束时,可配对计算停顿窗口。 can_generate_garbage_collection_events GC 停顿归因、与业务请求关联分析。
ObjectFree MEMORY 带标签对象被 GC 回收后。 can_generate_object_free_events 对象生命周期追踪、内存泄漏确认。
VMObjectAlloc MEMORY VM 内部代码分配 Java 对象时。 can_generate_vm_object_alloc_events 发现非 Java 字节码路径产生的对象分配。
SampledObjectAlloc MEMORY 按堆采样间隔选中新分配对象时。 can_generate_sampled_object_alloc_events 低开销分配热点分析;需较新 JDK 支持。
MonitorContendedEnter MONITOR 线程尝试进入被其他线程持有的监视器。 can_generate_monitor_events 锁竞争热点、阻塞链定位。
CompiledMethodLoad JIT 方法被 JIT 编译并加载为本地代码。 can_generate_compiled_method_load_events JIT 行为观察、代码缓存与编译日志。
NativeMethodBind METHOD native 方法绑定到本地函数地址时。 can_generate_native_method_bind_events JNI 绑定追踪、native 调用审计。
DataDumpRequest VM VM 收到外部 dump 请求(如特定信号)时。 无需额外能力 触发自定义线程 / 堆诊断数据的落盘。
没有匹配的事件。换一个关键词,或切回“全部”。
EVENT INDEX / 共 21 个精选事件高亮项为解释器 / JIT 关键路径

能力列只标注该事件的常见前置能力;实际可用性还取决于 JVM 实现、相位与 JDK 版本。GetPotentialCapabilities 是唯一的可靠探测入口。

#include <jni.h>
#include <jvmti.h>
#include <string.h>

static void JNICALL on_class_prepare(jvmtiEnv *jvmti, JNIEnv *jni,
                                     jthread thread, jclass klass);

static jint wire_events(jvmtiEnv *jvmti) {
    jvmtiEventCallbacks callbacks;
    memset(&callbacks, 0, sizeof(callbacks));
    callbacks.ClassPrepare = on_class_prepare;

    jvmtiError err = (*jvmti)->SetEventCallbacks(
        jvmti, &callbacks, sizeof(callbacks));
    if (err != JVMTI_ERROR_NONE) {
        return JNI_ERR;
    }

    /* 先注册回调,再打开通知 */
    err = (*jvmti)->SetEventNotificationMode(
        jvmti, JVMTI_ENABLE, JVMTI_EVENT_CLASS_PREPARE, NULL);
    return err == JVMTI_ERROR_NONE ? JNI_OK : JNI_ERR;
}
04FUNCTIONS

函数表与能力机制

先申请权限,
再提出问题。

JVMTI 的能力(Capabilities)不是装饰性的开关:每一项都可能改变 VM 的优化假设、内存开销或线程行为。函数调用则通过 jvmtiEnv 函数表进行,按“你想查询什么”分组理解,远比背函数名有效。

Capability explorer

选择一项能力,查看它的代价

CAPABILITY BROKER / 16
共同前提能力要在使用前申请。先调用 GetPotentialCapabilities 探测,再 AddCapabilities;不要用“试试看”代替版本与相位检查。
Capability first / 能力申请C · defensive pattern
static jint add_trace_capabilities(jvmtiEnv *jvmti) {
    jvmtiCapabilities potential;
    jvmtiCapabilities wanted;

    memset(&potential, 0, sizeof(potential));
    memset(&wanted, 0, sizeof(wanted));

    jvmtiError err = (*jvmti)->GetPotentialCapabilities(jvmti, &potential);
    if (err != JVMTI_ERROR_NONE) return JNI_ERR;

    /* 只申请当前 VM 确实支持的能力 */
    if (potential.can_generate_method_entry_events) {
        wanted.can_generate_method_entry_events = 1;
    }
    if (potential.can_generate_method_exit_events) {
        wanted.can_generate_method_exit_events = 1;
    }

    err = (*jvmti)->AddCapabilities(jvmti, &wanted);
    if (err != JVMTI_ERROR_NONE) {
        char *name = NULL;
        (*jvmti)->GetErrorName(jvmti, err, &name);
        fprintf(stderr, "[jvmti] AddCapabilities: %s\n", name ? name : "unknown");
        if (name) (*jvmti)->Deallocate(jvmti, (unsigned char *)name);
        return JNI_ERR;
    }
    return JNI_OK;
}
Function map / 函数地图

按九组能力,建立你的 JVMTI 心智模型

函数表很深,但日常只需要知道自己要问哪一类问题。每组只列代表性入口,完整列表见 JVMTI 规范。

{ }GROUP 01

类与字节码 Class / Bytecode

枚举已加载类、读取签名与方法表、获取原始字节与常量池,执行类重定义与重转换。

GetLoadedClassesGetClassSignatureGetBytecodesGetConstantPoolRedefineClasses
入口:Agent 取到 jclass 后,先 GetClassSignature 再做索引。
λGROUP 02

方法与位置 Method / Location

把 jmethodID 还原成人类可读的方法名、声明类、行号表与局部变量表。

GetMethodNameGetMethodDeclaringClassGetLineNumberTableGetLocalVariableTableGetMethodLocation
调试器与采样器把指令地址映射回源码,都靠这组函数。
⇅GROUP 03

线程与栈帧 Thread / Stack

枚举线程、读取状态、抓取栈轨迹、遍历帧与局部变量,必要时挂起或恢复线程。

GetAllThreadsSuspendThreadGetThreadStateGetStackTraceGetFrameLocationPopFrame
GetStackTrace 常被 Profiler 采样器高频调用,注意分配与开销。
◈GROUP 04

堆与对象 Heap / Object

遍历堆、跟随引用链、给对象打标签、查询对象大小,观察分配与回收生命周期。

IterateThroughHeapFollowReferencesSetTagGetObjectsWithTagsGetObjectSizeForceGarbageCollection
全堆遍历通常成本高,生产环境优先采样、增量或按需触发。
⇄GROUP 05

监视器与同步 Monitor

读取线程持有的监视器、当前竞争对象与 monitor 信息,定位锁竞争和死锁链路。

GetOwnedMonitorInfoGetCurrentContendedMonitorGetMonitorInfoGetOwnedMonitorStackDepthInfo
与 MonitorContendedEnter 事件组合,可以看到“谁在等谁”。
•GROUP 06

断点与调试 Breakpoint / Debug

设置源码断点、字段访问 / 修改观察点,控制帧弹出与单步交付。

SetBreakpointClearBreakpointSetFieldAccessWatchSetFieldModificationWatchNotifyFramePop
IDEA 调试器的断点 / 单步能力,经 JDI ↔ JDWP 最终映射到这里。
⌁GROUP 07

能力与事件 Capability / Event

申请与归还能力、探测能力上限、注册回调、按事件和线程粒度开关通知。

GetPotentialCapabilitiesAddCapabilitiesRelinquishCapabilitiesSetEventCallbacksSetEventNotificationModeGenerateEvents
这是所有 Agent 的“控制面”,最容易因相位错误而失败。
◷GROUP 08

时间与采样 Timing / Sampling

获取 VM 时间、线程 CPU 时间与计时器信息,设置堆分配采样间隔。

GetTimeGetCurrentThreadCpuTimeGetThreadCpuTimeGetTimerInfoSetHeapSamplingInterval
用 GetTime 统一时基,避免把 wall clock 与 CPU time 混在一起。
⌘GROUP 09

VM 与工具 VM / Utility

读取相位、系统属性与版本信息,翻译错误码,释放环境并完成优雅收尾。

GetPhaseGetVersionGetSystemPropertiesGetErrorNameDisposeEnvironment
Attach 场景先 GetPhase,再决定哪些事件还有意义。
05PRACTICE

从 0 到 1

写一个能跑的
最小 Agent。

下面是一套完整、可直接编译运行的最小示例:它通过 -agentpath 或 Attach 加载,在 stderr 打印 VM 生命周期与 类准备事件。没有框架,没有第三方依赖,只有 jni.h 和 jvmti.h。

Native agent / 最小完整实现C · C99 · JVMTI 1.2
/* HelloAgent.c — 最小 JVMTI Agent
 * 编译后通过 -agentpath 或 Attach API 加载。
 * 订阅:VMInit / VMDeath / ClassPrepare
 */
#include <jni.h>
#include <jvmti.h>
#include <stddef.h>
#include <stdio.h>
#include <string.h>

static void JNICALL on_vm_init(jvmtiEnv *jvmti, JNIEnv *jni, jthread thread) {
    (void)jvmti; (void)jni; (void)thread;
    fprintf(stderr, "[hello-jvmti] VMInit: JVM ready\n");
}

static void JNICALL on_vm_death(jvmtiEnv *jvmti, JNIEnv *jni) {
    (void)jvmti; (void)jni;
    fprintf(stderr, "[hello-jvmti] VMDeath: goodbye\n");
}

static void JNICALL on_class_prepare(jvmtiEnv *jvmti, JNIEnv *jni,
                                     jthread thread, jclass klass) {
    char *signature = NULL;
    char *generic = NULL;
    (void)jni; (void)thread;

    jvmtiError err = (*jvmti)->GetClassSignature(
        jvmti, klass, &signature, &generic);

    if (err == JVMTI_ERROR_NONE && signature != NULL) {
        fprintf(stderr, "[hello-jvmti] ClassPrepare: %s\n", signature);
        (*jvmti)->Deallocate(jvmti, (unsigned char *)signature);
    }
    if (generic != NULL) {
        (*jvmti)->Deallocate(jvmti, (unsigned char *)generic);
    }
}

static jint install(jvmtiEnv *jvmti) {
    jvmtiEventCallbacks callbacks;
    memset(&callbacks, 0, sizeof(callbacks));
    callbacks.VMInit = on_vm_init;
    callbacks.VMDeath = on_vm_death;
    callbacks.ClassPrepare = on_class_prepare;

    jvmtiError err = (*jvmti)->SetEventCallbacks(
        jvmti, &callbacks, sizeof(callbacks));
    if (err != JVMTI_ERROR_NONE) return JNI_ERR;

    const jvmtiEvent events[] = {
        JVMTI_EVENT_VM_INIT,
        JVMTI_EVENT_VM_DEATH,
        JVMTI_EVENT_CLASS_PREPARE
    };
    for (size_t i = 0; i < sizeof(events) / sizeof(events[0]); ++i) {
        err = (*jvmti)->SetEventNotificationMode(
            jvmti, JVMTI_ENABLE, events[i], NULL);
        if (err != JVMTI_ERROR_NONE) return JNI_ERR;
    }
    return JNI_OK;
}

JNIEXPORT jint JNICALL Agent_OnLoad(JavaVM *vm, char *options, void *reserved) {
    (void)options; (void)reserved;
    jvmtiEnv *jvmti = NULL;
    if ((*vm)->GetEnv(vm, (void **)&jvmti, JVMTI_VERSION_1_2) != JNI_OK) {
        fprintf(stderr, "[hello-jvmti] GetEnv failed\n");
        return JNI_ERR;
    }
    fprintf(stderr, "[hello-jvmti] Agent_OnLoad\n");
    return install(jvmti);
}

JNIEXPORT jint JNICALL Agent_OnAttach(JavaVM *vm, char *options, void *reserved) {
    (void)options; (void)reserved;
    jvmtiEnv *jvmti = NULL;
    if ((*vm)->GetEnv(vm, (void **)&jvmti, JVMTI_VERSION_1_2) != JNI_OK) {
        return JNI_ERR;
    }
    fprintf(stderr, "[hello-jvmti] Agent_OnAttach\n");
    return install(jvmti);
}

JNIEXPORT void JNICALL Agent_OnUnload(JavaVM *vm) {
    (void)vm;
    fprintf(stderr, "[hello-jvmti] Agent_OnUnload\n");
}

这个示例不申请额外能力。VMInit、ClassPrepare 与 VMDeath 都不要求 capability;因此它能作为最干净的“链路是否打通”验证。

Expected output / 预期输出
$ java -agentpath:./libhellojvmti.so Demo
[hello-jvmti] Agent_OnLoad
[hello-jvmti] VMInit: JVM ready
[hello-jvmti] ClassPrepare: Ljava/lang/Object;
[hello-jvmti] ClassPrepare: LDemo;
Demo started, pid=31415
working: task-0
... 30 秒后 ...
[hello-jvmti] Agent_OnUnload
Verification / 验证清单6 checks
Agent_OnLoad 被打印
ClassPrepare 持续出现
无 UnsatisfiedLinkError
Attach 后出现 OnAttach
退出时 OnUnload 被调用
架构与 JDK 版本一致

如果第一行就失败,先检查动态库架构、JAVA_HOME 头文件路径和 JVM 位数,而不是事件逻辑。

HelloAgent.c→libhellojvmti.so→-agentpath→Agent_OnLoad→ClassPrepare→stderr
06SCENARIOS

典型应用场景

当 JVM 开始
“自己讲述”。

JVMTI 不直接产生业务价值,它把运行时事实变成可编程信号。性能剖析、调试、热修复、内存分析、APM 与字节码增强,都是在这层信号之上构建的工具形态。

⌁SCENE / 01

APM 与分布式链路追踪Distributed tracing · method events

在方法进入 / 退出或类加载时注入上下文,把 trace_id、span_id 与业务调用关联。真正的生产实现通常用 Instrumentation + 字节码库完成自动埋点,再通过 JVMTI 提供的类文件钩子或重转换能力接入 VM。

SkyWalkingOpenTelemetry Java AgentByte BuddyMethodEntry / Exit
[event] MethodEntry OrderService.pay
  trace_id = 4d2f…a91
  span_id  = 8a91…c02
[event] MethodExit  elapsed=17.4ms
[agent] export → collector
◷SCENE / 02

性能剖析Profiling · sampling

周期采样线程栈,聚合 CPU 热点、分配热点与锁竞争。相比方法级全量追踪,采样把开销控制在可接受范围,是生产环境的首选路径。

JProfilerasync-profilerYourKitGetStackTrace
•SCENE / 03

调试器Debugger · breakpoint & step

断点、单步、异常捕获、线程挂起与局部变量读取。IDE 前端通过 JDI / JDWP 发送命令,目标 VM 内的调试 Agent 再把语义翻译成 JVMTI 调用。

IntelliJ IDEAEclipseJDIJDWP
↺SCENE / 04

热更新 / 热修复Redefine & retransform

不重启进程替换方法体,用于紧急修复、灰度验证与诊断增强。类结构(字段、方法签名、继承关系)不能随意变化。

ArthasRedefineClassesRetransformClasses
◈SCENE / 05

内存泄漏检测Heap · tags · references

给对象打 tag,跟随引用链,结合分配事件与 GC 窗口确认对象是否被错误持有。全堆遍历成本高,要控制触发频率。

SetTagFollowReferencesObjectFreeMAT
{ }SCENE / 06

字节码增强Instrumentation · transform

在类文件进入 VM 前拦截、解析并改写字节码,实现埋点、鉴权、灰度路由或规则引擎。JVMTI 负责提供钩子,ASM / Byte Buddy 负责改写。

ClassFileLoadHookASMJavassistByte Buddy
▤SCENE / 07

覆盖率与动态分析Coverage · runtime evidence

通过运行时插桩记录代码路径,或在测试环境开启更细粒度事件,得到真实执行证据。开销与采样策略直接决定它能否进入 CI。

JaCoCo运行时插桩单步 / 方法事件
Tool map / 工具坐标

知名工具到底站在哪一层?

直接调用 JVMTI,和“站在 Instrumentation 之上”,是两种不同的工程选择。

工具主要路径与 JVMTI 的关系
IJIntelliJ IDEA Debugger JDI → JDWP → JVM Debug Agent 调试 Agent 用 JVMTI 实现断点、单步、线程与栈帧访问
JPJProfiler / YourKit native agent → JVMTI 直接持有 jvmtiEnv,读取 CPU、分配、GC、锁与线程数据
APasync-profiler native JVMTI agent + AsyncGetCallTrace 低开销采样,结合 perf / 信号与 JVM 栈信息
ARArthas Attach API → Instrumentation → ASM 不直接手写 JVMTI;retransform 等能力由 JVM 的 native Agent 支持承载
SWSkyWalking Java Agent Java Agent → Byte Buddy 以 Instrumentation 自动埋点为主,底层依赖 JVM 工具能力
JCJaCoCo Java Agent → 字节码插桩 覆盖率为目标;未必直接使用 JVMTI 事件
STEP 01发现目标 PID

jps / Attach API 枚举,确认用户与权限。

STEP 02loadAgent

加载 native 库或 Java Agent JAR,建立环境。

STEP 03retransform

按需增强目标类,或订阅运行时事件。

STEP 04采集与观察

把最小事实写入缓冲区,再异步分析。

STEP 05恢复原状

关闭事件、还原类、释放句柄与缓冲区。

07TRADEOFFS

对比、开销与常见坑

越靠近 VM,
越需要克制。

没有一种接口能同时满足“最深观测、最低开销、最简单接入”。选择 JVMTI、Instrumentation、ASM/Javassist 还是 JDI,取决于你要的是运行时事实、字节码改写,还是调试协议。

← 左右滑动查看完整对比表 →

维度 JVMTI Instrumentation ASM / Javassist JDI / JPDA
接口层级 JVM 原生 ABI Java 层 Agent API 字节码操作库 Java 调试 API + JDWP
使用语言 C / C++ Java Java Java
运行时事件 ●最丰富 ◐类加载 / 转换 —无,自行织入 ◐调试事件
修改类 重定义、重转换、类文件钩子 retransform / redefine 生成或改写字节码 —不可
接入方式 -agentpath / Attach premain / agentmain 依赖 Agent 或构建期 远程调试连接
典型场景 Profiler、调试后端、深度监控 APM、增强、热修复 插桩实现、框架增强 IDE 调试器
学习曲线 ◐高 ●中 ◐中 ◐中高
可移植性 依赖 JVM 实现与版本 跨 JVM 较一致 受字节码版本约束 标准化调试协议
NEED / 01只想改方法体

优先 Instrumentation + ASM / Byte Buddy,别一开始就写 native。

NEED / 02需要线程 / 堆 / GC

JVMTI 是更直接的选择,尤其是 Profiler 与诊断 Agent。

NEED / 03在做 IDE 调试器

使用 JDI / JDWP,不要重新发明一套调试协议。

NEED / 04需要极低开销

采样 + native 栈遍历 + 按线程开关事件,而不是全量 MethodEntry。

概念性开销谱

定性示意 · 非基准数据
ClassPrepare / VM 生命周期极低
采样 · 线程 CPU 时间低
ClassFileLoadHook · 字节码转换中
Monitor 竞争事件中
FollowReferences · 全堆遍历高
MethodEntry / Exit · 全量极高

真正的开销取决于调用频率与目标程序,而不是事件名。 上线前必须用实际流量、实际 JVM 版本做 A/B 压测。

把开销关进笼子

PRODUCTION NOTES
01
回调只做“抄写”

在回调内复制 methodID、线程 ID、时间戳等最小事实,写入无锁环形队列;解析、聚合与 IO 放到专用线程。

02
按线程、按阶段收窄

SetEventNotificationMode 支持事件粒度;能采样就不要全量 MethodEntry,能短时开启就不要常驻。

03
能力与相位先探测

GetPotentialCapabilities + GetPhase,在影响优化之前申请能力。

04
版本矩阵要跑真机

HotSpot、OpenJ9、不同 JDK 版本、容器限制、Attach 策略都会改变可用性与边界行为。

Pitfalls / 常见坑

七个最容易在生产环境踩中的边界

展开每一条,查看触发条件与规避方式。

01能力申请得太晚CAPABILITY

部分能力依赖 VM 在启动或 JIT 编译阶段预留支持。等到事件回调里才尝试 AddCapabilities,可能返回错误,或让方法被迫去优化。Attach Agent 也应在 Agent_OnAttach 的早期完成能力协商。

先 GetPotentialCapabilities,再 AddCapabilities;能力失败时记录 GetErrorName,不要假设 Agent 已完整工作。
02在回调里做重活或阻塞CALLBACK

事件回调没有独立的“安全沙箱”。阻塞、长时间持锁、同步日志、复杂 JSON 序列化都可能拖慢 VM 线程。某些 JVMTI 函数在特定回调上下文中还受额外限制,必须查规范的事件说明。

回调内只做最小数据复制;用无锁队列交给后台线程;不要在回调里调用业务代码或等待网络。
03JNI 引用与 GC 生命周期混淆JNI / GC

JNI local reference 只在当前 native 调用帧内有效,不能跨线程长期保存;需要跨线程时使用 NewGlobalRef,并在合适的时候 DeleteGlobalRef。全局引用会阻止对象被回收,泄漏的引用本身就是一次内存泄漏。

循环中及时 DeleteLocalRef;明确每一个 global ref 的所有者;对象 tag 不替代强引用语义,但同样要管理生命周期。
04把 RedefineClasses 当成任意热更新REDEFINE

JVMTI 的类重定义主要面向方法体变更,不能随意增加 / 删除字段、改变方法签名、修改继承关系或注解结构。重转换会重新经过 ClassFileLoadHook,因此要保证转换器幂等、可回滚。

把热修复限制在“方法体级别”;为每次增强保留原始字节与回滚路径;在目标 JDK 上验证字节码版本。
05低估 MethodEntry / Exit 的开销PERFORMANCE

这两个事件可能出现在海量调用路径上,还会阻止内联等优化。即使回调本身很轻,事件分发与去优化也能让延迟显著上升。对高吞吐服务,全量方法事件几乎总是错误起点。

优先采样与异步栈聚合;先对少量线程或短时间窗口开启;用真实流量测试 P99,而不是只看 CPU。
06忽略 Attach 的环境与版本差异ATTACH

Attach 需要目标进程允许 attach:同一用户、正确的 PID 命名空间、未开启 -XX:+DisableAttachMechanism,并且动态库架构匹配。JDK 21+ 还收紧了动态 Agent 加载策略与警告提示。

在容器中确认 PID 映射;准备 JDK 8 / 11 / 17 / 21 的兼容矩阵;优先给用户显式的启用参数,而不是静默失败。
07假设 Agent_OnUnload 一定会执行LIFECYCLE

进程崩溃、强制 kill、容器驱逐都可能让 VM 来不及走优雅卸载。把所有关键指标只放在 Agent_OnUnload 里 flush,会丢失最后一段数据。

周期性 flush;用 VMDeath 与外部 signal 路径补充;对重要数据采用幂等、可恢复的写入策略。
08ROADMAP

学习路线与文档

从“能跑”到
“敢上生产”。

JVMTI 的难点很少在 API 语法,而在 JVM 运行时、JNI 生命周期、并发与版本兼容。按下面的路线推进,每一步都以一个可验证的小实验收尾。

STAGE / 01
Foundation

JVM 运行时基础

先理解类加载、运行时数据区、线程与栈帧、Safepoint、解释器与 JIT。否则事件参数只是名词。

  • 类加载与双亲委派
  • 栈帧 / 局部变量 / 常量池
  • GC 与对象生命周期
  • JNI 基础与引用类型
STAGE / 02
First Agent

原生 Agent 起步

编译第一个 .so / .dll,跑通 OnLoad、事件回调与日志。先在本地命令行程序验证,不碰生产。

  • GetEnv 与版本协商
  • SetEventCallbacks
  • ClassPrepare / VMInit
  • 构建、加载与符号导出
STAGE / 03
Deep Dive

能力、字节码与调试

开始处理字节码转换、方法追踪、断点与栈帧。把 ASM / Byte Buddy 与 JVMTI 钩子组合起来。

  • Capabilities 与相位
  • ClassFileLoadHook / retransform
  • ASM 访问者模式
  • JDI / JDWP 关系
STAGE / 04
Production

生产级 Agent 工程

把回调延迟、内存、错误处理、Attach 兼容与回滚设计当成一等公民。建立真实流量下的观测与压测。

  • 无锁缓冲与异步聚合
  • 版本 / 架构 / 容器矩阵
  • 故障隔离与降级
  • 安全边界与可审计性
Environment / 环境自查

开始之前,先确认这四件事

$ java -version
openjdk version "21.0.x" ...
$ echo $JAVA_HOME
/path/to/jdk
$ ls "$JAVA_HOME/include"
jni.h jvmti.h linux/ (或 darwin/、win32/)
$ uname -m   # Windows: echo $env:PROCESSOR_ARCHITECTURE
x86_64 或 aarch64

JRE 通常不包含 jvmti.h 与编译工具。请使用完整 JDK,并确保 Agent 与 JVM 的 CPU 架构、位数一致。

JDK, not JRE same arch same user attach enabled

Ready to instrument

现在,把第一个探针
放进 JVM 里。

从 HelloAgent 开始,不申请能力、不改写字节码,只验证事件链路。跑通之后,再逐层加入方法追踪、类文件钩子与分析逻辑。

打开最小示例 java -agentpath:./libhellojvmti.so Demo
已复制到剪贴板