文章目录
-
- 一、开篇:第26课留下的“盲区”
- 二、分布式追踪理论基础
-
- 2.1 Dapper论文的核心思想
- 2.2 三大核心概念:Trace、Segment、Span
- 2.3 上下文传播:跨服务追踪的核心
- 2.1 Dapper论文的核心思想
- 三、SkyWalking架构深度剖析
-
- 3.1 四层架构:Probe → OAP → Storage → UI
- 3.2 核心数据模型
- 3.3 Java Agent的字节码增强原理
- 3.1 四层架构:Probe → OAP → Storage → UI
- 四、SkyWalking部署实战
-
- 4.1 Docker Quick Start部署
- 4.2 验证部署
- 4.1 Docker Quick Start部署
- 五、Java Agent探针配置
-
- 5.1 下载Agent
- 5.2 核心配置项
- 5.3 配置覆盖优先级
- 5.4 Spring Boot应用的启动配置
- 5.5 Gateway与OpenFeign的链路透传
- 5.6 日志中注入TraceID
- 5.1 下载Agent
- 六、调用链路分析与拓扑图实战
-
- 6.1 验证链路数据
- 6.2 拓扑图解读
- 6.3 链路详情分析
- 6.4 性能瓶颈排查实战
- 6.5 日志与链路的联动
- 6.1 验证链路数据
- 七、生产采样策略与性能优化
-
- 7.1 采样率配置
- 7.2 OAP Server性能调优
- 7.3 Agent性能优化
- 7.4 SkyWalking与Micrometer Tracing的协同
- 7.1 采样率配置
- 八、踩坑指南
-
- 坑一:Agent版本与OAP版本不匹配
- 坑二:Gateway自定义过滤器覆盖了sw8头
- 坑三:异步线程中链路断裂
- 坑四:采样率为0导致无数据
- 坑五:Elasticsearch存储空间快速增长
- 坑六:JDK 21下Agent兼容性问题
- 坑一:Agent版本与OAP版本不匹配
- 九、课后作业
- 十、下节预告
- 🔗《最新版 SpringCloud 2025 从入门到实战》系列课程导航

适配版本:Apache SkyWalking 10.4.0(OAP + UI + Java Agent)、Spring Boot 4.0.8、Spring Cloud 2025.1.3(Oakwood)、JDK 21
课程定位:监控追踪阶段进阶篇,从分布式追踪理论到SkyWalking架构,从探针配置到链路分析,构建全链路可观测性能力
一、开篇:第26课留下的“盲区”
第26课我们完成了Prometheus+Grafana的指标监控体系。通过http_server_requests_seconds指标,我们能看到service-order的P95延迟从50ms飙升到了3秒。但指标只告诉了你“慢了”,没有告诉你“为什么慢”。
是service-user的数据库查询慢了?还是service-product的Feign调用超时了?还是service-order自己的业务逻辑阻塞了?Prometheus的指标是按服务聚合的——它知道每个服务各自的状态,但不知道一个请求在服务之间的流转路径。
链路追踪(Distributed Tracing) 正是为解决这个问题而设计的。它为每个请求生成全局唯一的TraceId,记录请求经过的每一个服务、每一次数据库查询、每一次RPC调用,以及每一段的精确耗时。当请求变慢时,通过链路追踪可以精确定位到是哪个服务、哪个方法、哪条SQL拖慢了整个请求。
SkyWalking是目前国内微服务生态中应用最广泛的开源APM(Application Performance Management)工具。与Zipkin、Jaeger等纯链路追踪工具不同,SkyWalking在同一个平台内覆盖Tracing、Metrics、Logging、Profiling、Event五类遥测数据,并提供零代码侵入的Java Agent探针,非常适合Spring Cloud微服务架构的快速接入。
本课将从分布式追踪的理论基础(Dapper论文)讲起,深入SkyWalking的四层架构和字节码增强原理,完成OAP+UI部署和Java Agent探针配置,实战微服务调用链路分析和拓扑图生成,最后给出生产环境的采样策略和性能优化建议。
二、分布式追踪理论基础
2.1 Dapper论文的核心思想
2010年,Google发表了《Dapper, a Large-Scale Distributed Systems Tracing Infrastructure》论文,奠定了分布式追踪的理论基础。今天所有的链路追踪系统——无论是SkyWalking、Zipkin还是Jaeger——其核心设计理念都可以追溯到这篇论文。
Dapper论文开篇描述了一个典型的场景:Google的一个搜索请求可能涉及数百个微服务、数千台机器。当用户说“搜索好慢”时,你该从哪查起?没有追踪系统,你可能需要查几十台机器的日志。Dapper的目标非常明确:性能分析和故障定位。
论文提出了两个基本要求:广泛的覆盖面——监控组件应作为基础组件提供,对应用开发者尽可能透明;低开销——监控系统本身对业务服务的性能影响必须降至最低。
2.2 三大核心概念:Trace、Segment、Span
Dapper将一次请求划分为三个层次,这一模型已成为所有链路追踪系统的基础:
Trace(追踪) :表示一整条完整的调用链,包含跨进程、跨线程的所有操作。全局唯一标识为TraceID,贯穿请求的全链路。通过TraceID可以串联起跨服务、跨进程的所有操作,还原完整的调用路径。
Segment(分段) :表示单个进程(如一个JVM实例)或线程内的所有操作集合,包含若干个Span。Segment是SkyWalking的特有概念,它比Zipkin/Jaeger的纯Span模型多了一层“进程级”的聚合。
Span(跨度) :表示一个具体的操作单元,是Trace的最小执行单元。Span分为三种类型:
| 类型 | 含义 | 典型场景 |
|---|---|---|
| Entry Span | 入口Span,是一个Segment的起点 | HTTP/RPC服务端入口、MQ消费者入口 |
| Local Span | 本地方法调用 | Service层方法、工具类方法 |
| Exit Span | 出口Span,是对外部的调用 | HTTP/RPC客户端调用、数据库访问、MQ生产者 |
每个Span包含以下核心属性:
| 属性 | 含义 |
|---|---|
| SpanID | 单个Span的唯一标识,单Trace内唯一 |
| ParentSpanID | 父Span的ID,用于构建树形调用层级 |
| 操作名 | 标识Span的操作类型,如GET /api/user |
| 起止时间戳 | 记录操作的开始/结束时间,计算耗时 |
| 状态码 | 标识操作的执行结果(成功/失败/异常) |
| 属性/标签 | 键值对形式的元数据,如HTTP URL、状态码、SQL语句 |
2.3 上下文传播:跨服务追踪的核心
上下文传播是实现跨服务链路串联的核心技术难点。它的核心任务是将Trace上下文(TraceID、SpanID、采样标记等)在跨进程、跨服务、跨线程的调用中进行传递,确保全链路的Span能被正确串联。
在HTTP场景中,上下文通过请求头传递。SkyWalking Java Agent会自动在Feign调用的请求头中注入sw8头,下游服务的Agent解析该头并恢复Trace上下文,从而将两个服务的Span关联到同一个Trace中。对于Spring Cloud Gateway,流量经过SkyWalking Agent时会自动生成包含TraceID的请求头。
在异步场景(如MQ、线程池)中,上下文通过ThreadLocal快照传递。SkyWalking的@Trace注解和ContextManager支持手动传递上下文,也可以通过apm-toolkit-trace工具包提供的TraceContext在异步线程中恢复上下文。
三、SkyWalking架构深度剖析
3.1 四层架构:Probe → OAP → Storage → UI
SkyWalking采用逻辑四层架构,每一层职责清晰、可独立扩展:
1┌──────────────────────────────────────────────────────────────┐ 2│ Probe(探针层) │ 3│ Java Agent / Python Agent / Go Agent / Node.js Agent │ 4│ Service Mesh Receiver / eBPF / OpenTelemetry / Zipkin │ 5│ 职责:采集数据,通过gRPC/OTLP上报到OAP │ 6└──────────────────────────────┬───────────────────────────────┘ 7 │ gRPC (11800) / HTTP (12800) 8 ▼ 9┌──────────────────────────────────────────────────────────────┐ 10│ OAP(Observability Analysis Platform) │ 11│ 接收 Trace/Metrics/Logs/Events │ 12│ OAL(指标分析)/ MAL(Meter分析)/ LAL(日志分析)DSL流水线 │ 13│ 聚合 · 流式处理 · 告警 │ 14│ 职责:数据接收、聚合计算、清洗分析、告警触发 │ 15└──────────────────────────────┬───────────────────────────────┘ 16 │ 17 ▼ 18┌──────────────────────────────────────────────────────────────┐ 19│ Storage(存储层) │ 20│ Elasticsearch / OpenSearch / BanyanDB / MySQL / H2 │ 21│ 职责:持久化存储链路数据、指标数据、日志数据 │ 22└──────────────────────────────┬───────────────────────────────┘ 23 │ 24 ▼ 25┌──────────────────────────────────────────────────────────────┐ 26│ UI(可视化层) │ 27│ Booster UI(10.x) / Horizon UI(11.x) │ 28│ 拓扑 · Trace · 指标 · 日志 · Profiling │ 29│ 职责:Web控制台,查看拓扑图、链路详情、性能指标 │ 30└──────────────────────────────────────────────────────────────┘ 31
Probe(探针层) :SkyWalking的核心优势在于零代码侵入。Java Agent通过-javaagent参数挂载,不需要改一行业务代码,自动拦截Spring MVC、OpenFeign、Dubbo、MySQL、Redis、MQ等中间件操作,采集链路、耗时、异常和JVM指标,异步上报数据。
OAP(平台后端) 是架构重心。它接收Trace/Metrics/Logs/Events数据,经OAL(指标分析)、MAL(Meter分析)、LAL(日志分析)等DSL流水线生成实体与指标。10.4版本起,MAL/LAL走V2引擎,指标聚合与持久化worker池合并为BatchQueue调度。
Storage(存储层) 是插件化的。生产环境常见Elasticsearch/OpenSearch或BanyanDB(SkyWalking自研时序+追踪存储)。
UI(可视化层) 在10.x版本中使用Booster UI,11.x版本中已正式切换为Horizon UI。
3.2 核心数据模型
SkyWalking用Service → Service Instance → Endpoint → Process四层结构描述观测对象:
| 层级 | 含义 | 示例 |
|---|---|---|
| Service | 一组提供相同行为的工作负载 | service-user服务 |
| Service Instance | Service下的单个实例(一个JVM进程) | host1@service-user:8081 |
| Endpoint | HTTP URI或gRPC方法签名等入口路径 | GET /api/user/{id} |
| Process | 进程级信息 | 进程ID、OS信息 |
跨K8s、Mesh、OS等多Layer时,可通过Service Hierarchy关联同一逻辑服务在不同层级的视图。
3.3 Java Agent的字节码增强原理
SkyWalking Java Agent采用字节码增强(Bytecode Enhancement) 技术实现无侵入埋点。其核心机制是:
第一层:JVM Instrumentation API。 Java Agent通过premain方法在应用启动时注册ClassFileTransformer。当JVM加载每个类时,Transformer会拦截类字节码,根据SkyWalking的插件规则判断是否需要增强。
第二层:插件化拦截。 SkyWalking内置了数百个插件,覆盖Spring MVC、OpenFeign、MySQL、Redis、RabbitMQ、Kafka等主流框架。每个插件定义了需要拦截的类和方法,以及增强后的逻辑——在方法执行前创建Span,在方法执行后记录耗时和结果。
第三层:上下文传播。 增强后的代码在Entry Span创建时从请求头中提取Trace上下文,在Exit Span创建时向请求头中注入Trace上下文,实现跨服务的链路串联。
性能开销:SkyWalking Agent对应用的性能影响通常小于3%,支持通过采样率进一步降低开销。
四、SkyWalking部署实战
4.1 Docker Quick Start部署
SkyWalking提供了官方一键部署脚本,交互式选择Elasticsearch或BanyanDB作为存储:
1# Linux / macOS / WSL 2bash <(curl -sSL https://skywalking.apache.org/quickstart-docker.sh) 3
脚本会启动三个容器:
| 容器 | 端口 | 职责 |
|---|---|---|
| skywalking-oap | 11800(gRPC)、12800(HTTP) | OAP平台后端 |
| skywalking-ui | 8080 | Web控制台 |
| elasticsearch | 9200 | 数据存储 |
手动部署方式(推荐生产环境):
1# 1. 启动Elasticsearch 2docker run -d --name elasticsearch \ 3 -p 9200:9200 \ 4 -e "discovery.type=single-node" \ 5 -e "ES_JAVA_OPTS=-Xms2g -Xmx2g" \ 6 elasticsearch:8.15.0 7 8# 2. 启动OAP Server(指定ES存储) 9docker run -d --name oap \ 10 -p 11800:11800 -p 12800:12800 \ 11 -e SW_STORAGE=elasticsearch \ 12 -e SW_STORAGE_ES_CLUSTER_NODES=elasticsearch:9200 \ 13 apache/skywalking-oap-server:10.4.0 14 15# 3. 启动UI 16docker run -d --name ui \ 17 -p 8080:8080 \ 18 -e SW_OAP_ADDRESS=http://oap:12800 \ 19 apache/skywalking-ui:10.4.0 20
端口说明:OAP默认gRPC接收端口为11800,HTTP为12800;UI默认端口为8080。
4.2 验证部署
访问http://localhost:8080,应看到SkyWalking UI界面。首次访问时,服务列表为空——需要应用挂载Agent并上报数据后才会显示。
五、Java Agent探针配置
5.1 下载Agent
从SkyWalking官网下载Java Agent包,版本必须与OAP Server保持一致:
1wget https://archive.apache.org/dist/skywalking/java-agent/9.4.0/apache-skywalking-java-agent-9.4.0.tgz 2tar -zxvf apache-skywalking-java-agent-9.4.0.tgz 3
解压后的目录结构:
1skywalking-agent/ 2├── config/ 3│ └── agent.config # 主配置文件 4├── plugins/ # 默认启用的插件 5├── optional-plugins/ # 可选插件(需手动移入plugins/) 6└── skywalking-agent.jar # Agent 主jar包 7
5.2 核心配置项
编辑config/agent.config,关键配置如下:
1# 服务名称(在UI中显示) 2agent.service_name=${SW_AGENT_NAME:Your_ApplicationName} 3 4# OAP服务器地址(gRPC端口) 5collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:127.0.0.1:11800} 6 7# 采样率:每3秒采集的请求数,-1表示全量采集,默认-1 8agent.sample_n_per_3_secs=${SW_AGENT_SAMPLE:-1} 9 10# 数据隔离命名空间 11agent.namespace=${SW_AGENT_NAMESPACE:} 12 13# 实例标识(默认自动生成) 14agent.instance_name=${SW_AGENT_INSTANCE_NAME:} 15
5.3 配置覆盖优先级
SkyWalking支持多种配置方式,优先级从高到低依次为:
| 优先级 | 配置方式 | 示例 |
|---|---|---|
| 1(最高) | 探针配置(jar后加参数) | -javaagent:agent.jar=agent.service_name=order-service |
| 2 | 系统配置(-D参数) | -Dskywalking.agent.service_name=order-service |
| 3 | 系统环境变量 | SW_AGENT_NAME=order-service |
| 4(最低) | 配置文件中的值 | agent.config 中的 Your_ApplicationName |
最佳实践:推荐通过环境变量配置参数,便于不同环境切换:
1export SW_AGENT_NAME=service-user 2export SW_AGENT_COLLECTOR_BACKEND_SERVICES=oap:11800 3java -javaagent:/agent/skywalking-agent.jar -jar service-user.jar 4
5.4 Spring Boot应用的启动配置
在microservice-platform的每个服务中,通过JVM参数挂载Agent:
1# service-user 启动命令 2java -javaagent:/opt/skywalking-agent/skywalking-agent.jar \ 3 -Dskywalking.agent.service_name=service-user \ 4 -Dskywalking.collector.backend_service=192.168.1.100:11800 \ 5 -jar service-user-1.0.0.jar 6
Maven插件方式(适合开发环境):
1<plugin> 2 <groupId>org.springframework.boot</groupId> 3 <artifactId>spring-boot-maven-plugin</artifactId> 4 <configuration> 5 <jvmArguments> 6 -javaagent:/opt/skywalking-agent/skywalking-agent.jar 7 -Dskywalking.agent.service_name=${project.artifactId} 8 -Dskywalking.collector.backend_service=127.0.0.1:11800 9 </jvmArguments> 10 </configuration> 11</plugin> 12
5.5 Gateway与OpenFeign的链路透传
SkyWalking Agent原生支持Spring Cloud Gateway和OpenFeign。Gateway的流量经过Agent时,会自动生成包含TraceID的请求头并在调用链中标记熔断器触发事件。OpenFeign的调用会被自动增强,在请求头中注入sw8头,下游服务解析后恢复Trace上下文。
需要在Gateway模块额外添加的依赖(确保Gateway的链路透传正确):
1<dependency> 2 <groupId>org.apache.skywalking</groupId> 3 <artifactId>apm-toolkit-trace</artifactId> 4 <version>9.4.0</version> 5</dependency> 6
踩坑提示:如果Gateway使用了自定义的
GlobalFilter修改了请求头,可能会覆盖SkyWalking注入的sw8头,导致链路断裂。解决方案:在自定义过滤器中,将sw8头添加到白名单中,不做修改。
5.6 日志中注入TraceID
在logback-spring.xml中配置TraceID输出:
1<pattern>%d{yyyy-MM-dd HH:mm:ss} [%X{tid}] [%thread] %-5level %logger{36} - %msg%n</pattern> 2
SkyWalking Agent会自动将TraceID注入到MDC的tid键中。配置后,日志中将显示类似:
12026-09-13 10:30:15 [a1b2c3d4e5f6.1234567890.123456.01] [http-nio-8081-exec-1] INFO c.e.m.u.controller.UserController - 查询用户: id=1 2
通过TraceID,可以在ELK中串联起该请求在所有服务中的日志。
六、调用链路分析与拓扑图实战
6.1 验证链路数据
启动所有服务(挂载Agent后),访问SkyWalking UI(http://localhost:8080):
- 服务列表:左侧菜单中应显示
service-user、service-order、service-product、gateway-server四个服务 - 拓扑图:导航至Topology页面,应显示服务间的调用关系。外部请求 → Gateway → service-order → service-user / service-product
- 链路追踪:导航至Trace页面,应能看到最近的请求链路
6.2 拓扑图解读
SkyWalking自动采集服务间的调用数据,生成实时拓扑图,展示服务节点(微服务、数据库、消息队列)、调用方向(箭头表示请求流向)和调用指标(响应时间、错误率)。
拓扑图的关键作用:
- 发现隐藏依赖:某版本发布后,拓扑图可能显示
order-service对perf-service的调用延迟突然升高 - 定位故障传播链路:当服务雪崩时,拓扑图能一眼看出故障从哪个服务开始、传播到了哪些服务
- 验证架构变更效果:例如将同步调用改为异步后,拓扑图中的实线箭头变为虚线箭头
依赖矩阵:拓扑图下方可以切换到依赖矩阵视图,以表格形式量化服务间依赖强度:
| 调用方 | 被调用方 | 调用次数/分钟 | 平均延迟 |
|---|---|---|---|
| order-service | user-service | 120 | 45ms |
| order-service | product-service | 240 | 12ms |
| order-service | mysql | 360 | 8ms |
6.3 链路详情分析
点击拓扑图中的某条调用边,或进入Trace页面查看单条链路的详情。SkyWalking的链路详情页面以火焰图和调用树两种视图展示:
调用树视图:
1Trace: a1b2c3d4e5f6 (总耗时: 523ms) 2├── [Gateway] GET /api/order/1 (523ms) 3│ ├── [service-order] OrderController.getOrder (515ms) 4│ │ ├── [service-order] OrderService.query (510ms) 5│ │ │ ├── [service-user] UserClient.getUserById (320ms) ← 慢!占比61% 6│ │ │ │ └── [service-user] UserController.getUserById (310ms) 7│ │ │ │ └── [MySQL] SELECT * FROM user WHERE id=1 (295ms) ← 慢SQL! 8│ │ │ ├── [service-product] ProductClient.getProductById (150ms) 9│ │ │ │ └── [service-product] ProductController.getProductById (145ms) 10│ │ │ └── [service-order] OrderService.assemble (35ms) 11│ │ └── [service-order] OrderController.response (5ms) 12│ └── [Gateway] Response (523ms) 13
从调用树中可以精确定位瓶颈:
- 总耗时523ms,其中
service-user调用耗时320ms(占比61%) service-user的耗时主要来自MySQL查询(295ms)- 定位到具体问题:
service-user的数据库查询缺少索引,导致全表扫描
关键指标:
- 自身耗时(Self Time) :Span的总耗时减去子Span的耗时。如果某个Span的Self Time很高,说明瓶颈在该Span自身的代码逻辑中
- 异常标记:发生异常的Span会以红色高亮显示,点击可查看异常堆栈
- SQL记录:数据库查询的SQL语句会被记录,便于分析慢SQL
6.4 性能瓶颈排查实战
场景一:Feign调用超时。在调用树中,UserClient.getUserById的耗时异常高(如3秒)。展开该Span,可以看到SkyWalking记录的HTTP请求详情——请求URL、状态码、响应时间。对比第15课配置的Feign超时时间(read-timeout),确认是否为下游服务响应慢导致的超时。
场景二:数据库慢查询。展开MySQL Span,可以看到执行的SQL语句和耗时。SkyWalking自动记录SQL语句(需要开启plugin.jdbc.trace_sql_parameters=true配置)。
场景三:Gateway转发慢。在调用树中,Gateway的Span耗时高,但下游服务的Span耗时正常。这说明瓶颈在Gateway自身的处理逻辑(如鉴权过滤器、限流过滤器)中。
6.5 日志与链路的联动
SkyWalking支持将TraceID注入到日志中,通过日志中的TraceID可以在ELK中检索到该请求在所有服务中的完整日志。当某个接口超时告警时,运维人员可以直接通过TraceID跳转到关联日志,查看当时数据库连接池的状态或异常堆栈。
七、生产采样策略与性能优化
7.1 采样率配置
SkyWalking的采样率通过agent.sample_n_per_3_secs配置,含义是每3秒采集的请求数:
| 配置值 | 含义 | 适用场景 |
|---|---|---|
| -1 | 全量采集 | 开发/测试环境 |
| 0 | 不采集 | 关闭Agent |
| 100 | 每3秒采集100个请求 | 生产环境(中等流量) |
| 10 | 每3秒采集10个请求 | 生产环境(高流量) |
生产建议:核心服务(支付、订单)使用较高采样率(100-500),非核心服务(日志上报、推荐)使用较低采样率(10-50)。全量采集在生产环境可能导致OAP和ES的存储压力过大。
7.2 OAP Server性能调优
OAP Server的JVM参数需要根据数据量调整:
1# OAP Server JVM 参数 2SW_JAVA_OPTS="-Xms4g -Xmx4g -XX:MetaspaceSize=256m" 3
存储层优化:
- Elasticsearch集群建议至少3节点,每个节点8核16G
- 配置ES的
index.refresh_interval为30s(而非默认的1s),减少写入压力 - 定期清理过期索引(OAP默认保留7天数据,可通过
SW_CORE_DATA_KEEPER_EXECUTE_PERIOD调整)
7.3 Agent性能优化
如果发现Agent对应用性能影响较大(超过5%),可以通过以下方式优化:
- 降低采样率:从
-1调整为100或更低 - 禁用不必要的插件:将
plugins/目录下不需要的插件移出(如kafka-plugin.jar、rocketmq-plugin.jar) - 关闭SQL参数记录:设置
plugin.jdbc.trace_sql_parameters=false - 调整上报批大小:增加
agent.buffer.channel_size和agent.buffer.buffer_size,减少网络请求次数
7.4 SkyWalking与Micrometer Tracing的协同
SkyWalking的Agent与Spring Boot Actuator的Micrometer Tracing可以共存,但需要注意:
- SkyWalking Agent:负责链路追踪(Trace/Span),通过字节码增强实现
- Micrometer Tracing:负责生成日志中的TraceID/SpanID,通过Spring Boot的自动配置实现
两者的TraceID是独立的——SkyWalking的TraceID存储在sw8头中,Micrometer的TraceID存储在traceparent头中。如果需要统一,可以通过SkyWalking的apm-toolkit-trace工具包将SkyWalking的TraceID注入到MDC中。
八、踩坑指南
坑一:Agent版本与OAP版本不匹配
现象:应用启动时报The OAP version is not compatible,或UI中看不到数据。
原因:Java Agent与OAP Server的版本不一致。SkyWalking对版本兼容性要求严格。
解决:确保Agent和OAP的主版本号一致。例如OAP使用10.4.0,Agent也应使用9.4.0(Java Agent的版本号与OAP版本号不完全对应,需要查看官方兼容性矩阵)。
坑二:Gateway自定义过滤器覆盖了sw8头
现象:Gateway的链路正常,但下游服务的链路断裂——下游服务的TraceID与Gateway的TraceID不同。
原因:Gateway的自定义GlobalFilter在修改请求头时,覆盖了SkyWalking注入的sw8头。
解决:在自定义过滤器中,对sw8头做白名单处理——读取但不对其进行修改。或者使用ServerHttpRequest.mutate()时保留原有的sw8头。
坑三:异步线程中链路断裂
现象:@Async方法或线程池中的任务,其Span的TraceID与父线程不同,导致链路断裂。
原因:SkyWalking的Trace上下文存储在ThreadLocal中,异步线程无法访问父线程的ThreadLocal。
解决:使用apm-toolkit-trace工具包中的TraceContext手动传递上下文:
1@Async 2public void asyncMethod() { 3 // 在异步方法中手动恢复上下文 4 // 或者使用 @Trace 注解 5} 6
或者使用ContextManager在异步任务提交前捕获上下文,在任务执行时恢复。
坑四:采样率为0导致无数据
现象:应用挂载了Agent,但UI中完全看不到数据。
原因:agent.sample_n_per_3_secs被设置为0(不采集)。
解决:检查agent.config中的agent.sample_n_per_3_secs,确保不是0。生产环境建议设置为100或更高。
坑五:Elasticsearch存储空间快速增长
现象:ES磁盘使用量快速增长,几天内占满磁盘。
原因:默认保留7天数据,且采样率为全量(-1)。在高流量场景下,7天的链路数据可能达到数百GB。
解决:降低采样率;缩短数据保留时间(通过SW_CORE_DATA_KEEPER_EXECUTE_PERIOD配置);定期清理过期索引。
坑六:JDK 21下Agent兼容性问题
现象:JDK 21环境下Agent启动报错,提示字节码增强失败。
原因:SkyWalking Java Agent的字节码增强在JDK 21下可能遇到UnsupportedOperationException,因为JDK 21对Instrumentation API的某些方法有限制。
解决:确保使用SkyWalking Java Agent 9.4.0或更高版本,这些版本已经适配了JDK 21。同时,在启动参数中添加--add-opens java.base/java.lang=ALL-UNNAMED。
九、课后作业
作业一:使用Docker部署SkyWalking(OAP + UI + Elasticsearch),验证UI可正常访问。记录OAP的gRPC端口和HTTP端口。
作业二:为service-user、service-order、service-product、gateway-server四个服务挂载SkyWalking Java Agent。通过环境变量配置SW_AGENT_NAME和SW_AGENT_COLLECTOR_BACKEND_SERVICES。验证UI中四个服务均正常显示。
作业三:发起一次完整的下单请求(通过Gateway → service-order → service-user + service-product),在SkyWalking UI中查看完整的调用链路。记录每个Span的耗时,找出耗时最高的三个Span。
作业四:在service-user的getUserById方法中添加Thread.sleep(2000),重新发起请求,通过链路详情验证能否精确定位到service-user的MySQL查询为瓶颈。
作业五(进阶) :配置plugin.jdbc.trace_sql_parameters=true,重新发起请求,验证链路详情中是否记录了完整的SQL语句和参数。分析SQL执行计划,确认是否存在索引缺失问题。
十、下节预告
第28课将进入统一日志收集、ELK搭建 & 线上问题排查体系。内容包括日志规范与分级、Logback配置、ELK(Elasticsearch + Logstash + Kibana)搭建、日志检索、链路ID追踪和线上报错快速定位。本课完成了链路追踪(Tracing)的完整链路,第28课将进入日志(Logging) 领域——指标告诉你“系统状态如何”,链路告诉你“请求经过了哪些服务”,日志告诉你“系统在某个时刻发生了什么”。三者结合,构成完整的可观测性体系。通过SkyWalking的TraceID与ELK日志的联动,可以实现“一键从链路跳转到日志”的高效排查体验。
🔗《最新版 SpringCloud 2025 从入门到实战》系列课程导航
第一部分:微服务前置基础 & 新版环境搭建(第1-5课)
第二部分:注册中心核心(Nacos 最新版)(第6-9课)
第三部分:配置中心核心(Nacos配置中心)(第10-12课)
第四部分:服务通信核心(OpenFeign + LoadBalancer)(第13-16课)
第五部分:网关核心(SpringCloud Gateway 新版)(第17-20课)
第六部分:熔断、限流、降级(Sentinel 新版)(第21-24课)
第七部分:微服务监控、链路追踪、日志体系(第25-28课)
第八部分:微服务高阶特性 & 分布式核心能力(第29-31课)
第九部分:企业级完整项目实战 & 架构复盘(第32-35课)
参考文档
- Primers 编程伙伴/Bash/帮助手册/curl
- Primers 编程伙伴/Bash/帮助手册/type
- Primers 编程伙伴/Bash/帮助手册/tar
- Primers 编程伙伴/Bash/帮助手册/export
- Primers 编程伙伴/HTML/HTML 元素/dd
- Primers 编程伙伴/Bash/帮助手册/read
- Primers 编程伙伴/Bash/帮助手册/true
- Primers 编程伙伴/Bash/帮助手册/false
- Primers 编程伙伴/HTML/HTML 元素/base
- Primers 编程伙伴/Bash/帮助手册/sleep
《第27课:SkyWalking全链路追踪实战 & 微服务调用链路分析》 是转载文章,点击查看原文。