Sentry

---
name: sentry
description: >
  Track external Sentry errors and issues, and route first-party captured
  errors to Agent-Native Analytics. Use this skill when the user asks about
  errors, exceptions, error trends, or application health.
---

# Sentry Integration

## Connection

- **Base URL**: `https://sentry.io/api/0`
- **Org slug**: discovered from the token's accessible organizations by default. Configure `SENTRY_ORG_SLUG` or pass `orgSlug` to the `sentry` action when a user needs a specific Sentry organization.
- **Auth**: `Authorization: Bearer $SENTRY_SERVER_TOKEN` (internal integration token, NOT user auth token or DSN)
- **Env vars**: `SENTRY_SERVER_TOKEN` (falls back to `SENTRY_AUTH_TOKEN`)
- **Caching**: 5-minute in-memory cache, max 100 entries
- **Scopes needed**: `alerts:read`, `event:read`, `org:read`, `project:distribution`, `project:read`, `team:read`

## Server Lib & API Routes

- **File**: `server/lib/sentry.ts`

### Exported Functions

| Function                                         | Description                              |
| ------------------------------------------------ | ---------------------------------------- |
| `listProjects()`                                 | List all projects in the org             |
| `listIssues(projectSlug?, query?, statsPeriod?)` | List issues (project-scoped or org-wide) |
| `getIssueEvents(issueId)`                        | Events for a specific issue              |
| `getOrganizationStats(statsPeriod?, category?)`  | Org-level error stats over time          |

### Agent Action

Use `sentry` for all agent-facing Sentry work. Do not call `/api/sentry/*`
directly from the agent.

| Mode            | Args                                         | Description                             |
| --------------- | -------------------------------------------- | --------------------------------------- |
| `organizations` |                                              | List organizations visible to the token |
| `issues`        | `statsPeriod`, `project`, `query`, `orgSlug` | Frequent issues, sorted by frequency    |
| `projects`      | `orgSlug`                                    | List projects                           |
| `issue-events`  | `issueId`, `orgSlug`                         | Events for a specific issue             |
| `stats`         | `statsPeriod`, `category`, `orgSlug`         | Org-level stats                         |

### API Routes

| Route                          | Description         |
| ------------------------------ | ------------------- |
| `GET /api/sentry/projects`     | List projects       |
| `GET /api/sentry/issues`       | List issues         |
| `GET /api/sentry/issue-events` | Events for an issue |
| `GET /api/sentry/stats`        | Org error stats     |

### Dashboard

- `/adhoc/sentry` — Sentry Error Health dashboard

## First-party Agent-Native Analytics errors

Agent-Native Analytics has its own Sentry-style error store, separate from the
external Sentry connection. Browser `configureTracking()` and server
`captureError()` can both emit `$exception` events when their Analytics keys are
configured; Analytics groups them under Monitoring -> Errors without an
external Sentry credential.

Use these authenticated actions for first-party issues:

| Action | Purpose |
| --- | --- |
| `list-error-issues` | Find grouped captured issues, filtered by status or search. |
| `get-error-issue` | Read occurrences, stacks, tags, breadcrumbs, and replay links. |
| `resolve-error-issue` | Resolve, ignore, or reopen an issue after triage. |

Use `query-agent-native-analytics` only for bounded `analytics_events` or
`$ai_generation` correlation; it does not expose the `error_issues` or
`error_events` tables.

## Key Patterns & Gotchas

- Token type: This is a **custom/internal integration** token from Sentry's integration settings TOKEN table (not the Client Secret)
- `getOrganizationStats` uses `stats_v2` endpoint with `field=sum(quantity)`, `groupBy=outcome`, default category `error`
- If the default org is wrong, pass `orgSlug` explicitly in the action call.