Spring Boot 应用在微服务链路中往往处于承上启下的位置，一次请求从前端到后端可能经过多个服务实例、消息队列和数据库。只依靠 logback 或 ELK 中的单点日志，很难还原请求在各个环节的耗时与依赖关系。SkyWalking 提供了 Java Agent 级别的探针，应用无需改动业务代码，即可在启动时增强字节码，采集 HTTP、数据库、缓存、消息队列等常见组件的调用数据，并生成全局唯一的 TraceId。
一、SkyWalking 的核心链路采集原理
SkyWalking 主要由探针（Agent）、后端 OAP 服务、存储引擎和 UI 四部分组成。探针以 -javaagent 参数挂载到 Spring Boot 应用上，启动时通过字节码增强在类加载阶段改写目标方法。由于改写发生在 JVM 内部，业务代码不需要引入任何 SkyWalking 依赖，也不需要实现拦截器接口。
当请求进入应用的 HTTP 入口，探针会创建一条 Trace 并生成 TraceId。随后在调用 RestTemplate、FeignClient、MyBatis 或数据库驱动时，探针继续记录每个跨进程调用或本地方法的耗时、状态码、SQL 文本等信息。这些数据会异步批量上报到 OAP 服务，OAP 负责聚合指标、生成拓扑和保存链路明细。UI 通过查询接口按 TraceId 展示调用瀑布图，让开发者能快速定位慢在哪个方法或网络节点。
这种机制的优势是接入成本极低，但也要注意它依赖字节码增强，如果应用使用了自定义类加载器或强制关闭了某些 JDK 模块，可能需要调整探针的增强范围。对于 Spring Boot 内嵌 Tomcat 和常规微服务框架，默认配置通常开箱即用。
二、Spring Boot 接入 SkyWalking Agent 的完整步骤
接入的第一步是获取与当前 Java 版本匹配的 SkyWalking Agent。可以从官方发布页下载压缩包，也可以通过 Docker 镜像中的 agent 目录挂载到宿主机。解压后的主要目录包括 skywalking-agent.jar 和 config/agent.config。不需要在 pom.xml 中增加任何 SkyWalking 依赖，这是与 Micrometer 或 OpenTelemetry SDK 方案最大的区别。
启动 Spring Boot 应用时，只需要在 java 命令中追加 -javaagent 参数。例如在 Linux 或 macOS 下可以这样写：
java -javaagent:/opt/skywalking-agent/skywalking-agent.jar \
-Dskywalking.agent.service_name=order-service \
-Dskywalking.collector.backend_service=127.0.0.1:11800 \
-jar order-service.jar
这里通过 JVM 参数直接覆盖配置，service_name 必须为每个服务设置不同值，它在 UI 中同时用于应用列表、拓扑节点和告警分组。如果通过 IDE 启动，可以把同样的 JVM 参数写入 IDEA 的 VM options。容器化部署时建议将 agent 目录打入镜像，或通过 Kubernetes 的 initContainer 把 agent 文件复制到共享卷。
如果需要用环境变量替代 JVM 参数，可以在 agent.config 中使用占位符形式。SkyWalking Agent 支持从系统属性和环境变量读取配置，常见配置项如下：
agent.service_name=${SW_AGENT_NAME:order-service}
agent.namespace=${SW_NAMESPACE:default}
collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:127.0.0.1:11800}
logging.file_name=${SW_LOGGING_FILE_NAME:skywalking-api.log}
logging.level=${SW_LOGGING_LEVEL:INFO}
这段配置的意思是优先读取环境变量，未设置时使用冒号后的默认值。使用 ${SW_AGENT_NAME:order-service} 时，如果启动参数同时存在，启动参数优先级更高。接入完成后启动应用，正常情况下控制台会输出 SkyWalking Agent 加载的类数量，或者在 UI 中出现新的服务名称。
三、去掉噪音数据与提高链路可读性
启动接入后，很多团队会立刻发现 UI 中涌入了大量健康检查、静态资源和定时探活请求。Spring Boot Actuator 的 /actuator/health 可能每几秒被 Kubernetes 或负载均衡调用一次，这些请求会让拓扑看起来非常混乱，并且增加存储成本。可以通过探针的忽略规则把这些路径排除在链路采集之外。
SkyWalking 提供了 agent.ignore_suffix、trace.ignore_path 和 plugin.springmvc.collect_http_params 等配置。例如下面配置会忽略常见静态资源和健康检查路径，同时只采集指定长度的参数，避免敏感信息进入链路：
agent.ignore_suffix=.jpg,.jpeg,.png,.css,.js,.ico trace.ignore_path=/actuator/health,/actuator/**,/api/health plugin.springmvc.collect_http_params=true plugin.springmvc.http.params_length_threshold=256
注意 trace.ignore_path 支持 Ant 风格匹配，** 可以覆盖多级路径。配置生效后，被忽略的路径不会再产生 Trace 数据，但应用本身的请求计数和 CPU 指标仍然保留。
除此之外，如果应用同时接入了日志系统，建议开启日志关联。SkyWalking 可以通过 toolkit 把 TraceId 放进 logback 或 log4j2 的 MDC 中。不过该功能需要在 pom.xml 里引入 apm-toolkit-logback-1.x 等可选依赖，并在日志配置中增加 %tid 占位符。这样在日志平台里搜索 TraceId，就能把一条错误的堆栈错误和对应链路绑定起来。
四、性能影响分析与采样策略
引入探针不可避免地会增加少量 CPU 和内存开销。SkyWalking Agent 默认开启全量链路采集，但在请求体很大的上传接口或高频循环调用中，什么对象需要记录、记录多少字段，会直接影响性能。通常建议配合采样率控制，例如将 agent.sample_n_per_3_secs 设置为负数表示全部采样，设置为正数则限制每 3 秒的最大 Trace 数量。对于非核心链路，可以设置为 1000，保证异常流量时不至于把后台压垮。
另一个容易忽略的问题是大响应体的采集。默认情况下，探针不会记录完整的 HTTP 请求体和响应体，但如果某些错误分析需要看到请求参数，可以单独开启 plugin.springmvc.collect_http_params 并限制长度。对于 MySQL、Redis 等插件，也可以调整 SQL 长度和参数记录，防止一条大字段 SQL 把链路明细撑得过大。
建议在生产环境先小规模接入，对比启动时间、GC 频率和接口 P95 延迟的变化。SkyWalking 自身也提供了 JVM 指标，可以直接观察探针带来的额外内存占用。一般来说，单个服务多几十 MB 到一百多 MB 的内存是常见范围，如果发现异常增长，优先检查是否开启了过大的参数采集或日志输出级别过高。
Spring BootSkyWalking全链路追踪修改时间：2026-10-03 03:12:34