home / skills / mitsuhiko / agent-stuff / sentry

sentry skill

safe

This skill helps you debug Sentry issues by fetching and analyzing errors, events, and logs for rapid root-cause insight.

npx playbooks add skill mitsuhiko/agent-stuff --skill sentry

Review the files below or copy the command above to add this skill to your agents.

Files (7)

SKILL.md

7.0 KB

---
name: sentry
description: "Fetch and analyze Sentry issues, events, transactions, and logs. Helps agents debug errors, find root causes, and understand what happened at specific times."
---

# Sentry Skill

Access Sentry data via the API for debugging and investigation. Uses auth token from `~/.sentryclirc`.

## 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"` |

## 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:[email protected]    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

Overview

This skill fetches and analyzes Sentry issues, events, transactions, and logs to speed up debugging and incident investigation. It uses your Sentry API credentials (from ~/.sentryclirc) to query Discover, Issue, Event, and Logs Explorer endpoints. The skill helps find root causes, reproduce timelines, and surface relevant metadata like stack traces, breadcrumbs, and tags.

How this skill works

The skill issues API calls to search events, list grouped issues, fetch full event payloads, and query logs. It can filter by time range, level, tags, transaction name, project, and organization, and it can return raw JSON or parsed summaries. For events and issues it can include the latest event, full stack traces, breadcrumbs, request context, and spans for transaction traces.

When to use it

Investigating what broke at a specific timestamp or during a deployment window
Listing unresolved or high-frequency issues affecting users
Drilling into a single issue or event to get stack traces and breadcrumbs
Searching logs for correlated messages, trace IDs, or error patterns
Filtering events by custom tags (user_id, thread_id, request_id) to correlate across systems

Best practices

Start broad with a time range and level filters, then narrow using tags, transactions, or query terms
Use list-issues sorted by frequency to prioritize high-impact problems
Fetch the latest event for an issue to get the most complete stack trace and request context
Include breadcrumbs and spans when available to reconstruct the execution path
Correlate events by trace ID or transaction name before assuming a single root cause

Example use cases

Find all errors in a two-hour window around an incident and list related transactions
List unresolved issues from the last 24 hours and sort by frequency to triage priorities
Fetch a specific issue with the latest event to inspect the stack trace, request payload, and breadcrumbs
Search logs for messages containing a timeout or specific trace ID to link logs to Sentry events
Query events by custom tag (e.g., thread_id:th_abc123) to find all related failures

FAQ

What credentials does this skill use?

It uses the Sentry auth token configured in ~/.sentryclirc to authenticate API requests.

Can I get raw JSON output?

Yes. Most commands support a --json option to return raw Sentry API responses for further processing.