nonebot-plugin-sentry-transaction 0.2.0

Non-invasive Sentry tracing for NoneBot events and matchers

nonebot-plugin-sentry-transaction

✨ NoneBot2 事件与 Matcher 的非侵入式 Sentry 性能追踪 ✨

---

简体中文 | English

📖 功能特性

• 每个事件产生一个 Sentry Transaction（op: nonebot.event）
• 每次 Matcher 运行产生一个 Sentry Span（op: nonebot.matcher）
• 并发事件拥有独立 trace，互不干扰
• 同优先级并发 Matcher 拥有独立 span
• httpx / SQLAlchemy / aiohttp 等集成的子 span 自动挂载
• Matcher 异常反映为 internal_error span 状态

🔧 前置条件

本插件不负责初始化 Sentry，请配合 nonebot-plugin-sentry 使用：

SENTRY_DSN=https://<key>@<org>.ingest.sentry.io/<project>
SENTRY_TRACES_SAMPLE_RATE=1.0

其他 Sentry 配置项请参阅 nonebot-plugin-sentry 文档。

💿 安装

🚀 使用 uv

uv add nonebot-plugin-sentry-transaction

🚀 使用 PDM

pdm add nonebot-plugin-sentry-transaction

🚀 使用 Poetry

poetry add nonebot-plugin-sentry-transaction

⚙️ 配置

配置项	默认值	说明
SENTRY_NB_TRACE_ENABLED	true	设为 false 可关闭事件/Matcher 追踪，同时保留 Sentry 错误上报。

📊 在 Sentry 中的呈现

Transaction 出现在 Performance 面板，名称来自 event.get_event_name()，例如 message.private.friend、notice.group_upload。

Span 以 Matcher 所属插件命名（plugin_name），回退到 module_name 或类名。

各 transaction/span 携带以下 tag：

Tag	来源
adapter	bot.type
event_type	event.get_type()
matcher.plugin	Matcher.plugin_name
matcher.module	Matcher.module_name

🔍 工作原理

插件在加载时 monkey-patch NoneBot 的两个内部函数：

• nonebot.message.handle_event — 包装 sentry_sdk.isolation_scope() + start_transaction()
• nonebot.message._run_matcher — 包装 sentry_sdk.new_scope() + start_span()

同时注册 run_postprocessor 钩子，检测被 NoneBot 内部捕获的 Matcher 异常并将 span 状态设为 internal_error。

不修改任何业务插件代码。

📄 许可证

本项目使用 MIT 许可证开源。