# 接入 LogHive 日志系统指南

## 前置准备

向管理员提供你的**项目名称**（如 `user-service`），管理员会返回一个 **API Key**。

拿到 API Key 后，在你的项目 `.env` 文件中添加：

```env
# LogHive 日志系统
LOGHIVE_ENDPOINT=http://10.10.10.14:8000
LOGHIVE_PROJECT=你的项目名称
LOGHIVE_API_KEY=管理员给你的API-Key
```

> **不要**把 API 地址和 Key 硬编码在代码里，全部从环境变量读取。

---

## 方式一：零代码改动（推荐）

适用于已使用 Python 标准 `logging` 模块的项目。只需在入口文件添加 3 行：

```python
import logging
import os
from loghive_client import LogHiveHandler

handler = LogHiveHandler(
    project=os.environ["LOGHIVE_PROJECT"],
    api_key=os.environ["LOGHIVE_API_KEY"],
    endpoint=os.environ["LOGHIVE_ENDPOINT"],
    level=logging.INFO,  # 只发送 INFO 及以上级别
)
logging.getLogger().addHandler(handler)

# 现有代码无需任何修改，所有日志自动发送到 LogHive
logging.info("服务启动成功")
logging.error("数据库连接超时", exc_info=True)
```

### 仅发送特定 logger 的日志

```python
logger = logging.getLogger("myapp.api")
logger.addHandler(handler)
logger.setLevel(logging.WARNING)
```

---

## 方式二：使用 LogHive SDK

适合需要更精细控制的场景，或者不想影响全局 logging 配置。

### 安装

```bash
pip install /path/to/loghive-client
```

### 同步项目使用

```python
import os
from loghive_client import LogHiveLogger

logger = LogHiveLogger(
    project=os.environ["LOGHIVE_PROJECT"],
    api_key=os.environ["LOGHIVE_API_KEY"],
    endpoint=os.environ["LOGHIVE_ENDPOINT"],
)

logger.info("用户登录成功", user_id=42, ip="1.2.3.4")
logger.warning("API 限流触发", rate="90%")
logger.error("支付回调验签失败", trace_id="req-abc-123", exc_info=True)
logger.debug("缓存命中 key=user:42")
logger.critical("磁盘空间不足，服务即将崩溃")
```

SDK 在后台线程异步批量发送，**不会阻塞主线程**。程序退出时会自动 flush 剩余日志。

### 异步项目使用（FastAPI / aiohttp）

```python
import os
from loghive_client import AsyncLogHiveLogger

async def main():
    async with AsyncLogHiveLogger(
        project=os.environ["LOGHIVE_PROJECT"],
        api_key=os.environ["LOGHIVE_API_KEY"],
        endpoint=os.environ["LOGHIVE_ENDPOINT"],
    ) as logger:
        await logger.info("请求处理完成", path="/api/users", status=200)
```

---

## 方式三：直接调用 REST API（非 Python 项目）

```bash
curl -X POST $LOGHIVE_ENDPOINT/api/logs/ingest \
  -H "Authorization: Bearer $LOGHIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "'$LOGHIVE_PROJECT'",
    "entries": [
      {
        "level": "error",
        "message": "服务异常",
        "logger": "myapp.module",
        "trace_id": "abc-123",
        "extra": {"key": "value"}
      }
    ]
  }'
```

---

## 日志字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `level` | string | 是 | `debug` / `info` / `warning` / `error` / `critical` |
| `message` | string | 是 | 日志内容，最长 65536 字符 |
| `logger` | string | 否 | Logger 名称，默认 `root` |
| `trace_id` | string | 否 | 链路追踪 ID，用于关联跨模块日志 |
| `exception` | string | 否 | 异常堆栈，SDK 通过 `exc_info=True` 自动捕获 |
| `extra` | object | 否 | 任意键值对，支持嵌套结构 |

---

## 在 LogHive 前端查看

访问 `http://10.10.10.14:3000`，按项目、级别、关键词、时间范围搜索和统计。

---

## 常见问题

**Q: 发送失败会影响我的主业务吗？**
A: 不会。SDK 在后台线程异步发送，网络失败会自动重试 3 次，最终丢弃并记录本地 warning。

**Q: 日志量很大怎么办？**
A: SDK 默认每 2 秒或积攒 50 条批量发送。可通过 `batch_size` 和 `flush_interval` 参数调节。

**Q: 多个进程/worker 同时发送有问题吗？**
A: 没问题。每个进程创建自己的 LogHiveLogger 实例即可。