告别分布式系统黑盒：PiggyMetrics Sleuth分布式追踪traceId/spanId日志与Zipkin实战-平芜编程栈

告别分布式系统黑盒：PiggyMetrics Sleuth分布式追踪traceId/spanId日志与Zipkin实战

【免费下载链接】piggymetricsMicroservice Architecture with Spring Boot, Spring Cloud and Docker项目地址: https://gitcode.com/gh_mirrors/pi/piggymetrics

一、为什么微服务系统会变成"黑盒" 🕳️

PiggyMetrics 是一个基于 Spring Boot、Spring Cloud 和 Docker 的微服务架构财务演示项目。一次普通的"查看账户统计"请求，实际会依次经过 API 网关gateway、账户服务account-service、统计服务statistics-service，再经过 OAuth2 认证服务auth-service校验令牌。

请求链越长，排障越痛苦：

用户反馈"页面慢"，但哪个服务慢？
某个ERROR日志出现在 3 个服务里，哪几条日志属于同一次请求？
没有统一标识，只能靠时间戳"人肉对齐"日志——这就是分布式系统的"黑盒"问题

💡核心解法：给每一次请求发一张"身份证号"，并让所有日志都带上它。这正是 Spring Cloud Sleuth 干的事。

二、Sleuth 如何给日志"盖章"：traceId 与 spanId

Spring Cloud Sleuth 会为每个进入系统的请求生成一个全局traceId（追踪 ID），并为请求链上的每一步操作生成spanId（跨度 ID）：

概念	含义	类比
`traceId`	一次完整请求的链路 ID	快递单号
`spanId`	链路中一个基础工作单元（如一次 HTTP 调用）	单号下的每一段运输记录

PiggyMetrics 在 gateway/pom.xml、account-service/pom.xml、auth-service/pom.xml、statistics-service/pom.xml、notification-service/pom.xml 中都引入了spring-cloud-starter-sleuth依赖，五个服务统一接入追踪。

接入后，所有日志会自动带上 Sleuth 注入的 MDC 字段，格式为[appname, traceId, spanId, exportable]。项目 README.md 中给出了真实日志示例：

2018-07-26 23:13:49.381 WARN [gateway,3216d0de1384bb4f,3216d0de1384bb4f,false] 2999 --- o.s.c.n.z.f.r.s.AbstractRibbonCommand : The Hystrix timeout ... 2018-07-26 23:13:49.562 INFO [account-service,3216d0de1384bb4f,404ff09c5cf91d2e,false] 3079 --- c.p.account.service.AccountServiceImpl : new account has been created: test

看懂这两行，就入门了分布式日志排查：

3216d0de1384bb4f是同一个traceId——两条日志虽然来自gateway和account-service两个不同服务，但属于同一次请求
spanId各自不同：网关的 spanId 等于 traceId（它是链路起点），账户服务的 spanId404ff09c5cf91d2e则标识"处理该请求"这个具体步骤
最后一个false是exportable字段，表示该 span 是否应上报到 Zipkin 后端

🔍 实战技巧：在集中日志平台（如 ELK）里直接grep "3216d0de1384bb4f"，即可瞬间拉出这次请求在所有服务中的完整轨迹——黑盒瞬间变成透视图。

三、配置中心如何统一托管追踪相关配置

PiggyMetrics 采用 Spring Cloud Config 作为配置中心，各服务的公共配置集中在 config/src/main/resources/shared/ 目录下：

shared/application.yml：所有服务共享的日志级别、Hystrix 超时（10000ms）、Eureka 注册地址等
shared/gateway.yml、shared/account-service.yml 等：各服务专属配置

这种"一处修改、全链路生效"的模式，让追踪、超时、限流等横切配置可以被统一治理，而不是散落在每个服务里。

四、Zipkin 实战：把请求链"画"出来 🎨

traceId解决日志关联问题，而Zipkin则把整条调用链可视化为瀑布图：每个 span 是谁发起的、调用了谁、耗时多少，一目了然。

最快上手步骤：

为 Sleuth 加上 Zipkin 上报支持：在需要上报的服务（如 gateway、account-service）中追加spring-cloud-sleuth-zipkin依赖
通过 docker-compose.yml 编排体系新增一个 Zipkin 容器（监听9411端口），并设置spring.zipkin.base-url指向它
启动全部服务后，向http://localhost:8000发起一次请求，打开 Zipkin UI 按服务名检索，即可看到gateway → account-service的完整链路及每段耗时

慢请求排查套路（推荐背下来）：

✅ 用户报障 → 拿到出问题的那次请求的 traceId（从网关日志或响应头获取）
✅ Zipkin 瀑布图定位耗时最长的 span与出错的 span
✅ 用 traceId 回查集中日志，拿到该 span 的完整上下文与堆栈
✅ 修复后用同一个请求回归验证，确认链路耗时恢复正常

五、小结

能力	工具	PiggyMetrics 中的位置
请求链路 ID 注入	Spring Cloud Sleuth	各服务 pom.xml
traceId/spanId 日志格式	Sleuth MDC 自动注入	README.md
统一配置治理	Spring Cloud Config	config/src/main/resources/shared/
调用链可视化	Zipkin	通过 docker-compose 扩展部署