nonebot-plugin-sentry-transaction 0.1.0__tar.gz

nonebot_plugin_sentry_transaction-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 呵呵です
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nonebot_plugin_sentry_transaction-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.3
+Name: nonebot-plugin-sentry-transaction
+Version: 0.1.0
+Summary: Non-invasive Sentry tracing for NoneBot events and matchers
+Author: shoucandanghehe
+Author-email: shoucandanghehe <wallfjjd@gmail.com>
+License: MIT License
+         
+         Copyright (c) 2026 呵呵です
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Requires-Dist: nonebot-plugin-sentry>=2.0.0
+Requires-Dist: nonebot2>=2.4.4
+Requires-Dist: sentry-sdk>=2.15.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+<!-- markdownlint-disable MD033 MD036 MD041 -->
+<div align="center">
+  <a href="https://v2.nonebot.dev/store">
+    <img src="./assets/NoneBotPlugin.png" width="300" alt="logo" />
+  </a>
+
+# nonebot-plugin-sentry-transaction
+
+✨ NoneBot2 事件与 Matcher 的非侵入式 Sentry 性能追踪 ✨
+
+![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
+![PyPI](https://img.shields.io/pypi/v/nonebot-plugin-sentry-transaction)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+![License](https://img.shields.io/github/license/shoucandanghehe/nonebot-plugin-sentry-transaction)
+![CI](https://github.com/shoucandanghehe/nonebot-plugin-sentry-transaction/actions/workflows/test.yml/badge.svg)
+[![Codecov](https://codecov.io/gh/shoucandanghehe/nonebot-plugin-sentry-transaction/graph/badge.svg)](https://codecov.io/gh/shoucandanghehe/nonebot-plugin-sentry-transaction)
+
+---
+
+简体中文 | [English](./README.en-us.md)
+
+</div>
+
+## 📖 功能特性
+
+- 每个事件产生一个 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](https://github.com/nonebot/plugin-sentry) 使用：
+
+```env
+SENTRY_DSN=https://<key>@<org>.ingest.sentry.io/<project>
+SENTRY_TRACES_SAMPLE_RATE=1.0
+```
+
+其他 Sentry 配置项请参阅 [nonebot-plugin-sentry 文档](https://github.com/nonebot/plugin-sentry)。
+
+## 💿 安装
+
+### 🚀 使用 uv
+
+```bash
+uv add nonebot-plugin-sentry-transaction
+```
+
+### 🚀 使用 PDM
+
+```bash
+pdm add nonebot-plugin-sentry-transaction
+```
+
+### 🚀 使用 Poetry
+
+```bash
+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](./LICENSE) 许可证开源。

nonebot_plugin_sentry_transaction-0.1.0/README.md

@@ -0,0 +1,99 @@
+<!-- markdownlint-disable MD033 MD036 MD041 -->
+<div align="center">
+  <a href="https://v2.nonebot.dev/store">
+    <img src="./assets/NoneBotPlugin.png" width="300" alt="logo" />
+  </a>
+
+# nonebot-plugin-sentry-transaction
+
+✨ NoneBot2 事件与 Matcher 的非侵入式 Sentry 性能追踪 ✨
+
+![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
+![PyPI](https://img.shields.io/pypi/v/nonebot-plugin-sentry-transaction)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+![License](https://img.shields.io/github/license/shoucandanghehe/nonebot-plugin-sentry-transaction)
+![CI](https://github.com/shoucandanghehe/nonebot-plugin-sentry-transaction/actions/workflows/test.yml/badge.svg)
+[![Codecov](https://codecov.io/gh/shoucandanghehe/nonebot-plugin-sentry-transaction/graph/badge.svg)](https://codecov.io/gh/shoucandanghehe/nonebot-plugin-sentry-transaction)
+
+---
+
+简体中文 | [English](./README.en-us.md)
+
+</div>
+
+## 📖 功能特性
+
+- 每个事件产生一个 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](https://github.com/nonebot/plugin-sentry) 使用：
+
+```env
+SENTRY_DSN=https://<key>@<org>.ingest.sentry.io/<project>
+SENTRY_TRACES_SAMPLE_RATE=1.0
+```
+
+其他 Sentry 配置项请参阅 [nonebot-plugin-sentry 文档](https://github.com/nonebot/plugin-sentry)。
+
+## 💿 安装
+
+### 🚀 使用 uv
+
+```bash
+uv add nonebot-plugin-sentry-transaction
+```
+
+### 🚀 使用 PDM
+
+```bash
+pdm add nonebot-plugin-sentry-transaction
+```
+
+### 🚀 使用 Poetry
+
+```bash
+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](./LICENSE) 许可证开源。

nonebot_plugin_sentry_transaction-0.1.0/nonebot_plugin_sentry_transaction/__init__.py

@@ -0,0 +1,19 @@
+from nonebot import get_plugin_config, require
+from nonebot.plugin import PluginMetadata
+
+require('nonebot_plugin_sentry')
+
+from .config import Config  # noqa: E402
+from .tracing import setup_tracing  # noqa: E402
+
+__plugin_meta__ = PluginMetadata(
+    name='nonebot-plugin-sentry-transaction',
+    description='NoneBot Event 与 Matcher 的非侵入式 Sentry tracing',
+    usage='配置 nonebot-plugin-sentry 完成 Sentry 初始化。设置 SENTRY_NB_TRACE_ENABLED=false 可关闭 tracing。',
+    type='library',
+    config=Config,
+    supported_adapters=None,
+)
+
+config = get_plugin_config(Config)
+setup_tracing(config)

nonebot_plugin_sentry_transaction-0.1.0/nonebot_plugin_sentry_transaction/config.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel
+
+
+class Config(BaseModel):
+    """Sentry tracing 插件配置。"""
+
+    sentry_nb_trace_enabled: bool = True

nonebot_plugin_sentry_transaction-0.1.0/nonebot_plugin_sentry_transaction/tracing.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import contextlib
+import sys
+from typing import TYPE_CHECKING
+
+import nonebot.message
+import sentry_sdk
+from nonebot.exception import StopPropagation
+from nonebot.message import run_postprocessor
+from sentry_sdk.tracing import Span as SentrySpan
+
+if TYPE_CHECKING:
+    from contextlib import AsyncExitStack
+
+    from nonebot.adapters import Bot, Event
+    from nonebot.matcher import Matcher
+    from nonebot.typing import T_DependencyCache, T_State
+
+    from .config import Config
+
+
+_original_handle_event = nonebot.message.handle_event
+
+
+async def traced_handle_event(bot: Bot, event: Event) -> None:
+    # isolation_scope 为每个事件创建独立的隔离作用域，防止并发事件之间污染 trace 状态。
+    with sentry_sdk.isolation_scope() as scope:
+        scope.set_tag('adapter', bot.type)
+        scope.set_tag('event_type', event.get_type())
+
+        with sentry_sdk.start_transaction(op='nonebot.event', name=event.get_event_name()) as transaction:
+            transaction.set_tag('adapter', bot.type)
+            transaction.set_tag('event_type', event.get_type())
+            await _original_handle_event(bot, event)
+
+
+def patch_handle_event() -> None:
+    nonebot.message.handle_event = traced_handle_event
+
+    # Adapter 在导入时通过 from nonebot.message import handle_event 绑定了本地引用，
+    # 仅替换模块属性无法覆盖这些引用，需遍历 sys.modules 逐一替换。
+    for module in sys.modules.values():
+        if module is nonebot.message:
+            continue
+        try:
+            module_dict = vars(module)
+        except TypeError:
+            continue
+        for attr_name, attr_value in module_dict.items():
+            if attr_value is _original_handle_event:
+                with contextlib.suppress(AttributeError, TypeError):
+                    setattr(module, attr_name, traced_handle_event)
+
+
+_original_run_matcher = nonebot.message._run_matcher  # noqa: SLF001
+
+
+async def traced_run_matcher(  # noqa: PLR0913
+    Matcher: type[Matcher],  # noqa: N803
+    bot: Bot,
+    event: Event,
+    state: T_State,
+    stack: AsyncExitStack | None = None,
+    dependency_cache: T_DependencyCache | None = None,
+) -> None:
+    # new_scope 分叉当前 scope，防止同优先级并发 matcher 互相覆盖 active span。
+    with sentry_sdk.new_scope() as scope:
+        span_name = Matcher.plugin_name or Matcher.module_name or Matcher.__name__
+        scope.set_tag('matcher.plugin', Matcher.plugin_name or 'unknown')
+        scope.set_tag('matcher.module', Matcher.module_name or 'unknown')
+
+        # 在 span 内部捕获 StopPropagation，确保 span 以 ok 状态正常结束，
+        # 随后重新抛出以保持 NoneBot 的事件传播语义。
+        stop_propagation = False
+        with sentry_sdk.start_span(op='nonebot.matcher', name=span_name):
+            try:
+                await _original_run_matcher(Matcher, bot, event, state, stack, dependency_cache)
+            except StopPropagation:
+                stop_propagation = True
+
+    if stop_propagation:
+        raise StopPropagation
+
+
+def patch_run_matcher() -> None:
+    # check_and_run_matcher 通过模块全局名调用 _run_matcher（运行时解析），
+    # 因此只需替换模块属性，无需扫描 sys.modules。
+    nonebot.message._run_matcher = traced_run_matcher  # noqa: SLF001
+
+
+async def _on_matcher_done(exception: Exception | None = None) -> None:
+    """检测 matcher 内部异常并将 span 标记为错误。
+
+    _run_matcher 会捕获 matcher 异常但不重新抛出，导致 span 的 __exit__
+    无法感知异常。此 hook 通过 exception 参数补充设置 span 状态。
+    """
+    span = sentry_sdk.get_current_span()
+    if isinstance(span, SentrySpan) and exception is not None:
+        span.set_status('internal_error')
+
+
+def setup_tracing(config: Config) -> None:
+    """在插件加载时安装 tracing patch。"""
+    if not config.sentry_nb_trace_enabled or not sentry_sdk.is_initialized():
+        return
+    patch_handle_event()
+    patch_run_matcher()
+    run_postprocessor(_on_matcher_done)

nonebot_plugin_sentry_transaction-0.1.0/pyproject.toml

@@ -0,0 +1,135 @@
+[project]
+name = "nonebot-plugin-sentry-transaction"
+version = "0.1.0"
+description = "Non-invasive Sentry tracing for NoneBot events and matchers"
+readme = "README.md"
+authors = [{ name = "shoucandanghehe", email = "wallfjjd@gmail.com" }]
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+dependencies = [
+    "nonebot-plugin-sentry>=2.0.0",
+    "nonebot2>=2.4.4",
+    "sentry-sdk>=2.15.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.6,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "nonebot_plugin_sentry_transaction"
+module-root = ""
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "F",     # pyflakes
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "C90",   # mccabe
+    "I",     # isort
+    "N",     # PEP8-naming
+    "UP",    # pyupgrade
+    "YTT",   # flake8-2020
+    "ANN",   # flake8-annotations
+    "ASYNC", # flake8-async
+    "S",     # flake8-bandit
+    "BLE",   # flake8-blind-except
+    "FBT",   # flake8-boolean-trap
+    "B",     # flake8-bugbear
+    "A",     # flake8-builtins
+    "COM",   # flake8-commas
+    "C4",    # flake8-comprehensions
+    "DTZ",   # flake8-datetimez
+    "T10",   # flake8-debugger
+    "EM",    # flake8-errmsg
+    "FA",    # flake8-future-annotations
+    "ISC",   # flake8-implicit-str-concat
+    "ICN",   # flake8-import-conventions
+    "PIE",   # flake8-pie
+    "T20",   # flake8-print
+    "PYI",   # flake8-pyi
+    "Q",     # flake8-quotes
+    "RSE",   # flake8-raise
+    "RET",   # flake8-return
+    "SLF",   # flake8-self
+    "SLOT",  # flake8-slots
+    "SIM",   # flake8-simplify
+    "TID",   # flake8-tidy-imports
+    "TC",    # flake8-type-checking
+    "ARG",   # flake8-unused-arguments
+    "PTH",   # flake8-use-pathlib
+    "ERA",   # eradicate
+    "PD",    # pandas-vet
+    "PGH",   # pygrep-hooks
+    "PL",    # pylint
+    "TRY",   # tryceratops
+    "FLY",   # flynt
+    "FAST",  # FastAPI
+    "PERF",  # Perflint
+    "FURB",  # refurb
+    "RUF",   # Ruff-specific rules
+]
+ignore = [
+    "E501",   # 过长的行由 ruff format 处理, 剩余的都是字符串
+    "ANN202", # 向 NoneBot 注册的函数
+    "TRY003",
+    "COM812", # 强制尾随逗号
+    "TID252", # 相对导入
+    "ISC001", # format warning
+    "RUF002", # docstring 中的全角标点
+    "RUF003", # 注释中的全角标点
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "ANN", "PLR2004", "SIM117", "E402"]
+
+[tool.ruff.lint.flake8-quotes]
+inline-quotes = "single"
+multiline-quotes = "double"
+
+[tool.ruff.lint.flake8-annotations]
+mypy-init-return = true
+
+[tool.ruff.lint.flake8-builtins]
+builtins-ignorelist = ["id"]
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.basedpyright]
+pythonVersion = "3.10"
+pythonPlatform = "All"
+defineConstant = { PYDANTIC_V2 = true }
+typeCheckingMode = "standard"
+reportExplicitAny = 'hint'
+reportUnnecessaryTypeIgnoreComment = 'error'
+reportImplicitOverride = 'error'
+reportUnnecessaryComparison = 'error'
+reportImplicitAbstractClass = 'error'
+enableTypeIgnoreComments = false
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.38.3",
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=4.0",
+    "ruff>=0.15.7",
+]
+
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+
+[tool.coverage.run]
+source = ["nonebot_plugin_sentry_transaction"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "if TYPE_CHECKING:",
+]