Sentry

Sentry

Pull Sentry data for debugging via the Sentry API. Auth comes from ~/.sentryclirc.

Auth setup

Scripts read the auth token from ~/.sentryclirc. If the file is missing or the token is missing/stale:

sentry-cli login

Or write the file by hand:

[auth]
token=sntryu_<your-token>

Tokens come from https://sentry.io/settings/account/api/auth-tokens/ — needs at least event:read, project:read, org:read.

Quick reference

All scripts live under ./scripts/ relative to this skill folder.

Common workflows

"What went wrong at this time?"

# All events in a 2-hour window
./scripts/search-events.js --org myorg --project backend \
    --start 2026-05-07T15:00:00 --end 2026-05-07T17:00:00

# Just errors in that window
./scripts/search-events.js --org myorg --start 2026-05-07T15:00:00 --level error

# A specific transaction
./scripts/search-events.js --org myorg --start 2026-05-07T15:00:00 \
    --transaction process-incoming-email

"What's broken in production right now?"

# Unresolved errors in the last 24h
./scripts/list-issues.js --org myorg --status unresolved --level error --period 24h

# High-frequency issues (most events)
./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

"Drill into a specific issue or event"

# Issue with the latest event (stack trace, breadcrumbs)
./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

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

"Find by tag"

# Custom tag (thread_id, request_id, user_id)
./scripts/search-events.js --org myorg --tag thread_id:th_abc123

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

# By trace ID (links errors that share a request)
./scripts/search-events.js --org myorg --query "trace:abc123def456"

Script reference

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

Get a grouped issue. Accepts numeric ID, full URL, or short ID like MYPROJ-123 (with --org).

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

Full details of a single event.

search-events.js [options]

Search via Sentry Discover.

Time range:

• --period 24h / 7d / 14d (relative)
• --start <ISO> / --end <ISO> (absolute)

Filters:

• --org, --project
• --query <discover-query> (raw Discover syntax)
• --transaction <name> (filter by transaction name)
• --tag <key:value> (repeatable)
• --level error|warning|info
• --limit <n> (default 25, max 100)
• --fields <a,b,c> (which fields to include)

Discover query examples:

transaction:process-*           wildcard match
level:error                     level filter
user.email:foo@bar.com          user filter
environment:production          environment
has:stack.filename              has stack trace

list-issues.js [options]

List grouped issues.

Issue query examples:

is:unresolved
is:assigned / assigned:me
firstSeen:+7d / lastSeen:-24h
times_seen:>100
has:user
error.handled:0                 unhandled only

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

Search Sentry's Logs Explorer.

Log query examples:

level:error
message:*timeout*
trace:abc123
project:my-project

Also accepts a Sentry Logs Explorer URL directly:

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

Debugging tips

1. Start broad, then narrow. Use search-events.js with a time range first; drill into specific events with fetch-event.js.
2. Breadcrumbs are gold. fetch-event.js --breadcrumbs shows the chain of actions before an error. Often the actual cause is 3-5 breadcrumbs back.
3. Sort by frequency. list-issues.js --sort freq surfaces the issues that actually matter at scale.
4. Trace ID links cross-service errors. If a downstream API failure surfaces in two services, both events share a trace tag. Search by it.
5. Custom tags > tribal knowledge. If your codebase tags events with request_id, thread_id, tenant_id, use them. They're the only way to correlate without trace context.

Adapted from

• mitsuhiko/agent-stuff