在業(yè)務(wù)系統(tǒng)里做性能診斷、故障排查、方法鏈路觀測(cè)時(shí)很多人第一反應(yīng)是改代碼加日志或者引入一個(gè)重量級(jí) APM。但遇到線上不能隨意發(fā)布、依賴不好升級(jí)、框架源碼不好改的場(chǎng)景Java Agent 幾乎是繞不開(kāi)的方案。Java Agent 可以做到不修改業(yè)務(wù)源碼就在類加載階段對(duì)目標(biāo)類進(jìn)行增強(qiáng)也正因如此很多團(tuán)隊(duì)都想做一個(gè)屬于自己的輕量 Agent 工具。不過(guò)絕大多數(shù)人剛接觸 Java Agent 時(shí)都會(huì)卡在字節(jié)碼操作、Instrumentation 機(jī)制、類加載器邊界這些問(wèn)題上寫出來(lái)的 Agent 經(jīng)常出現(xiàn)“不生效”“重復(fù)增強(qiáng)”“把應(yīng)用改崩了”之類的詭異現(xiàn)象。本文將圍繞 embabel 這類目標(biāo)驅(qū)動(dòng)的 Java Agent 開(kāi)發(fā)框架展開(kāi)先解釋 Java Agent 與目標(biāo)驅(qū)動(dòng)開(kāi)發(fā)的核心概念再通過(guò)一個(gè)可運(yùn)行的方法耗時(shí)監(jiān)控 Agent 實(shí)戰(zhàn)案例完整演示從工程搭建、目標(biāo)聲明、增強(qiáng)邏輯到運(yùn)行驗(yàn)證的全過(guò)程。文章還會(huì)整理高頻故障的排查思路和生產(chǎn)環(huán)境落地的注意事項(xiàng)。適合剛接觸 Java Agent 的讀者入門也適合正在設(shè)計(jì)內(nèi)部診斷組件的后端同學(xué)參考。1. 為什么 Java Agent 開(kāi)發(fā)如此繁瑣1.1 傳統(tǒng) Agent 開(kāi)發(fā)的“三座大山”如果一個(gè)團(tuán)隊(duì)打算自研一個(gè) Java Agent最常遇到的阻礙通常有三個(gè)。第一是字節(jié)碼操作門檻。JVM 加載類時(shí)ClassFileTransformer 會(huì)收到類的字節(jié)碼數(shù)組開(kāi)發(fā)者需要在這個(gè)數(shù)組上操作增加方法計(jì)時(shí)、打印入?yún)?、吞掉異常等邏輯。直接操作字?jié)碼不現(xiàn)實(shí)常用 ASM 或 ByteBuddy 這類庫(kù)來(lái)做。ASM 更底層性能好但代碼寫起來(lái)很繁瑣ByteBuddy 封裝程度高但對(duì)新手來(lái)說(shuō) API 依然有學(xué)習(xí)成本。第二是 Instrumentation 機(jī)制細(xì)節(jié)。Java 提供 premain 和 agentmain 兩種入口分別用于啟動(dòng)時(shí)增強(qiáng)和運(yùn)行時(shí) Attach 增強(qiáng)。要做運(yùn)行時(shí)增強(qiáng)還需要正確處理 retransform/redefine 的時(shí)機(jī)以及不同 JVM 版本對(duì) Can-Redefine-Classes、Can-Retransform-Classes 的限制。第三是類加載器邊界。同一個(gè)類可能被多個(gè) ClassLoader 加載Agent 中的增強(qiáng)類可能對(duì)目標(biāo)類的 ClassLoader 不可見(jiàn)一旦邊界處理不對(duì)要么增強(qiáng)不生效要么直接拋 NoClassDefFoundError。1.2 傳統(tǒng)方式寫一個(gè)方法耗時(shí)統(tǒng)計(jì)有多麻煩先看一個(gè)傳統(tǒng) ByteBuddy 方式的方法耗時(shí)統(tǒng)計(jì)樣例。雖然 ByteBuddy 已經(jīng)幫我們屏蔽了大量字節(jié)碼細(xì)節(jié)但開(kāi)發(fā)者仍然需要理解 AgentBuilder、Transformer、Advice 這些概念public class CostAgent { public static void premain(String arg, Instrumentation inst) { new AgentBuilder.Default() .type(ElementMatchers.nameStartsWith(com.example)) .transform((builder, typeDescription, classLoader, module, protectionDomain) - builder.visit(Advice.to(CostAdvice.class) .on(ElementMatchers.named(hello)))) .installOn(inst); } }這段代碼還不算復(fù)雜。真正復(fù)雜的是當(dāng)目標(biāo)類變成幾十個(gè)、方法變成幾百個(gè)、每個(gè)增強(qiáng)動(dòng)作還不太一樣時(shí)開(kāi)發(fā)者就不得不維護(hù)一堆類型匹配規(guī)則、方法匹配規(guī)則、Advice 類映射關(guān)系。可讀性和可維護(hù)性都會(huì)明顯下降。1.3 目標(biāo)驅(qū)動(dòng)換一種思考方式目標(biāo)驅(qū)動(dòng)開(kāi)發(fā)的核心思路是開(kāi)發(fā)者不再面向“字節(jié)碼增強(qiáng)規(guī)則”編程而是面向“我要增強(qiáng)誰(shuí)、增強(qiáng)后做什么”編程。開(kāi)發(fā)者只需要聲明目標(biāo)類、目標(biāo)方法、增強(qiáng)動(dòng)作框架負(fù)責(zé)把聲明翻譯成底層 Instrumentation 和字節(jié)碼增強(qiáng)邏輯。這個(gè)體驗(yàn)有點(diǎn)像我們?cè)?Spring 里通過(guò)注解聲明切面而不需要手寫 AOP 代理的生成邏輯。embabel 這類目標(biāo)驅(qū)動(dòng)框架就是要把 Java Agent 開(kāi)發(fā)從“底層機(jī)制編碼”提升到“目標(biāo)聲明與動(dòng)作編排”的層次從而降低 Agent 開(kāi)發(fā)門檻提升治理規(guī)則的可維護(hù)性。2. Java Agent 與目標(biāo)驅(qū)動(dòng)開(kāi)發(fā)的核心概念2.1 Java Agent 到底是什么Java Agent 是 JVM 對(duì)外提供的一種擴(kuò)展機(jī)制。開(kāi)發(fā)者可以編寫一個(gè)包含 premain 或 agentmain 方法的 JAR 包通過(guò)-javaagent:xxx.jar參數(shù)在應(yīng)用啟動(dòng)前掛載或者通過(guò) Attach API 在運(yùn)行期掛載到目標(biāo) JVM。掛載成功后Agent 可以獲得 Instrumentation 對(duì)象注冊(cè) ClassFileTransformer從而在 JVM 加載類或重新轉(zhuǎn)換類時(shí)修改字節(jié)碼。典型應(yīng)用場(chǎng)景包括性能監(jiān)控統(tǒng)計(jì)方法耗時(shí)、采集 JVM 指標(biāo)。鏈路追蹤自動(dòng)給 RPC 方法注入 traceId。故障診斷動(dòng)態(tài)打印參數(shù)、返回值和異常堆棧。熱修復(fù)替換某些方法的實(shí)現(xiàn)邏輯。增強(qiáng)框架在 Spring、MyBatis 等框架調(diào)用鏈路上增加邏輯。2.2 Premain 與 Agentmain 的區(qū)別入口方式掛載時(shí)機(jī)使用方式典型場(chǎng)景premainJVM 啟動(dòng)時(shí)main 方法執(zhí)行前-javaagent:xxx.jar靜態(tài)增強(qiáng)適合發(fā)布時(shí)統(tǒng)一掛載agentmainJVM 運(yùn)行中Attach API動(dòng)態(tài)掛載適合診斷已有進(jìn)程premain 的優(yōu)點(diǎn)是掛載時(shí)機(jī)早能在業(yè)務(wù)類加載前就完成 Transformer 注冊(cè)增強(qiáng)邏輯可控性高。agentmain 的優(yōu)點(diǎn)是無(wú)需重啟進(jìn)程但需要處理類重新轉(zhuǎn)換的問(wèn)題復(fù)雜度更高。目標(biāo)驅(qū)動(dòng)框架一般都會(huì)同時(shí)支持這兩種入口。2.3 目標(biāo)驅(qū)動(dòng)開(kāi)發(fā)框架解決了什么問(wèn)題目標(biāo)驅(qū)動(dòng)開(kāi)發(fā)框架解決的核心問(wèn)題是讓 Agent 增強(qiáng)邏輯更加“可聲明、可編排、可復(fù)用”。如果不使用目標(biāo)驅(qū)動(dòng)框架每增加一個(gè)增強(qiáng)目標(biāo)開(kāi)發(fā)者都要理解類型匹配器、方法匹配器、Advice 綁定規(guī)則、類加載器可見(jiàn)性。如果使用目標(biāo)驅(qū)動(dòng)框架增強(qiáng)目標(biāo)可以寫成類似下面這種結(jié)構(gòu)目標(biāo)類com.example.demo.HelloService目標(biāo)方法hello增強(qiáng)動(dòng)作方法進(jìn)入時(shí)記錄時(shí)間、方法退出時(shí)打印耗時(shí)這樣開(kāi)發(fā)者只需要專注增強(qiáng)動(dòng)作本身類型匹配、方法匹配、Advice 織入方式都由框架層統(tǒng)一處理。這也是“目標(biāo)驅(qū)動(dòng)”四個(gè)字的核心含義。3. 環(huán)境準(zhǔn)備與工程搭建3.1 基礎(chǔ)環(huán)境說(shuō)明本文實(shí)戰(zhàn)案例使用以下環(huán)境JDK 8 或更高版本Maven 3.6 以上操作系統(tǒng)Windows / macOS / Linux 均可字節(jié)碼操作庫(kù)ByteBuddy不同項(xiàng)目的 JDK 版本會(huì)存在差異實(shí)際開(kāi)發(fā)時(shí)應(yīng)根據(jù)線上運(yùn)行環(huán)境調(diào)整編譯源碼級(jí)別。本文示例統(tǒng)一使用 JDK 8 兼容的編譯方式方便在大多數(shù)存量項(xiàng)目中復(fù)現(xiàn)。3.2 Maven 工程結(jié)構(gòu)規(guī)劃為了讓 Agent 和被增強(qiáng)的應(yīng)用分離建議使用多模塊工程。本文的工程結(jié)構(gòu)如下javaagent-tutorial/ ├── agent-core/ │ ├── pom.xml │ └── src/main/java/com/example/agent/ │ ├── AgentMain.java │ ├── AgentAction.java │ ├── AgentTarget.java │ └── HelloCostAction.java │ └── src/main/resources/META-INF/services/com.example.agent.AgentAction └── demo-app/ ├── pom.xml └── src/main/java/com/example/demo/ ├── DemoApp.java └── HelloService.java模塊劃分的原則很簡(jiǎn)單agent-core 負(fù)責(zé) Agent 掛載和增強(qiáng)邏輯。demo-app 負(fù)責(zé)模擬一個(gè)普通業(yè)務(wù)應(yīng)用。這樣在運(yùn)行驗(yàn)證時(shí)可以清楚看到業(yè)務(wù)應(yīng)用本身沒(méi)有做任何修改增強(qiáng)完全來(lái)自 Agent。3.3 manifest 配置說(shuō)明一個(gè) Java Agent JAR 包必須在 manifest 中聲明 Premain-Class 等信息否則 JVM 不會(huì)識(shí)別它的 Agent 身份。常用配置項(xiàng)如下配置項(xiàng)作用Premain-Classpremain 入口類的全限定名Agent-Classagentmain 入口類的全限定名Can-Redefine-Classes是否允許重新定義類Can-Retransform-Classes是否允許重新轉(zhuǎn)換類本文示例使用 premain 方式所以重點(diǎn)配置 Premain-Class。如果需要?jiǎng)討B(tài)掛載還需要在 manifest 中增加 Agent-Class 配置。4. embabel 目標(biāo)驅(qū)動(dòng)的核心抽象4.1 目標(biāo)聲明的表示方式在目標(biāo)驅(qū)動(dòng)框架中目標(biāo)聲明通常包含三部分信息目標(biāo)類的全限定名、目標(biāo)方法名、處理動(dòng)作?；谧⒔饪梢赃@樣表達(dá)AgentTarget(className com.example.demo.HelloService, method hello) public class HelloCostAction implements AgentAction { }框架層通過(guò)讀取注解拿到字符串形式的目標(biāo)類名和目標(biāo)方法名再將其翻譯成 ByteBuddy 能識(shí)別的匹配規(guī)則。這樣做的好處是目標(biāo)信息與動(dòng)作代碼放在同一個(gè)類上一眼就能看出這個(gè)動(dòng)作要增強(qiáng)誰(shuí)。4.2 動(dòng)作編排攔截后做什么動(dòng)作編排是目標(biāo)驅(qū)動(dòng)框架最體現(xiàn)設(shè)計(jì)價(jià)值的部分。一個(gè)增強(qiáng)動(dòng)作通?？梢圆鸱殖蓛蓚€(gè)階段方法進(jìn)入階段在目標(biāo)方法執(zhí)行前執(zhí)行可以記錄開(kāi)始時(shí)間、打印入?yún)?、修改參?shù)、控制是否繼續(xù)執(zhí)行。方法退出階段在目標(biāo)方法正常返回或拋異常后執(zhí)行可以記錄耗時(shí)、打印返回值、上傳異常信息。在 ByteBuddy Advice 中對(duì)應(yīng)的是 Advice.OnMethodEnter 和 Advice.OnMethodExit 兩個(gè)注解方法。目標(biāo)驅(qū)動(dòng)框架要做的就是把這些動(dòng)作編排能力封裝成統(tǒng)一接口讓開(kāi)發(fā)者不用關(guān)心 ByteBuddy 細(xì)節(jié)。4.3 生命周期與上下文傳遞生產(chǎn)級(jí)目標(biāo)驅(qū)動(dòng)框架不只是簡(jiǎn)單做一次方法織入它還需要考慮生命周期和上下文傳遞。例如多個(gè)增強(qiáng)動(dòng)作之間存在順序要求時(shí)如何編排執(zhí)行順序。方法進(jìn)入階段產(chǎn)生的臨時(shí)數(shù)據(jù)如何傳遞到方法退出階段。同一個(gè)類被多個(gè) Agent 或者自身重復(fù)匹配時(shí)如何避免重復(fù)增強(qiáng)。這些都屬于目標(biāo)驅(qū)動(dòng)框架的工程化能力。開(kāi)發(fā)者在選擇框架時(shí)應(yīng)該重點(diǎn)考察這些能力而不只是看它能不能做一次方法耗時(shí)打印。4.4 目標(biāo)驅(qū)動(dòng)與 AOP 的異同目標(biāo)驅(qū)動(dòng) Agent 和 AOP 都解決“在不改動(dòng)業(yè)務(wù)代碼的前提下增強(qiáng)邏輯”的問(wèn)題但它們的作用層不同。AOP 通常在應(yīng)用啟動(dòng)后由 Spring 容器生成代理對(duì)象目標(biāo)驅(qū)動(dòng) Agent 則通過(guò) JVM Instrumentation 在類加載階段修改字節(jié)碼。后者不依賴 Spring 容器也不需要被增強(qiáng)類實(shí)現(xiàn)接口或允許繼承對(duì)第三方 Jar 包內(nèi)部的方法也可以生效。這決定了目標(biāo)驅(qū)動(dòng) Agent 更適合做框架級(jí)增強(qiáng)、線上診斷、統(tǒng)一治理這類場(chǎng)景。5. 完整實(shí)戰(zhàn)構(gòu)建一個(gè)方法耗時(shí)監(jiān)控 Agent5.1 場(chǎng)景拆解本文實(shí)戰(zhàn)案例要完成的任務(wù)是不修改 HelloService 的任何代碼給 hello 方法增加耗時(shí)統(tǒng)計(jì)并在方法進(jìn)入和退出時(shí)打印日志。先編寫 agent-core 模塊的 pom.xml?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdagent-core/artifactId version1.0.0/version packagingjar/packaging properties maven.compiler.source8/maven.compiler.source maven.compiler.target8/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding bytebuddy.version1.14.9/bytebuddy.version /properties dependencies dependency groupIdnet.bytebuddy/groupId artifactIdbyte-buddy/artifactId version${bytebuddy.version}/version /dependency dependency groupIdnet.bytebuddy/groupId artifactIdbyte-buddy-agent/artifactId version${bytebuddy.version}/version /dependency /dependencies build plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-shade-plugin/artifactId version3.4.1/version executions execution phasepackage/phase goals goalshade/goal /goals configuration transformers transformer implementationorg.apache.maven.plugins.shade.resource.ManifestResourceTransformer manifestEntries Premain-Classcom.example.agent.AgentMain/Premain-Class Can-Redefine-Classestrue/Can-Redefine-Classes Can-Retransform-Classestrue/Can-Retransform-Classes /manifestEntries /transformer /transformers /configuration /execution /executions /plugin /plugins /build /project這里有一個(gè)關(guān)鍵點(diǎn)Agent JAR 打包時(shí)需要把 ByteBuddy 依賴一起打進(jìn)最終 JAR否則應(yīng)用啟動(dòng)時(shí)雖然能加載 AgentMain但找不到 net.bytebuddy 相關(guān)的類。maven-shade-plugin 的作用就是把依賴整合到一個(gè) JAR 里。版本說(shuō)明ByteBuddy 版本建議以你實(shí)際項(xiàng)目中測(cè)試過(guò)的穩(wěn)定版本為準(zhǔn)不同大版本的 Agent API 可能略有差異。5.2 agent-core 模塊實(shí)現(xiàn)首先定義目標(biāo)注解 AgentTarget它是“目標(biāo)驅(qū)動(dòng)”的可視化入口package com.example.agent; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * 目標(biāo)驅(qū)動(dòng)聲明標(biāo)記一個(gè) Agent 動(dòng)作要增強(qiáng)哪個(gè)類的哪個(gè)方法。 */ Retention(RetentionPolicy.RUNTIME) Target(ElementType.TYPE) public interface AgentTarget { String className(); String method(); }接著定義動(dòng)作標(biāo)記接口 AgentAction。這個(gè)接口不定義任何必須實(shí)現(xiàn)的方法作用是讓框架能夠通過(guò) ServiceLoader 統(tǒng)一加載所有增強(qiáng)動(dòng)作package com.example.agent; /** * Agent 動(dòng)作標(biāo)記接口。 */ public interface AgentAction { }接下來(lái)是核心入口 AgentMain。它讀取 ServiceLoader 加載到的所有 AgentAction解析目標(biāo)注解并將其翻譯成 ByteBuddy 匹配和織入邏輯package com.example.agent; import net.bytebuddy.agent.builder.AgentBuilder; import net.bytebuddy.asm.Advice; import net.bytebuddy.description.type.TypeDescription; import net.bytebuddy.dynamic.DynamicType; import net.bytebuddy.matcher.ElementMatchers; import net.bytebuddy.utility.JavaModule; import java.lang.instrument.Instrumentation; import java.security.ProtectionDomain; import java.util.ServiceLoader; /** * Agent 啟動(dòng)入口。 */ public class AgentMain { public static void premain(String arg, Instrumentation inst) { AgentBuilder agentBuilder new AgentBuilder.Default() .disableClassFormatChanges() .with(AgentBuilder.RedefinitionStrategy.RETRANSFORMATION); ServiceLoaderAgentAction actions ServiceLoader.load(AgentAction.class); for (AgentAction action : actions) { AgentTarget target action.getClass().getAnnotation(AgentTarget.class); if (target null) { System.out.println([agent] skip action without AgentTarget: action.getClass().getName()); continue; } agentBuilder agentBuilder .type(ElementMatchers.named(target.className())) .transform(new AgentBuilder.Transformer() { Override public DynamicType.Builder? transform( DynamicType.Builder? builder, TypeDescription typeDescription, ClassLoader classLoader, JavaModule module, ProtectionDomain protectionDomain) { return builder.visit(Advice.to(action.getClass()) .on(ElementMatchers.named(target.method()))); } }); System.out.println([agent] register target: target.className() # target.method() - action.getClass().getName()); } agentBuilder.installOn(inst); System.out.println([agent] target-driven agent installed successfully.); } }這段代碼最需要理解的是 ServiceLoader 的使用方式。目標(biāo)驅(qū)動(dòng)的動(dòng)作類不通過(guò)硬編碼注冊(cè)而是通過(guò)META-INF/services/com.example.agent.AgentAction文件聲明這樣新增一個(gè)增強(qiáng)動(dòng)作時(shí)不需要改動(dòng) AgentMain 的注冊(cè)代碼符合開(kāi)閉原則。再來(lái)看 HelloCostAction它就是我們要執(zhí)行的增強(qiáng)動(dòng)作。package com.example.agent; import net.bytebuddy.asm.Advice; /** * 方法耗時(shí)統(tǒng)計(jì)動(dòng)作示例。 */ AgentTarget(className com.example.demo.HelloService, method hello) public class HelloCostAction implements AgentAction { Advice.OnMethodEnter public static long enter(Advice.Origin(#t.#m) String method) { System.out.println([embabel-example] enter method); return System.nanoTime(); } Advice.OnMethodExit(onThrowable Throwable.class) public static void exit(Advice.Origin(#t.#m) String method, Advice.Enter long startNanos, Advice.Return Object result, Advice.Thrown Throwable throwable) { long costUs (System.nanoTime() - startNanos) / 1000; System.out.println([embabel-example] exit method , costUs costUs , result result , throwable throwable); } }這里的幾個(gè)注解參數(shù)需要重點(diǎn)解釋Advice.Origin 可以拿到被增強(qiáng)方法的原始描述信息#t.#m表示“類型名.方法名”。Advice.Enter 可以拿到 OnMethodEnter 方法的返回值這里是把方法進(jìn)入時(shí)間傳遞給退出階段。Advice.Return 是目標(biāo)方法的返回值如果目標(biāo)方法拋異常這個(gè)值會(huì)是 null。Advice.Thrown 是目標(biāo)方法拋出的異常沒(méi)有異常時(shí)是 null。為了讓 ServiceLoader 識(shí)別 HelloCostAction還需要在 resources 目錄下創(chuàng)建服務(wù)文件。文件路徑agent-core/src/main/resources/META-INF/services/com.example.agent.AgentAction內(nèi)容com.example.agent.HelloCostAction5.3 被監(jiān)控的示例應(yīng)用先編寫 demo-app 模塊的 pom.xml?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIddemo-app/artifactId version1.0.0/version packagingjar/packaging properties maven.compiler.source8/maven.compiler.source maven.compiler.target8/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties build plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-jar-plugin/artifactId version3.3.0/version configuration archive manifest mainClasscom.example.demo.DemoApp/mainClass /manifest /archive /configuration /plugin /plugins /build /project創(chuàng)建 HelloServicepackage com.example.demo; public class HelloService { public String hello(String name) { if (slow.equals(name)) { try { Thread.sleep(500); } catch (InterruptedException e) { Thread.currentThread().interrupt(); } } return hello name; } }創(chuàng)建應(yīng)用入口 DemoApppackage com.example.demo; public class DemoApp { public static void main(String[] args) throws Exception { HelloService service new HelloService(); System.out.println(service.hello(embabel)); System.out.println(service.hello(slow)); } }這個(gè)應(yīng)用本身非常簡(jiǎn)單只是一個(gè)包含普通方法和 sleep 的業(yè)務(wù)類。接下來(lái)我們要驗(yàn)證不修改任何業(yè)務(wù)代碼Agent 就能自動(dòng)給 hello 方法增加耗時(shí)統(tǒng)計(jì)。5.4 構(gòu)建與運(yùn)行先構(gòu)建 agent-corecd agent-core mvn clean package -DskipTests再構(gòu)建 demo-appcd ../demo-app mvn clean package -DskipTests最后用 javaagent 參數(shù)啟動(dòng)應(yīng)用java -javaagent:../agent-core/target/agent-core-1.0.0.jar -jar target/demo-app-1.0.0.jar如果你的工程目錄結(jié)構(gòu)與本文不完全一致注意把-javaagent的路徑換成實(shí)際 agent JAR 的絕對(duì)路徑或相對(duì)路徑。6. 運(yùn)行與驗(yàn)證6.1 預(yù)期輸出正常運(yùn)行后控制臺(tái)輸出大致如下[agent] register target: com.example.demo.HelloService#hello - com.example.agent.HelloCostAction [agent] target-driven agent installed successfully. [embabel-example] enter com.example.demo.HelloService.hello [embabel-example] exit com.example.demo.HelloService.hello, costUsxxx, resulthello embabel, throwablenull hello embabel [embabel-example] enter com.example.demo.HelloService.hello [embabel-example] exit com.example.demo.HelloService.hello, costUs500xxx, resulthello slow, throwablenull hello slow6.2 驗(yàn)證 Agent 確實(shí)生效如果輸出中出現(xiàn)了[embabel-example]日志說(shuō)明 Agent 已經(jīng)成功織入目標(biāo)方法。此時(shí)我們不需要在 DemoApp 中打印任何額外日志Agent 的增強(qiáng)邏輯已經(jīng)生效。還可以進(jìn)一步驗(yàn)證不添加任何 Agent 參數(shù)直接啟動(dòng) DemoApp輸出中不會(huì)有[embabel-example]日志這能幫助確認(rèn)增強(qiáng)邏輯完全來(lái)自 Java Agent。6.3 常見(jiàn)變體在實(shí)際項(xiàng)目中你可能需要同時(shí)監(jiān)控多個(gè)類、多個(gè)方法或者在同一方法上執(zhí)行多個(gè)動(dòng)作。目標(biāo)驅(qū)動(dòng)框架的思路是增加更多帶 AgentTarget 注解的 Action 類并在 ServiceLoader 文件中注冊(cè)對(duì)應(yīng)實(shí)現(xiàn)類注冊(cè)邏輯不需要改動(dòng)。7. 常見(jiàn)問(wèn)題與排查思路目標(biāo)驅(qū)動(dòng) Agent 雖然降低了開(kāi)發(fā)門檻但底層仍然是 JVM Instrumentation 和字節(jié)碼增強(qiáng)線上運(yùn)行時(shí)不缺各種問(wèn)題。下面整理一張常見(jiàn)故障速查表。問(wèn)題現(xiàn)象常見(jiàn)原因解決思路Agent 啟動(dòng)日志都沒(méi)打印JAR 未配置 Premain-Class或 javaagent 路徑錯(cuò)誤檢查 manifest 中 Premain-Class修正路徑增強(qiáng)方法沒(méi)有生效目標(biāo)類名、方法名匹配不上或類加載器不同確認(rèn)全限定名和加載器調(diào)整匹配范圍拋 ClassNotFoundException增強(qiáng)動(dòng)作類對(duì)目標(biāo)類的 ClassLoader 不可見(jiàn)將動(dòng)作類放入可見(jiàn)類加載器或使用委托機(jī)制方法被重復(fù)增強(qiáng)多個(gè) Agent 或重復(fù)注冊(cè)了 Transformer加冪等保護(hù)檢查重復(fù)掛載情況啟動(dòng)后應(yīng)用變慢增強(qiáng)方法范圍過(guò)大或動(dòng)作邏輯太重縮小目標(biāo)范圍異步化處理最少化增強(qiáng)邏輯retransform 拋出異常類格式變化被拒絕或與 JVM 參數(shù)沖突檢查 Can-Retransform-Classes關(guān)閉 disableClassFormatChanges7.1 Agent 啟動(dòng)日志都沒(méi)打印首先確認(rèn) manifest 里有沒(méi)有 Premain-Class?？梢詧?zhí)行命令查看unzip -p agent-core-1.0.0.jar META-INF/MANIFEST.MF也能直接檢查agent-path是否誤寫成 jar 內(nèi)目錄。另外Agent 通常會(huì)在 main 方法之前執(zhí)行如果 premain 方法內(nèi)部拋了異常會(huì)有明確堆棧需要優(yōu)先處理這類報(bào)錯(cuò)。7.2 增強(qiáng)方法沒(méi)有生效比較常見(jiàn)的原因有三個(gè)目標(biāo)類名不是完整二進(jìn)制名例如把com.example.demo.HelloService寫成了HelloService。方法名不匹配ByteBuddy 默認(rèn)匹配精確方法名重載方法需要額外聲明參數(shù)類型。目標(biāo)類由自定義 ClassLoader 加載Agent 匹配規(guī)則沒(méi)有覆蓋到該 ClassLoader。生產(chǎn)環(huán)境排查時(shí)可以先在 premain 里打印注冊(cè)日志再通過(guò)-verbose:class日志確認(rèn)目標(biāo)類的加載情況觀察 Transformer 是否被觸發(fā)。7.3 拋 ClassNotFoundException當(dāng)被增強(qiáng)的類位于自定義 ClassLoader 中比如 Tomcat 的 WebAppClassLoader而 Action 類在 Agent JAR 中時(shí)目標(biāo)類加載器可能無(wú)法加載 Action 類。普通java -jar應(yīng)用一般沒(méi)有這個(gè)問(wèn)題但容器類應(yīng)用需要注意。解決方法是把動(dòng)作相關(guān)類放到能被目標(biāo)類加載器看到的 ClassLoader 中或者使用類加載器委托策略讓增強(qiáng)代碼在正確的加載器上下文中執(zhí)行。7.4 方法被重復(fù)增強(qiáng)重復(fù)增強(qiáng)多發(fā)生在同一個(gè) Agent 重復(fù)掛載或者多個(gè) Agent 都注冊(cè)了相同目標(biāo)的 Transformer。目標(biāo)驅(qū)動(dòng)框架里可以通過(guò)維護(hù)一個(gè)全局注冊(cè)表在 register 時(shí)檢查目標(biāo)是否已經(jīng)注冊(cè)避免重復(fù)織入。生產(chǎn)環(huán)境也應(yīng)該約定一個(gè)唯一標(biāo)識(shí)防止多個(gè)實(shí)例同時(shí)掛載同一個(gè) Agent 時(shí)互相影響。7.5 啟動(dòng)后應(yīng)用變慢Java Agent 增強(qiáng)邏輯運(yùn)行在業(yè)務(wù)線程中如果動(dòng)作里做了比較重的 IO、鎖等待或遠(yuǎn)程調(diào)用業(yè)務(wù)接口 RT 就會(huì)明顯上升。目標(biāo)驅(qū)動(dòng)框架適合做輕量級(jí)增強(qiáng)耗時(shí)統(tǒng)計(jì)之外參數(shù)采集、日志輸出都應(yīng)盡量異步和降級(jí)。必要時(shí)可以增加開(kāi)關(guān)在業(yè)務(wù)低峰期開(kāi)啟。8. 生產(chǎn)環(huán)境最佳實(shí)踐8.1 最小化增強(qiáng)范圍目標(biāo)驅(qū)動(dòng)框架提供了目標(biāo)匹配能力但開(kāi)發(fā)者不能因此濫用。建議只增強(qiáng)必要的方法不要整包掃描、全量增強(qiáng)。增強(qiáng)范圍過(guò)大不僅影響性能還會(huì)增大類加載階段的風(fēng)險(xiǎn)。可以用“白名單”思路控制目標(biāo)范圍只列出確需增強(qiáng)的類和方法其他一律排除。上線前最好在預(yù)發(fā)環(huán)境做一次全鏈路回歸觀察核心接口耗時(shí)變化。8.2 動(dòng)作邏輯保持輕量Agent 動(dòng)作在目標(biāo)方法調(diào)用鏈路上執(zhí)行任何阻塞操作都會(huì)反向影響業(yè)務(wù)。增強(qiáng)動(dòng)作應(yīng)該具備以下特點(diǎn)不執(zhí)行遠(yuǎn)程調(diào)用。不申請(qǐng)長(zhǎng)時(shí)間鎖。不批量創(chuàng)建大對(duì)象。不做大日志輸出。如果確實(shí)需要上傳數(shù)據(jù)建議統(tǒng)一寫入一個(gè)內(nèi)存隊(duì)列由獨(dú)立線程異步消費(fèi)。8.3 可觀測(cè)性日志、指標(biāo)、鏈路Agent 本身也應(yīng)該被觀測(cè)。建議在 Agent 層補(bǔ)充以下能力啟動(dòng)成功/失敗日志。目標(biāo)匹配統(tǒng)計(jì)。動(dòng)作執(zhí)行失敗計(jì)數(shù)。增強(qiáng)耗時(shí)上報(bào)。這能幫助你在 Agent 不出問(wèn)題時(shí)快速發(fā)現(xiàn)出了問(wèn)題時(shí)快速定位。8.4 灰度與快速回滾生產(chǎn)環(huán)境掛載 Java Agent 本質(zhì)上是在線修改字節(jié)碼風(fēng)險(xiǎn)不可完全忽略。上線前必須先在一組低流量節(jié)點(diǎn)驗(yàn)證再逐步擴(kuò)大范圍。接線時(shí)最好保留兩組發(fā)布配置一組開(kāi)啟 Agent一組不開(kāi)啟 Agent。一旦發(fā)現(xiàn) Agent 導(dǎo)致異?？梢钥焖偻ㄟ^(guò)配置中心切換回滾。8.5 安全與最小權(quán)限對(duì)線上應(yīng)用做字節(jié)碼增強(qiáng)需要遵循最小權(quán)限原則只讀類信息時(shí)不進(jìn)行類定義。只在必要方法上織入邏輯。不在 Agent 邏輯中保存業(yè)務(wù)敏感參數(shù)。Agent 包發(fā)布前經(jīng)過(guò)代碼評(píng)審避免內(nèi)部邏輯成為攻擊面。如果你在生產(chǎn)環(huán)境需要臨時(shí)排查問(wèn)題優(yōu)先考慮使用動(dòng)態(tài)掛載的 agentmain而不是直接改動(dòng)業(yè)務(wù)代碼。9. 總結(jié)與后續(xù)學(xué)習(xí)建議通過(guò)本文的講解和實(shí)戰(zhàn)我們圍繞 embabel 這類目標(biāo)驅(qū)動(dòng)的 Java Agent 開(kāi)發(fā)框架拆解了目標(biāo)驅(qū)動(dòng)帶來(lái)的變化開(kāi)發(fā)者只需聲明目標(biāo)類、目標(biāo)方法再編寫增強(qiáng)動(dòng)作框架層負(fù)責(zé)將目標(biāo)翻譯成 Instrumentation 與字節(jié)碼增強(qiáng)邏輯。在實(shí)戰(zhàn)部分我們用 ByteBuddy 結(jié)合 ServiceLoader搭建了一個(gè)可運(yùn)行的方法耗時(shí)監(jiān)控 Agent。這個(gè)示例雖然不復(fù)雜但它完整展示了目標(biāo)驅(qū)動(dòng) Agent 的核心流程注解聲明目標(biāo)、動(dòng)作類承載增強(qiáng)邏輯、ServiceLoader 自動(dòng)注冊(cè)、premain 入口完成織入。如果你接下來(lái)要繼續(xù)深入學(xué)習(xí)建議按以下路徑推進(jìn)掌握 ASM 和 ByteBuddy 的匹配器 API理解字節(jié)碼增強(qiáng)邊界。研究 agentmain 動(dòng)態(tài)掛載技術(shù)配合 Attach API 實(shí)現(xiàn)生產(chǎn)環(huán)境局部增強(qiáng)。在 Agent 中增加指標(biāo)上報(bào)和降級(jí)開(kāi)關(guān)往生產(chǎn)級(jí)組件靠近。閱讀 SkyWalking、Arthas 等開(kāi)源項(xiàng)目的 Agent 設(shè)計(jì)思路體會(huì)底層機(jī)制。回到目標(biāo)驅(qū)動(dòng)這個(gè)話題真正適合生產(chǎn)環(huán)境的 Java Agent 開(kāi)發(fā)框架不只是讓新手能寫幾行示例代碼而是能在復(fù)雜類加載環(huán)境、高并發(fā)場(chǎng)景和灰度回滾訴求下讓增強(qiáng)邏輯變得可控、可觀測(cè)、可維護(hù)。如果你也在設(shè)計(jì)內(nèi)部診斷組件可以先從最小目標(biāo)開(kāi)始驗(yàn)證再逐步把發(fā)布和回滾流程補(bǔ)起來(lái)。