sentry

# 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.