Python SDK

PyPI 上的 kestrel-sdk —— 仅依赖 Python 标准库，无传递依赖。

安装

pip install kestrel-sdk
# 或：uv add kestrel-sdk / poetry add kestrel-sdk

初始化

import os
import kestrel_sdk

kestrel_sdk.init(
    endpoint="https://kestrel.example.com/api/v1/ingest",
    token=os.environ["KESTREL_TOKEN"],
    release=os.environ.get("GIT_COMMIT"),
)

init() 安装 sys.excepthook，主线程里任何未捕获的异常都会被上报。asyncio 场景：

import asyncio
import kestrel_sdk

async def main():
    # ...

loop = asyncio.new_event_loop()
kestrel_sdk.install_asyncio_handler(loop)
loop.run_until_complete(main())

这覆盖了未捕获异常实际逃逸的两条路径。线程池里的异常不会被自动捕获（Python 没暴露这种钩子）；如果需要，在你 worker 的 except 里调 kestrel_sdk.capture()。

手动捕获

try:
    do_thing()
except Exception as exc:
    kestrel_sdk.capture(exc, context={"user_id": user_id})
    raise  # 或 swallow，看你需要

不做的事

SDK 不 patch requests、httpx、logging、Django middleware、Flask error handler、FastAPI exception hook，或任何其他框架内部。如果你想让某个 web 框架上报错误，让框架自己的异常处理直接调 kestrel_sdk.capture() —— 通常 5 行代码就够。

这是有意为之。Patch 框架内部正是"我们升级了 SDK 然后请求 middleware 跑了两次"这种 bug 的源头；我们不想成为那种 SDK。

类型提示

完全标注 —— pip install kestrel-sdk 携带 py.typed 标记，mypy --strict 和 pyright 都能直接识别。

发布节奏

Python SDK 与服务端独立版本。订阅 CHANGELOG.md 看 SDK 专属条目（每条标注 (Python SDK)）。