# log-collector

**Repository Path**: teeoo/log-collector

## Basic Information

- **Project Name**: log-collector
- **Description**: 基于Spring Boot 3的日志收集组件，支持异步采集WARNING及以上级别的日志，并提供多种存储方式（MySQL/Elasticsearch）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-29
- **Last Updated**: 2025-03-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Log Collector

基于Spring Boot 3的日志收集组件，支持异步采集WARNING及以上级别的日志，并提供多种存储方式（MySQL/Elasticsearch）。

## 项目架构

本项目采用模块化设计，主要包含以下组件：

- **log-collector-core**: 核心模块，提供日志收集的基础功能
  - LogCollectorService: 日志收集服务，提供异步日志收集能力
  - LogEntry: 日志实体类，定义日志数据结构
  - LogStorage: 存储接口，基于SPI机制支持多种存储实现

- **log-collector-demo**: 示例应用，展示如何集成和使用日志收集器

## 特性

- **基于Spring Boot 3**: 充分利用Spring Boot 3的新特性和性能优化
- **异步处理**: 使用@Async注解实现异步日志收集，不影响主业务流程
- **多种存储方式**: 基于SPI机制实现可扩展的存储层
  - MySQL存储: 支持将日志存储到MySQL数据库
  - Elasticsearch存储: 支持将日志存储到Elasticsearch，便于日志检索和分析
- **简单集成**: 提供简单的配置方式和API，快速集成到现有项目
- **可定制化**: 支持自定义日志收集级别、存储方式和其他配置

## 快速开始

### 1. 添加依赖

```xml
<!-- 日志收集器核心包 -->
<dependency>
    <groupId>cn.kickegg.log</groupId>
    <artifactId>log-collector-core</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

<!-- MySQL存储方式需要添加以下依赖 -->
<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
</dependency>
```

### 2. 配置存储方式

#### MySQL存储配置示例（application.yml）

```yaml
# 日志收集器配置
log:
  collector:
    storage:
      type: mysql

# 数据源配置
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/logs?createDatabaseIfNotExist=true
    username: your-username
    password: your-password
    driver-class-name: com.mysql.cj.jdbc.Driver

# MyBatis配置
mybatis:
  mapper-locations: classpath*:mapper/*.xml  # 使用classpath*以支持扫描依赖jar包中的mapper
  configuration:
    map-underscore-to-camel-case: true      # 开启驼峰命名转换
```

#### MySQL存储的Mapper配置

在您的项目中创建以下配置类：

```java
@Configuration
@MapperScan(basePackages = {
    "cn.kickegg.log.core.mapper",   // 扫描core包中的mapper
    "your.package.mapper"           // 您自己的mapper包
})
public class MyBatisConfig {
}
```

#### Elasticsearch存储配置示例（application.yml）

```yaml
log:
  collector:
    storage:
      type: elasticsearch
    elasticsearch:
      hosts: localhost:9200
      username: elastic  # 可选
      password: your-password  # 可选
      ssl: false
      certificate-path: /path/to/certificate  # 如果启用SSL时需要
      connection-timeout: 5000
      socket-timeout: 60000
      index-name: application_logs
```

### 3. 使用日志收集器

```java
@Service
public class YourService {
    private final LogCollectorService logCollectorService;
    
    public YourService(LogCollectorService logCollectorService) {
        this.logCollectorService = logCollectorService;
    }
    
    public void someMethod() {
        try {
            // 你的业务代码
        } catch (Exception e) {
            logCollectorService.collectLog(
                "your-app-name",
                "ERROR",
                e.getMessage(),
                getStackTrace(e),
                this.getClass().getName(),
                "methodName",
                Thread.currentThread().getName()
            );
        }
    }
    
    private String getStackTrace(Exception e) {
        StringBuilder sb = new StringBuilder();
        for (StackTraceElement element : e.getStackTrace()) {
            sb.append(element.toString()).append("\n");
        }
        return sb.toString();
    }
}
```

## 配置说明

### MySQL配置要求

MySQL存储方式需要使用方提供以下配置：

1. 数据源配置（spring.datasource）：
   - url：数据库连接URL
   - username：数据库用户名
   - password：数据库密码
   - driver-class-name：数据库驱动类

2. MyBatis配置（可选）：
   - mapper-locations：Mapper XML文件位置
   - type-aliases-package：实体类包路径

### Elasticsearch配置项

| 配置项             | 说明               | 默认值           |
| ------------------ | ------------------ | ---------------- |
| hosts              | ES主机地址列表     | localhost:9200   |
| username           | 用户名             | null             |
| password           | 密码               | null             |
| ssl                | 是否启用SSL        | false            |
| certificate-path   | 证书路径           | null             |
| connection-timeout | 连接超时时间(ms)   | 5000             |
| socket-timeout     | Socket超时时间(ms) | 60000            |
| index-name         | 索引名称           | application_logs |

## 数据库表结构

MySQL存储方式使用的表结构如下：

```sql
CREATE TABLE log_entries (
    id VARCHAR(36) PRIMARY KEY,
    application_name VARCHAR(100),
    level VARCHAR(20),
    message TEXT,
    stack_trace TEXT,
    class_name VARCHAR(255),
    method_name VARCHAR(255),
    timestamp DATETIME,
    thread_name VARCHAR(100)
);
```

## 示例项目

项目中包含了一个完整的示例应用（log-collector-demo），展示了如何集成和使用这个日志收集器。你可以参考这个示例来了解具体的使用方式。

## 最佳实践

### 日志收集策略

1. **选择合适的日志级别**
   - WARNING: 业务警告信息
   - ERROR: 业务错误信息
   - FATAL: 致命错误信息

2. **异常处理最佳实践**
   ```java
   try {
       // 业务代码
   } catch (BusinessException e) {
       // 业务异常，使用WARNING级别
       logCollectorService.collectLog(
           "your-app-name",
           "WARNING",
           e.getMessage(),
           getStackTrace(e),
           this.getClass().getName(),
           "methodName",
           Thread.currentThread().getName()
       );
   } catch (Exception e) {
       // 系统异常，使用ERROR级别
       logCollectorService.collectLog(
           "your-app-name",
           "ERROR",
           e.getMessage(),
           getStackTrace(e),
           this.getClass().getName(),
           "methodName",
           Thread.currentThread().getName()
       );
   }
   ```

3. **日志信息规范**
   - applicationName: 使用有意义的应用名称，便于区分不同应用
   - message: 提供清晰的错误描述
   - stackTrace: 包含完整的堆栈信息
   - className和methodName: 准确记录异常发生的位置

### 存储选择建议

1. **MySQL存储**
   - 适用于日志量较小的应用
   - 需要与业务数据关联分析的场景
   - 对实时性要求不高的场景

2. **Elasticsearch存储**
   - 大规模日志收集和分析
   - 需要复杂查询和聚合分析
   - 实时日志监控和告警

## 注意事项

1. **环境准备**
   - 确保选择的存储方式（MySQL/Elasticsearch）服务可用
   - 所有数据源配置（MySQL/MyBatis等）都需要在您自己的项目中完成
   - 如果使用MySQL存储，需要确保数据表已经创建

2. **性能考虑**
   - 日志收集是异步进行的，不会影响主业务流程
   - 默认只收集WARNING及以上级别的日志
   - 建议定期清理历史日志数据
   - 合理设置Elasticsearch的索引策略

3. **安全建议**
   - 妥善保管数据库和Elasticsearch的访问凭证
   - 避免在日志中记录敏感信息
   - 建议启用SSL加密传输

## 常见问题

1. **日志丢失问题**
   - 确保存储服务的可用性
   - 检查异步线程池配置
   - 验证存储服务的连接配置

2. **性能问题**
   - 合理设置日志级别
   - 优化日志内容大小
   - 定期维护存储服务

3. **存储选择**
   - 小规模应用推荐使用MySQL
   - 大规模应用推荐使用Elasticsearch
   - 可以根据需求同时使用多种存储方式