Sentry 26.10.0 快速入门与集成示例

Sentry 26.10.0 快速上手：创建项目、获取 DSN，Python 与 Node.js SDK 接入并真实上报错误事件，验证 Issue 入库与 API 查询，配置 Issue 告警规则。

SentrySentryPythonJavaScriptAPM2026/10/17

Sentry 26.10.0 快速入门与集成示例

目标：以一套可直接复制的最小流程跑通 Sentry 的核心闭环——创建项目、获取 DSN、用 Python 与 Node.js SDK 真实上报错误、在界面与 API 中确认 Issue 已入库、配置第一条告警规则。本文所有命令输出均为自托管 26.10.0 实测环境的真实回显。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • Sentry self-hosted：26.10.0，部署于本机（访问入口 http://127.0.0.1:9000，远程接入把地址换成服务器 IP 或域名即可）
  • Python：3.12.3 + sentry-sdk 2.72.0
  • Node.js：v18.19.1 + npm 9.2.0 + @sentry/node 11.8.0
  • 组织：sentry（安装初始化时自动创建的默认组织）
  • 演示项目：python-demo（本文第四章创建）
  • 管理员账号：admin@sentry.local / q1w2e3r4（本文演示账号）

二、前置条件

三、核心概念速览

概念说明
组织（Organization）租户单位，安装后默认创建 sentry 组织，可再建多个
团队/项目（Project）一个应用对应一个项目，Issue 按项目隔离
DSN数据源名称（Data Source Name），SDK 上报的唯一凭证，含密钥与地址
Event一次错误/性能/日志上报的原始记录
IssueSentry 按「根因指纹」把同类 Event 聚合后的分组，去重计数展示
告警规则（Alert Rule）Issue 或指标满足条件时触发邮件/Webhook 等通知

💡 技术拓展：「Issue」在 Sentry 里指聚合后的问题分组，不是单条报错。SDK 每次抛错产生 Event，Sentry 用堆栈指纹（fingerprint）把相同根因的 Event 归并到同一 Issue，并记录首次出现/最近出现/次数。因此「接入后 Issue 数量比报错次数少」是正常现象。

💡 技术拓展：Sentry 有两套告警体系——Issue Alert（问题告警），面向聚合后的 Issue（如「新问题出现」「问题重新出现」「某个问题 1 小时内出现 10 次」）；Metric Alert（指标告警），面向数值指标（如「5 分钟错误率超过 10%」）。前者按事件触达，时效分钟级；后者按时间窗口聚合，适合大盘监控。本文演示 Issue Alert。

四、创建组织与项目

4.1 命令行方式（实测）

部署机上有管理命令行，可直接创建项目：

cd /root/sentry
docker compose run --rm -T web createproject --name python-demo --platform python --organization sentry

实测回显：

Created project:
  ID: 2
  Slug: python-demo

💡 说明：项目全局唯一 ID 为 2（1 被内部项目占用），Slug 是 URL/API 中使用的项目标识 python-demo。--platform 指定主要语言平台，影响界面展示的接入指引。

命令行可用的项目/组织管理命令清单（实测 docker compose run --rm -T web help 输出节选）：

createflag            Registers all flags in FlagRegistry
createissueflag       Registers all issue tracking plugin flags in FlagRegistry
createorg
createproject
createuser

4.2 界面方式

登录后进入组织 → Projects → Create Project → 选择平台（Python）→ 填写项目名 → Create Project，创建成功页会直接展示 DSN。

五、获取 DSN

5.1 DSN 结构

DSN 形如：

http://<public_key>@<host>:<port>/<project_id>
  • public_key：项目密钥（即项目 API Key），Sentry 以此识别项目；
  • host:port：Sentry 入口地址（自托管即 nginx 入口）；
  • project_id：项目数字 ID。
  • 同一项目还有 secret_key（旧版协议使用，当前 SDK 主要用 public_key）。

5.2 API 方式获取（实测）

用个人 API Token 调用项目密钥接口。Token 在界面 Settings → Account → API → Auth Tokens 创建（勾选 project:read、event:write 等权限），自托管生成的用户 Token 以 sntryu_ 开头。

curl -s -H "Authorization: Bearer sntryu_dfd5756ce4524f914587de6febba83467c72fbc26d8f7e1f" \
  http://127.0.0.1:9000/api/0/projects/sentry/python-demo/keys/

实测回显（输出节选，密钥字段为实测值）：

[{
  "id": "739eaf5acad60fa61c7700b1ea7afc29",
  "name": "Default",
  "label": "Default",
  "public": "739eaf5acad60fa61c7700b1ea7afc29",
  "secret": "5cdfab3c62a36cc2978df7c49b8dce87",
  "projectId": 2,
  "isEnabled": true,
  "dateCreated": "2026-10-16T15:44:45.538087Z"
}]

由此拼出本项目 DSN（本机部署）：

http://739eaf5acad60fa61c7700b1ea7afc29@127.0.0.1:9000/2

⚠️ 注意：远程应用接入时，把 127.0.0.1:9000 换成 Sentry 服务器的实际 IP 或域名（同时建议配置 system.url-prefix 保持链接一致，见《Sentry 26.10.0 配置参数详解》）。DSN 含密钥，泄漏即可向项目注入伪造事件，不要提交到公开仓库。

六、Python SDK 集成示例

6.1 安装 SDK

python3 -m venv /root/sdktest
/root/sdktest/bin/pip install sentry-sdk
/root/sdktest/bin/pip show sentry-sdk | head -2

实测回显：

Name: sentry-sdk
Version: 2.72.0

6.2 上报第一个错误

创建 /root/sdktest/scripts/report.py：

import sentry_sdk

sentry_sdk.init(
    dsn="http://739eaf5acad60fa61c7700b1ea7afc29@127.0.0.1:9000/2",
    traces_sample_rate=1.0,
)

try:
    division = 1 / 0
except ZeroDivisionError as e:
    event_id = sentry_sdk.capture_exception(e)
    print("capture_exception event_id =", event_id)

event_id2 = sentry_sdk.capture_message("手动测试消息：Sentry Python SDK 上报成功")
print("capture_message event_id =", event_id2)

sentry_sdk.flush(timeout=10)
print("flush 完成")

执行：

/root/sdktest/bin/python /root/sdktest/scripts/report.py

实测回显：

capture_exception event_id = 359c70313a9346c58568c1ba3534050d
capture_message event_id = 545abb24556b4efdb4e6cd336e3db760
flush 完成

💡 说明：capture_exception(e) 返回的 32 位十六进制串就是该事件的 Event ID，也是界面上事件详情 URL 的一部分。traces_sample_rate=1.0 开启性能追踪全采样（生产建议 0.1~0.5）。flush 确保进程退出前把缓冲的事件发出，脚本类程序建议保留。

6.3 确认事件入库

事件经 Kafka 消费链写入 ClickHouse 再关联到 PostgreSQL 的 Issue 分组，实测约 30~60 秒完成。查询项目 Issue 分组（Sentry 管理命令行）：

cd /root/sentry
docker compose run --rm -T web shell -c "
from sentry.models.group import Group
for g in Group.objects.filter(project_id=2).order_by('-last_seen')[:5]:
    print(g.id, '|', g.level, '|', g.type, '|', g.title[:60], '|', g.times_seen)
"

实测回显：

2 | 40 | error | ZeroDivisionError: division by zero | 1
1 | 20 | info | 手动测试消息：Sentry Python SDK 上报成功 | 1

level 列：20=info、30=warning、40=error。Python SDK 的 capture_exception 自动定为 error 级别，capture_message 默认 info。

七、Node.js SDK 集成示例

7.1 安装 SDK

mkdir -p /root/nodetest && cd /root/nodetest
npm init -y
npm install @sentry/node
node -e "console.log('@sentry/node version:', require('@sentry/node/package.json').version)"

实测回显：

added 23 packages in 43s
@sentry/node version: 11.8.0

7.2 上报第一个错误

创建 /root/nodetest/report.js：

const Sentry = require("@sentry/node");

Sentry.init({
  dsn: "http://739eaf5acad60fa61c7700b1ea7afc29@127.0.0.1:9000/2",
  tracesSampleRate: 1.0,
});

const eventId = Sentry.captureException(new Error("Node.js 手动抛出的测试错误"));
console.log("captureException event_id =", eventId);

Sentry.captureMessage("Node.js 手动测试消息：SDK 上报成功", "warning");
setTimeout(() => {
  Sentry.flush().then(() => console.log("flush 完成"));
}, 2000);

执行：

node report.js

实测回显：

captureException event_id = 4939e5fe2db2437cb4c259a37c1cdac7
flush 完成

7.3 确认事件入库

cd /root/sentry
docker compose run --rm -T web shell -c "
from sentry.models.group import Group
for g in Group.objects.filter(project_id=2).order_by('-last_seen')[:2]:
    print(g.id, '|', g.level, '|', g.title[:60], '|', g.times_seen)
"

实测回显：

4 | 30 | Object.? | 1
3 | 40 | Error: Node.js 手动抛出的测试错误 | 1

💡 说明：Node 侧 captureMessage 的分组标题显示为 Object.?（warning 级，level=30），是 26.x 对消息类事件聚合显示的实际形态；打开该 Issue 详情可看到完整消息内容。错误类事件（level=40）则直接以异常类型+消息作为标题。

八、查看 Issue 与事件详情

8.1 API 方式（实测）

curl -s -H "Authorization: Bearer sntryu_dfd5756ce4524f914587de6febba83467c72fbc26d8f7e1f" \
  "http://127.0.0.1:9000/api/0/organizations/sentry/issues/?query=&project=2&sort=date" \
  | python3 -c "import json,sys; [print(i['id'], '|', i['shortId'], '|', i['title'][:50], '|', i['level'], '|', i['count']) for i in json.load(sys.stdin)]"

实测回显：

4 | PYTHON-DEMO-4 | Object.? | warning | 1
3 | PYTHON-DEMO-3 | Error: Node.js 手动抛出的测试错误 | error | 1
2 | PYTHON-DEMO-2 | ZeroDivisionError: division by zero | error | 1
1 | PYTHON-DEMO-1 | 手动测试消息：Sentry Python SDK 上报成功 | info | 1

shortId（如 PYTHON-DEMO-2）是 Issue 在项目内的短编号，可拼出界面直达链接：http://<入口>/organizations/sentry/issues/?id=<shortId>。

8.2 界面方式

登录后左侧菜单 Issues 即问题列表；点击任意 Issue 进入详情页，可查看完整堆栈、请求上下文、面包屑、出现次数与影响用户数。Performance 页签查看 traces_sample_rate 采样的请求链路。

九、告警规则配置

9.1 界面创建（推荐路径）

进入组织 Alerts → New Alert → Issue Alert（问题告警）：

  1. 数据集：选 Errors；
  2. 归属项目：python-demo；
  3. 条件（conditions）：如「The issue is first seen」（新问题首次出现）、「The event matches a specific filter」（按字段过滤）、「An issue is seen more than N times in M minutes」（频次触发）；
  4. 动作（actions）：Send a notification to…（邮件，成员/团队）、Send a test notification 可立即验证；Webhook/钉钉/Slack 需先在 Settings → Integrations 安装集成；
  5. 频率限制（frequency）：同一 Issue 触发通知的最小间隔，默认 5 分钟；
  6. 保存后可在 Alerts 列表页看到规则及其历史触发记录。

规则的核心结构即 2.x 以来通用的「条件 + 匹配策略（全部满足/任一满足）+ 动作 + 频率限制」四元组，界面上每一步都有即时预览。

9.2 关于 API 创建告警规则的版本说明（实测）

旧版 API POST /api/0/organizations/{org}/rules/ 在 26.10.0 已被移除（官方正把告警迁移到新的工作流引擎，新端点仅开放规则详情/编辑查询能力）。实测：

curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer sntryu_dfd5756ce4524f914587de6febba83467c72fbc26d8f7e1f" \
  http://127.0.0.1:9000/api/0/organizations/sentry/rules/

实测回显：

404

因此 26.10.0 下建议通过界面创建与管理告警规则；自动化诉求可用邮件/Webhook 通知接收端做二次编排。

十、注意事项与常见问题

Q1：SDK 上报成功但界面看不到 Issue？ 事件链路为：SDK → relay → Kafka → 消费器 → ClickHouse → 后处理 → Issue 分组，实测需要 30~60 秒。若超过数分钟仍未出现，按顺序检查：docker compose ps 是否全部 healthy、docker compose logs --tail=50 post-process-forwarder-errors、docker compose logs --tail=50 snuba-errors-consumer。

Q2：DSN 地址应该填 127.0.0.1 还是域名？ DSN 里的地址是「应用服务器访问 Sentry 入口」的地址。同一台机器可填 127.0.0.1；跨机器必须填可达的 IP/域名。若配置了 system.url-prefix，界面展示的 DSN 会自动用该前缀。

Q3：capture_exception 与 capture_message 该用哪个？ 有异常对象（except 分支、未捕获异常自动上报）用前者，携带完整堆栈；无异常对象的业务级提示（如「订单状态异常」）用后者。

Q4：性能追踪（traces_sample_rate）会不会拖慢应用？ SDK 采样在本地完成，未采样请求几乎零开销；采样率 1.0 只用于测试环境，生产建议按流量设置 0.1~0.5，或用 traces_sampler 函数按路由动态采样。

Q5：Token 认证报 Invalid org token？ 自托管用户 Token 以 sntryu_ 开头；sntrys_ 前缀是组织集成 Token，二者不通用。用错前缀的 Token 调 API 会返回认证失败，实测确认需用界面 Auth Tokens 创建的用户 Token。

Q6：怎么验证 SDK 与 Sentry 之间网络通？ 直接对入口发一个空 POST 看响应即可（SDK 底层即走该路径）：

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:9000/api/2/envelope/

实测回显：

401

返回 401（未带 DSN 凭证被拒）说明入口与上报通道可达，SDK 配好 DSN 即可上报成功。

十一、参考链接