ContiNew

切换日光/暗黑模式

链路追踪 (trace) ​

最后更新: 3 天前
实践版本: v2.13.4

简介 ​

continew-starter-trace 是 ContiNew Starter 链路追踪模块，底层基于 TLog 实现分布式系统的调用链路追踪，通过自动生成和传递 TraceId，帮助开发者快速定位跨服务调用问题，提升系统可观测性。

主要特性 ​

  • 自动生成全局唯一TraceId，支持跨服务传递
  • 集成日志框架MDC，实现全链路日志关联
  • 自定义TraceId生成策略
  • 灵活的配置选项，支持日志输出格式自定义
  • 低侵入式设计，通过过滤器自动拦截请求

快速开始 ​

引入依赖 ​

pom.xml
xml
<dependency>
    <groupId>top.continew.starter</groupId>
    <artifactId>continew-starter-trace</artifactId>
</dependency>

添加配置 ​

添加完如下配置后，链路追踪功能将自动生效，自动生成 TraceId 并添加到响应头中。

application.yml
yaml
--- ### 链路追踪配置
continew-starter.trace:
  enabled: true
  trace-id-name: X-Trace-Id
  ## TLog 配置
  tlog:
    enable-invoke-time-print: false
    pattern: '[$spanId][$traceId]'
    mdc-enable: false

修改日志配置 ​

如果需要在日志输出中添加 TraceId，请修改日志配置文件。

logback-spring.xml
xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration debug="false" scan="true" scanPeriod="30 seconds">

    <!-- 应用名 -->
    <springProperty name="APP_NAME" source="spring.application.name" scope="context"/>
    <!-- 保存路径 -->
    <property name="LOG_PATH" value="${LOG_PATH:-./logs}"/>
    <!-- 字符集 -->
    <property name="LOG_CHARSET" value="utf-8"/>
    <!-- 格式化输出：%d 表示日期；%thread 表示线程名；%-5level：级别从左显示 5 个字符宽度；%msg：日志消息；%n 是换行符 -->
    <!-- 控制台输出格式（带颜色） -->
    <property name="CONSOLE_LOG_PATTERN" value="%red(%d{yyyy-MM-dd HH:mm:ss}) %highlight(%-5level) %green([%thread]) %boldMagenta(%logger{50}) - %msg%n"/>
    <!-- 文件输出格式 -->
    <property name="FILE_LOG_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss} %-5level [%thread] %logger{50} - %msg%n"/>
    <!-- 单个日志文件大小上限 -->
    <property name="FILE_MAX_SIZE" value="20MB"/>

    <!-- 输出日志到控制台 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="com.yomahub.tlog.core.enhance.logback.AspectLogbackEncoder">
            <pattern>${CONSOLE_LOG_PATTERN}</pattern>
            <charset>${LOG_CHARSET}</charset>
        </encoder>
    </appender>

    <!-- 输出日志到控制台（不带颜色） -->
    <appender name="CONSOLE_PROD" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="com.yomahub.tlog.core.enhance.logback.AspectLogbackEncoder">
            <pattern>${FILE_LOG_PATTERN}</pattern>
            <charset>${LOG_CHARSET}</charset>
        </encoder>
    </appender>

    <!-- 输出日志到文件 -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <!-- 正在记录的日志文件的路径及文件名 -->
        <file>${LOG_PATH}/${APP_NAME}.log</file>
        <!-- 滚动策略：基于文件大小和时间归档日志文件 -->
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_PATH}/%d{yyyy-MM-dd}/${APP_NAME}.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>${FILE_MAX_SIZE}</maxFileSize>
            <maxHistory>${FILE_MAX_HISTORY}</maxHistory>
        </rollingPolicy>
        <encoder class="com.yomahub.tlog.core.enhance.logback.AspectLogbackEncoder">
            <pattern>${FILE_LOG_PATTERN}</pattern>
            <charset>${LOG_CHARSET}</charset>
        </encoder>
    </appender>

    <!-- 输出日志到文件（异步） -->
    <appender name="ASYNC_FILE" class="com.yomahub.tlog.core.enhance.logback.async.AspectLogbackAsyncAppender">
        <!-- 不丢失日志，默认：如果队列的 80% 已满，则会丢弃 TRACT、DEBUG、INFO 级别的日志 -->
        <discardingThreshold>0</discardingThreshold>
        <!-- 更改默认的队列的深度，该值会影响性能，默认：256 -->
        <queueSize>512</queueSize>
        <!-- 添加附加的 appender，最多只能添加一个 -->
        <appender-ref ref="FILE"/>
    </appender>

    <!-- 开发环境：只打印到控制台 -->
    <springProfile name="dev">
        <!-- 如果配置的日志等级，和 application.yml 中的日志等级配置重叠，application.yml 配置优先级高 -->
        <root level="INFO">
            <appender-ref ref="CONSOLE"/>
        </root>
    </springProfile>

    <!-- 生产环境：打印到控制台并输出到文件 -->
    <springProfile name="prod">
        <root level="INFO">
            <appender-ref ref="CONSOLE_PROD"/>
            <appender-ref ref="ASYNC_FILE"/>
        </root>
        <!-- 日志保留天数（根据国家法律，网络运行状态、网络安全事件、个人敏感信息操作等相关记录，留存的日志不少于六个月，并且进行网络多机备份。） -->
        <property name="FILE_MAX_HISTORY" value="180"/>
    </springProfile>
</configuration>

自定义TraceId生成器 ​

默认使用TraceIdGenerator基于雪花算法生成TraceId，如需自定义实现：

  1. 创建自定义生成器类实现TLogIdGenerator接口
java
public class CustomTraceIdGenerator extends TLogIdGenerator {
    @Override
    public String generateTraceId() {
        // 自定义TraceId生成逻辑
        return UUID.randomUUID().toString().replace("-", "");
    }
}
  1. 注册为Spring Bean
java
@Configuration
public class TraceConfig {
    @Bean
    public TLogIdGenerator customTraceIdGenerator() {
        return new CustomTraceIdGenerator();
    }
}

核心依赖 ​

依赖描述
top.continew.starter:continew-starter-core核心模块
com.yomahub:tlog-web-spring-boot-starterTLog（轻量级的分布式日志标记追踪神器）

参考资料 ​

  1. TLog 官方文档：https://tlog.yomahub.com/