Sentry Release 追踪 #
什么是 Release 追踪？ #
Release 追踪是 Sentry 的重要功能，帮助你了解每个版本的健康状况，快速定位问题归属版本。
text
┌─────────────────────────────────────────────────────────────┐
│ Release 追踪价值 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 问题归属 │
│ - 知道哪个版本引入的问题 │
│ - 快速定位问题来源 │
│ │
│ 2. 版本健康 │
│ - 每个版本的错误率 │
│ - 新增问题数量 │
│ - 解决问题数量 │
│ │
│ 3. 部署追踪 │
│ - 部署到不同环境 │
│ - 部署后问题检测 │
│ │
│ 4. 回滚决策 │
│ - 版本对比 │
│ - 决定是否回滚 │
│ │
└─────────────────────────────────────────────────────────────┘
创建 Release #
命名规范 #
text
┌─────────────────────────────────────────────────────────────┐
│ Release 命名规范 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 推荐格式： │
│ │
│ 1. 语义化版本 │
│ my-app@1.0.0 │
│ my-app@2.1.3 │
│ │
│ 2. Git Commit SHA │
│ my-app@abc123def456 │
│ │
│ 3. 时间戳 │
│ my-app@2024-01-15 │
│ │
│ 注意： │
│ - 使用唯一标识 │
│ - 保持命名一致 │
│ - 包含项目名称 │
│ │
└─────────────────────────────────────────────────────────────┘
SDK 配置 Release #
javascript
// JavaScript
import * as Sentry from "@sentry/browser";
Sentry.init({
dsn: "https://xxxxxxxx@o123456.ingest.sentry.io/1234567",
release: `my-app@${process.env.npm_package_version}`,
environment: process.env.NODE_ENV,
});
python
# Python
import sentry_sdk
sentry_sdk.init(
dsn="https://xxxxxxxx@o123456.ingest.sentry.io/1234567",
release=f"my-app@{os.environ.get('APP_VERSION', 'unknown')}",
environment=os.environ.get("ENVIRONMENT", "development"),
)
go
// Go
sentry.Init(sentry.ClientOptions{
Dsn: "https://xxxxxxxx@o123456.ingest.sentry.io/1234567",
Release: "my-app@1.0.0",
Environment: "production",
})
使用 Sentry CLI 创建 Release #
bash
# 安装 Sentry CLI
npm install -g @sentry/cli
# 创建 Release
sentry-cli releases new my-app@1.0.0
# 设置 Release 项目
sentry-cli releases set-commits my-app@1.0.0 --auto
# 完成 Release
sentry-cli releases finalize my-app@1.0.0
CI/CD 集成 #
GitHub Actions #
yaml
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Create Sentry Release
uses: getsentry/action-release@v1
env:
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
SENTRY_ORG: my-org
SENTRY_PROJECT: my-project
with:
environment: production
release: my-app@${{ github.sha }}
- name: Deploy
run: |
# 部署逻辑
npm run deploy
GitLab CI #
yaml
# .gitlab-ci.yml
stages:
- deploy
deploy:
stage: deploy
script:
- npm install -g @sentry/cli
- sentry-cli releases new my-app@$CI_COMMIT_SHA
- sentry-cli releases set-commits my-app@$CI_COMMIT_SHA --auto
- sentry-cli releases finalize my-app@$CI_COMMIT_SHA
- sentry-cli releases deploys my-app@$CI_COMMIT_SHA new -e production
environment:
name: production
only:
- main
Jenkins #
groovy
// Jenkinsfile
pipeline {
agent any
environment {
SENTRY_AUTH_TOKEN = credentials('sentry-auth-token')
SENTRY_ORG = 'my-org'
SENTRY_PROJECT = 'my-project'
}
stages {
stage('Deploy') {
steps {
sh '''
npm install -g @sentry/cli
# 创建 Release
sentry-cli releases new my-app@$GIT_COMMIT
# 关联提交
sentry-cli releases set-commits my-app@$GIT_COMMIT --auto
# 部署
npm run deploy
# 完成 Release
sentry-cli releases finalize my-app@$GIT_COMMIT
# 创建部署记录
sentry-cli releases deploys my-app@$GIT_COMMIT new -e production
'''
}
}
}
}
CircleCI #
yaml
# .circleci/config.yml
version: 2.1
orbs:
sentry: sentry/sentry@1.0.0
jobs:
deploy:
docker:
- image: cimg/node:18
steps:
- checkout
- sentry/create-release:
release: my-app@${CIRCLE_SHA1}
environment: production
- run:
name: Deploy
command: npm run deploy
workflows:
deploy:
jobs:
- deploy:
filters:
branches:
only: main
部署追踪 #
创建部署记录 #
bash
# 创建部署记录
sentry-cli releases deploys my-app@1.0.0 new -e production
# 带部署时间
sentry-cli releases deploys my-app@1.0.0 new -e production --time 1705312800
# 带部署名称
sentry-cli releases deploys my-app@1.0.0 new -e production --name "Production Deploy #123"
多环境部署 #
bash
# 部署到 staging
sentry-cli releases deploys my-app@1.0.0 new -e staging
# 部署到 production
sentry-cli releases deploys my-app@1.0.0 new -e production
# 部署到 canary
sentry-cli releases deploys my-app@1.0.0 new -e canary
部署流程示例 #
text
┌─────────────────────────────────────────────────────────────┐
│ 部署流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 创建 Release │
│ sentry-cli releases new my-app@1.0.0 │
│ │
│ 2. 关联代码提交 │
│ sentry-cli releases set-commits my-app@1.0.0 --auto │
│ │
│ 3. 上传 Source Maps │
│ sentry-cli sourcemaps upload ... │
│ │
│ 4. 部署应用 │
│ npm run deploy │
│ │
│ 5. 创建部署记录 │
│ sentry-cli releases deploys my-app@1.0.0 new -e prod │
│ │
│ 6. 完成 Release │
│ sentry-cli releases finalize my-app@1.0.0 │
│ │
└─────────────────────────────────────────────────────────────┘
Release 健康 #
健康指标 #
text
┌─────────────────────────────────────────────────────────────┐
│ Release 健康指标 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 错误率 │
│ - Crash Free Users: 无崩溃用户比例 │
│ - Crash Free Sessions: 无崩溃会话比例 │
│ │
│ 2. 问题数量 │
│ - 新问题数量 │
│ - 解决问题数量 │
│ - 总问题数量 │
│ │
│ 3. 性能指标 │
│ - 平均响应时间 │
│ - P95 响应时间 │
│ - 吞吐量 │
│ │
│ 4. 用户影响 │
│ - 影响用户数 │
│ - 用户反馈 │
│ │
└─────────────────────────────────────────────────────────────┘
查看 Release 健康 #
在 Sentry 控制台：
- 进入 Releases 页面
- 选择要查看的 Release
- 查看健康指标：
- Crash Free Users
- 新问题数量
- 问题趋势图
- 性能数据
设置健康阈值 #
yaml
# 告警规则
rules:
- name: "Crash Free Rate Alert"
conditions:
- type: crash_free_users
threshold: 95 # 低于 95% 告警
comparison: less_than
actions:
- type: slack
channel: "#releases"
问题归属 #
自动关联 #
当错误发生时，Sentry 会自动关联到当前 Release：
javascript
// 错误会自动关联到当前 Release
Sentry.init({
release: "my-app@1.0.0",
});
// 发生错误时，会记录 release 信息
throw new Error("Something went wrong");
查看问题归属 #
在 Sentry 控制台：
- 进入 Issues 页面
- 选择问题
- 查看 First Seen 和 Last Seen
- 查看 Release 信息
问题引入版本 #
text
┌─────────────────────────────────────────────────────────────┐
│ 问题引入分析 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Issue #1234: TypeError: Cannot read property 'id' │
│ │
│ 引入版本: my-app@1.0.0 │
│ 首次发现: 2024-01-15 10:30:00 │
│ │
│ 版本分布: │
│ ├── my-app@1.0.0: 500 次 (首次出现) │
│ ├── my-app@1.0.1: 300 次 │
│ └── my-app@1.0.2: 100 次 │
│ │
│ 解决版本: my-app@1.0.3 │
│ │
└─────────────────────────────────────────────────────────────┘
版本回滚 #
回滚决策 #
text
┌─────────────────────────────────────────────────────────────┐
│ 回滚决策流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 监控新版本健康指标 │
│ ├── Crash Free Rate < 95%? │
│ ├── 新问题数量激增? │
│ └── 性能严重下降? │
│ │
│ 2. 评估影响 │
│ ├── 影响用户数量 │
│ ├── 问题严重程度 │
│ └── 修复时间预估 │
│ │
│ 3. 决策 │
│ ├── 回滚到上一版本 │
│ ├── 紧急修复发布 │
│ └── 继续监控 │
│ │
└─────────────────────────────────────────────────────────────┘
版本对比 #
bash
# 使用 CLI 对比版本
sentry-cli releases info my-app@1.0.0
sentry-cli releases info my-app@1.0.1
在 Sentry 控制台：
- 进入 Releases 页面
- 选择两个版本进行对比
- 查看差异：
- 错误率变化
- 新问题数量
- 性能变化
Suspect Commits #
启用 Suspect Commits #
bash
# 关联提交信息
sentry-cli releases set-commits my-app@1.0.0 --auto
# 或手动指定
sentry-cli releases set-commits my-app@1.0.0 --commit "owner/repo@abc123"
查看 Suspect Commits #
Sentry 会根据问题首次出现的版本，自动推断可能的提交：
text
┌─────────────────────────────────────────────────────────────┐
│ Suspect Commits │
├─────────────────────────────────────────────────────────────┤
│ │
│ Issue #1234 首次出现在 my-app@1.0.0 │
│ │
│ 可疑提交: │
│ ├── abc123 - Fix user authentication (John Doe) │
│ ├── def456 - Update API endpoints (Jane Smith) │
│ └── ghi789 - Refactor user service (Bob Wilson) │
│ │
│ 点击提交可查看具体代码变更 │
│ │
└─────────────────────────────────────────────────────────────┘
Release 最佳实践 #
1. 一致的命名 #
javascript
// ✅ 好的做法
const release = `${process.env.npm_package_name}@${process.env.npm_package_version}`;
// 结果: my-app@1.0.0
// ❌ 不好的做法
const release = "v1.0.0"; // 缺少项目名称
const release = "2024-01-15"; // 不够具体
2. 自动化发布流程 #
yaml
# 完整的发布流程
name: Release
on:
push:
tags:
- 'v*'
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Create Sentry Release
uses: getsentry/action-release@v1
env:
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
SENTRY_ORG: my-org
SENTRY_PROJECT: my-project
with:
release: my-app@${{ github.ref_name }}
environment: production
sourcemaps: ./dist
- name: Deploy
run: npm run deploy
3. 环境隔离 #
javascript
// 不同环境使用不同的 Release 标识
const release = `my-app@${process.env.APP_VERSION}`;
Sentry.init({
dsn: "https://xxxxxxxx@o123456.ingest.sentry.io/1234567",
release,
environment: process.env.ENVIRONMENT, // staging, production, etc.
});
4. 发布后监控 #
yaml
# 发布后自动监控
name: Post-Deploy Monitor
on:
workflow_run:
workflows: ["Deploy"]
types: [completed]
jobs:
monitor:
runs-on: ubuntu-latest
steps:
- name: Check Release Health
run: |
# 使用 Sentry API 检查版本健康
curl -H "Authorization: Bearer ${{ secrets.SENTRY_AUTH_TOKEN }}" \
"https://sentry.io/api/0/projects/my-org/my-project/releases/my-app@${{ github.sha }}/" \
| jq '.stats.crashFreeUsers'
5. 回滚准备 #
yaml
# 保留回滚能力
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Get previous release
id: previous
run: |
PREVIOUS=$(curl -H "Authorization: Bearer ${{ secrets.SENTRY_AUTH_TOKEN }}" \
"https://sentry.io/api/0/projects/my-org/my-project/releases/" \
| jq -r '.[1].version')
echo "version=$PREVIOUS" >> $GITHUB_OUTPUT
- name: Deploy new version
run: npm run deploy
- name: Store rollback info
run: |
echo "Previous version: ${{ steps.previous.outputs.version }}"
echo "To rollback: sentry-cli releases deploys ${{ steps.previous.outputs.version }} new -e production"
下一步 #
现在你已经掌握了 Release 追踪的知识，接下来学习 告警配置 了解如何配置错误告警！
最后更新：2026-03-29