> ## 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 during investigations

OpenSRE queries Sentry to retrieve recent issues, error events, and stack traces — correlating application errors with infrastructure alerts to identify root causes faster.

## Prerequisites

* Sentry account with at least one organization
* Auth token with `event:read` scope

## Setup

### Option 1: Interactive CLI

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

Select **Sentry** when prompted and provide your organization slug and auth token.

### Option 2: Environment variables

Add to your `.env`:

```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.** Sentry auth token with `event:read`         |
| `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 (e.g. `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 (e.g. `SENTRY_STATS_PERIOD=14d`)
  to surface older issues. If you expect more issues than appear, the cause is
  almost always the time window or a `SENTRY_PROJECT_SLUG` scope — not a cap of one.
</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"
      }
    }
  ]
}
```

## Creating an auth token

**Recommended: Organization Token**

1. In Sentry, go to **Settings** → **Developer Settings** → **Organization Tokens**
2. Click **Create New Token**
3. Enable the `event:read` scope
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>

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

<Note>
  The count reflects issues seen in the last 7 days (capped at 100, shown as
  `100+` when it saturates). Use a search (e.g. `search_sentry_issues` during an
  investigation) to enumerate the full issue set over a custom window.
</Note>

## Telemetry knobs

| 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` and `logger.exception` calls to Sentry as events, without affecting `capture_exception` |

## Verify Error Reporting

Send one test event to confirm OpenSRE can report runtime errors:

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

For a custom or self-hosted project, set the DSN first:

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

## Troubleshooting

| Symptom                                   | Fix                                                                                                             |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **403 Forbidden**                         | Ensure the token has `event:read` scope                                                                         |
| **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 no issues exist in the time window — check `SENTRY_PROJECT_SLUG`                                      |
| **Fewer issues than the Sentry UI shows** | Widen `SENTRY_STATS_PERIOD` (e.g. `14d`) and confirm the search isn't scoped to the wrong `SENTRY_PROJECT_SLUG` |

## Security best practices

* Use an **Organization Token** with only `event:read` — do not use admin tokens.
* Store the token in `.env`, not in source code.
* Rotate tokens periodically.