Skip to content

Latest commit

 

History

History
119 lines (74 loc) · 5.47 KB

README.md

File metadata and controls

119 lines (74 loc) · 5.47 KB

Auto Trace for Java

Run Tests Maven Central Version Release License: Apache 2.0

​ autotrace4j是一个基于ByteBuddy编写的轻量级日志跟踪工具，其基本逻辑是在各个上下文当中通过代码增强关键节点来传递trace id，最后在日志输出时注入到输出结果当中，以实现日志的跟踪串联。

易使用

​ 基于Agent的方式来使用该工具，对业务代码无侵入、运维可在基础层面统一配置，业务方可无感知。

轻量级

​ 只依赖ByteBuddy，且增加的增强代码只是往Thread Local当中写入字符串或读出字符串，没有做额外事项，不会增加性能开销。

Startup

​ autotrace4j的使用非常简单，只需从release中下载最新的agent jar包，在启动脚本中以agent方式运行：

$ java -javaagent=/dir/to/autotrace4j.jar -Dautotrace4j.log.enable=true -jar YourJar.jar  # 省略其他无关参数
  • 一般情况下不需要开启autotrace4j内部日志，即不需要-Dautotrace4j.log.enable=true，如果需要观测到增强过程增强了哪些类，或在调试autotrace4j时有需要，可开启该日志选项，其他选项可使用默认参数：
    • -Dautotrace4j.log.enable=true 设置开启autotrace4j内部日志
    • -Dautotrace4j.log.dir=/path/to/your/log/dir 修改autotrace4j内部日志保存路径
    • -Dautotrace4j.log.level=TRACE （可选TRACE, DEBUG, INFO, WARN, ERROR）修改日志级别
    • -Dautotrace4j.log.file.retention=5 设置autotrace4j内部日志保留天数为5天
    • -Dautotrace4j.log.file.size=10485760设置单个文件大小为10M(10*1024*1024=10485760)

关于日志

可通过如下系统属性开启和设置日志来观察增强过程：

  • autotrace4j.log.enable：是否开启autotrace4j日志，默认false
  • autotrace4j.log.dir：autotrace4j日志文件保存路径，默认为临时目录java.io.tmpdir
  • autotrace4j.log.level：autotrace4j日志级别，默认为DEBUG
  • autotrace4j.log.file.retention：autotrace4j日志文件保留时间，单位天，默认为7天
  • autotrace4j.log.file.size：autotrace4j日志文件大小限制，单位字节(B)，默认为0表示不限制

关于MDC

可通过slf4j或者log4j的MDC获取当前上下文的Trace ID：

  • 当通过 MDC.get("X-Ato-Span-Id")时返回当前上下文的 SpanId
  • 当通过 MDC.get("X-Ato-P-Span-Id")时返回当前上下文的 ParentSpanId
  • 当通过 MDC.get("X-Ato-Trace-Id")时返回当前上下文的 TraceId

Supported Context

1、Thread

​ 针对Thread进行了增强，在创建线程时支持自动传递当前Trace: java.lang.Thread

2、Thread Pool

​ 基于如下包作为基础的线程池均支持自动Trace跟踪:

  • java.util.concurrent.ThreadPoolExecutor
  • java.util.concurrent.ForkJoinPool
  • java.util.concurrent.ScheduledThreadPoolExecutor

3、Http Client

​ 基于如下几个Client的HTTP请求客户端在发送请求时都会自动将当前上下文的TraceId设置到请求头：

  • OkHttp3：com.squareup.okhttp3:okhttp
  • JDK Http Client：jdk:sun.net.www.http.HttpClient
  • ApacheHttpClient：org.apache.httpcomponents:httpclient

4、Http Servlet

​ 我们支持了HTTP Filter和HTTP Servlet来从请求头当中接收TraceId并设置到当前上下文：

  • javax.servlet.Filter
  • javax.servlet.http.HttpServlet

5、Middleware

​ 支持Dubbo、Kafka、阿里云ONS、RocketMQ在生产和消费时传递trace：

  • Spring Kafka：Producer & Consumer
    • 如果消息没有trace信息，则生成新的trace信息
    • 📢：如果是批量消费消息，traceId取第一条消息的traceId，parentSpanId取第一条消息的spanId
  • Spring RocektMQ & Aliyun ONS：Producer & Consumer
  • Dubbo：org.apache.dubbo.rpc.protocol.dubbo.filter.TraceFilter org.apache.dubbo.rpc.protocol.dubbo.filter.FutureFilter

6、Scheduled

​ 支持XXL Job、Spring Scheduled定时任务、PowerJob在产生时传递TraceId：

  • XxlJob Handler：com.handler.com.xxl.job.core.IJobHandler
  • Spring Schedule Task：org.springframework.scheduling.annotation.Scheduled
  • PowerJob Processor：tech.powerjob.worker.core.processor.sdk.BasicProcessor

7、Logging

​ 支持几个主流日志框架的最终输出，自动加入trace信息(主要针对Stream和RollingFile的字符串和JSON格式)：

  • JUL、Log4j、Logback、Log4j2

Contribute

欢迎贡献你的代码(Fork & Pull Request)，一起完善autotrace4j库：

  • 如何增加支持：

    在io.github.artlibs.autotrace4j.transformer下仿照其他转换器新增

  • 关于单元测试：

    在io.github.artlibs.autotrace4j.At4jTest中参考其他案例增加单元测试

本地单测：

$ export JAVA_HOME=/path/to/your/jdk21/home
$ make test