架构与系统设计 / 系统课时
租户日志与链路追踪
租户日志与链路追踪
本课解决多租户请求“出了问题却无法快速定位属于谁、经过哪里、影响哪笔业务”的问题。完成后,你将建立统一上下文,在日志与链路中稳定记录租户、用户、请求和业务标识,并能按一次请求还原完整调用路径。
学习目标
- 设计租户日志与链路追踪的统一字段集合
- 在 Spring Boot 请求入口写入并安全清理日志上下文
- 使用请求标识和链路标识完成跨服务检索与故障定位
统一可观测上下文
一次请求至少要关联四类标识:tenantId 表示数据归属,userId 表示操作主体,requestId 表示本次入口请求,traceId 表示跨服务调用链。订单号、任务号等 businessId 则负责把技术链路映射到具体业务对象。
requestId 通常由网关生成并向下游透传;traceId 由追踪组件维护,一个请求经过多个服务时保持不变,而每个调用片段拥有独立的 spanId。二者职责不同,不应只保留其中一个。

字段必须从可信位置取得。tenantId 应来自已校验的租户上下文,userId 应来自认证结果,不能直接相信客户端随意传入的同名请求头。日志中还应保留 HTTP 方法、路径、状态码和耗时,避免只有标识却缺少事件内容。
在请求入口写入 MDC
下面是 Spring Boot 3 的片段示例,依赖 Spring Web、SLF4J 和 Micrometer Tracing。示例为便于演示从请求头读取租户与用户,生产环境应替换为网关验签结果或认证上下文。
package com.example.observability;
import io.micrometer.tracing.Span;
import io.micrometer.tracing.Tracer;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
import java.util.UUID;
@Component
public class TenantTraceContextFilter extends OncePerRequestFilter {
private static final Logger log =
LoggerFactory.getLogger(TenantTraceContextFilter.class);
private final Tracer tracer;
public TenantTraceContextFilter(Tracer tracer) {
this.tracer = tracer;
}
@Override
protected void doFilterInternal(
HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain) throws ServletException, IOException {
long startNanos = System.nanoTime();
String requestId = valueOrDefault(
request.getHeader("X-Request-Id"),
UUID.randomUUID().toString());
Span span = tracer.currentSpan();
try {
// 生产环境应从已认证、已校验的上下文读取租户和用户。
MDC.put("tenantId", valueOrDefault(
request.getHeader("X-Tenant-Id"), "anonymous"));
MDC.put("userId", valueOrDefault(
request.getHeader("X-User-Id"), "anonymous"));
MDC.put("businessId", valueOrDefault(
request.getHeader("X-Business-Id"), "-"));
MDC.put("requestId", requestId);
MDC.put("traceId", span == null ? "-" : span.context().traceId());
MDC.put("spanId", span == null ? "-" : span.context().spanId());
response.setHeader("X-Request-Id", requestId);
filterChain.doFilter(request, response);
} finally {
long elapsedMs = (System.nanoTime() - startNanos) / 1_000_000;
log.info("request completed method={} path={} status={} elapsedMs={}",
request.getMethod(),
request.getRequestURI(),
response.getStatus(),
elapsedMs);
// 线程池会复用线程,必须清空 MDC,防止租户信息串到下一次请求。
MDC.clear();
}
}
private String valueOrDefault(String value, String defaultValue) {
return value == null || value.isBlank() ? defaultValue : value;
}
}预期输出如下,<ID>、<TIME> 和链路标识会随实际请求变化。
<TIME> INFO tenant=1001 user=2008 request=<ID> trace=<ID> span=<ID> business=ORDER-20260803-001 request completed method=POST path=/api/orders status=200 elapsedMs=37要让这些字段出现在控制台或文件日志中,需要在日志格式中读取 MDC。使用 Logback 时可在 application.yml 配置:
logging:
pattern:
console: "%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level tenant=%X{tenantId:-} user=%X{userId:-} request=%X{requestId:-} trace=%X{traceId:-} span=%X{spanId:-} business=%X{businessId:-} %msg%n"预期结果是每条请求日志都带有相同的租户、请求和链路上下文;没有业务标识时显示 -,不会影响日志解析。
跨服务透传与检索
服务间调用必须透传租户上下文和 X-Request-Id,追踪组件则负责注入标准链路头。不要在每个服务重新生成 requestId 或手工拼接 traceId,否则同一请求会被拆成多段,链路平台也无法正确建立父子关系。
排查时先用 tenantId + businessId 找到业务日志,再复制 traceId 查看整条调用链,最后用 spanId 定位具体服务片段。若请求尚未进入追踪系统,可退回使用 requestId 检索网关和应用日志。
敏感字段不能直接写入日志。密码、令牌、银行卡号、身份证件和完整请求体应进行脱敏或禁止记录;租户管理员也不应默认拥有其他租户日志的检索权限。
验证与常见边界
发起一次带租户和业务标识的请求,确认响应中存在 X-Request-Id,应用日志包含五类标识,并且链路平台可以按 traceId 找到下游调用。随后发送一次缺少业务标识的请求,确认日志使用默认值而不是抛出异常。
异步任务、消息消费和线程池会脱离原始 HTTP 线程。此时要把必要上下文放入消息头或任务参数,并在消费端重新写入 MDC;任务结束后同样需要清理,避免上下文污染后续任务。
本课总结
tenantId、userId、requestId、traceId和businessId共同连接技术事件与业务对象- MDC 必须在入口写入并在
finally中清理,跨服务和异步场景还要显式透传 - 定位问题时先缩小租户与业务范围,再用
traceId还原调用链
下一课预告
下一课将设计独立的审计日志模型,记录登录、授权、配置变更、数据导出和敏感操作,并保证事件可查询、可追责且难以篡改。