第三方扩展支持：Sentry 集成

MagicTradeBot 原生支持与 Sentry 的集成 — 一个功能强大的实时错误追踪与监控平台。该功能允许开发人员和运维人员从每个机器人实例发送结构化的 日志和事件数据 到 Sentry，从而实现快速调试、集中告警以及系统健康状况的全面可视化。

无论您运行的是 单个机器人实例，还是在多个交易所、账户、交易对或服务器节点上运行 数百个机器人，Sentry 都可以帮助您集中监控并有效地追踪问题。在这种规模下，人工监控已不可行 —— Sentry 通过强大的自动化与洞察力填补了这一空白。

🚀 概览

通过与 Sentry 的集成，MagicTradeBot 可以自动捕捉以下内容：

运行时异常和未处理的错误
交易执行失败
与交易所的连接问题
自定义日志和诊断事件

所有日志和错误事件都会实时推送到 Sentry，使您可以：

按机器人实例、交易对或交易所追踪问题
分析堆栈追踪、性能瓶颈和错误频率
为关键故障设置邮件、Slack 或 Webhook 告警

🔧 核心功能

📡 实时异常与错误上报
🧠 自动捕获带上下文的堆栈信息
🌍 支持多实例与分布式运行环境
🕵️ 问题分组、严重性标记与版本追踪
📊 集中式仪表盘，支持告警规则与多种集成

🛠️ 前提条件

有效的 Sentry 帐号与 DSN（数据源名称）
在 MagicTradeBot 运行环境中安装 Sentry SDK
机器人已配置唯一的 instance_id 或 tags，以便更好地追踪

⚙️ 配置步骤

1. 安装 Sentry SDK

根据运行环境（如 Python、Go、Node.js）安装 Sentry：

pip install --upgrade sentry-sdk

2. 在机器人启动代码中初始化 Sentry

添加以下代码片段来初始化 Sentry：

import sentry_sdk

sentry_sdk.init(
    dsn="YOUR_SENTRY_DSN",
    environment="production",
    release="magictradebot@2.0.0",
    traces_sample_rate=1.0,
    send_default_pii=True
)

3. 在配置文件中启用 Sentry

在 config.yaml 或 appsettings.json 中启用 Sentry 集成：

monitoring:
  sentry:
    enabled: true
    dsn: "YOUR_SENTRY_DSN"
    environment: "production"
    release: "magictradebot@2.0.0"
    tags:
      instance_id: "bot-apac-01"
      exchange: "binance"

4. 添加自定义日志与错误捕获（可选）

您可以手动报告关键错误，例如：

from sentry_sdk import capture_exception

try:
    bot.execute_trade()
except Exception as e:
    capture_exception(e)

🧪 Sentry 事件数据示例

{
  "level": "error",
  "message": "Trade execution failed",
  "timestamp": "2025-06-20T11:25:41Z",
  "bot_instance": "bot-us-1",
  "symbol": "SOL/USDT",
  "exchange": "kucoin",
  "exception": {
    "type": "InsufficientBalanceError",
    "value": "Not enough USDT to place order",
    "stacktrace": [...]
  }
}

✅ 集成 Sentry 的优势

📍 集中跟踪所有机器人活动的日志与错误
⚠️ 立即发现故障、配置错误或服务中断
📈 可视化仪表盘展示问题频率与趋势
🚨 支持 Slack、Teams、邮件与 Webhook 告警集成
🔍 借助堆栈追踪与 Breadcrumb 快速定位并解决问题