一、功能概述
上一篇《增加企业级日志打印》解决了两个问题:日志落盘归档 + 每行日志带上 [TID:xxx]。
但做完之后还剩一个说不清的地方:
运维:用户说下单失败了,帮我查一下。
我: traceId 给我。
运维:a1b2c3d4...
我: grep 一下,日志是串起来了,但是——
· 网关到服务花了几毫秒?不知道
· 服务里那条 SQL 是不是慢查询?不知道
· AI 服务又调了哪个下游?不知道
· 整体服务之间的调用拓扑长什么样?不知道日志能告诉你"发生了什么",但告诉不了你"慢在哪、断在哪、拓扑长什么样"——那需要 APM。
改造前的现状
=== 全仓库搜索 APM / TraceContext 相关代码 ===
grep -rn "TraceContext|skywalking|apm-toolkit" --include=*.java .
(0 命中:既没有 Agent 依赖,也没有任何链路埋点)
=== 各服务 JVM 启动参数 ===
java -jar xxx.jar ← 只挂了应用本身,没有 -javaagent也就是说:系统只有"日志级"的追踪(自建 traceId),没有"调用链级"的可观测。
功能特性
- 零代码侵入:Java Agent 字节码增强,业务代码一行不改
- 跨服务自动串联:HTTP / Feign 调用通过
sw8头自动透传 traceId,A→B→C 一条链 - 日志与链路对齐:日志里的
[TID:xxx]就是 SkyWalking 的 traceId,可直接互查 - 拓扑与指标:服务拓扑图、接口 RT、慢 SQL、错误率、JVM 指标在 UI 一站式呈现
- 可降级:不挂 Agent 也能正常启动,traceId 自动回退为
local-前缀
二、技术栈
| 组件 | 选型 | 说明 |
|---|---|---|
| 链路追踪服务端 | SkyWalking OAP 9.0.0 | 链路采集、聚合、存储(项目已有远端实例) |
| 可视化 | SkyWalking UI | http://117.72.88.11:1080 |
| 探针 | SkyWalking Java Agent 9.0.0 | 挂载即生效,无需改代码 |
| 日志工具包 | apm-toolkit-trace / apm-toolkit-logback-1.x 9.0.0 | 读取 traceId、上报日志 |
| 日志框架 | Logback + SLF4J MDC | 承接 traceId,输出到每行日志 |
| 服务端存储 | Elasticsearch | OAP 侧使用,开发无需关心 |
版本必须三方对齐(本项目统一 9.0.0):
Java Agent 9.0.0 ←→ apm-toolkit-* 9.0.0 ←→ OAP 9.0.0
(探针) (应用侧依赖) (服务端)版本不一致的典型症状:
%tid布局类找不到、gRPC 上报协议不匹配、UI 里服务列表空白。这套接法参考了同技术栈的商城微服务项目:依赖由公共模块引入(
apm-toolkit-trace+apm-toolkit-logback-1.x)、每行日志输出%tid、每个服务挂-javaagent启动。知识库在它基础上做了两处增强:traceId 三级回退 +local-前缀可辨识(见 4.2),以及网关插件自检(见 4.4)。
三、整体架构

为什么用 Agent,而不是代码埋点
| 方案 | 侵入性 | 覆盖度 | 维护成本 |
|---|---|---|---|
| 手写代码埋点(每个方法前后打点) | 高,改动大量业务代码 | 取决于人的自觉 | 极高,漏一处断一处 |
| 引入追踪 SDK 手动埋点 | 中,需要改 Service 层 | 较好 | 中,升级要改代码 |
| Java Agent 字节码增强 | 零,业务代码不动 | 框架级全覆盖(HTTP/MVC/Feign/JDBC/Redis/MQ) | 低,换 Agent 版本即可 |
选 Agent 的核心理由:这次改造要的是"立刻能看到链路",而不是"再写一套埋点代码"。Agent 在类加载期增强,Spring MVC、Feign、JDBC、Redis、RabbitMQ 这些框架级入口全部自动覆盖。
代价:optional-plugins/ 里的插件要手动启用(见第十节踩坑 10.1,这是本项目实际踩到的最大一个坑)。四、方案选型与关键决策
4.1 日志里已经有 traceId 了,为什么还要接 SkyWalking
上一篇的自建 traceId 只能解决**"日志之间能不能串"**,它有三个天花板:
| 能力 | 自建 traceId | SkyWalking |
|---|---|---|
| 日志按请求串起来 | ✅ | ✅ |
| 每个调用段的耗时 | ❌ | ✅ |
| 服务拓扑图 | ❌ | ✅ |
| 慢 SQL / 慢接口定位 | ❌ | ✅ |
| 错误率、QPS、JVM 指标 | ❌ | ✅ |
| 调用链可视化(瀑布图) | ❌ | ✅ |
所以这次不是"重复造",而是在已有 traceId 基础上把链路数据接进来,并且让两者用同一个 ID。
4.2 为什么 traceId 取值要「SkyWalking → 上游头 → 本地」,且本地兜底要加 local- 前缀
这是本项目最容易被误解的一点:日志里有 traceId,不代表 SkyWalking UI 里能查到。
取值优先级(TraceIdUtil.resolveTraceId):
1) TraceContext.traceId() // SkyWalking 真实 traceId —— UI 能查
2) 上游请求头 X-Request-Id // 前端/网关传的 —— UI 查不到
3) 本地生成 UUID + local- 前缀 // 兜底 —— UI 查不到为什么必须判断第 1 步是否有效?因为 SkyWalking 在"没有有效链路"时会返回占位值,实测(Agent 9.0.0):
| 场景 | TraceContext.traceId() 返回 |
|---|---|
| 未挂 Agent | 空串 "" |
| 挂了 Agent 但当前无追踪 | "N/A" |
| 有追踪但未被采样 | "Ignored_Trace" |
| 正常被追踪 | 真实 traceId(32 位十六进制) |
如果不做有效性判断,日志里会满屏 [TID:N/A]——等于没做。所以 isValid() 把这三种占位值判为无效并回退。
为什么本地兜底要加 local- 前缀:这三种 ID 混在一起,光看格式分不出来。加了前缀之后:
[TID:c03554c8f38b4ee49578aff24cd41fe2] → 去 UI 查,一定能查到
[TID:local-fe7f6282288c43e48971725e6ba17ab7] → 本地兜底,不用去 UI 白找
[TID:1792145426666-1rpxeg7] → 前端传的,UI 查不到这个前缀是实际排障中加的——一开始没有它,运维拿着 local- 那种 ID 去 UI 查了半天查不到,误以为是链路丢失。
4.3 为什么 gRPC 日志上报只在 prod 启用
logback-spring.xml 里 SkyWalking 的 GRPCLogClientAppender 被放在 <springProfile name="prod"> 内:
- 开发环境没有 OAP,常开只会不停刷连接错误,淹没正常日志;
- 生产环境才有 OAP,日志才能真的上报到 UI 供检索。
4.4 为什么网关要单独启用插件(本项目的关键决策)
SkyWalking Agent 的插件分两档,optional-plugins/** 默认不加载**:
| 目录 | 是否默认生效 | 说明 |
|---|---|---|
plugins/ | ✅ | 基础框架插件(Tomcat、Spring MVC、JDBC、Redis…) |
optional-plugins/ | ❌ | 需要手动 copy 到 plugins/ 才生效 |

而网关用到的两个插件恰好都在 optional-plugins/:
apm-spring-cloud-gateway-3.x-plugin ← 网关路由/转发追踪(缺了它网关完全没有链路)
apm-spring-webflux-5.x-plugin ← WebFlux 服务端追踪这两个不能同时启用——它们增强的是同一批类:
spring-webflux-5.x → DispatcherHandlerInstrumentation, ServerWebExchangeInstrumentation
gateway-3.x → 上面两个 + NettyRoutingFilterInstrumentation + HttpClientFinalizerInstrumentation同时启用 = 重复埋点。网关的正确做法是只启用 gateway-3.x 插件(它已包含 WebFlux 部分)。
五、核心实现
5.1 依赖:kb-common/pom.xml
工具包放公共模块,所有服务自动继承(和上一篇的日志配置同一思路):
<!-- 根 pom.xml -->
<properties>
<skywalking.version>9.0.0</skywalking.version>
</properties>
<!-- kb-common/pom.xml -->
<!-- TraceContext:读取当前请求的 SkyWalking traceId,写入日志 MDC -->
<dependency>
<groupId>org.apache.skywalking</groupId>
<artifactId>apm-toolkit-trace</artifactId>
<version>${skywalking.version}</version>
</dependency>
<!-- Logback 集成:TraceId 布局 + 通过 gRPC 上报日志到 OAP -->
<dependency>
<groupId>org.apache.skywalking</groupId>
<artifactId>apm-toolkit-logback-1.x</artifactId>
<version>${skywalking.version}</version>
</dependency>5.2 traceId 工具类:TraceIdUtil.java
public static String resolveTraceId(String upstreamTraceId) {
String swTraceId = currentTraceId();
if (isValid(swTraceId)) {
return swTraceId; // SkyWalking 真实 traceId -> UI 可查
}
if (StrUtil.isNotBlank(upstreamTraceId)) {
return limit(upstreamTraceId); // 上游透传(前端/网关)
}
return LOCAL_PREFIX + generateTraceId(); // 本地兜底,带 local- 前缀
}
public static String currentTraceId() {
try {
return TraceContext.traceId();
} catch (Throwable t) {
return null; // 工具包未就绪时不影响主流程
}
}
public static boolean isValid(String traceId) {
return StrUtil.isNotBlank(traceId)
&& !"N/A".equals(traceId)
&& !"Ignored_Trace".equals(traceId);
}5.3 服务端写入 MDC:TraceIdFilter.java(Servlet 服务通用)
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
public class TraceIdFilter extends OncePerRequestFilter {
protected void doFilterInternal(HttpServletRequest req, HttpServletResponse resp, FilterChain chain) {
String traceId = TraceIdUtil.resolveTraceId(req.getHeader(TraceIdConstants.HEADER));
MDC.put(TraceIdConstants.MDC_KEY, traceId); // 后续所有日志自动带上 tid
resp.setHeader(TraceIdConstants.HEADER, traceId);
try {
chain.doFilter(req, resp);
} finally {
MDC.remove(TraceIdConstants.MDC_KEY); // 线程复用必须清理
}
}
}@ConditionalOnWebApplication(SERVLET)是关键:网关是 WebFlux,不会加载这个过滤器,它用的是TraceIdGlobalFilter。
5.4 网关侧:TraceIdGlobalFilter.java(WebFlux)
网关是链路起点,同时承担向上下游传递 traceId 的职责:
ServerHttpRequest mutated = request.mutate()
.header(TraceIdConstants.HEADER, traceId) // 1) 注入下游请求头
.build();
response.getHeaders().set(TraceIdConstants.HEADER, traceId); // 2) 回写响应头给前端
MDC.put(TraceIdConstants.MDC_KEY, traceId); // 3) 尽力写入 MDC为什么是"尽力":Netty 事件循环下 MDC(ThreadLocal)无法可靠跨异步线程,所以网关的请求/响应日志另外从请求头直读 traceId(见 5.5)。
5.5 网关日志:从请求头读 traceId
GlobalLogFilter 与 UnifiedResponseFilter 都改成从请求头读,避免依赖 MDC:
String traceId = request.getHeaders().getFirst(TraceIdConstants.HEADER);
log.info("[{}] 请求 => Method: {}, URI: {}", traceId, request.getMethod(), request.getURI());
log.info("[{}] 网关转发响应: URI={}, Status={}", traceId, uri, status);5.6 跨服务 + 异步:Feign 透传与 MDC 传递
| 场景 | 实现 | 文件 |
|---|---|---|
| 服务间 Feign 调用 | 从 MDC 取 traceId 放进下游请求头 | FeignInterceptorConfig |
@Async 异步任务 | 任务提交时快照 MDC、执行前恢复、finally 清理 | MdcTaskDecorator |
// FeignInterceptorConfig
String traceId = MDC.get(TraceIdConstants.MDC_KEY);
if (StrUtil.isNotBlank(traceId)) {
template.header(TraceIdConstants.HEADER, traceId);
}挂了 Agent 之后,跨服务的 traceId 主要由 Agent 的 sw8 头自动透传,上面这两处是"没挂 Agent 时的兜底",两者不冲突。5.7 生产环境日志上报:logback-spring.xml
<springProfile name="prod">
<appender name="GRPC_LOG"
class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.log.GRPCLogClientAppender">
<encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
<layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.mdc.TraceIdMDCPatternLogbackLayout">
<pattern>${LOG_PATTERN_FILE}</pattern>
</layout>
</encoder>
</appender>
<root level="INFO">
<appender-ref ref="CONSOLE"/>
<appender-ref ref="ASYNC_FILE_ALL"/>
<appender-ref ref="ASYNC_FILE_ERROR"/>
<appender-ref ref="GRPC_LOG"/> <!-- 日志同时上报到 OAP -->
</root>
</springProfile>启动时必须带 -Dskywalking.agent.service_name=xxx,否则日志会按默认名(或 Your_ApplicationName)上报,UI 里认不出是哪个服务。
六、一条请求是如何跨服务串起来的
6.1 链路流转

6.2 traceId 的三种形态(判断能不能去 UI 查)
| 日志里的 TID | 来源 | UI 能否检索 |
|---|---|---|
[TID:c03554c8f38b4ee49578aff24cd41fe2] | SkyWalking Agent 的真实 traceId | ✅ 能 |
[TID:local-fe7f6282288c43e48971725e6ba17ab7] | 本地兜底(未挂 Agent / 未被采样) | ❌ 不能(属正常) |
[TID:1792145426666-1rpxeg7] | 前端/网关透传的 X-Request-Id | ❌ 不能 |
只有第一种能进 UI 检索。如果日志里全是后两种,说明 Agent 没生效或请求没被采样——排查思路见第十节。
6.3 实证:不用打开 UI 也能验证链路是否存在
SkyWalking OAP 提供 GraphQL 接口,可以直接用命令行查(比开 UI 快):
OAP=http://117.72.88.11:12800/graphql
# 1) 这个 traceId 在 OAP 里有没有链路
curl -s -X POST $OAP -H "Content-Type: application/json" \
-d '{"query":"query{queryTrace(traceId:\"c03554c8f38b4ee49578aff24cd41fe2\"){spans{serviceCode endpointName}}}"}'
# 返回 {"spans":[...]} = 有链路,UI 能查到
# 返回 {"spans":[]} = 该 ID 不是 SkyWalking 的
# 2) OAP 上当前有哪些服务
curl -s -X POST $OAP -H "Content-Type: application/json" \
-d '{"query":"query{getAllServices(duration:{start:\"2026-10-16 0000\",end:\"2026-10-16 2359\",step:MINUTE}){name}}"}'
# 实测输出(挂了 Agent 的服务都会出现):
# kb-gateway, kb-user-auth, kb-document, kb-foundation, kb-file, kb-ai, localhost:3306
# ↑ 最后的 localhost:3306 是 JDBC 插件把数据库也注册成了一个"服务",属正常现象七、接入方式
7.1 服务端地址(项目已有远端环境,直接用)
| 组件 | 地址 | 说明 |
|---|---|---|
| UI | http://117.72.88.11:1080 | 拓扑 / 链路 / 日志检索 |
| OAP gRPC | 117.72.88.11:11800 | Agent 上报地址 |
| OAP HTTP / GraphQL | 117.72.88.11:12800 | UI 与命令行查询 |
实测 OAP 版本:
$ curl -s -X POST http://117.72.88.11:12800/graphql -d '{"query":"query{version}"}'
{"data":{"version":"9.0.0-89644fe (20220217220813)"}}与本地 Agent(9.0.0)、kb-common 引入的 toolkit(9.0.0)版本完全一致,无需额外处理。7.2 IDEA 启动(推荐,已内置运行配置)
后端仓库里已放好 9 个共享运行配置(.run/kb-xxx (SkyWalking).run.xml),IDEA 打开后直接出现在运行下拉框:
| 运行配置 | service\_name | 端口 |
|---|---|---|
kb-gateway (SkyWalking) | kb-gateway | 8080 |
kb-user-auth (SkyWalking) | kb-user-auth | 8081 |
kb-document (SkyWalking) | kb-document | 8082 |
kb-search (SkyWalking) | kb-search | 8083 |
kb-file (SkyWalking) | kb-file | 8084 |
kb-statistics (SkyWalking) | kb-statistics | 8085 |
kb-ai (SkyWalking) | kb-ai | 8086 |
kb-graph (SkyWalking) | kb-graph | 8088 |
kb-foundation (SkyWalking) | kb-foundation | 8089 |
每个配置的 VM options 都已经带好参数:
-javaagent:/Users/mac/Downloads/skywalking-agent/skywalking-agent.jar
-DSW_AGENT_NAME=kb-document
-DSW_AGENT_COLLECTOR_BACKEND_SERVICES=117.72.88.11:11800
-DSW_AGENT_SAMPLE=-1手动加到已有配置:Run → Edit Configurations → Modify options → Add VM options。
⚠️ **不要加到 **Help → Edit Custom VM Options —— 那改的是 IDEA 自己的 JVM,和应用无关。7.3 脚本启动(一键挂 Agent)
cd project/knowledge-base-backend
./start-with-skywalking.sh脚本会依次:校验 Agent → 自检并补齐必需插件 → 安装 kb-common → 逐个挂 Agent 启动 9 个服务。
# 自定义 agent 路径 / OAP 地址
SKYWALKING_AGENT_JAR=/path/to/skywalking-agent.jar \
SW_AGENT_COLLECTOR_BACKEND_SERVICES=127.0.0.1:11800 \
./start-with-skywalking.sh7.4 两种 JVM 参数写法等价(有反编译依据)
商城项目用的是 -DSW_AGENT_NAME=xxx 这种写法,我们文档里也有 -Dskywalking.agent.service_name=xxx。两者完全等价:
// 反编译 SkyWalking Agent 的 SnifferConfigInitializer#overrideConfigBySystemProp
for (Map.Entry e : System.getProperties().entrySet()) {
String key = e.getKey().toString();
if (key.startsWith("skywalking.")) {
AGENT_SETTINGS.put(key.substring("skywalking.".length()), value); // 剥掉前缀覆盖配置键
}
}而 agent.config 里的键本身引用占位符:
agent.service_name=${SW_AGENT_NAME:Your_ApplicationName}
collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:127.0.0.1:11800}所以两条路都通。实测(用 Agent 的 %agent_name 变量回显实际生效值):
| 启动参数 | Agent 解析出的服务名 |
|---|---|
-DSW_AGENT_NAME=kbtest-sw | ✅ kbtest-sw |
-Dskywalking.agent.service_name=kbtest-direct | ✅ kbtest-direct |
SW_AGENT_* 的好处是同时支持环境变量(去掉 -D 前缀),容器 / K8s 里更顺手,本项目统一采用这种写法。
八、配置说明
8.1 Agent 启动参数
| 参数 | 值 | 说明 |
|---|---|---|
-javaagent | ~/Downloads/skywalking-agent/skywalking-agent.jar | 必填,路径含空格要加引号 |
SW_AGENT_NAME | kb-gateway 等 | 服务在 UI 上的显示名,每个服务不同 |
SW_AGENT_COLLECTOR_BACKEND_SERVICES | 117.72.88.11:11800 | OAP gRPC 地址 |
SW_AGENT_SAMPLE | -1 | 采样数,-1 = 全采样(开发建议) |
SW_LOGGING_LEVEL | INFO / WARN | Agent 自身日志级别(不是业务日志) |
SW_LOGGING_OUTPUT | FILE / CONSOLE | Agent 自身日志输出位置 |
采样说明:agent.sample_n_per_3_secs的语义是每 3 秒最多采样多少条,本机 Agent(9.0.0)的agent.config里默认值是-1,即全采样。把它设成正整数(例如1)后,超出配额的请求会返回Ignored_Trace,日志里就会回落到local-兜底 ID。开发环境显式设-1,是为了不依赖默认值。
8.2 必须启用的插件(从 optional-plugins/ 复制到 plugins/)
| 插件 | 作用 | 影响的模块 |
|---|---|---|
apm-spring-cloud-gateway-3.x-plugin-9.0.0.jar | 网关路由 / 转发追踪 | kb-gateway(必须) |
apm-springmvc-annotation-6.x-plugin-9.0.0.jar | Spring MVC 6 方法级追踪 | 各业务服务(Spring Boot 3) |
apm-mybatis-3.x-plugin-9.0.0.jar | MyBatis SQL 追踪(慢 SQL) | 各业务服务 |
cd ~/Downloads/skywalking-agent
cp optional-plugins/apm-spring-cloud-gateway-3.x-plugin-9.0.0.jar plugins/
cp optional-plugins/apm-springmvc-annotation-6.x-plugin-9.0.0.jar plugins/
cp optional-plugins/apm-mybatis-3.x-plugin-9.0.0.jar plugins/不要同时启用 apm-spring-webflux-5.x-plugin(与 gateway 插件增强同一批类,会重复埋点)。start-with-skywalking.sh 已内置这段自检,缺失会自动补齐。
九、测试验证
链路追踪最容易踩的坑是「看起来接了,其实没接」——服务能正常启动,日志格式也没变,但 UI 上就是没有数据。所以验证要按顺序做四件事:Agent 挂上了吗 → 插件加载了吗 → 服务注册了吗 → 链路串起来了吗。
9.1 先确认 Agent 真的挂上了(三种判据)
**判据一:启动命令里有 **-javaagent
$ jps -lv | grep kb-gateway
16234 .../kb-gateway/target/classes -javaagent:/Users/mac/Downloads/skywalking-agent/skywalking-agent.jar -DSW_AGENT_NAME=kb-gateway ...jps -lv会打印完整 VM 参数。没有-javaagent就是没挂,后面所有验证都不用做了。
判据二:Agent 自己的日志里有启动记录
Agent 会把启动过程写到 ~/Downloads/skywalking-agent/logs/skywalking-api.log,其中包含版本号:
$ grep "SkyWalking agent version" ~/Downloads/skywalking-agent/logs/skywalking-api.log | tail -1
INFO 2026-10-16 19:10:30.527 main Version : SkyWalking agent version: 9.0.0-bc4c179判据三:服务启动时间 vs Agent 日志写入时间
场景是:部分服务有链路、部分没有。原因是中途重启服务时漏挂了 Agent(比如用 IDE 的普通运行配置重启了一次),而"没挂 Agent"本身不会报任何错。
# ① 该服务最近一次启动时间
$ grep "Starting .*Application" logs/kb-user-auth/kb-user-auth.log | tail -1 | cut -d' ' -f1,2
2026-10-16 18:42:43
# ② Agent 日志最后写入时间(macOS)
$ stat -f "%Sm %N" -t "%Y-%m-%d %H:%M:%S" ~/Downloads/skywalking-agent/logs/skywalking-api.log
2026-10-16 19:19:12 /Users/mac/Downloads/skywalking-agent/logs/skywalking-api.log判据:服务的启动时刻必须落在 Agent 日志的写入窗口内。如果某服务启动之后,Agent 日志在整个运行期间一条新增记录都没有,这个实例就是裸奔启动的。
实测(用户实际反馈的一段日志,18:23 的 kb-user-auth):
2026-10-16 18:23:17.282 [http-nio-8081-exec-3] INFO [TID:local-4044bab92f34436da7212686f4728081]
c.k.b.u.filter.JwtAuthenticationFilter - JWT认证成功,已设置SecurityContextTID 是 local- 开头(本地兜底)而不是 32 位真实 traceId —— 说明这次启动根本没挂上 Agent。用 jps -lv 一查,该进程的 VM 参数里确实没有 -javaagent。
9.2 插件加载了吗(尤其是网关)
Agent 每加载一个插件都会打一行日志,可以直接数:
# ① 实际参与增强的插件数量
$ ls ~/Downloads/skywalking-agent/plugins/*.jar | wc -l
144
# ② Agent 启动日志里的加载记录,按来源目录归类(还有 10 条来自 activations/)
$ grep -a "jar loaded\." ~/Downloads/skywalking-agent/logs/skywalking-api.log \
| sed -E 's#.*/skywalking-agent/([^/]+)/.*#\1#' | sort | uniq -c
10 activations
144 plugins
# ③ 网关插件是否在其中(关键)
$ grep -a "apm-spring-cloud-gateway-3.x-plugin" ~/Downloads/skywalking-agent/logs/skywalking-api.log | tail -1
INFO 2026-10-16 19:13:32.181 main AgentClassLoader : /Users/mac/Downloads/skywalking-agent/plugins/apm-spring-cloud-gateway-3.x-plugin-9.0.0.jar loaded.反例(本次改造中最有价值的一次验证):启用网关插件之前,用 UI 的「追踪」页按服务名 kb-gateway 过滤,一条链路都没有;而从 UI 看 kb-user-auth、kb-document 是有数据的。也就是说网关这个"链路的入口"压根没被追踪过——问题定位就从"链路数据不对"收敛到了"网关插件没加载"。
9.3 服务注册到 OAP 了吗
不用打开 UI,直接问 OAP 要当前服务列表:
$ OAP=http://117.72.88.11:12800/graphql
$ curl -s -X POST $OAP -H "Content-Type: application/json" \
-d '{"query":"query{getAllServices(duration:{start:\"2026-10-16 0000\",end:\"2026-10-16 2359\",step:MINUTE}){name}}"}'
# 实测输出(挂上 Agent 并上报成功的服务都会出现):
# kb-gateway, kb-user-auth, kb-document, kb-foundation, kb-file, kb-ai, localhost:3306两点说明:
- 列表里没有的服务 = 该服务没挂 Agent,或没产生过流量(Agent 是"有请求才注册");
- 多出来的
localhost:3306不是异常 —— JDBC 插件会把数据库也注册成一个"服务",UI 拓扑图上表现为一条指向数据库的边。
9.4 同一个 TID 能不能跨服务串起来
这是端到端验证,也是最有说服力的一条。挑一个真实 TID,同时 grep 网关和业务服务的日志:
$ grep -H "1792146172231-85xlzg7" logs/kb-gateway/kb-gateway.log logs/kb-user-auth/kb-user-auth.log
logs/kb-gateway/kb-gateway.log:2026-10-16 18:22:52.961 [parallel-2] INFO [TID:1792146172231-85xlzg7]
com.knowledge.base.gateway.filter.GlobalLogFilter - [1792146172231-85xlzg7] 请求 => Method: GET, URI: http://localhost:8080/api...
logs/kb-user-auth/kb-user-auth.log:2026-10-16 18:22:58.289 [http-nio-8081-exec-1] INFO [TID:1792146172231-85xlzg7]
c.k.base.userauth.filter.JwtAuthenticationFilter - 请求URI: /auth/me, Method: GET一个 ID,从网关(parallel-2 线程)一路捞到业务服务(http-nio-8081-exec-1 线程),跨服务、跨线程都一致 —— 说明网关侧的 X-Request-Id 透传和下游的 TraceIdFilter 都在按设计工作。
9.5 日志里的 TID 能不能在 UI 里查到
「日志里有 TID」和「UI 里能查到」是两件事,必须分别验:
# ① 真实 SkyWalking traceId —— 应该能查到
$ curl -s -X POST $OAP -H "Content-Type: application/json" \
-d '{"query":"query{queryTrace(traceId:\"c03554c8f38b4ee49578aff24cd41fe2\"){spans{serviceCode endpointName}}}"}'
{"data":{"queryTrace":{"spans":[ ... ]}}} # spans 非空 = UI 能查到
# ② 本地兜底 UUID —— 查不到(属正常)
$ curl -s -X POST $OAP -H "Content-Type: application/json" \
-d '{"query":"queryTrace(traceId:\"fe7f6282288c43e48971725e6ba17ab7\"){spans{serviceCode}}}"}'
{"data":{"queryTrace":{"spans":[]}}} # 空 = 该 ID 不是 SkyWalking 的这两条一条能查、一条查不到,正好演示了 local- 前缀存在的意义:不加前缀时,②这种本地 UUID 长得和①一模一样(都是 32 位十六进制),运维拿着它去 UI 里翻半天,最后只能得出"链路丢了"的错误结论。
9.6 网关自身日志的 TID(本次修复的验证点)
网关是 WebFlux,响应回调发生在 reactor-http-nio-* 线程上,拿不到请求线程的 MDC,所以早期网关的响应日志 TID 是空的:
$ grep "网关转发响应" logs/kb-gateway/kb-gateway.log | tail -1
2026-10-16 19:13:24.680 [reactor-http-nio-1] INFO [TID:] com.knowledge.base.gateway.filter.UnifiedResponseFilter - 网关转发响应: URI=http://localhost:8080/api/document/categories/children/0, Status=200 OK, ...
^^^^^^^ 空的修复方式见 5.5:UnifiedResponseFilter 改为从请求头直接读 traceId,不再依赖 MDC。修复后的验证方法:
# 重启网关后随便调一个接口,再看这一行(下面是示意输出)
$ grep "网关转发响应" logs/kb-gateway/kb-gateway.log | tail -1
2026-10-16 20:31:12.104 [reactor-http-nio-2] INFO [TID:local-3f7c9a...] c.k.b.gateway.filter.UnifiedResponseFilter - [local-3f7c9a...] 网关转发响应: URI=..., Status=200 OK注意:这一处属于代码修复,需要重启网关才生效 —— 日志是启动时按类加载的旧版本打的,进程不重启就还是老样子(见 10.4)。
总结
这次改造解决了什么
| 改造前 | 改造后 |
|---|---|
| 只有日志里能 grep 到 traceId | 同一个 ID 既能 grep 日志,又能在 SkyWalking UI 查链路 |
| 一次请求慢在哪,靠打点或猜 | 瀑布图直接给出网关转发、服务处理、Feign 调用、SQL 各自耗时 |
| 服务之间谁调谁,看代码确认 | 拓扑图自动生成(含 localhost:3306 这类数据库节点) |
| 慢 SQL 只能翻数据库慢日志 | MyBatis 插件把 SQL 直接标在链路上 |
| 排障只能翻日志文件 | 先看链路定位到具体服务/方法,再按 traceId 回捞那一段日志 |
几个关键落点
- 工具包放公共模块,一处引入全服务生效 —— 与上一篇的日志配置同样的思路,接入成本集中在
kb-common一处。 - 同一个 ID 走两条通道 —— traceId 既进日志的 MDC,又是 SkyWalking 的链路 ID。不做这件事,就会变成"日志一套 ID、APM 一套 ID",排障时两头对不上。
- 静默失败最危险 —— Agent 没挂、插件没启用、服务中途被普通配置重启,这三种情况都不会报错:服务照常工作,只是链路没了。所以必须有一份可执行的验证清单(第九章),而不是靠"我觉得配好了"。
- MDC 不是万能的 —— 网关是响应式/多线程模型,响应回调不在请求线程上。凡是跨线程的日志,取值要么从请求头读,要么显式传递上下文,不能默认 MDC 一定在。
- 兜底 ID 要有辨识度 ——
local-前缀是一行代码的改动,却省掉了运维拿着本地 UUID 去 UI 里白找的半天空。