# Sentry

> Connect Sentry so issue and metric alerts open incidents in Ace, and Ace reads errors, releases, spans, logs and replays while it investigates.

Source: https://tryace.dev/docs/integrations/sentry

Sentry alerts open incidents in Ace, and Ace reads the errors behind them while it investigates. Repeated events of one Sentry issue land in the same incident, so a noisy error doesn't open a new incident each time it fires.

| | |
| --- | --- |
| Category | Errors |
| Ace reads | Unresolved issues, latest events, releases, Explore queries over errors, spans and logs, session replays, projects |
| Ace can change | Issue status and assignee, only after an admin allows it |
| Opens incidents | Yes, for workloads that route Sentry alerts |
| Setup | Settings form, plus a webhook on a Sentry internal integration |

## What Ace reads

Ace reads Sentry while it investigates a workload that lists Sentry under **Investigation sources** or routes its alerts. Every read covers the incident window and stays inside your project allowlist, if you set one.

- Unresolved issues in the window, most frequent first.
- The latest event of an issue. Ace gets exception types and messages, in-app stack frames, the release, and only these tags: `environment`, `release`, `transaction`, `url`, `server_name` and `runtime`.
- Recent releases, with dates and the number of new issues each one introduced.
- Explore table and aggregate queries over errors, spans and logs.
- Session replays with errors. Replays carry user identity, so Ace gets only the pages visited (without query strings), environment, browser, OS and error IDs.
- New events of the incident's issue after a fix, to confirm the errors stopped.

Ace also adds your Sentry projects to the System Map.

## What Ace can change

These writes change what your team sees in Sentry and never touch code or infrastructure. They need extra token permissions and run only after an admin turns on **Allow Ace to update this tool during incidents** for the connection, and from then on they run without an approval step.

| Action | When it runs | Undo |
| --- | --- | --- |
| Resolve issue | Ace resolves the incident's Sentry issues once it verifies the incident recovered. | Yes. Undo reopens the issue. |
| Assign issue | When an approved fix starts, Ace assigns the incident's Sentry issues to the approver, matched by email. | Yes |

Ace skips issues outside your project allowlist, and it leaves an issue alone if someone changed its status in the meantime, so it doesn't overwrite your team's triage. You undo each change from the incident. See [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals) for how actions work in general.

## What opens an incident

Sentry alerts open incidents only on workloads that route this connection (**Integration alerts** on, Sentry selected). Ace drops alerts that no workload routes.

| Sentry sends | What Ace does |
| --- | --- |
| An alert rule action (issue alert) | Opens or joins an incident for that Sentry issue. Fatal events are critical, errors high, warnings medium and anything else low. |
| Issue `created` or `unresolved` | Opens or joins an incident, but only for issues at level error or fatal. User feedback issues never open incidents. |
| Issue `resolved`, `ignored` or `archived` | Marks that issue resolved in Ace. An incident resolves once nothing in it is still firing. |
| Metric alert | Opens or joins an incident. A `critical` trigger is critical severity and anything else is high. A resolved metric alert resolves it. |

Ace ignores every other delivery, such as issue assignments.

Ace also polls Sentry for new unresolved issues at level error or fatal, so a missed webhook doesn't hide a new failure. Polling never opens incidents for warnings, info or user feedback.

## Before you start

- The **admin** role in Ace.
- The **Manager** or **Owner** role in your Sentry organization, to create an internal integration. Organization auth tokens can't read events, so use an internal integration.

## Credentials and permissions

Both credentials come from one Sentry internal integration. Leave every permission not listed here at No Access.

| Credential | Where to create it | Permissions | Why Ace needs it |
| --- | --- | --- | --- |
| Auth token (needed) | **Settings** > **Custom Integrations** > **Create New Integration** > **Internal Integration**, under **Tokens** | Project: Read, Release: Admin, Issue & Event: Read, Organization: Read (scopes `org:read`, `project:read`, `event:read`, `project:releases`) | Read issues, events, releases, Explore data and replays. Release: Admin is the only level that grants `project:releases`. |
| Auth token (only for issue updates) | Same integration | Issue & Event: Read & Write, Member: Read (`event:write`, `member:read`) | Resolve and reopen issues, and look up the approver to assign issues. |
| Client secret (only for alerts) | Same integration, under **Credentials** | None | Verifies that webhook deliveries come from Sentry. |

## Set up

### 1. Create the internal integration in Sentry

1. Go to **Settings** > **Custom Integrations** > **Create New Integration** > **Internal Integration**.
2. Name it Ace. Under **Permissions**, set Project: Read, Release: Admin, Issue & Event: Read and Organization: Read. For issue updates, set Issue & Event: Read & Write and Member: Read instead.
3. Select **Save Changes**, then copy the token under **Tokens** and the Client Secret under **Credentials** right away. Sentry shows the client secret only briefly after creation, and **Rotate client secret** issues a new one later.

### 2. Connect Sentry in Ace

1. Open **Settings** > **Data sources** and choose **Sentry**.
2. Fill in the form:

   | Field | What to enter |
   | --- | --- |
   | **Auth token** | The token from the internal integration. |
   | **Organization slug** | Your Sentry organization slug. |
   | **Sentry URL** | Optional. `https://de.sentry.io` for organizations hosted in the EU, or your self-hosted URL. Leave blank for `https://sentry.io`. |
   | **Projects** | Optional. A comma-separated allowlist of project slugs. |
   | **Client secret** | Optional. The client secret from the same integration. Ace needs it to verify alert webhooks. |

3. Select **Connect Sentry**. Ace checks the token before it saves.

A self-hosted Sentry URL must use HTTPS and be reachable from the public internet, because Ace doesn't connect to private or internal network addresses.

### 3. Send alerts to Ace

1. In the **Alerts** section, copy the webhook URL.
2. In Sentry, open the internal integration and paste it as the **Webhook URL**.
3. Turn on **Alert Rule Action**, subscribe to **issue**, and save.
4. In **Monitors** > **Alerts**, open or create each alert that should open incidents. Under **Then**, add the Ace integration.

### 4. Route alerts to a workload

Open the workload in Ace, turn on **Integration alerts**, and select Sentry as a source.

### 5. Optional: allow issue updates

If the token has the write permissions, turn on **Allow Ace to update this tool during incidents** on the connection.

## Confirm it's working

- The connection's checks read the organization and report how many projects the token sees. If the token can't see a project in your allowlist, the check names it.
- The **Alerts** badge shows **Not set up**, **Waiting for first event**, **Verified** or **Last delivery failed**. Send a test alert from Sentry, and the badge turns **Verified** when the first signed delivery arrives.
- A failed delivery shows the reason, such as a signature that doesn't match the saved client secret.
- **Re-validate** reruns the checks.

## Disconnect

1. In Ace, open the Sentry connection under **Settings** > **Data sources** and select **Disconnect**. To stop issue updates and keep the connection, turn off **Allow Ace to update this tool during incidents** instead.
2. In Sentry, delete the Ace internal integration or its token. Ace creates nothing else in Sentry.

## Next steps

- [How Ace works](https://tryace.dev/docs/concepts/how-ace-works)
- [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals)
- [All integrations](https://tryace.dev/docs/integrations)