v6ole
848f804169
- FastAPI 后端 + Vue 3 前端 - Docker Compose 一键部署 - Casdoor OAuth 认证集成 - LogHive 集中式日志 - 设备批量 CSV 导入/导出 - WebSocket 实时状态推送 - 企业微信告警通知 - fping 高性能并发 Ping 检测 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
151 lines
4.0 KiB
Markdown
151 lines
4.0 KiB
Markdown
# 接入 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 实例即可。
|