Metadata-Version: 2.1
Name: insightoslog
Version: 1.0.3
Summary: InsightOS Log SDK - Unified log collection SDK
Home-page: https://git.insightos.cn:40080/hzh/logging-sdk
Author: InsightOS Team
Author-email: team@insightos.org
License: UNKNOWN
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# InsightOS Log SDK 统一日志接口

InsightOS Log SDK 是一个跨语言的统一日志接口实现，支持 C++、Go、Python 三种语言。该 SDK 遵循统一日志接口设计规范，提供结构化 JSON 日志输出、链路追踪、跨线程/协程上下文传播等功能。

---

## 测试目录

独立测试文件位于 `test/` 目录下：

```
test/
├── cpp/      # C++ 测试 (xmake build && xmake run test)
├── go/       # Go 测试
└── python/   # Python 测试
```

---

## 目录

- [日志库架构](#日志库架构)
- [功能特性](#功能特性)
- [日志结构](#日志结构)
- [快速开始](#快速开始)
  - [C++ SDK](#1-c-sdk)
  - [Go SDK](#2-go-sdk)
  - [Python SDK](#3-python-sdk)
- [API 参考](#api-reference)
  - [初始化配置](#初始化配置)
  - [日志记录](#日志记录)
  - [链路追踪](#链路追踪)
  - [上下文传播](#上下文传播)
- [输出模式](#输出模式)
- [文件滚动策略](#文件滚动策略)
- [依赖说明](#依赖说明)
- [打包发布](#打包发布)

---

## 日志库架构

InsightOS Log SDK 采用分层架构设计，每种语言都包含核心 SDK 层和 Wrapper 封装层。

### 架构分层

```
┌─────────────────────────────────────────────────────────────┐
│                     用户代码 (User Code)                     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Wrapper Layer (封装层)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │ C++: Logger │  │ Go: Logger  │  │ Python:     │        │
│  │       Trace │  │       Trace │  │ 模块级函数  │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│         │                │                │                │
│  wrapper.hpp       wrapper.go        __init__.py          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Core SDK Layer (核心层)                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  初始化配置 (InitParam)                              │   │
│  │  日志消息 (Message/Builder)                         │   │
│  │  链路追踪 (Context/TraceID)                         │   │
│  │  上下文传播 (Propagation)                           │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                 Platform Layer (平台层)                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │ C++: spdlog │  │ Go: zap     │  │ Python:     │        │
│  │             │  │             │  │ logging     │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────────────────────────────────────────────┘
```

### 各语言模块结构

#### C++ (`cpp/`)

```
cpp/
├── include/insightoslog/
│   ├── logging/
│   │   ├── logging.hpp    # 核心 SDK
│   │   ├── macros.hpp     # 宏定义
│   │   ├── message.hpp    # 消息结构
│   │   ├── context.hpp    # 上下文
│   │   ├── config.hpp     # 配置结构
│   │   ├── level.hpp      # 日志级别
│   │   ├── builder.hpp    # 建造者模式
│   │   └── api.hpp        # API 声明
│   └── wrapper/
│       └── wrapper.hpp    # Wrapper 封装 (Logger, Trace 类)
├── src/
│   └── logging.cpp        # 核心实现
└── xmake.lua
```

#### Go (`go/`)

```
go/
├── logging_sdk.go       # 根模块入口（Facade 重新导出层）
├── impl/                # impl 子模块（核心实现）
│   ├── api.go          # 核心 API（全局函数）
│   ├── config.go       # 配置结构
│   ├── context.go      # 上下文管理
│   ├── builder.go      # 建造者模式
│   ├── helper.go       # 辅助函数
│   ├── id.go           # TraceID/SpanID 生成
│   ├── init.go         # 初始化与链路追踪函数
│   ├── level.go        # 日志级别定义
│   ├── message.go      # 数据结构定义
│   └── go.mod          # 子模块 go.mod
└── wrapper/             # wrapper 子模块（面向对象封装）
    ├── wrapper.go       # Logger / Trace 类封装
    └── go.mod           # 子模块 go.mod
```

#### Python (`python/`)

```
python/
└── insightoslog/
    ├── __init__.py        # Wrapper 封装 + 核心实现
    ├── wrapper.py         # Wrapper 封装
    ├── _impl/
    │   └── __init__.py   # 核心实现
    └── pyproject.toml     # 包配置
```

### Wrapper 层设计

Wrapper 层提供统一的面向对象 API，与 C++/Python 风格保持一致：

| 语言 | Wrapper 类 | 便捷函数 |
|------|-----------|----------|
| C++ | `Logger`, `Trace` | `IOSLOG_INFO()`, `IOSLOG_DEBUG()` |
| Go | `Logger`, `Trace` | `Logger.Info()`, `Logger.Debug()` |
| Python | 模块级函数 | `info()`, `debug()` |

### 使用方式

**C++:**
```cpp
#include <insightoslog/wrapper/wrapper.hpp>

using namespace insightoslog;

// 使用 Logger 类
Logger::Init({.service_name = "my-app"});
Logger::Info("Hello World");

// 使用 Trace 类
std::string trace_id = Trace::StartNewTrace();
```

**Go:**
```go
import log "git.insightos.cn/hzh/logging-sdk"

// 使用全局函数（推荐）
log.Init(log.InitParam{ServiceName: "my-app"})
log.Info("Hello World")

// 或使用 Logger2/Trace2 类（面向对象风格）
log.Logger2.Init(log.LoggerInitParam{ServiceName: "my-app"})
log.Logger2.Info("Hello World")
traceID := log.Trace2.StartNewTrace()
```

**Python:**
```python
import insightoslog as log

# 使用模块级函数
log.init({"service_name": "my-app"})
log.info("Hello World")

# 或使用类封装
log.Logger.info("Hello from Logger")
trace_id = log.Trace.start_new_trace()
```

---

## 功能特性

### 1. 结构化 JSON 日志
- 按域（Domain）组织的 JSON 输出
- 支持的域：`meta`、`resource`、`context`、`event`、`data`、`error`、`caller`
- Pretty Print 格式（2 空格缩进）

### 2. 链路追踪（Tracing）
- 自动生成 `trace_id` 和 `span_id`
- 支持 HTTP Header 传播（`X-InsightOSLog-TraceID`、`X-InsightOSLog-SpanID`、`X-InsightOSLog-ParentSpanID`）
- 支持跨线程/协程自动上下文传播

### 3. 敏感信息过滤
- 自动过滤密码、Token、API Key 等敏感信息

### 4. 多语言支持
- C++ (使用 spdlog)
- Go (使用 zap)
- Python (使用标准 logging)

### 5. 多种输出模式
- `stdout`: 终端输出（带颜色）
- `rotate_file`: 滚动日志文件

### 6. 异步缓存层
- 内存缓冲区，日志先写入缓冲，定时刷新到输出
- 可配置队列大小和刷新间隔
- 大幅提升高并发场景性能

### 7. 建造者模式 API
- 链式调用支持
- 支持 `on_request`、`with_data`、`with_error` 等方法

---

## 日志结构

终端输出格式（stdout 模式）为：

```
LEVEL YYYY-MM-DDTHH:MM:SS.sss+08:00 [PID] {
  "meta": {...},
  "resource": {...},
  ...
}
```

各字段含义：

```json
{
  "meta": {
    "level": "INFO",
    "time": "2026-03-11T10:00:00.000+08:00"
  },
  "resource": {
    "type": "ability",
    "name": "MyAbility",
    "instance_id": "abc-123",
    "host": "server-01",
    "pid": 12345
  },
  "context": {
    "trace_id": "550436d474944d77a6833ba578d53e6d",
    "span_id": "767461a9d8ea41f29c3defe40a755ede",
    "parent_span_id": ""
  },
  "event": {
    "msg": "Ability onStart",
    "request": {
      "method": "POST",
      "url": "/api/v1/ability",
      "latency_ms": 50
    }
  },
  "data": {
    "param": {"key": "value"},
    "result": {"status": "ok"},
    "truncate": false
  },
  "error": {
    "type": "RuntimeError",
    "message": "connection failed",
    "stacktrace": "..."
  },
  "caller": {
    "file": "main.cpp",
    "line": 42,
    "function": "main"
  }
}
```

**说明：**
- `level` 行颜色与 JSON 行保持一致（不同级别对应不同颜色）
- 时间格式统一为本地时区（+08:00），与 Go/C++/Python 三端一致
```

---

## 快速开始

### 配置文件格式

所有SDK都支持通过 `InsightOSLogConfig.yaml` 文件进行配置：

```yaml
# 配置文件示例 (InsightOSLogConfig.yaml)
level: INFO                    # 日志级别: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
service_type: "ability"        # 服务类型
service_name: "MyService"      # 服务名称
instance_id: "instance-001"   # 实例ID
log_root: "/root/InsightOSLog/logs"  # 日志根目录
output: "stdout"               # 输出模式: stdout / rotate_file

file:
  max_size: 5242880           # 单文件最大字节数 (5MB)
  max_files: 3                # 保留的旧日志文件数量

async:
  buffer_size: 4096           # 异步队列大小 (字节)
  flush_interval: 2           # 刷新间隔 (秒)

enable_tracing: true           # 是否启用链路追踪
```

### 1. C++ SDK

#### 安装

通过 apt 直接安装：

```bash
# 添加 apt 源（首次使用时）
# 将 deb 包放到 apt 仓库目录后执行
apt update
apt install libinsightoslog-dev
```

或通过源码编译：

```bash
# 使用 xmake
cd cpp
xmake build
```

#### 示例代码

```cpp
#include <insightoslog/wrapper/wrapper.hpp>

using namespace insightoslog;

int main() {
    // 方式一：从配置文件初始化（默认 ./InsightOSLogConfig.yaml）
    Logger::InitFromConfig();

    // 或指定配置文件路径
    // Logger::InitFromConfig("/etc/insightos/InsightOSLogConfig.yaml");

    // 方式二：直接传入配置
    InitParam config;
    config.level = LogLevel::INFO;
    config.service_type = "ability";
    config.service_name = "MyAbility";
    config.instance_id = "abc-123";
    config.output = "stdout";  // 或 "rotate_file"

    Logger::Init(config);

    // 2. 开始新链路
    Trace::StartNewTrace();

    // 3. 记录日志
    Logger::Info("Application started");

    // 使用 fmt 格式化
    Logger::Info("User {} logged in", "john");

    // 或使用宏（更方便）
    IOSLOG_INFO("Application started");

    // 程序结束前调用 Shutdown 等待异步日志写入完成
    Logger::Shutdown();

    return 0;
}
```

#### 编译运行

```bash
cd cpp
xmake build       # 编译 SDK

# 运行测试
cd ../test/cpp
xmake
xmake run
```

#### 测试覆盖

C++ SDK 测试覆盖以下功能：

| 测试编号 | 测试名称 | 说明 |
|---------|---------|------|
| 1 | 基础初始化 | SDK 初始化测试 |
| 2 | 便捷宏 | INSIGHTOSLOG_INFO 等宏 |
| 3 | fmt 格式化 | 格式化日志消息 |
| 4 | 建造者模式 | 链式调用 API |
| 5 | on_request / with_data | 请求和数据日志 |
| 6 | 错误日志 | 错误信息记录 |
| 7 | HTTP Header 传播 | 链路信息 Header 传播 |
| 8 | 跨线程传播 | Context 跨线程继承 |
| 9 | 嵌套 Span | 多级服务调用链路 |
| 10 | make_context | 手动创建 Context |
| 11 | LogBuilder 详细 | 建造者模式完整测试 |
| 12 | 多线程日志 | 并发写入测试 |
| 13 | ID 生成 | Trace ID / Span ID 生成 |
| 14 | Header 常量 | HTTP Header 常量验证 |
| 15 | 全局 Resource | Resource 信息测试 |
| 16 | 文件输出 | rotate_file 模式测试 |
| 17 | 异步日志 | 异步队列测试 |
| 18 | 配置文件加载 | InsightOSLogConfig.yaml 加载测试 |
| 19 | RefreshPID | PID 刷新测试 |

---

### 2. Go SDK

#### 安装

通过 go get 安装：

```bash
go get git.insightos.cn/hzh/logging-sdk@v1.0.0
```

#### 示例代码

```go
package main

import (
    log "git.insightos.cn/hzh/logging-sdk"
)

func main() {
    // 方式一：从配置文件初始化（默认 ./InsightOSLogConfig.yaml）
    log.InitFromConfig("./InsightOSLogConfig.yaml")

    // 方式二：直接传入配置
    log.Init(log.InitParam{
        Level:        log.LevelInfo,
        ServiceType:  "ability",
        ServiceName:  "MyAbility",
        InstanceID:   "abc-123",
        Output:       "stdout", // 或 "rotate_file"
        LogRoot:      "/var/log/insightos",
    })

    // 2. 开始新链路
    log.StartNewTrace()

    // 3. 记录日志
    log.Info("Application started")

    // 使用格式化
    log.Infof("User %s logged in", "john")
}

func handler(w http.ResponseWriter, r *http.Request) {
    // 从 HTTP Header 提取链路信息
    log.ExtractFromHeaders(
        r.Header.Get("X-InsightOSLog-TraceID"),
        r.Header.Get("X-InsightOSLog-SpanID"),
        r.Header.Get("X-InsightOSLog-ParentSpanID"),
    )

    log.Info("Handling request")
}
```

#### 运行测试

```bash
cd go
go test -v          # 运行所有测试
go test -v -run TestComplete  # 运行完整测试套件
```

#### 测试覆盖

Go SDK 测试覆盖以下功能：

| 测试名称 | 说明 |
|---------|------|
| TestInit | SDK 初始化测试 |
| TestConvenienceMacros | 便捷日志函数 |
| TestFmtFormatting | 格式化日志 |
| TestBuilderPattern | 建造者模式 |
| TestOnRequestWithData | 请求和数据日志 |
| TestErrorLogging | 错误日志记录 |
| TestHTTPHeaderPropagation | HTTP Header 传播 |
| TestCrossGoroutinePropagation | 跨 Goroutine 传播 |
| TestNestedSpans | 嵌套 Span 测试 |
| TestMultiGoroutineLogging | 多 Goroutine 并发日志 |
| TestIDGeneration | ID 生成 |
| TestContextFunctions | Context 函数 |
| TestHeaderConstants | Header 常量 |
| TestGlobalResource | 全局 Resource |
| TestFileOutput | 文件输出测试 |
| TestAsyncLogging | 异步日志测试 |
| TestConfigLoading | 配置文件加载 |

---

### 3. Python SDK

#### 安装


```bash
pip install insightoslog
```



#### 示例代码

```python
import insightoslog as log

# 方式一：从配置文件初始化（默认 ./InsightOSLogConfig.yaml）
log.init_from_config()

# 或指定配置文件路径
# log.init_from_config("/etc/insightos/InsightOSLogConfig.yaml")

# 方式二：直接传入配置
log.init(log.InitParam(
    level=30,  # LogLevel.INFO
    service_type="ability",
    service_name="MyAbility",
    instance_id="abc-123",
    output="stdout",  # 或 "rotate_file"
    log_root="/var/log/insightos",
))

# 2. 开始新链路
log.LogContext.start_new_trace()

# 3. 记录日志
log.info("Application started")

# 使用格式化
log.info("User {} logged in".format("john"))


def handler(request):
    # 从 HTTP Header 提取链路信息
    log.LogContext.extract_and_inject_from_headers(
        request.headers.get("X-InsightOSLog-TraceID"),
        request.headers.get("X-InsightOSLog-SpanID"),
        request.headers.get("X-InsightOSLog-ParentSpanID"),
    )
    
    log.info("Handling request")
```

#### 运行测试

```bash
cd test/python
python3 test_main.py
```

#### 测试覆盖

Python SDK 测试覆盖以下功能：

| 测试编号 | 测试名称 | 说明 |
|---------|---------|------|
| 1 | 基础初始化 | SDK 初始化测试 |
| 2 | 便捷宏 | trace/info/warn/error 等函数 |
| 3 | 格式化 | 格式化日志消息 |
| 4 | 建造者模式 | 链式调用 API |
| 5 | on_request / with_data | 请求和数据日志 |
| 6 | 错误日志 | 错误信息记录 |
| 7 | HTTP Header 传播 | 链路信息 Header 传播 |
| 8 | 跨线程传播 | Context 跨线程继承 |
| 9 | ID 生成 | Trace ID / Span ID 生成 |
| 10 | Context 函数 | Context 管理函数 |
| 11 | 嵌套 Span | 多级服务调用链路 |
| 12 | 多线程日志 | 并发写入测试 |
| 13 | Header 常量 | HTTP Header 常量验证 |
| 14 | 全局 Resource | Resource 信息测试 |
| 15 | 文件输出 | rotate_file 模式测试 |
| 16 | 异步日志 | 异步队列测试 |
| 17 | 配置文件加载 | InsightOSLogConfig.yaml 加载测试 |
| 18 | Refresh PID | PID 刷新测试 |
| 19 | LogBuilder 详细方法 | truncate/latency/with_result 等方法 |

---

## API 参考

### 初始化配置

#### C++

```cpp
struct InitParam {
    LogLevel level = LogLevel::INFO;
    std::string service_type;
    std::string service_name;
    std::string instance_id;
    std::filesystem::path log_root = "/root/InsightOSLog/logs";
    std::string output = "stdout";  // stdout / rotate_file
    int buffer_size = 4096;         // 异步队列大小
    std::chrono::seconds async_flush_interval{2};  // 刷新间隔（秒）
    bool enable_tracing = true;
    
    struct FileSpec {
        std::filesystem::path path;
        size_t max_size = 1048576 * 5;  // 5MB
        size_t max_files = 3;
    };
    FileSpec file;
};

void init(const InitParam& config);
```

#### Go

```go
type InitParam struct {
    Level         LogLevel
    ServiceType   string
    ServiceName   string
    InstanceID    string
    LogRoot       string
    Output        string  // "stdout" / "rotate_file"
    MaxSize       int64   // 单文件最大字节数
    MaxFiles      int     // 最大文件数
    BufferSize    int     // 缓冲区大小（字节），0 表示同步
    FlushInterval int     // 刷新间隔（秒），0 表示不使用定时刷新
    EnableTracing bool
    Host          string
    PID           int
}

func Init(config InitParam)
```

#### Python

```python
class InitParam:
    def __init__(self, level: int = LogLevel.INFO, 
                 service_type: str = "", 
                 service_name: str = "", 
                 instance_id: str = "",
                 log_root: str = "/tmp/insightoslog/logs", 
                 output: str = "stdout",
                 max_bytes: int = 10*1024*1024, 
                 backup_count: int = 5,
                 queue_size: int = 1000,     # 异步队列大小，0 表示同步
                 flush_interval: int = 2):   # 刷新间隔（秒）
        pass

def init(config: InitParam)
```

---

### 日志记录

#### 便捷函数

| 级别 | C++ | Go | Python |
|------|-----|-----|--------|
| 级别 | C++ | Go | Python |
|------|-----|-----|--------|
| TRACE | `Logger::Trace(msg)` | `LogTrace(msg)` | `trace(msg)` |
| DEBUG | `Logger::Debug(msg)` | `Debug(msg)` | `debug(msg)` |
| INFO | `Logger::Info(msg)` | `Info(msg)` | `info(msg)` |
| WARN | `Logger::Warn(msg)` | `Warn(msg)` | `warn(msg)` |
| ERROR | `Logger::Error(msg)` | `Error(msg)` | `error(msg)` |
| FATAL | `Logger::Fatal(msg)` | `Fatal(msg)` | `fatal(msg)` |

#### 格式化日志

| C++ | Go | Python |
|-----|-----|--------|
| `info("msg {}", arg)` | `Infof("msg %s", arg)` | `info_f("msg {}", arg)` |

#### 建造者模式

```cpp
// C++
Context ctx = current_context();
ctx.info("msg")
   .on_request({"POST", "/api", 100})
   .with_data(params, result)
   .with_error(error_obj)
   .truncate(true)
   .latency(50)
   .send();
```

```go
// Go
ctx.Info("msg").
    OnRequest(EventRequest{Method: "POST", Path: "/api", LatencyMs: 100}).
    WithData(params, result).
    WithError(errorObj).
    Send()
```

```python
# Python
ctx.info("msg") \
    .on_request(EventRequest(method="POST", path="/api", latency_ms=100)) \
    .with_data(params, result) \
    .with_error(error_obj) \
    .send()
```

---

### 链路追踪

#### 开始新链路

```cpp
// C++
Logger::StartNewTrace();
```

```go
// Go
log.StartNewTrace()
```

```python
# Python
LogContext.start_new_trace()
```

#### 注入上下文

```cpp
// C++
Logger::Inject(trace_id, span_id, parent_span_id);
```

```go
// Go
log.Inject(traceID, spanID, parentSpanID)
```

```python
# Python
LogContext.inject(trace_id, span_id, parent_span_id)
```

#### 从 HTTP Header 提取

```cpp
// C++
Logger::ExtractFromHeaders({
    .trace_id       = headers["X-InsightOSLog-TraceID"],
    .span_id        = headers["X-InsightOSLog-SpanID"],
    .parent_span_id = headers["X-InsightOSLog-ParentSpanID"],
});
```

```go
// Go
log.ExtractFromHeaders(
    r.Header.Get("X-InsightOSLog-TraceID"),
    r.Header.Get("X-InsightOSLog-SpanID"),
    r.Header.Get("X-InsightOSLog-ParentSpanID"),
)
```

```python
# Python
LogContext.extract_and_inject_from_headers(
    request.headers.get("X-InsightOSLog-TraceID"),
    request.headers.get("X-InsightOSLog-SpanID"),
    request.headers.get("X-InsightOSLog-ParentSpanID"),
)
```

---

### 上下文传播

#### 手动传播（跨线程/协程）

```cpp
// C++ - 父线程
Logger::PrepareForChildThread();
// 在新线程中
Logger::InheritFromPrepared();
```

```go
// Go - 主 goroutine
log.PrepareForChildThread()
// 在新 goroutine 中
log.InheritFromPrepared()
```

```python
# Python - 主线程
LogContext.prepare_for_child_thread()
# 在新线程中
LogContext.inherit_from_prepared()
```

#### 自动传播

```cpp
// C++ - 无需 ctx 参数，自动获取当前上下文
IOSLOG_INFO("msg");
```

```go
// Go - 无需 ctx 参数，自动获取当前上下文
log.Info("msg")
```

```python
# Python - 无需 ctx 参数，自动获取当前上下文
info("msg")
```

---

## 输出模式

| 模式 | 说明 | 颜色输出 |
|------|------|---------|
| `stdout` | 输出到终端 | ✅ 是 |
| `rotate_file` | 输出到滚动日志文件 | ❌ 否 |

---

## 文件滚动策略

### rotate_file 模式

当日志文件达到指定大小时，自动进行轮转：

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `max_size` / `MaxSize` / `max_bytes` | 单个日志文件最大字节数 | 10MB (C++/Python) / 5MB (Go) |
| `max_files` / `MaxFiles` / `backup_count` | 保留的旧日志文件数量 | 3 (C++/Go) / 5 (Python) |

### 日志文件路径

```
{log_root}/{service_type}/{service_name}.log
```

例如：`/var/log/insightoslog/ability/MyAbility.log`

---

## 依赖说明

### C++ SDK
- spdlog
- nlohmann_json
- stduuid
- fmt

### Go SDK
- github.com/google/uuid
- go.uber.org/zap
- go.uber.org/multierr

### Python SDK
- 无外部依赖（使用标准库）

---

## 打包发布

使用 `build_package.sh` 一键打包 C++、Go、Python 三个 SDK 的发布产物。

### 用法

```bash
# 默认版本 1.0.0，仅构建
./build_package.sh

# 指定版本
./build_package.sh 2.0.0

# 构建并发布（需设置环境变量）
GITLAB_TOKEN=xxx PYPI_TOKEN=yyy ./build_package.sh 1.0.0

# 指定架构（C++ deb 包）
./build_package.sh 1.0.0 arm64
```

### 发布方式

| 语言 | 发布平台 | 用户安装命令 |
|------|---------|-------------|
| **C++** | apt (.deb) | `apt install libinsightoslog-dev` |
| **Go** | Go 官方模块代理 | `go get git.insightos.cn/hzh/logging-sdk@latest` |
| **Python** | PyPI (.whl) | `pip install insightoslog` |

### 输出结构

```
dist/{VERSION}/
├── cpp/
│   └── libinsightoslog-dev_{VERSION}_{ARCH}.deb   # deb 安装包
├── go/
│   ├── logging_sdk.go       # 根模块入口（Facade 层）
│   ├── go.mod               # 根模块 go.mod（含 replace 指令）
│   ├── go.sum
│   ├── impl/                # impl 子模块
│   │   ├── api.go
│   │   ├── config.go
│   │   └── ...
│   └── wrapper/             # wrapper 子模块
│       └── wrapper.go
└── python/
    └── insightoslog-{VERSION}-py3-none-any.whl              # wheel 安装包
```

### 各 SDK 打包说明

#### C++ SDK

通过 `build_package.sh` 自动编译 `.so` 动态库并打包成 `.deb` 安装包。

**发布方式：**

1. 将 `.deb` 包放到 apt 仓库目录
2. 用户通过 `apt install libinsightoslog-dev` 安装

**使用方式：**

```bash
# 安装 SDK
apt install libinsightoslog-dev

# 编译时链接
g++ -o myapp main.cpp -linsightoslog-log -lpthread -ldl

# 运行
./myapp
```

#### Go SDK

通过 `build_package.sh` 自动发布到 GitLab，Go 官方模块代理会自动同步。

**发布方式：**

1. 设置 `GITLAB_TOKEN` 环境变量
2. 运行 `./build_package.sh` 后自动创建 tag 并推送到 GitLab
3. GitLab 会自动同步到 `proxy.golang.org`

**使用方式：**

```bash
go get git.insightos.cn/hzh/logging-sdk@v1.0.0
```

```go
import (
    log "git.insightos.cn/hzh/logging-sdk"
)

func main() {
    log.Init(log.InitParam{
        ServiceName: "my-app",
        Level:       log.LevelInfo,
    })
    log.Info("Hello World")
}
```

#### Python SDK

通过 `build_package.sh` 自动编译成 `.whl` 轮子文件并上传到 PyPI。

**发布方式：**

1. 设置 `PYPI_TOKEN` 环境变量
2. 运行 `./build_package.sh` 后自动上传到 PyPI

**使用方式：**

```bash
pip install insightoslog
```

```python
from insightoslog import init, InitParam, info

init(InitParam(
    service_name="my-app",
    level=30,
))
info("Hello from packaged SDK")
```

---

## 许可证

MIT License


