sentry

Sentry 技能

通过 API 访问 Sentry 数据，用于调试和调查。使用 ~/.sentryclirc 中的身份验证令牌。

快速参考

任务	命令
查找某个日期的错误	search-events.js --org X --start 2025-12-23T15:00:00 --level error
列出未解决的问题	list-issues.js --org X --status unresolved
获取问题详情	fetch-issue.js <issue-id-or-url> --latest
获取事件详情	fetch-event.js <event-id> --org X --project Y
搜索日志	search-logs.js --org X --project Y "level:error"

常见调试工作流

“这个时间发生了什么问题？”

查找特定时间戳附近的事件：

# Find all events in a 2-hour window
./scripts/search-events.js --org myorg --project backend \
  --start 2025-12-23T15:00:00 --end 2025-12-23T17:00:00

# Filter to just errors
./scripts/search-events.js --org myorg --start 2025-12-23T15:00:00 \
  --level error

# Find a specific transaction type
./scripts/search-events.js --org myorg --start 2025-12-23T15:00:00 \
  --transaction process-incoming-email

“最近发生了哪些错误？”

# List unresolved errors from last 24 hours
./scripts/list-issues.js --org myorg --status unresolved --level error --period 24h

# Find high-frequency issues
./scripts/list-issues.js --org myorg --query "times_seen:>50" --sort freq

# Issues affecting users
./scripts/list-issues.js --org myorg --query "is:unresolved has:user" --sort user

“获取特定问题／事件的详情”

# Get issue with latest stack trace
./scripts/fetch-issue.js 5765604106 --latest
./scripts/fetch-issue.js https://sentry.io/organizations/myorg/issues/123/ --latest
./scripts/fetch-issue.js MYPROJ-123 --org myorg --latest

# Get specific event with all breadcrumbs
./scripts/fetch-event.js abc123def456 --org myorg --project backend --breadcrumbs

“查找带有特定标签的事件”

# Find by custom tag (e.g., thread_id, user_id)
./scripts/search-events.js --org myorg --tag thread_id:th_abc123

# Find by user email
./scripts/search-events.js --org myorg --query "user.email:*@example.com"

---

获取问题

./scripts/fetch-issue.js <issue-id-or-url> [options]

获取特定问题（归类后的错误）的详情。

接受：

• 问题 ID：5765604106
• 问题 URL：https://sentry.io/organizations/sentry/issues/5765604106/
• 新版 URL 格式：https://myorg.sentry.io/issues/5765604106/
• 短 ID：JAVASCRIPT-ABC（需要 --org 标志）

选项：

• --latest - 包含最新事件及完整堆栈跟踪
• --org <org> - 组织 slug（用于短 ID）
• --json - 输出原始 JSON

输出包括：

• 标题、问题来源、状态、级别
• 首次／最后出现的时间戳
• 事件数量和用户影响
• 标签和环境信息
• 使用 --latest 时：堆栈跟踪、请求详情、面包屑、运行时上下文

---

获取事件

./scripts/fetch-event.js <event-id> --org <org> --project <project> [options]

根据事件 ID 获取特定事件的完整详情。

选项：

• --org, -o <org> - 组织 slug（必需）
• --project, -p <project> - 项目 slug（必需）
• --breadcrumbs, -b - 显示所有面包屑（默认：最近 30 条）
• --spans - 显示事务的跨度树
• --json - 输出原始 JSON

输出包括：

• 时间戳、项目、标题、消息
• 所有标签
• 上下文（运行时、浏览器、操作系统、跟踪信息）
• 请求详情
• 带堆栈跟踪的异常
• 面包屑
• 跨度（使用 --spans 时）

---

搜索事件

./scripts/search-events.js [options]

使用 Sentry Discover 搜索事件（事务、错误）。

时间范围选项：

• --period, -t <period> - 相对时间（24h、7d、14d）
• --start <datetime> - 开始时间（ISO 8601：2025-12-23T15:00:00）
• --end <datetime> - 结束时间（ISO 8601）

筛选选项：

• --org, -o <org> - 组织 slug（必需）
• --project, -p <project> - 项目 slug 或 ID
• --query, -q <query> - Discover 搜索查询
• --transaction <name> - 事务名称筛选条件
• --tag <key:value> - 标签筛选条件（可重复）
• --level <level> - 级别筛选条件（error、warning、info）
• --limit, -n <n> - 最大结果数（默认：25，最大：100）
• --fields <fields> - 以逗号分隔的要包含的字段

查询语法：

transaction:process-*     Wildcard transaction match
level:error               Filter by level
user.email:[email protected]    Filter by user
environment:production    Filter by environment
has:stack.filename        Has stack trace

---

列出问题

./scripts/list-issues.js [options]

列出并搜索项目中的问题（归类后的错误）。

选项：

• --org, -o <org> - 组织 slug（必需）
• --project, -p <project> - 项目 slug（可重复）
• --query, -q <query> - 问题搜索查询
• --status <status> - unresolved、resolved、ignored
• --level <level> - error、warning、info、fatal
• --period, -t <period> - 时间段（默认：14d）
• --limit, -n <n> - 最大结果数（默认：25）
• --sort <sort> - date、new、priority、freq、user
• --json - 输出原始 JSON

查询语法：

is:unresolved             Status filter
is:assigned               Has assignee
assigned:me               Assigned to current user
level:error               Level filter
firstSeen:+7d             First seen > 7 days ago
lastSeen:-24h             Last seen within 24h
times_seen:>100           Event count filter
has:user                  Has user context
error.handled:0           Unhandled errors only

---

搜索日志

./scripts/search-logs.js [query|url] [options]

在 Sentry 的 Logs Explorer 中搜索日志。

选项：

• --org, -o <org> - 组织 slug（除非提供 URL，否则必需）
• --project, -p <project> - 按项目 slug 或 ID 筛选
• --period, -t <period> - 时间段（默认：24h）
• --limit, -n <n> - 最大结果数（默认：100，最大：1000）
• --json - 输出原始 JSON

查询语法：

level:error              Filter by level (trace, debug, info, warn, error, fatal)
message:*timeout*        Search message text with wildcards
trace:abc123             Filter by trace ID
project:my-project       Filter by project slug

接受 Sentry URL：

./scripts/search-logs.js "https://myorg.sentry.io/explore/logs/?project=123&statsPeriod=7d"

---

调试技巧

1. 先从宽泛范围入手，再逐步缩小：先使用 search-events.js 配合时间范围进行搜索，然后深入查看具体事件

2. 利用面包屑：fetch-event.js 中的 --breadcrumbs 标志会显示错误发生前的完整历史记录

3. 寻找规律：使用 list-issues.js --sort freq 查找频繁出现的问题

4. 检查相关事件：如果找到一个事件，可以查找具有相同事务名称或跟踪 ID 的其他事件

5. 善用标签：thread_id、user_id、request_id 等自定义标签有助于关联事件