sentry

# Sentry Skill Access Sentry data via the API for debugging and investigation. ## Authentication The skill supports multiple authentication methods (checked in order): ### Option 1: Environment Variables (recommended for CI/containers) ```bash export SENTRY_AUTH_TOKEN="your-token-here" export SENTRY_URL="https://de.sentry.io" # For EU region (optional) ``` ### Option 2: Config File (`~/.sentryclirc`) ```ini [auth] token=your-token-here url=https://de.sentry.io # For EU region (optional) ``` Create via `sentry-cli login` or manually. ### Token Permissions Create a token at https://sentry.io/settings/account/api/auth-tokens/ with scopes: - `project:read` - `event:read` - `org:read` ### Region Support The skill auto-detects the region from: 1. `SENTRY_URL` environment variable 2. `url=` in `~/.sentryclirc` 3. Region embedded in new-style tokens (`sntrys_...`) 4. Defaults to US (`sentry.io`) For EU: use `https://de.sentry.io` ## Quick Reference | Task | Command | |------|---------| | Find errors on a date | `search-events.js --org X --start 2025-12-23T15:00:00 --level error` | | List open issues | `list-issues.js --org X --status unresolved` | | Get issue details | `fetch-issue.js <issue-id-or-url> --latest` | | Get event details | `fetch-event.js <event-id> --org X --project Y` | | Search logs | `search-logs.js --org X --project Y "level:error"` | | List releases | `list-releases.js --org X [--env vercel-production] [--commit <sha>]` | ## Common Debugging Workflows ### "What went wrong at this time?" Find events around a specific timestamp: ```bash # 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 ``` ### "What errors have occurred recently?" ```bash # 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 details about a specific issue/event" ```bash # 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 events with a specific tag" ```bash # 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" ``` --- ## Fetch Issue ```bash ./scripts/fetch-issue.js <issue-id-or-url> [options] ``` Get details about a specific issue (grouped error). **Accepts:** - Issue ID: `5765604106` - Issue URL: `https://sentry.io/organizations/sentry/issues/5765604106/` - New URL format: `https://myorg.sentry.io/issues/5765604106/` - Short ID: `JAVASCRIPT-ABC` (requires `--org` flag) **Options:** - `--latest` - Include the latest event with full stack trace - `--org <org>` - Organization slug (for short IDs) - `--json` - Output raw JSON **Output includes:** - Title, culprit, status, level - First/last seen timestamps - Event count and user impact - Tags and environment info - With `--latest`: stack trace, request details, breadcrumbs, runtime context --- ## Fetch Event ```bash ./scripts/fetch-event.js <event-id> --org <org> --project <project> [options] ``` Get full details of a specific event by its ID. **Options:** - `--org, -o <org>` - Organization slug (required) - `--project, -p <project>` - Project slug (required) - `--breadcrumbs, -b` - Show all breadcrumbs (default: last 30) - `--spans` - Show span tree for transactions - `--json` - Output raw JSON **Output includes:** - Timestamp, project, title, message - All tags - Context (runtime, browser, OS, trace info) - Request details - Exception with stack trace - Breadcrumbs - Spans (with `--spans`) --- ## Search Events ```bash ./scripts/search-events.js [options] ``` Search for events (transactions, errors) using Sentry Discover. **Time Range Options:** - `--period, -t <period>` - Relative time (24h, 7d, 14d) - `--start <datetime>` - Start time (ISO 8601: 2025-12-23T15:00:00) - `--end <datetime>` - End time (ISO 8601) **Filter Options:** - `--org, -o <org>` - Organization slug (required) - `--project, -p <project>` - Project slug or ID - `--query, -q <query>` - Discover search query - `--transaction <name>` - Transaction name filter - `--tag <key:value>` - Tag filter (repeatable) - `--level <level>` - Level filter (error, warning, info) - `--limit, -n <n>` - Max results (default: 25, max: 100) - `--fields <fields>` - Comma-separated fields to include **Query Syntax:** ``` transaction:process-* Wildcard transaction match level:error Filter by level user.email:foo@bar.com Filter by user environment:production Filter by environment has:stack.filename Has stack trace ``` --- ## List Issues ```bash ./scripts/list-issues.js [options] ``` List and search issues (grouped errors) in a project. **Options:** - `--org, -o <org>` - Organization slug (required) - `--project, -p <project>` - Project slug (repeatable) - `--query, -q <query>` - Issue search query - `--status <status>` - unresolved, resolved, ignored - `--level <level>` - error, warning, info, fatal - `--period, -t <period>` - Time period (default: 14d) - `--limit, -n <n>` - Max results (default: 25) - `--sort <sort>` - date, new, priority, freq, user - `--json` - Output raw JSON **Query Syntax:** ``` 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 ``` --- ## Search Logs ```bash ./scripts/search-logs.js [query|url] [options] ``` Search for logs in Sentry's Logs Explorer. **Options:** - `--org, -o <org>` - Organization slug (required unless URL provided) - `--project, -p <project>` - Filter by project slug or ID - `--period, -t <period>` - Time period (default: 24h) - `--limit, -n <n>` - Max results (default: 100, max: 1000) - `--json` - Output raw JSON **Query Syntax:** ``` 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 ``` **Accepts Sentry URLs:** ```bash ./scripts/search-logs.js "https://myorg.sentry.io/explore/logs/?project=123&statsPeriod=7d" ``` --- ## Tips for Debugging 1. **Start broad, then narrow down**: Use `search-events.js` with a time range first, then drill into specific events 2. **Use breadcrumbs**: The `--breadcrumbs` flag on `fetch-event.js` shows the full history of what happened before an error 3. **Look for patterns**: Use `list-issues.js --sort freq` to find frequently occurring problems 4. **Check related events**: If you find one event, look for others with the same transaction name or trace ID 5. **Tags are your friend**: Custom tags like `thread_id`, `user_id`, `request_id` help correlate events