一、功能概述

上一篇《增加企业级日志打印》解决了两个问题:日志落盘归档 + 每行日志带上 [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 UIhttp://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,输出到每行日志
服务端存储ElasticsearchOAP 侧使用,开发无需关心

版本必须三方对齐(本项目统一 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)。


三、整体架构

图片.png

为什么用 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 只能解决**"日志之间能不能串"**,它有三个天花板:

能力自建 traceIdSkyWalking
日志按请求串起来✅✅
每个调用段的耗时❌✅
服务拓扑图❌✅
慢 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/ 才生效

图片.png

而网关用到的两个插件恰好都在 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 链路流转

图片.png

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 服务端地址(项目已有远端环境,直接用)

组件地址说明
UIhttp://117.72.88.11:1080拓扑 / 链路 / 日志检索
OAP gRPC117.72.88.11:11800Agent 上报地址
OAP HTTP / GraphQL117.72.88.11:12800UI 与命令行查询

实测 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-gateway8080
kb-user-auth (SkyWalking)kb-user-auth8081
kb-document (SkyWalking)kb-document8082
kb-search (SkyWalking)kb-search8083
kb-file (SkyWalking)kb-file8084
kb-statistics (SkyWalking)kb-statistics8085
kb-ai (SkyWalking)kb-ai8086
kb-graph (SkyWalking)kb-graph8088
kb-foundation (SkyWalking)kb-foundation8089

每个配置的 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.sh

7.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_NAMEkb-gateway 等服务在 UI 上的显示名,每个服务不同
SW_AGENT_COLLECTOR_BACKEND_SERVICES117.72.88.11:11800OAP gRPC 地址
SW_AGENT_SAMPLE-1采样数,-1 = 全采样(开发建议)
SW_LOGGING_LEVELINFO / WARNAgent 自身日志级别(不是业务日志)
SW_LOGGING_OUTPUTFILE / CONSOLEAgent 自身日志输出位置
采样说明: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.jarSpring MVC 6 方法级追踪各业务服务(Spring Boot 3)
apm-mybatis-3.x-plugin-9.0.0.jarMyBatis 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认证成功,已设置SecurityContext

TID 是 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

两点说明:

  1. 列表里没有的服务 = 该服务没挂 Agent,或没产生过流量(Agent 是"有请求才注册");
  2. 多出来的 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 回捞那一段日志

几个关键落点

  1. 工具包放公共模块,一处引入全服务生效 —— 与上一篇的日志配置同样的思路,接入成本集中在 kb-common 一处。
  2. 同一个 ID 走两条通道 —— traceId 既进日志的 MDC,又是 SkyWalking 的链路 ID。不做这件事,就会变成"日志一套 ID、APM 一套 ID",排障时两头对不上。
  3. 静默失败最危险 —— Agent 没挂、插件没启用、服务中途被普通配置重启,这三种情况都不会报错:服务照常工作,只是链路没了。所以必须有一份可执行的验证清单(第九章),而不是靠"我觉得配好了"。
  4. MDC 不是万能的 —— 网关是响应式/多线程模型,响应回调不在请求线程上。凡是跨线程的日志,取值要么从请求头读,要么显式传递上下文,不能默认 MDC 一定在。
  5. 兜底 ID 要有辨识度 —— local- 前缀是一行代码的改动,却省掉了运维拿着本地 UUID 去 UI 里白找的半天空。
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏