sentry-monitoring

模式：认知/提示词驱动——没有独立的实用脚本；通过 Agent 上下文使用。

Sentry 监控技能

概述

与直接调用 Sentry API 相比，可节省 90% 以上的上下文。按功能类别逐步披露：错误跟踪、性能监控、版本管理和项目配置。

要求

• 已配置项目的 Sentry 账户
• SENTRY_AUTH_TOKEN 环境变量（可选，用于经过身份验证的 API 调用）
• SENTRY_ORG 环境变量（可选，默认为第一个组织）
• SENTRY_PROJECT 环境变量（可选，默认为第一个项目）

工具（逐步披露）

错误跟踪

工具	描述	是否需要确认
list-issues	列出最近的问题/错误	否
issue-details	获取详细的问题信息	否
resolve-issue	将问题标记为已解决	是
ignore-issue	忽略/暂缓处理问题	是

性能监控

工具	描述	是否需要确认
list-transactions	列出性能事务	否
transaction-summary	获取事务性能统计信息	否
slow-queries	找出缓慢的数据库查询	否

版本管理

工具	描述	是否需要确认
list-releases	列出版本	否
create-release	创建新版本	是
set-commits	将提交与版本关联	是

项目配置

工具	描述	是否需要确认
list-projects	列出 Sentry 项目	否
project-settings	查看项目设置	否
list-alerts	列出告警规则	否

快速参考

# List recent issues
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/$SENTRY_ORG/$SENTRY_PROJECT/issues/?query=is:unresolved"

# Get issue details
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/issues/{issue_id}/"

# Resolve issue
curl -X PUT -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/issues/{issue_id}/" \
  -d '{"status": "resolved"}'

# List transactions
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/events/?field=transaction"

# Create release
curl -X POST -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/releases/" \
  -d '{"version": "1.0.0", "projects": ["project-slug"]}'

# List projects
curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/projects/"

配置

环境变量

变量	必需	描述
SENTRY_AUTH_TOKEN	可选	用于 API 调用的 Sentry 身份验证令牌
SENTRY_ORG	可选	组织标识（默认为第一个组织）
SENTRY_PROJECT	可选	项目标识（默认为第一个项目）
SENTRY_DSN	否	用于 SDK 集成（此技能不会使用）

获取身份验证令牌

1. 前往 Sentry 设置 → 账户 → API → 身份验证令牌
2. 创建具有以下权限范围的新令牌：project:read、project:write、event:read
3. 将其设为环境变量：export SENTRY_AUTH_TOKEN=your_token_here

安全

⚠️ 切勿在输出中泄露身份验证令牌 ⚠️ 破坏性操作（resolve-issue、ignore-issue、create-release、set-commits）需要确认 ⚠️ 使用环境变量存储凭据，切勿硬编码

Agent 集成

• devops（主要）：生产监控、事件响应
• incident-responder（主要）：错误分诊、问题解决
• developer（次要）：调试、性能优化
• qa（次要）：测试环境监控

错误处理

如果工具执行失败：

1. 确认已设置 SENTRY_AUTH_TOKEN：echo $SENTRY_AUTH_TOKEN
2. 检查令牌权限是否包含所需权限范围
3. 确认组织和项目标识正确
4. 查看 Sentry API 速率限制（默认：每分钟 3000 个请求）

常见工作流

事件响应

1. list-issues - 获取最近未解决的错误
2. issue-details - 调查特定问题
3. resolve-issue - 修复部署后将问题标记为已解决

性能优化

1. list-transactions - 找出响应缓慢的端点
2. transaction-summary - 分析性能模式
3. slow-queries - 找出数据库瓶颈

发布管理

1. create-release - 创建新的发布版本
2. set-commits - 将提交关联到发布
3. list-releases - 跟踪发布状态

故障排查

问题	解决方案
401 Unauthorized	检查 SENTRY_AUTH_TOKEN 是否有效且未过期
403 Forbidden	确认令牌具有所需的作用域（project:read、project:write、event:read）
404 Not Found	确认 SENTRY_ORG 和 SENTRY_PROJECT 是正确的 slug
超出速率限制	等待 1 分钟，并降低请求频率

相关内容

• Sentry API 文档：https://docs.sentry.io/api/
• Sentry 错误跟踪：https://docs.sentry.io/product/issues/
• Sentry 性能：https://docs.sentry.io/product/performance/
• Sentry 发布：https://docs.sentry.io/product/releases/

记忆协议（强制）

开始前： 读取 .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设任务可能中断：如果没有记录在记忆中，就等于没有发生。

OpenTelemetry + Grafana 技术栈

使用 OTel 自动埋点，同时导出到 Sentry 和 Grafana：

import { NodeSDK } from '@opentelemetry/sdk-node';
import { SentrySpanProcessor } from '@sentry/opentelemetry';
const sdk = new NodeSDK({ spanProcessor: new SentrySpanProcessor() });
sdk.start();

持续性能剖析（Pyroscope）

# pyroscope.configure({ applicationName: 'api', serverAddress: 'http://pyroscope:4040' })

Grafana + Prometheus

services:
  prometheus: { image: prom/prometheus }
  grafana: { image: grafana/grafana }
  otel-collector: { image: otel/opentelemetry-collector-contrib }