# logmodule

**Repository Path**: sheeplight/logmodule

## Basic Information

- **Project Name**: logmodule
- **Description**: No description available
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-13
- **Last Updated**: 2025-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LogModule - Go 日志记录 SDK

一个功能强大的 Go 日志记录 SDK，支持本地文件记录和远程 gRPC 服务传输，基于 zap 日志库构建。

## 特性

- 🚀 **双模式记录**: 同时支持本地文件记录和远程服务传输
- 📁 **多文件分类**: 自动将日志分类到不同文件（local.log, info.log, error.log）
- 🌐 **gRPC 远程传输**: 支持通过 gRPC 将日志发送到远程服务
- ⚡ **异步批量发送**: 高性能异步批量日志传输，避免阻塞主业务
- 🏷️ **结构化字段**: 丰富的字段类型支持，包括字符串、数字、时间、错误等
- 🎯 **智能标签**: 支持标签系统，便于日志分类和检索
- 📊 **统计监控**: 内置统计功能，监控日志发送状态
- 🔧 **灵活配置**: 支持多种初始化方式和配置选项

## 安装

```bash
go get gitee.com/sheeplight/logmodule
```

## 快速开始

### 基本使用

```go
package main

import (
    "gitee.com/sheeplight/logmodule/package/loggo"
)

func main() {
    // 创建日志器
    logger, err := loggo.NewLoggo()
    if err != nil {
        panic(err)
    }
    defer logger.Close()

    // 记录日志
    logger.Info("用户登录成功", 
        loggo.String("user_id", "12345"),
        loggo.String("username", "john_doe"),
        loggo.Tags("auth", "login", "success"))
}
```

### 带远程服务的日志器

```go
package main

import (
    "gitee.com/sheeplight/logmodule/package/loggo"
)

func main() {
    // 创建带远程服务的日志器
    logger, err := loggo.NewLoggoWithRemote(
        "localhost:8080",  // 远程服务地址
        true,              // 启用远程日志
        "my-service",      // 服务名称
        false,             // 是否只记录远程日志
    )
    if err != nil {
        panic(err)
    }
    defer logger.Close()

    // 记录日志（会同时写入本地文件和发送到远程服务）
    logger.Info("API 请求处理完成",
        loggo.String("endpoint", "/api/users"),
        loggo.Int("status_code", 200),
        loggo.Duration("response_time", 150*time.Millisecond),
        loggo.Tags("api", "users", "success"))
}
```

## 初始化方式

### 1. 默认初始化

```go
logger, err := loggo.NewLoggo()
```

- 使用默认配置
- 日志目录: `logs/`
- 远程服务: `localhost:8080`
- 不启用远程日志

### 2. 自定义配置

```go
logger, err := loggo.NewLoggoWithConfig("/var/logs", "info")
```

- `storagePath`: 日志存储路径
- `level`: 最小日志级别 (debug, info, warn, error, fatal)

### 3. 完整配置

```go
logger, err := loggo.NewLoggoWithConfigAndRemote(
    "/var/logs",           // 日志存储路径
    "debug",               // 最小日志级别
    "log-server:8080",     // 远程服务地址
    true,                  // 启用远程日志
    "user-service",        // 服务名称
    false,                 // 是否只记录远程日志
)
```

### 4. 仅远程日志

```go
logger, err := loggo.NewLoggoWithRemoteOnly("log-server:8080", "user-service")
```

- 只发送到远程服务，不写入本地文件
- 适用于微服务架构中的日志聚合

## 日志级别

SDK 支持以下日志级别：

- `Debug`: 调试信息
- `Info`: 一般信息
- `Warn`: 警告信息
- `Error`: 错误信息
- `Fatal`: 致命错误

```go
logger.Debug("调试信息", loggo.String("debug_key", "debug_value"))
logger.Info("一般信息", loggo.String("info_key", "info_value"))
logger.Warn("警告信息", loggo.String("warn_key", "warn_value"))
logger.Error("错误信息", loggo.String("error_key", "error_value"))
logger.Fatal("致命错误", loggo.String("fatal_key", "fatal_value"))
```

## 字段类型

SDK 提供了丰富的字段类型支持：

### 基本类型

```go
logger.Info("用户信息",
    loggo.String("name", "张三"),
    loggo.Int("age", 25),
    loggo.Int64("user_id", 123456789),
    loggo.Bool("is_active", true),
    loggo.Float64("score", 95.5),
)
```

### 时间类型

```go
logger.Info("操作记录",
    loggo.Time("created_at", time.Now()),
    loggo.Duration("duration", 2*time.Second),
)
```

### 错误类型

```go
err := errors.New("数据库连接失败")
logger.Error("操作失败", loggo.Error(err))
logger.Error("操作失败", loggo.NamedError("db_error", err))
```

### 数组类型

```go
logger.Info("用户列表",
    loggo.Strings("usernames", []string{"alice", "bob", "charlie"}),
    loggo.Ints("ages", []int{25, 30, 35}),
    loggo.Bools("statuses", []bool{true, false, true}),
)
```

### 复杂类型

```go
// 任意类型
logger.Info("复杂数据", loggo.Any("data", map[string]interface{}{
    "key1": "value1",
    "key2": 123,
}))

// JSON 数据
logger.Info("JSON 数据", loggo.JSON("config", configStruct))

// 反射类型
logger.Info("反射数据", loggo.Reflect("object", someStruct))
```

### 标签系统

```go
logger.Info("API 请求",
    loggo.String("endpoint", "/api/users"),
    loggo.Int("status_code", 200),
    loggo.Tags("api", "users", "success", "v1"), // 标签用于分类
)
```

## 本地日志方法

除了标准的日志级别方法，SDK 还提供了专门的本地日志方法：

```go
// 基本本地日志
logger.Local("本地日志消息", loggo.String("key", "value"))

// 带级别的本地日志
logger.LocalDebug("调试信息")
logger.LocalInfo("信息日志")
logger.LocalWarn("警告信息")
logger.LocalError("错误信息")
logger.LocalFatal("致命错误")

// 带时间戳的日志
startTime := time.Now()
// ... 执行操作 ...
logger.LocalWithTime(loggo.InfoLevel, "操作完成", startTime)

// 成功/失败日志
logger.LocalSuccess("操作成功", loggo.String("operation", "create_user"))
logger.LocalFailure("操作失败", loggo.String("operation", "delete_user"))

// 开始/结束日志
logger.LocalStart("用户注册")
// ... 执行注册逻辑 ...
logger.LocalEnd("用户注册", startTime)
```

## 远程日志统计

SDK 提供了远程日志发送的统计信息：

```go
// 获取统计信息
stats := logger.GetRemoteStats()
if stats != nil {
    fmt.Printf("发送成功: %d, 失败: %d, 丢弃: %d\n", 
        stats.SentCount, stats.FailedCount, stats.DroppedCount)
}

// 记录统计信息到日志
logger.LogRemoteStats()
```

## 日志文件结构

SDK 会自动创建以下日志文件：

```
logs/
├── local.log    # 所有本地日志（带格式化）
├── info.log     # INFO 级别及以上日志
└── error.log    # ERROR 级别及以上日志
```

## 异步发送机制

远程日志采用异步批量发送机制：

- **缓冲区大小**: 默认 1000 条日志
- **批量大小**: 默认 50 条日志
- **刷新间隔**: 默认 100ms
- **立即刷新**: Debug 和 Error 级别日志会立即刷新缓冲区

## 示例项目

查看 `example/` 目录中的完整示例：

- `example/local/main.go`: 本地日志示例
- `example/remote_only/main.go`: 远程日志示例

## 最佳实践

### 1. 服务标识

为每个服务设置唯一的服务名称：

```go
logger, err := loggo.NewLoggoWithRemote(
    "log-server:8080", 
    true, 
    "user-service-v1.0", // 使用版本号
    false,
)
```

### 2. 结构化字段

使用有意义的字段名：

```go
logger.Info("用户操作",
    loggo.String("user_id", "12345"),
    loggo.String("operation", "login"),
    loggo.String("ip_address", "192.168.1.100"),
    loggo.Duration("response_time", duration),
    loggo.Tags("auth", "login", "success"),
)
```

### 3. 错误处理

```go
if err != nil {
    logger.Error("操作失败",
        loggo.String("operation", "create_user"),
        loggo.Error(err),
        loggo.String("user_id", userID),
        loggo.Tags("error", "database"),
    )
    return err
}
```

### 4. 性能监控

```go
startTime := time.Now()
defer func() {
    logger.Info("API 请求完成",
        loggo.String("endpoint", "/api/users"),
        loggo.Duration("duration", time.Since(startTime)),
        loggo.Int("status_code", statusCode),
    )
}()
```

## 依赖

- Go 1.25.0+
- go.uber.org/zap
- google.golang.org/grpc
- google.golang.org/protobuf

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v1.0.0
- 初始版本发布
- 支持本地和远程日志记录
- 异步批量发送机制
- 丰富的字段类型支持
- 标签系统
- 统计监控功能