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> - 組織スラッグ（短縮 ID の場合）
• --json - 生の JSON を出力します

出力内容：

• タイトル、原因箇所、ステータス、レベル
• 初回／最終確認時刻
• イベント数とユーザーへの影響
• タグと環境情報
• --latest 指定時：スタックトレース、リクエストの詳細、ブレッドクラム、ランタイムコンテキスト

---

イベントの取得

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

ID を指定して、特定のイベントの詳細をすべて取得します。

オプション：

• --org, -o <org> - 組織スラッグ（必須）
• --project, -p <project> - プロジェクトスラッグ（必須）
• --breadcrumbs, -b - すべてのブレッドクラムを表示します（デフォルトでは直近の 30 件）
• --spans - トランザクションのスパンツリーを表示します
• --json - 生の JSON を出力します

出力内容：

• タイムスタンプ、プロジェクト、タイトル、メッセージ
• すべてのタグ
• コンテキスト（ランタイム、ブラウザー、OS、トレース情報）
• リクエストの詳細
• スタックトレース付きの例外
• ブレッドクラム
• スパン（--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> - 組織スラッグ（必須）
• --project, -p <project> - プロジェクトスラッグまたは 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> - 組織スラッグ（必須）
• --project, -p <project> - プロジェクトスラッグ（繰り返し指定可能）
• --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> - 組織スラッグ（URL を指定しない場合は必須）
• --project, -p <project> - プロジェクトスラッグまたは 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 のようなカスタムタグは、イベントを関連付けるのに役立ちます