configure-sentry

/configure:sentry

检查 Sentry 错误跟踪集成，并根据项目标准进行配置。

适用场景

在以下情况下使用此技能……	在以下情况下采用其他方法……
为新项目设置 Sentry 错误跟踪	调试特定的 Sentry 问题或警报（使用 Sentry MCP 服务）
深入了解 Sentry 专属设置和合规性	配置整个可观测性技术栈——OTel 跟踪/指标 + 日志记录（使用 /configure:instrumentation，它会将 Sentry 相关缺项交由此处处理）
检查 Sentry SDK 的安装和配置是否合规	查询 Sentry 事件或性能数据（使用 Sentry API/MCP）
修复硬编码的 DSN 或缺失的环境变量引用	在 Sentry 控制面板中管理 Sentry 项目设置
在 CI/CD 中添加源映射上传和版本跟踪	配置 Sentry 警报规则或通知渠道
验证前端、Next.js、Node.js 或 Python 项目中的 Sentry 配置	安装其他错误跟踪工具（例如 Bugsnag、Rollbar）
添加性能分析、结构化日志记录或增强辅助工具	配置 Sentry 警报规则或通知渠道
审查项目级设置和合规性	了解日常 SDK 使用模式——spans、面包屑、cron 监控、回放（使用 typescript-plugin:typescript-sentry）

上下文

• Package.json：!find . -maxdepth 1 -name \'package.json\'
• Pyproject.toml：!find . -maxdepth 1 -name \'pyproject.toml\'
• Requirements.txt：!find . -maxdepth 1 -name \'requirements.txt\'
• 项目标准：!find . -maxdepth 1 -name '.project-standards.yaml' -type f
• package.json 中的 Sentry：!find . -maxdepth 1 -name 'package.json' -exec grep -o '"@sentry/[^"]*"' {} +
• pyproject.toml 中的 Sentry：!find . -maxdepth 1 -name 'pyproject.toml' -exec grep 'sentry' {} +
• Sentry 初始化文件：!find . -maxdepth 3 -name "*sentry*" -type f
• Next.js 配置：!find . -maxdepth 1 -name 'next.config.*'
• Instrumentation 文件：!find . -path '*/src/*' -maxdepth 2 -name 'instrumentation*' -type f
• 引用了 DSN 的环境文件：!find . \( -name '.env*' -o -path '*/.github/workflows/*' \) -type f -exec grep -l 'SENTRY_DSN' {} +
• CI 工作流：!find . -path '*/.github/workflows/*' -maxdepth 3 -name '*.yml'

引用的技能：sentry（用于 Sentry API 的 MCP 服务）

参数

从 $ARGUMENTS 中解析以下参数：

标志	说明
--check-only	报告状态，但不提供修复方案
--fix	无需提示，自动应用所有修复
--type <type>	覆盖项目类型检测（frontend、nextjs、python、node）

版本检查

重要：配置 Sentry SDK 之前，请验证最新版本：

1. @sentry/vue / @sentry/react：查看 npm
2. @sentry/nextjs：查看 npm
3. @sentry/node：查看 npm
4. sentry-sdk（Python）：查看 PyPI
5. @sentry/vite-plugin：查看 npm

配置 Sentry 之前，使用 WebSearch 或 WebFetch 验证当前 SDK 版本。

执行

执行此 Sentry 合规性检查：

第 1 步：检测项目类型

确定项目类型，以选择合适的 SDK 和配置：

1. 读取 .project-standards.yaml 中的 project_type 字段
2. 如果未找到，则自动检测：
   • nextjs：package.json 中包含 next 依赖项（检查是否有 @sentry/nextjs）
   • frontend：package.json 中包含 vue/react 依赖项（不含 Next.js）
   • node：package.json 中包含 Node.js 后端（express、fastify 等）
   • python：存在 pyproject.toml 或 requirements.txt
3. 如果提供了 --type 标志，则使用其值

步骤 2：检查 SDK 安装情况

根据检测到的项目类型，检查是否安装了 Sentry SDK：

Next.js：

• package.json 的依赖项中包含 @sentry/nextjs
• @sentry/profiling-node（推荐用于服务端性能分析）

前端（Vue/React）：

• package.json 的依赖项中包含 @sentry/vue 或 @sentry/react
• @sentry/vite-plugin，用于源映射

Node.js 后端：

• package.json 的依赖项中包含 @sentry/node
• @sentry/profiling-node（推荐）

Python：

• pyproject.toml 或 requirements.txt 中包含 sentry-sdk
• 框架集成（django、flask、fastapi）

步骤 3：分析配置

读取 Sentry 初始化文件，并对照 REFERENCE.md 中的合规性表格进行检查。验证：

1. DSN 来自环境变量（未硬编码）
2. 已配置追踪采样率（生产环境和开发环境采用不同的采样率）
3. 已启用源映射（前端/Next.js）
4. 初始化位置正确（Node.js：在其他导入之前）
5. 已启用框架集成（Python）

Next.js 项目的额外检查：

6. src/instrumentation.ts 存在，且导出了 register() 和 onRequestError
7. src/instrumentation-client.ts 存在，且包含客户端 Sentry 初始化
8. 项目根目录下存在 sentry.server.config.ts 和 sentry.edge.config.ts
9. next.config.mjs 使用 withSentryConfig() 包装配置
10. 已配置隧道路由（tunnelRoute: "/monitoring"）
11. 已隐藏源映射，并在上传后删除（hideSourceMaps、deleteSourcemapsAfterUpload）
12. serverExternalPackages 中列出了 @sentry/profiling-node
13. 存在错误边界（src/app/error.tsx、src/app/global-error.tsx）
14. 已启用结构化日志记录（enableLogs: true）
15. 在 beforeSend 中剥离敏感标头
16. 在 beforeSendTransaction 中过滤事务（丢弃健康检查和静态资源）

步骤 4：运行安全检查

1. 确认所有源文件中都没有硬编码的 DSN
2. 检查是否有 DSN 被提交到 Git 跟踪的文件中
3. 确认前端代码中没有身份验证令牌
4. 检查生产环境的采样率是否合理（不是 1.0）

步骤 5：报告结果

输出合规性报告，包含：

• 项目类型（检测到的或被覆盖指定的）
• SDK 版本和安装状态
• 配置检查结果（PASS/WARN/FAIL）
• 安全检查结果
• 缺失的配置项
• 建议

如果指定了 --check-only，则在此处停止。

步骤 6：应用修复（如果指定了 --fix 或用户确认）

1. 缺少 SDK：将适用的 Sentry SDK 添加到依赖项
2. 缺少 Vite 插件：添加 @sentry/vite-plugin，用于源映射
3. 缺少配置文件：使用 REFERENCE.md 中的模板创建 Sentry 初始化文件
4. 硬编码的 DSN：替换为环境变量引用
5. 缺少采样率：添加建议的采样率

步骤 7：检查 CI/CD 集成

验证 CI/CD 中的 Sentry 集成：

• 已配置 SENTRY_AUTH_TOKEN 机密
• 构建工作流中包含源映射上传步骤
• 部署时创建版本

如果缺少这些内容，则询问是否添加 REFERENCE.md 中建议的工作流步骤。

步骤 8：更新标准跟踪文件

更新或创建 .project-standards.yaml：

standards_version: "2025.1"
project_type: "<detected>"
last_configured: "<timestamp>"
components:
  sentry: "2025.1"

环境变量

变量	描述	必需
SENTRY_DSN	Sentry 数据源名称（服务端）	是
NEXT_PUBLIC_SENTRY_DSN	客户端 Sentry DSN（Next.js）	仅限 Next.js
SENTRY_ENVIRONMENT	环境名称（服务端）	建议设置
NEXT_PUBLIC_SENTRY_ENVIRONMENT	环境名称（客户端，Next.js）	仅限 Next.js
SENTRY_ORG	Sentry 组织标识	用于源代码映射
SENTRY_PROJECT	Sentry 项目标识	用于源代码映射
SENTRY_AUTH_TOKEN	CI/CD 身份验证令牌	用于源代码映射
NEXT_PUBLIC_SENTRY_SKIP_BUILD	构建时跳过 Sentry webpack 插件	容器构建

切勿提交 DSN 或身份验证令牌。请使用环境变量或机密管理工具。

如需查看详细的配置检查表、初始化模板和 CI/CD 工作流示例，请参阅 REFERENCE.md。

Agent 优化

场景	命令
快速合规性检查	/configure:sentry --check-only
自动修复所有问题	/configure:sentry --fix
仅限前端项目	/configure:sentry --type frontend
Next.js 项目	/configure:sentry --type nextjs
仅限 Python 项目	/configure:sentry --type python
仅限 Node.js 项目	/configure:sentry --type node
检查是否存在硬编码的 DSN	rg -l 'https://[a-f0-9]*@.*sentry\.io' --type-not env

错误处理

• 没有 Sentry SDK：提供为项目类型安装合适 SDK 的选项
• 硬编码的 DSN：报告为 FAIL，并提供使用环境变量引用进行修复的选项
• DSN 格式无效：报告错误，并提供 DSN 格式说明
• 缺少 Sentry 项目：报告警告，并提供设置说明

另请参阅

• /configure:instrumentation - 完整的可观测性技术栈（OTel 跟踪/指标、结构化日志）；将 Sentry 相关缺失项交由此技能处理
• /configure:all - 运行所有合规性检查
• /configure:status - 快速查看合规性概况
• /configure:workflows - GitHub Actions 集成
• typescript-plugin:typescript-sentry - Bun/Node.js/Next.js 日常 Sentry SDK 使用（跨度、面包屑、定时任务监控、回放）
• sentry MCP 服务 - 用于项目验证的 Sentry API 访问