Alauda Container Platform
  • 简体中文
    • TIP

    本文将指导开发者如何在应用代码中集成获取 TraceID和将 TraceID 添加到应用日志的方法，适合具有一定开发经验的后端开发者。

    业务日志与 TraceID 关联

    目录

    背景在 Java 应用日志中添加 TraceID在 Python 应用日志中添加 TraceID验证方法

    背景

    • 为了将单次请求过程中自动发送的多个 span（不同模块/节点/服务调用）正确关联成一个完整的 trace，服务的 HTTP 请求头中会携带 TraceID 及其他用于关联 trace 的信息。

    • 一个 trace 代表一次请求的调用过程，TraceID 是标识该请求的唯一 ID。日志中有了 TraceID，便可以将 trace 与应用日志关联起来。

    基于以上背景，本文将说明如何从 HTTP 请求头中获取 TraceID 并将其添加到应用日志中，从而使您能够在平台上通过 TraceID 精准查询日志数据。

    在 Java 应用日志中添加 TraceID

    TIP

    • 以下示例基于 Spring Boot 框架，使用 Log4j 和 Logback 进行说明。

    • 您的应用需满足以下前置条件：

      • 日志库类型及版本需满足以下要求：

        日志库版本要求
        Log4j 11.2+
        Log4j 22.7+
        Logback1.0+

      • 应用已注入 Java Agent。

    方法一：配置 logging.pattern.level

    在应用配置中修改 logging.pattern.level 参数如下：

    logging.pattern.level = trace_id=%mdc{trace_id}

    方法二：配置 CONSOLE_LOG_PATTERN

    1. 修改 logback 配置文件如下。

      TIP

      此处以控制台输出为例，%X{trace_id} 表示从 MDC 中获取 key 为 trace_id 的值。

      <property name="CONSOLE_LOG_PATTERN"
    value="${CONSOLE_LOG_PATTERN:-%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} [trace_id=%X{trace_id}] %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}}"/>

    2. 在需要输出日志的类中添加 @Slf4j 注解，并使用 log 对象输出日志，示例如下：

      @RestController
@Slf4j
public class ProviderController {

    @GetMapping("/hello")
    public String hello(HttpServletRequest request) {
        log.info("request /hello");
        return "hello world";
    }
}

    在 Python 应用日志中添加 TraceID

    1. 在应用代码中添加如下代码，从请求头中获取 TraceID。示例代码如下，可根据需要调整：

      TIP

      getForwardHeaders 函数从请求头中获取 trace 信息，其中 x-b3-traceid 的值即为 TraceID。

         def getForwardHeaders(request):
       headers = {}
       incoming_headers = [
           'x-request-id',  # 所有应用均应传递 x-request-id，用于访问日志和一致的 trace/log 采样决策
           'x-b3-traceid',  # B3 trace 头，兼容 Zipkin、OpenCensusAgent 和 Stackdriver 配置
           'x-b3-spanid',
           'x-b3-parentspanid',
           'x-b3-sampled',
           'x-b3-flags',
       ]
       for ihdr in incoming_headers:
           val = request.headers.get(ihdr)
           if val is not None:
               headers[ihdr] = val

       return headers

    2. 在应用代码中添加如下代码，将获取到的 TraceID 添加到日志中。示例代码如下，可根据需要调整：

      headers = getForwardHeaders(request)
tracing_section = ' [%(x-b3-traceid)s,%(x-b3-spanid)s] ' % headers
logging.info(tracing_section + "Oops, unexpected error happens.")

    验证方法

    1. 点击左侧导航栏的 Tracing。

    2. 在查询条件中选择 TraceID，输入要查询的 TraceID，点击 Add to query。

    3. 在下方展示的 trace 数据中，点击 TraceID 旁的 View Log。

    4. 在 Log Query 页面，勾选 Contain Trace ID，系统将仅展示包含该 TraceID 的日志数据。