cli-sentry

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sentry CLI Issue Management

Sentry CLI 问题管理

Compatibility: This skill is compatible with
sentry-cli
v3 only.
兼容性:此技能仅兼容
sentry-cli
v3。

Overview

概述

Expert guidance for managing Sentry issues via the CLI and API. Use this skill for fetching, triaging, categorizing, and resolving Sentry issues.
Key capabilities:
  • Preflight validation of sentry-cli installation and auth
  • List and filter issues by status, time period, and query
  • Categorize issues (Valid, False Positive, Already Resolved, Third Party)
  • Resolve, mute, and unresolve issues (individually or in bulk)
通过CLI和API管理Sentry问题的专业指南。使用此技能来获取、分类、归类和解决Sentry问题。
核心功能:
  • sentry-cli安装和身份验证的预检查验证
  • 按状态、时间段和查询条件列出和筛选问题
  • 归类问题(有效问题、误报、已解决、第三方问题)
  • 解决、静音和取消解决问题(单个或批量操作)

Safety Rules

安全规则

Prohibited operations:
  • DELETE /issues/{id}/
    - Issue deletion (irreversible)
  • Project or release deletion
  • Bulk status changes without explicit user confirmation
  • Modifying alert rules, notification settings, or project configuration
Allowed operations:
  • Listing and viewing issues (read-only)
  • Resolving issues (reversible via unresolve)
  • Muting/ignoring issues (reversible via unmute)
  • Fetching event details and stack traces
禁止操作:
  • DELETE /issues/{id}/
    - 删除问题(不可恢复)
  • 删除项目或版本
  • 未经用户明确确认的批量状态更改
  • 修改警报规则、通知设置或项目配置
允许操作:
  • 列出和查看问题(只读)
  • 解决问题(可通过取消解决恢复)
  • 静音/忽略问题(可通过取消静音恢复)
  • 获取事件详情和堆栈追踪

Prerequisites

前置条件

Required Environment Variables

必需的环境变量

The following env vars must be set before running any Sentry operations. Add them to your project's
.envrc
:
bash
export SENTRY_AUTH_TOKEN=sntrys_...
export SENTRY_ORG=<your-org-slug>
export SENTRY_PROJECT=<your-project-slug>
These are the native sentry-cli env var names. The CLI reads them automatically, so setting them in
.envrc
(and running
direnv allow
) means you don't need to pass
--org
,
--project
, or
--auth-token
flags.
在运行任何Sentry操作之前,必须设置以下环境变量。将它们添加到项目的
.envrc
中:
bash
export SENTRY_AUTH_TOKEN=sntrys_...
export SENTRY_ORG=<your-org-slug>
export SENTRY_PROJECT=<your-project-slug>
这些是原生sentry-cli的环境变量名称。CLI会自动读取它们,因此在
.envrc
中设置(并运行
direnv allow
)后,无需传递
--org
--project
--auth-token
参数。

Preflight Check

预检查

Run the preflight check before any Sentry operations:
bash
bash scripts/check-sentry.sh -v
This validates env vars, sentry-cli installation, and authentication.
在执行任何Sentry操作之前运行预检查:
bash
bash scripts/check-sentry.sh -v
这将验证环境变量、sentry-cli安装和身份验证状态。

Configuration Resolution Order

配置解析顺序

Settings resolve in this order (first wins):
  1. CLI flags (
    --org
    ,
    --project
    ,
    --auth-token
    )
  2. Environment variables (
    SENTRY_ORG
    ,
    SENTRY_PROJECT
    ,
    SENTRY_AUTH_TOKEN
    )
  3. .sentryclirc
    file (project root or
    ~/.sentryclirc
    )
设置按以下顺序生效(优先级从高到低):
  1. CLI参数(
    --org
    --project
    --auth-token
  2. 环境变量(
    SENTRY_ORG
    SENTRY_PROJECT
    SENTRY_AUTH_TOKEN
  3. .sentryclirc
    文件(项目根目录或
    ~/.sentryclirc

Issue Management

问题管理

List Issues (CLI)

列出问题(CLI)

bash
undefined
bash
undefined

List unresolved issues

列出未解决的问题

sentry-cli issues list --project <project>
sentry-cli issues list --project <project>

List with status filter

按状态筛选列出

sentry-cli issues list --project <project> --status unresolved
undefined
sentry-cli issues list --project <project> --status unresolved
undefined

List Issues (API - Richer Data)

列出问题(API - 更丰富的数据)

Use
scripts/fetch-issues.sh
for triage-quality JSON with metadata, culprit, event counts, and timestamps:
bash
bash scripts/fetch-issues.sh --org=<org> --project=<project>
bash scripts/fetch-issues.sh --org=<org> --project=<project> --stats-period=7d --limit=50
使用
scripts/fetch-issues.sh
获取包含元数据、问题根源、事件计数和时间戳的可用于分类的JSON数据:
bash
bash scripts/fetch-issues.sh --org=<org> --project=<project>
bash scripts/fetch-issues.sh --org=<org> --project=<project> --stats-period=7d --limit=50

Get Issue Details (API)

获取问题详情(API)

bash
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/issues/{issue_id}/" | jq
bash
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/issues/{issue_id}/" | jq

Get Latest Event / Stack Trace (API)

获取最新事件/堆栈追踪(API)

bash
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/issues/{issue_id}/events/latest/" | jq '.exception'
bash
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/issues/{issue_id}/events/latest/" | jq '.exception'

Resolve / Mute / Unresolve (CLI)

解决/静音/取消解决(CLI)

bash
undefined
bash
undefined

Resolve

解决

sentry-cli issues resolve --project <project> -i <issue_id>
sentry-cli issues resolve --project <project> -i <issue_id>

Mute (ignore)

静音(忽略)

sentry-cli issues mute --project <project> -i <issue_id>
sentry-cli issues mute --project <project> -i <issue_id>

Unresolve

取消解决

sentry-cli issues unresolve --project <project> -i <issue_id>
undefined
sentry-cli issues unresolve --project <project> -i <issue_id>
undefined

Issue Categorization

问题归类

Categorize each issue into one of four categories:
将每个问题归类为以下四类之一:

1. Valid

1. 有效问题

Genuine application errors requiring investigation and fixes.
Indicators:
  • Stack trace points to application code (
    src/
    ,
    app/
    ,
    webpack://
    )
  • Error originates from application logic, not external code
  • Reproducible user-facing issues
  • API errors from application endpoints
需要调查和修复的真实应用程序错误。
判断指标:
  • 堆栈追踪指向应用程序代码(
    src/
    app/
    webpack://
  • 错误源自应用程序逻辑,而非外部代码
  • 可复现的用户端问题
  • 应用程序端点产生的API错误

2. False Positive

2. 误报

Errors that appear as issues but are not actual problems.
Indicators:
  • Network errors from user connectivity issues (timeouts, DNS failures)
  • Browser-specific quirks not affecting functionality
  • Expected errors (e.g., 401 for unauthenticated users, 404 for deleted resources)
  • Errors from automated bots/crawlers
看似问题但实际并非真正故障的错误。
判断指标:
  • 用户连接问题导致的网络错误(超时、DNS失败)
  • 不影响功能的浏览器特定异常
  • 预期内的错误(例如,未认证用户的401、资源已删除的404)
  • 自动化爬虫/机器人产生的错误

3. Already Resolved

3. 已解决

Issues that have been fixed in subsequent deployments.
Indicators:
  • Last seen date predates a known fix
  • No recent occurrences (check
    lastSeen
    field)
  • Related code has been refactored or removed
  • Issue matches a closed GitHub issue or merged PR
在后续部署中已修复的问题。
判断指标:
  • 最后出现时间早于已知修复版本的发布时间
  • 近期无出现记录(查看
    lastSeen
    字段)
  • 相关代码已被重构或移除
  • 问题与已关闭的GitHub议题或合并的PR匹配

4. Third Party

4. 第三方问题

Errors originating from browser extensions or external scripts. See
references/extension-patterns.md
for comprehensive detection patterns.
Indicators:
  • Stack trace contains extension URLs (
    chrome-extension://
    ,
    moz-extension://
    , etc.)
  • Error from injected scripts (
    inpage.js
    ,
    content.js
    ,
    inject.js
    )
  • Known extension error messages (
    ResizeObserver loop
    ,
    Extension context invalidated
    )
  • Stack trace mentions known extensions (MetaMask, Grammarly, LastPass, etc.)
源自浏览器扩展或外部脚本的错误。查看
references/extension-patterns.md
获取全面的检测模式。
判断指标:
  • 堆栈追踪包含扩展URL(
    chrome-extension://
    moz-extension://
    等)
  • 注入脚本产生的错误(
    inpage.js
    content.js
    inject.js
  • 已知的扩展错误信息(
    ResizeObserver loop
    Extension context invalidated
  • 堆栈追踪提及已知扩展(MetaMask、Grammarly、LastPass等)

Triage Workflow

分类工作流

  1. Preflight - Run
    bash scripts/check-sentry.sh -v
    to verify sentry-cli and auth
  2. Fetch - Run
    bash scripts/fetch-issues.sh --org=<org> --project=<project>
    to get all unresolved issues
  3. Inspect - For each issue, fetch its latest event to examine the stack trace:
    bash
    curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
      "https://sentry.io/api/0/issues/{issue_id}/events/latest/" | jq '.exception.values[0].stacktrace.frames'
    Check
    culprit
    ,
    title
    ,
    metadata
    ,
    lastSeen
    , and event count
  4. Categorize - Assign each issue to Valid, False Positive, Already Resolved, or Third Party
  5. Present - Summarize in a triage report table:
markdown
undefined
  1. 预检查 - 运行
    bash scripts/check-sentry.sh -v
    验证sentry-cli和身份验证状态
  2. 获取问题 - 运行
    bash scripts/fetch-issues.sh --org=<org> --project=<project>
    获取所有未解决的问题
  3. 检查详情 - 针对每个问题,获取其最新事件以检查堆栈追踪:
    bash
    curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
      "https://sentry.io/api/0/issues/{issue_id}/events/latest/" | jq '.exception.values[0].stacktrace.frames'
    查看
    culprit
    title
    metadata
    lastSeen
    和事件计数
  4. 归类 - 将每个问题分配到有效问题、误报、已解决或第三方问题类别
  5. 呈现 - 在分类报告表格中汇总:
markdown
undefined

Sentry Issue Triage Report

Sentry问题分类报告

Valid (N issues)

有效问题(N个)

IssueTitleEventsLast Seen
PROJ-123TypeError in Component452h ago
问题标题事件数最后出现时间
PROJ-123组件中的TypeError452小时前

Third Party (N issues)

第三方问题(N个)

IssueTitleSourceEvents
PROJ-126ResizeObserver loopBrowser Extension234
问题标题来源事件数
PROJ-126ResizeObserver循环浏览器扩展234

False Positives (N issues)

误报(N个)

IssueTitleReason
PROJ-128Network ErrorUser connectivity
问题标题原因
PROJ-128网络错误用户连接问题

Already Resolved (N issues)

已解决(N个)

IssueTitleLast SeenNotes
PROJ-130Hydration mismatch14d agoFixed in v2.3.1
undefined
问题标题最后出现时间备注
PROJ-130Hydration不匹配14天前在v2.3.1中修复
undefined

Bulk Actions

批量操作

After triage, resolve or mute issues in bulk. Always confirm with the user before executing.
bash
undefined
分类完成后,批量解决或静音问题。执行前务必获得用户确认。
bash
undefined

Bulk resolve via API

通过API批量解决

curl -X PUT -H "Authorization: Bearer $SENTRY_AUTH_TOKEN"
-H "Content-Type: application/json"
-d '{"status": "resolved"}'
"https://sentry.io/api/0/projects/{org}/{project}/issues/?id=123&id=456&id=789"
curl -X PUT -H "Authorization: Bearer $SENTRY_AUTH_TOKEN"
-H "Content-Type: application/json"
-d '{"status": "resolved"}'
"https://sentry.io/api/0/projects/{org}/{project}/issues/?id=123&id=456&id=789"

Bulk ignore/mute via API

通过API批量忽略/静音

curl -X PUT -H "Authorization: Bearer $SENTRY_AUTH_TOKEN"
-H "Content-Type: application/json"
-d '{"status": "ignored"}'
"https://sentry.io/api/0/projects/{org}/{project}/issues/?id=123&id=456&id=789"
undefined
curl -X PUT -H "Authorization: Bearer $SENTRY_AUTH_TOKEN"
-H "Content-Type: application/json"
-d '{"status": "ignored"}'
"https://sentry.io/api/0/projects/{org}/{project}/issues/?id=123&id=456&id=789"
undefined

Quick Reference

快速参考

OperationMethodCommand / Endpoint
List issuesCLI
sentry-cli issues list --project <p>
List issues (rich)Script
scripts/fetch-issues.sh --org=<o> --project=<p>
Issue detailsAPI
GET /issues/{id}/
Latest eventAPI
GET /issues/{id}/events/latest/
Event listAPI
GET /issues/{id}/events/
ResolveCLI
sentry-cli issues resolve -i <id>
MuteCLI
sentry-cli issues mute -i <id>
UnresolveCLI
sentry-cli issues unresolve -i <id>
Bulk updateAPI
PUT /projects/{org}/{project}/issues/?id=...
操作方式命令/端点
列出问题CLI
sentry-cli issues list --project <p>
列出问题(丰富数据)脚本
scripts/fetch-issues.sh --org=<o> --project=<p>
获取问题详情API
GET /issues/{id}/
获取最新事件API
GET /issues/{id}/events/latest/
列出事件API
GET /issues/{id}/events/
解决问题CLI
sentry-cli issues resolve -i <id>
静音问题CLI
sentry-cli issues mute -i <id>
取消解决CLI
sentry-cli issues unresolve -i <id>
批量更新API
PUT /projects/{org}/{project}/issues/?id=...

Additional Resources

额外资源

  • scripts/check-sentry.sh
    - Preflight validation (installation, responsiveness, auth)
  • scripts/fetch-issues.sh
    - Fetch unresolved issues with rich JSON
  • references/api-fallbacks.md
    - API endpoints for operations sentry-cli can't handle
  • references/extension-patterns.md
    - Browser extension error detection patterns
  • scripts/check-sentry.sh
    - 预检查验证(安装、响应性、身份验证)
  • scripts/fetch-issues.sh
    - 获取包含丰富JSON数据的未解决问题
  • references/api-fallbacks.md
    - sentry-cli无法处理的操作对应的API端点
  • references/extension-patterns.md
    - 浏览器扩展错误检测模式

Tips

提示

  1. Run
    sentry-cli info
    to verify configuration and auth status from any source
  2. Pipe API responses through
    jq
    for readable output:
    ... | jq '.[] | {shortId, title, count, lastSeen}'
  3. Triage Third Party issues first - they are the easiest to identify and often the most numerous
  4. Check
    references/extension-patterns.md
    before categorizing ambiguous stack traces
  1. 运行
    sentry-cli info
    可从任意来源验证配置和身份验证状态
  2. 将API响应通过
    jq
    管道处理以获得易读输出:
    ... | jq '.[] | {shortId, title, count, lastSeen}'
  3. 先处理第三方问题 - 它们最容易识别,且通常数量最多
  4. 对模糊的堆栈追踪进行归类前,请查看
    references/extension-patterns.md