PingWatch/接入LogHive日志系统.md

接入 LogHive 日志系统指南

前置准备

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

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

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

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

---

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

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

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 的日志

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

---

方式二：使用 LogHive SDK

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

安装

pip install /path/to/loghive-client

同步项目使用

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）

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 项目）

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 实例即可。