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

# Sentry integration

> Connect Sentry so ewake can read the Sentry issue behind an alert, with its stack trace, tags and trace id.

> [!NOTE]
>
> **What you'll get:** when an alert or a message names a Sentry issue, ewake reads that issue and its event during the investigation, down to the stack trace, so it can find where the error occurs in your code. A Sentry alert can also push its issues straight to ewake, so each one starts an investigation.

***

## Prerequisites

* A Sentry organization on **sentry.io**. Self-hosted Sentry is not supported.
* A Sentry account that can create an internal integration in **Settings** → **Developer Settings** → **Custom Integrations**
* Access to your ewake dashboard

***

## Configuration

**1. Create an internal integration in Sentry**

In Sentry, go to **Settings** → **Developer Settings** → **Custom Integrations** and click **Create New Integration**. Pick **Internal Integration**, then click **Get started**.

Name it, for example `ewake`. Leave **Webhook URL** empty for now.

**2. Give it read access**

Under **Permissions**, set **Issue & Event** to **Read**. That is the only permission ewake needs.

Leave every webhook unticked, because Sentry asks for a Webhook URL as soon as you tick one. Click **Save Changes**.

> [!TIP]
>
> To also [send Sentry alerts to ewake](#send-sentry-alerts-to-ewake), copy the **Client Secret** under **Credentials** now. Sentry shows it only briefly after it creates the integration.

**3. Copy the token**

Copy the token of the internal integration.

**4. Connect in ewake**

In your ewake dashboard, go to **Integrations** and click the **Sentry** tile under **Add more**.

| Field | Value |
| - | - |
| **Organization slug** | The slug in your Sentry URL, e.g. `acme` in `https://acme.sentry.io` |
| **Auth token** | The token from Step 3 |

**5. Test and save**

Click **Test connection**. Ewake reads one issue of the organization and reports **Read issues and events** as granted or missing. If it is missing, check the **Issue & Event** permission and the organization slug. Then click **Save**.

> [!TIP]
>
> Sentry is connected. Ewake can now read Sentry issues during investigations.

***

## What ewake reads

Ewake reads a Sentry issue by its id, when an alert or a message names it.

| Read | What ewake gets |
| - | - |
| **The issue** | Title, culprit, level, status, priority, category, number of events, number of users affected, first and last release, project, and a link to the issue |
| **One event of the issue** | The event that fired the alert when the alert names it, else the latest event: its message, tags (such as `environment` and `release`), trace id, and the stack trace of each exception |

A stack trace keeps at most 20 frames for each exception: the frames in your application code nearest the crash, or the frames nearest the crash of any kind when none is in your code.

***

## Send Sentry alerts to ewake

Sentry can also be an alert source of the [on-call agent](https://docs.ewake.ai/working-with-ewake/on-call-agent.md). A Sentry alert pushes the issues it fires on to ewake, and each push can start an investigation. When you resolve the issue in Sentry, ewake marks its report resolved.

The Sentry integration has one webhook. You set it up **once**, and every On-Call flow of Sentry reads it, each by its own conditions.

**1. Open the webhook of the integration in ewake**

In your ewake dashboard, go to **Integrations** → **Sentry** → **Overview**. The **Webhook** section shows the **Webhook URL** and the steps below.

**2. Set up the internal integration**

In Sentry, open the internal integration again from **Settings** → **Developer Settings** → **Custom Integrations**:

* Paste the **Webhook URL** from ewake.
* Turn on **Alert Action**, so that a Sentry alert can send issues to ewake.
* Under **Webhooks**, in the **Issues** row, tick **Resolved** only.

Click **Save Changes**.

**3. Create a Sentry alert**

In Sentry, go to **Monitors** → **Alerts** and click **Create Alert**.

* Under **Source**, pick the projects that ewake should watch.
* Under **Filter Issues**, pick the environment that ewake should investigate, for example `production`. An alert takes one environment, so make one alert for each.
* Under **Alert Builder**, keep the triggers and add the action **Send a notification via an integration**. Pick the internal integration.

Click **Create Alert**.

**4. Paste the Client Secret in ewake**

In the **Webhook** section, paste the **Client Secret** of the internal integration and click **Set up the webhook**.

Ewake checks the signature of each push from Sentry with it. To change it later, paste the new one and click **Replace the Client Secret**.

> [!WARNING]
>
> Send each issue to ewake one way only: by a Sentry alert, or through a Slack channel that ewake reads. If both send it, ewake investigates it twice.

Then create an On-Call flow of Sentry, to choose which issues ewake investigates and how. See [On-call agent](https://docs.ewake.ai/working-with-ewake/on-call-agent.md).

***

> [!NOTE]
>
> Ewake uses **read-only** access. It reads issues and events, and never changes issues, alerts or settings in Sentry.


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