# TraceLog

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

## Basic Information

- **Project Name**: TraceLog
- **Description**: TraceLog是一个简单易用的Java日志记录组件，专为Spring Boot应用设计，可以轻松集成到您的项目中，并提供丰富的日志记录功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-23
- **Last Updated**: 2025-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TraceLog

TraceLog是一个简单易用的Java日志记录组件，专为Spring Boot应用设计，可以轻松集成到您的项目中，并提供丰富的日志记录功能。

## 特性

- 基于AOP的自动日志记录
- 支持记录完整的请求和响应信息
- 支持敏感信息脱敏处理
- 支持多种日志级别控制
- 支持异步日志记录提高性能
- 支持控制台和文件双重输出
- 支持大对象智能检测
- 支持异常堆栈记录
- 支持自定义日志存储方式
- 支持Ant风格的路径排除模式
- 支持类和方法级别的注解配置
- 支持分布式链路追踪（TraceID）
- 支持MDC上下文变量
- 无需修改现有代码，即插即用

## 快速开始

### 1. 添加依赖

```xml
<dependency>
    <groupId>com.tracelog</groupId>
    <artifactId>tracelog-core</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 2. 配置TraceLog

在`application.yml`中添加TraceLog配置：

```yaml
trace-log:
  enabled: true
  cache-request-body: true
  enable-trace-id: true
  async: true
  print-to-console: true
  file-output: true
  log-file-path: logs/tracelog.log
  mask-sensitive-info: true
  sensitive-fields:
    - password
    - email
  exclude-patterns:
    - /actuator/**
```

### 3. 配置日志格式（可选）

在`application.yml`中配置日志格式以显示TraceID：

```yaml
logging:
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{36} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{36} - %msg%n"
```

### 4. 使用@TraceLog注解

在控制器或服务类上添加`@TraceLog`注解：

```java
@RestController
@RequestMapping("/api/users")
@TraceLog(module = "用户管理")
public class UserController {

    @GetMapping
    @TraceLog("获取所有用户")
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }

    @PostMapping
    @TraceLog(value = "创建新用户", level = LogLevel.INFO, 
        sensitiveFields = {"password", "email"})
    public User createUser(@RequestBody User user) {
        return userService.createUser(user);
    }
}
```

## 配置选项

| 配置项 | 描述 | 默认值 |
| ---- | ---- | ---- |
| enabled | 是否启用 | true |
| cache-request-body | 是否缓存请求体 | true |
| enable-trace-id | 是否启用跟踪ID | true |
| async | 是否异步记录日志 | true |
| print-to-console | 是否启用控制台输出 | true |
| file-output | 是否启用文件输出 | false |
| log-file-path | 日志文件路径 | logs/tracelog.log |
| mask-sensitive-info | 是否脱敏敏感信息 | true |
| record-exception-stack-trace | 是否记录异常堆栈 | true |
| exception-stack-trace-lines | 异常堆栈记录行数 | 10 |
| sensitive-fields | 敏感字段列表 | ["password", "pwd", ...] |
| exclude-patterns | 排除的路径模式 | [] |
| large-object-threshold | 大对象检测阈值（字节） | 10240 |

## 注解选项

`@TraceLog`注解支持以下选项：

| 选项 | 描述 | 默认值 |
| ---- | ---- | ---- |
| value | 日志描述 | "" |
| module | 所属模块 | "" |
| level | 日志级别 | LogLevel.INFO |
| includes | 包含信息 | [] |
| excludes | 排除信息 | [] |
| ignore | 是否忽略日志记录 | false |
| recordResponse | 是否记录响应内容 | true |
| sensitiveFields | 脱敏字段 | [] |

## 默认包含的信息

TraceLog默认会记录以下信息：

- **基本信息**：时间戳、日志级别、模块、描述
- **请求信息**：URI、方法、请求体、客户端IP
- **执行信息**：执行时间、异常信息
- **响应信息**：响应体、状态码
- **追踪信息**：TraceID、用户ID（如果有）

## 自定义实现

TraceLog提供了多个接口，您可以自定义实现：

- `LogHandler`：日志处理器，负责创建和处理日志记录
- `LogRecordDao`：日志存储接口，负责持久化日志记录

### 自定义存储

```java
@Component
public class DatabaseLogRecordDao implements LogRecordDao {
    
    @Autowired
    private JdbcTemplate jdbcTemplate;
    
    @Override
    public void save(LogRecord logRecord) {
        // 将日志保存到数据库
        String sql = "INSERT INTO operation_log(trace_id, module, description, method, uri, execution_time) " +
                     "VALUES(?, ?, ?, ?, ?, ?)";
        jdbcTemplate.update(sql, 
            MDC.get("traceId"),
            logRecord.getModule(),
            logRecord.getDescription(),
            logRecord.getMethod(),
            logRecord.getUri(),
            logRecord.getExecutionTime().toMillis()
        );
    }
}
```

### 自定义处理器

```java
@Component
public class CustomLogHandler implements LogHandler {
    // 实现自定义的日志处理逻辑
    // ...
}
```

## 高级功能

### 敏感信息脱敏

TraceLog会自动对以下字段进行脱敏：

- 密码字段：password、pwd
- 认证相关：token、authorization、secret
- 个人信息：email、mobile、phone

您可以通过配置文件或注解添加更多敏感字段。

### 异常堆栈记录

TraceLog可以记录异常的堆栈信息，默认记录前10行，可以通过配置调整：

```yaml
trace-log:
  record-exception-stack-trace: true
  exception-stack-trace-lines: 20
```

### 大对象处理

对于超过阈值的大型响应对象，TraceLog会自动记录其大小而不是完整内容，避免占用过多存储空间：

```yaml
trace-log:
  large-object-threshold: 20480  # 20KB
```

### 分布式链路追踪

TraceLog为每个请求生成唯一的跟踪ID，并通过MDC记录到日志中：

- 支持从请求头中获取 `X-Trace-Id`，便于跨服务追踪
- 自动将跟踪ID添加到响应头中，便于客户端排查问题
- 可以通过MDC在日志中显示跟踪ID：`%X{traceId}`

### 条件激活示例

在启用特定配置时才使用某种日志存储实现：

```java
@Bean
@Primary
@Profile("db-storage")
public LogRecordDao databaseLogRecordDao() {
    return new DatabaseLogRecordDao();
}
```

## 示例项目

查看`tracelog-example`模块，了解如何在实际项目中使用TraceLog。示例项目提供了完整的用户管理API实现，展示了TraceLog的各种使用场景。

## 兼容性

- 支持Spring Boot 2.x和3.x版本
- 支持Java 8及以上版本
- 无第三方存储依赖

## 许可证

TraceLog使用MIT许可证。