> ## 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)](/docs/integrations/incidents/sentry-mcp).

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

<Info>
  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.
</Info>

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

<Info>
  The organization slug appears in your Sentry URL:
  `https://sentry.io/organizations/<slug>/`
</Info>

## 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](/docs/integrations/messaging/rocketchat); 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.