# TraceLog

**Repository Path**: itSpurs/trace-log

## Basic Information

- **Project Name**: TraceLog
- **Description**: 源自项目中自研的日志组件。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 2
- **Created**: 2021-01-25
- **Last Updated**: 2025-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TraceLog



#### 背景

源自实际生产系统中的自研日志组件，提取核心部分，进行优化、整理后形成该项目。

希望和大家一起交流学习。



#### 功能特性

* 基于 slf4j框架，所以适配与log4j和logback等多种日志框架
* 自动生成机器IP、类名、方法名、行号等日志Tag数据，加入到日志数据中。

* 自动生成traceId信息，串联Spring Cloud Gateway 、 Spring Cloud Feign 、 Spring Cloud Hystrix 、 SpringMVC 、Spring Cloud Stream 等组件的调用链路。

* 使用 阿里的开源框架 [transmittable-thread-local](https://github.com/alibaba/transmittable-thread-local) 框架实现跨线程调用时 ThreadLocal 信息的传递

* 使用Spring AOP技术，实现引入注解即可自动打印方法入参、出参、请求耗时
* 如果使用当前组件的应用同时使用了SkyWalking Agent，则会自动将SkyWalking的traceId加到日志中，使得logging信息和tracing信息结合在一起，方便定位问题。



#### 使用方法

代码示例：

定义扫描的路径
```
@ComponentScan("com.terry.trace")
```

定义LOGGER
```
private static final TraceLogger LOGGER = TraceLogger.getLogger(LogController.class);
```

使用@LogAround，可自动打印方法入参、出参、请求耗时(打印日志会自动填充上tag信息)
```
// 打印方法入参、出参、请求耗时
@LogAround
public String say(String name) {
    // 打印日志	
    LOGGER.info("say name = [{}]", name);
    return "success";
}
```


日志示例：

```
2021-02-03 18:19:27.649  INFO 20004 --- [nio-8080-exec-1] com.terry.trace.plugin.LogAspect         : {"ip":"99.248.1.1","hostName":"JiangYaopeng-PC","flowNo":"202102031819243261069467316","service":"LogController","funcName":"say","lineNum":"0","time":"2021-02-03 18:19:27","traceId":"c21b3c489ac24cc58acee22bee2e1c41.85.16123400454510793","msg":"LogController.say start. parameter: name = [张三]"}

2021-02-03 18:19:29.727  INFO 20004 --- [nio-8080-exec-1] c.t.trace.test.controller.LogController  : {"ip":"99.248.1.1","hostName":"JiangYaopeng-PC","flowNo":"202102031819243261069467316","service":"LogController","funcName":"say","lineNum":"16","time":"2021-02-03 18:19:29","traceId":"c21b3c489ac24cc58acee22bee2e1c41.85.16123400454510793","msg":"say name = [张三]"}

2021-02-03 18:19:29.728  INFO 20004 --- [nio-8080-exec-1] com.terry.trace.plugin.LogAspect         : {"ip":"99.248.1.1","hostName":"JiangYaopeng-PC","flowNo":"202102031819243261069467316","service":"LogController","funcName":"say","lineNum":"0","time":"2021-02-03 18:19:29","traceId":"","msg":"LogController.say end. cost time: 2125ms. return value: success"}
```



为方便理解日志，我们将日志message部分格式化：

```
{
	"ip": "99.248.1.1",
	"hostName": "JiangYaopeng-PC",
	"flowNo": "202102031819243261069467316",
	"service": "LogController",
	"funcName": "say",
	"lineNum": "16",
	"time": "2021-02-03 18:19:29",
	"traceId": "c21b3c489ac24cc58acee22bee2e1c41.85.16123400454510793",
	"msg": "say name = [张三]"
}

{
	"ip": "99.248.1.1",
	"hostName": "JiangYaopeng-PC",
	"flowNo": "202102031819243261069467316",
	"service": "LogController",
	"funcName": "say",
	"lineNum": "0",
	"time": "2021-02-03 18:19:29",
	"traceId": "c21b3c489ac24cc58acee22bee2e1c41.85.16123400454510793",
	"msg": "LogController.say end. cost time: 2125ms. return value: success"
}
```

message中tag字段的含义：

| 字段     | 含义                                                         |
| -------- | ------------------------------------------------------------ |
| ip       | 应用的ip地址                                                 |
| hostName | 应用所在主机的名称                                           |
| flowNo   | 全局流水号，和traceId一样，一个完整链路对应一个traceId。为了与SkyWalking的traceId区分，命名为flowNo |
| service  | 日志代码所属类                                               |
| funcName | 日志代码所属方法                                             |
| lineNum  | 日志代码所属行号。如果是方法环绕打印出参和入参，则行号为0    |
| time     | 打印日志的时间                                               |
| traceId  | SkyWalking的traceId                                          |
| msg      | 日志信息                                                     |