Metadata-Version: 2.4
Name: log-collector-sdk
Version: 0.1.1
Summary: 轻量级日志收集 Python SDK — 批量异步上报到 logcollector-server
License-Expression: MIT
Project-URL: Homepage, https://github.com/yourusername/log-collector
Project-URL: Repository, https://github.com/yourusername/log-collector
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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 :: System :: Logging
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 个人日志收集平台

轻量级日志收集平台：Python SDK 上报 → Go 服务端存储/推送 → Vue 3 Web 查看。

## 架构

```
Python App (SDK) ──HTTP POST──→ Go Server ←──SSE── Vue Web
                                    │
                                SQLite (WAL)
```

## 快速开始

### Docker（推荐）

```bash
docker-compose up -d
# 访问 http://localhost:8080
```

### 手动启动

```bash
# 终端 1：启动服务端
cd server && go run cmd/server/main.go

# 终端 2：启动前端（开发模式）
cd web && npm install && npm run dev
# 访问 http://localhost:3000
```

## Python SDK 使用

```python
import logging
from logcollector import LogCollectorHandler

handler = LogCollectorHandler(
    server_url="http://localhost:8080",
    service="my-app",
    batch_size=50,
    flush_interval=2.0,
)
logging.getLogger().addHandler(handler)

logging.info("hello world")
logging.error("something broke", extra={"user_id": 42, "trace_id": "abc-123"})
```

### 配置参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| server_url | `http://localhost:8080` | 服务端地址 |
| service | `""` | 应用名称 |
| batch_size | 50 | 批量大小 |
| flush_interval | 2.0 | 定时刷新间隔（秒） |
| max_buffer_size | 10000 | 内存队列上限 |
| max_retries | 3 | 失败重试次数 |

## API 参考

### 日志上报

```http
POST /api/v1/logs/bulk
Content-Type: application/json

{
  "logs": [
    {
      "timestamp": 1700000000000,  // 毫秒时间戳
      "service": "my-app",
      "hostname": "macbook",
      "level": "INFO",
      "message": "user login success",
      "logger": "app.auth",
      "extra": "{\"user_id\":123}"
    }
  ]
}
```

### 日志查询

```http
GET /api/v1/logs?service=my-app&level=ERROR&keyword=timeout&start=1700000000000&end=1700100000000&limit=100&offset=0
```

### 实时流

```http
GET /api/v1/logs/stream?service=my-app&level=ERROR
```

SSE 事件格式：`event: log\ndata: {json}\n\n`

### 元数据

```http
GET /api/v1/services    # 服务列表
GET /api/v1/levels      # 日志级别枚举
```

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| DB_PATH | `logs.db` | SQLite 数据库路径 |
| WEB_DIR | (空) | 前端静态文件目录（Docker 内自动设置） |
| RETENTION_HOURS | 24 | 日志保留时长 |
| TZ | `Asia/Shanghai` | 时区 |

## 技术栈

- **SDK**: Python（logging.Handler 插件）
- **服务端**: Go + chi + modernc.org/sqlite
- **前端**: Vue 3 + Vite + Element Plus
- **实时推送**: SSE (Server-Sent Events)
- **部署**: Docker Compose
