tracer-cloud--opensre/docs/sentry.mdx

---
title: "Sentry"
description: "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
opensre integrations setup
```

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

### Option 2: Environment variables

Add to your `.env`:

```bash
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
{
  "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
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
opensre debug sentry
```

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

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

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