> ## Documentation Index
> Fetch the complete documentation index at: https://opensre.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sentry

> Connect Sentry so OpenSRE can surface error trends and issue details as evidence

## Overview

OpenSRE queries Sentry for recent issues, error events, and stack traces so
the agent can correlate application errors with infrastructure alerts.

This page covers the **REST Sentry integration**. For the broader MCP surface
(Seer, traces, replays, and more), see [Sentry (MCP)](https://opensre.com/docs/integrations/incidents/sentry-mcp.md).

## Prerequisites

* Sentry account with at least one organization
* Auth token with `event:read` scope (Issues lookup)
* For uptime watching: also `alerts:read` (or `org:read`) so
  `opensre sentry uptime` can list monitors

## Setup

### Option 1: Interactive CLI

```bash theme={null}
opensre integrations setup sentry
```

Provide your organization slug and auth token when prompted.

### Option 2: Environment variables

```bash theme={null}
SENTRY_ORG_SLUG=your-organization-slug
SENTRY_AUTH_TOKEN=sntrys_your_token
SENTRY_URL=https://sentry.io           # optional, for self-hosted Sentry
SENTRY_PROJECT_SLUG=my-project         # optional, to scope to one project
SENTRY_STATS_PERIOD=24h                # optional, issue search time window
```

| Variable | Default | Description |
| - | - | - |
| `SENTRY_ORG_SLUG` | — | **Required.** Your Sentry organization slug |
| `SENTRY_AUTH_TOKEN` | — | **Required.** Auth token with `event:read` (add `alerts:read` for uptime watch) |
| `SENTRY_URL` | `https://sentry.io` | Override for self-hosted Sentry |
| `SENTRY_PROJECT_SLUG` | — | Scope queries to a specific project |
| `SENTRY_STATS_PERIOD` | `24h` | Time window for issue searches (for example `24h`, `14d`, `90d`) |

> [!NOTE]
>
> A search returns up to 100 issues per query (Sentry's maximum page size) within
> the `SENTRY_STATS_PERIOD` window. Widen the window (for example
> `SENTRY_STATS_PERIOD=14d`) to surface older issues. If you expect more issues
> than appear, the cause is usually the time window or a `SENTRY_PROJECT_SLUG`
> scope — not a hard cap of one page forever.

### Option 3: Persistent store

```json theme={null}
{
  "version": 1,
  "integrations": [
    {
      "id": "sentry-prod",
      "service": "sentry",
      "status": "active",
      "credentials": {
        "base_url": "https://sentry.io",
        "organization_slug": "your-org",
        "auth_token": "sntrys_your_token",
        "project_slug": "my-project"
      }
    }
  ]
}
```

## Credentials

**Recommended: Organization Token**

1. In Sentry, go to **Settings** → **Developer Settings** → **Organization Tokens**
2. Click **Create New Token**
3. Enable the `event:read` scope (and `alerts:read` if you use uptime watch)
4. Copy the token

**Alternative: Internal Integration**

For broader access, create an Internal Integration under **Settings** →
**Developer Settings** → **Internal Integrations**.

> [!NOTE]
>
> The organization slug appears in your Sentry URL:
> `https://sentry.io/organizations/<slug>/`

## Tools

| Tool | What it does |
| - | - |
| `search_sentry_issues` | Search issues in the configured org / project window |
| `get_sentry_issue_details` | Fetch details for one issue |
| `list_sentry_issue_events` | List error events for an issue |
| `list_sentry_uptime_alerts` | List uptime monitor health |
| `get_sentry_uptime_digest` | Roll up recent DOWN / RECOVERED transitions for digests |

## Verify

```bash theme={null}
opensre integrations verify sentry
```

Expected output:

```
Service: sentry
Status: passed
Detail: Sentry validated for org your-org; 30 issue(s) in the last 7 days.
```

The count reflects issues seen in the last 7 days (capped at 100, shown as
`100+` when it saturates). Use `search_sentry_issues` when investigating an
issue to enumerate issues over a custom window.

## Troubleshooting

| Symptom | Fix |
| - | - |
| **403 Forbidden** | Ensure the token has `event:read`; for uptime watch also `alerts:read` |
| **Organization not found** | Verify `SENTRY_ORG_SLUG` matches the slug in your Sentry URL |
| **Connection refused** | Check `SENTRY_URL` for self-hosted instances |
| **No issues returned** | Normal if none exist in the time window — check `SENTRY_PROJECT_SLUG` |
| **Fewer issues than the Sentry UI shows** | Widen `SENTRY_STATS_PERIOD` (for example `14d`) and confirm project scope |

## Security

* Use an **Organization Token** with only `event:read` (plus `alerts:read` if needed) — not an admin token.
* Store the token in `.env` or your secret manager — not in source control.
* Rotate tokens periodically.

## Extras

### Morning digest (scheduled)

Deliver a daily unresolved-issues summary to Slack, Telegram, or Rocket.Chat.
This uses the headless **summarizing-sentry-issues** skill path (tools + LLM via the
gateway), not generic `opensre cron` kinds.
When an uptime watch schedule is running, the skill also calls
`get_sentry_uptime_digest` to include downtime/recovery context.

| Command | What it does |
| - | - |
| `/sentry digest schedule add …` | Same as CLI — schedule from the REPL |
| `opensre sentry digest run` | Run once and print the digest to stdout |
| `opensre sentry digest schedule add` | Schedule daily delivery (cron + provider + chat) |
| `opensre sentry digest schedule list` | List Sentry digest schedules |
| `opensre sentry digest schedule run TASK_ID` | Run a scheduled digest immediately |
| `opensre sentry digest schedule remove TASK_ID` | Remove a schedule |

Example — weekdays at 08:00 London time to Telegram:

```bash theme={null}
opensre sentry digest schedule add \
  --cron "0 8 * * mon-fri" \
  --tz Europe/London \
  --provider telegram \
  --chat-id "-1001234567890"
```

Example — Slack channel (`C…` member/channel id):

```bash theme={null}
opensre sentry digest schedule add \
  --cron "0 8 * * mon-fri" \
  --tz Europe/London \
  --provider slack \
  --chat-id C0123ABCD
```

Example — Rocket.Chat (requires token credentials — see
[Rocket.Chat](https://opensre.com/docs/integrations/messaging/rocketchat.md); an incoming webhook alone cannot target
an explicit `--chat-id`):

```bash theme={null}
opensre sentry digest schedule add \
  --cron "0 8 * * mon-fri" \
  --tz Europe/London \
  --provider rocketchat \
  --chat-id "#alerts"
```

Optional `--project my-service` scopes the digest to one Sentry project.

When an **uptime watch** schedule is running, the digest includes an
**Uptime / downtime (last 24h)** section. If no uptime watch history exists,
the digest stays Issues-only.

The gateway daemon picks up scheduled digests when it is running. If the LLM
is unavailable, the run fails with an error.

### Uptime watch (downtime notifications)

Poll Sentry **uptime monitors** (Alerts / Uptime — not the Issues digest) and
ping Slack, Telegram, or Rocket.Chat only when a monitor transitions to
**down** or **recovered**. Quiet polls deliver nothing.

| Command | What it does |
| - | - |
| `opensre sentry uptime check` | List current uptime monitor health once |
| `opensre sentry uptime watch add` | Schedule polling (default every 5 minutes) |
| `opensre sentry uptime watch list` | List uptime watch schedules |
| `opensre sentry uptime watch run TASK_ID` | Run a watch tick now (may notify) |
| `opensre sentry uptime watch remove TASK_ID` | Remove a watch schedule |

Example — poll every 5 minutes and ping Slack on transitions:

```bash theme={null}
opensre sentry uptime watch add \
  --cron "*/5 * * * *" \
  --tz UTC \
  --provider slack \
  --chat-id C0123ABCD
```

Requires `alerts:read` (or equivalent) on the Sentry token.
`list_sentry_uptime_alerts` exposes the same monitor list in chat.

Schedule an uptime watch alongside the morning digest so `summarizing-sentry-issues` can
include yesterday's downtime summary via `get_sentry_uptime_digest`.

Follow-ups (not in v1): inbound Sentry webhooks and auto-remediation attempts.

### Telemetry knobs (OpenSRE error reporting)

These control OpenSRE's own Sentry error reporting — separate from the Issues
integration above.

| Variable | Default | Description |
| - | - | - |
| `OPENSRE_SENTRY_DSN` | — | Override the bundled Sentry DSN |
| `OPENSRE_SENTRY_DISABLED` | `0` | Set to `1` to disable Sentry entirely |
| `OPENSRE_SENTRY_LOGGING_DISABLED` | `0` | Set to `1` to disable automatic forwarding of `logger.error` / `logger.exception` without affecting `capture_exception` |

Send one test event:

```bash theme={null}
opensre debug sentry
```

For a custom or self-hosted project:

```bash theme={null}
OPENSRE_SENTRY_DSN=https://public-key@example.ingest.sentry.io/123 opensre debug sentry
```

```text theme={null}
Sentry DSN host: example.ingest.sentry.io
Sentry event ID: <event-id>
Sentry flush sent: yes
```

The event is synthetic and tagged `debug=true`. If telemetry is disabled, the
command exits non-zero without sending anything.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.