log-collector-sdk 0.1.1

轻量级日志收集 Python SDK — 批量异步上报到 logcollector-server

个人日志收集平台

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

架构

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

快速开始

Docker（推荐）

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

手动启动

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

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

Python SDK 使用

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 参考

日志上报

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}"
    }
  ]
}

日志查询

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

实时流

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

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

元数据

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