Java开发如何配置链路追踪环境_SkyWalking探针本地挂载-java教程-PHP中文网

最常见的原因是路径错误或未下载探针包；需手动下载完整SkyWalking包并解压获取skywalking-agent.jar，使用绝对路径配置-javaagent，注意JDK版本兼容性、插件缺失及ClassLoader干扰问题。

java开发如何配置链路追踪环境_skywalking探针本地挂载

Java应用启动时找不到`skywalking-agent.jar`

本地挂载探针失败，最常见的原因是路径写错或 jar 包根本没下载。SkyWalking 探针不是 JDK 自带组件，必须手动下载对应版本的 apache-skywalking-apm-bin 压缩包，解压后才能拿到 agent/skywalking-agent.jar。

别从 Maven 仓库直接找 skywalking-agent.jar —— 它不单独发布，只随完整包分发
确认 Java 应用启动命令里 -javaagent: 后面的路径是绝对路径，或相对于启动脚本所在目录的正确相对路径（推荐绝对路径，避免歧义）
Windows 下路径含空格或中文会静默失败，建议把 agent 放到 C:/sw-agent/ 这类干净路径下
如果用 IDE（如 IntelliJ）运行，得在 Run Configuration → VM options 里加参数，而不是改 shell 脚本

配置`agent.config`后服务上报数据但链路不完整

探针加载成功、也能连上 OAP，但 UI 里只有入口 Span，下游 HTTP 调用、DB 查询全没了 —— 这大概率是插件没生效，不是配置文件本身的问题。

agent.config 中的 agent.service_name 必须唯一且不含下划线（下划线会被转成连字符，导致服务名归并异常）
检查 agent/plugins/ 目录：Spring Web、OkHttp、MySQL JDBC 等插件 jar 是按需加载的，删掉不用的插件不会影响功能，但漏掉关键插件（比如没放 mysql-8-plugin.jar 却用了 MySQL 8 驱动）就会丢 DB Span
Java Agent 的字节码增强依赖类加载顺序，若应用用了自定义 ClassLoader（如某些老框架或热部署工具），可能绕过探针 —— 可临时加 agent.is_open_debugging_class_transformer=true 查日志确认是否增强成功

本地调试时`java.lang.instrument.IllegalClassFormatException`

这个错误通常出现在用了较新 JDK（如 JDK 17+）但探针版本太旧，或者应用用了 GraalVM、JLink 等定制化运行时环境。

java-api-doc-generator

分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。

下载

SkyWalking 9.3.0 开始才正式支持 JDK 17，低于该版本的 agent 在 JDK 17+ 上会抛 IllegalClassFormatException；查清你用的 SkyWalking 服务端版本，下载对应 agent（比如 OAP 是 9.4.0，就用 9.4.0 的 agent）
若项目用了 Lombok，确保 lombok.jar 在 classpath 中位置靠前，否则 agent 可能先尝试增强未脱糖的 AST，触发格式异常
禁用特定类增强可临时绕过：在 agent.config 加 agent.ignore_suffix=.jar,.war 或用 plugin.springmvc-annotation-class-define 类似配置缩小增强范围

IDEA 启动 Spring Boot 时探针不生效

命令行启动没问题，IDEA 里跑却看不到 trace，问题往往出在启动方式和类路径隔离上。

不要勾选 Build and run in debug mode 下的 Enable coverage —— JaCoCo 代理和 SkyWalking 代理冲突，会互相干扰字节码操作
确保 Run Configuration → Environment variables 里没设置 SW_AGENT_COLLECTOR_BACKEND_SERVICES 指向错误地址（比如填了 localhost:11800 但本地 OAP 实际监听 127.0.0.1:11800，某些系统 resolve 不一致）
Spring Boot DevTools 默认启用 restart classloader，会导致 agent 初始化一次后被丢弃；加 spring.devtools.restart.enabled=false 或把 agent 参数加到 Preferences → Build → Compiler → Java Compiler → Additional command line parameters（不推荐，仅临时排查）

真正麻烦的是混合环境：比如本地同时跑多个微服务，共用一个 OAP，但某个服务用了 Netty + 自定义 HTTP 客户端，又没对应插件 —— 这时候链路断点不在配置，而在字节码增强的边界上。得看 agent/logs/skywalking-api.log 里有没有 transform class xxx failed，而不是只盯着 UI 刷不出来。