架构与系统设计 / 系统课时

租户日志与链路追踪

租户日志与链路追踪

本课解决多租户请求“出了问题却无法快速定位属于谁、经过哪里、影响哪笔业务”的问题。完成后,你将建立统一上下文,在日志与链路中稳定记录租户、用户、请求和业务标识,并能按一次请求还原完整调用路径。

学习目标

  • 设计租户日志与链路追踪的统一字段集合
  • 在 Spring Boot 请求入口写入并安全清理日志上下文
  • 使用请求标识和链路标识完成跨服务检索与故障定位

统一可观测上下文

一次请求至少要关联四类标识:tenantId 表示数据归属,userId 表示操作主体,requestId 表示本次入口请求,traceId 表示跨服务调用链。订单号、任务号等 businessId 则负责把技术链路映射到具体业务对象。

requestId 通常由网关生成并向下游透传;traceId 由追踪组件维护,一个请求经过多个服务时保持不变,而每个调用片段拥有独立的 spanId。二者职责不同,不应只保留其中一个。

多租户请求的日志与链路关联图

字段必须从可信位置取得。tenantId 应来自已校验的租户上下文,userId 应来自认证结果,不能直接相信客户端随意传入的同名请求头。日志中还应保留 HTTP 方法、路径、状态码和耗时,避免只有标识却缺少事件内容。

在请求入口写入 MDC

下面是 Spring Boot 3 的片段示例,依赖 Spring Web、SLF4J 和 Micrometer Tracing。示例为便于演示从请求头读取租户与用户,生产环境应替换为网关验签结果或认证上下文。

java
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> 和链路标识会随实际请求变化。

text
<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 配置:

yaml
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 还原调用链

下一课预告

下一课将设计独立的审计日志模型,记录登录、授权、配置变更、数据导出和敏感操作,并保证事件可查询、可追责且难以篡改。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

租户日志与链路追踪

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通