# Sentry

[Sentry](https://sentry.io/welcome/) is an application monitoring platform that helps developers identify, debug, and resolve issues.

Integrating Sentry with Cortex allows you to:

* [View errors on entity pages in Cortex](#viewing-sentry-errors-on-an-entity), giving you insight into your entity's operational maturity
* [Pull a list of recent Sentry issues directly in Slack](#using-the-cortex-slack-bot-with-sentry), using the Cortex Slack Bot
* Create [Scorecards](#scorecards-and-cql) that include rules related to Sentry errors

## How to configure Sentry with Cortex

### Prerequisites

Before getting started:

* Create a [personal token](https://docs.sentry.io/api/auth/#user-authentication-tokens) in your Sentry user settings.
  * The token requires `Read` [permissions](https://docs.sentry.io/api/permissions/) for the **Issue & Event** and **Project** scopes.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Sentry settings page](https://app.getcortexapp.com/admin/integrations/sentry):
   * Click **Integrations** from the main nav. Search for and select **Sentry**.
2. Click **Add configuration**.
3. Configure the integration form:
   * **Auth token**: Enter the personal token you generated in Sentry.
   * **Organization slug**: Enter your Sentry organization slug.
     * You can find this in your Sentry URL, e.g., `https://sentry.io/organizations/{SLUG}/issues/`.
   * **Host**: If using a self-hosted Sentry instance, enter the URL here *without* the API path (e.g., `bugsnag.getcortexapp.com`).
4. Click **Save**.

After saving your configuration, you are redirected to the Sentry integration settings page in Cortex. In the upper right corner of the page, click **Test configuration** to ensure Sentry was configured properly.

## How to connect Cortex entities to Sentry projects

### Discovery

By default, Cortex will use the [Cortex tag](https://docs.cortex.io/entities#cortex-tag) (e.g., `my-entity`) as the best guess for Sentry projects. For example, if your Cortex tag is `my-entity`, then the corresponding project in Sentry should also be `my-entity`.

If your Sentry projects don't cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.

### Editing the entity descriptor

You can define projects under the `x-cortex-sentry` block:

```yaml
x-cortex-sentry:
  projects:
  - name: my-project
  - name: my-second-project
```

| Field  | Description                                                                          | Required |
| ------ | ------------------------------------------------------------------------------------ | :------: |
| `name` | <p>Project ID or slug defined in Sentry.</p><p>Note that this is case sensitive.</p> |   **✓**  |

## Using the Sentry integration

### Viewing Sentry errors on an entity

Error data will appear on an [entity's details page](https://docs.cortex.io/ingesting-data-into-cortex/entities/details). In an entity's sidebar, click **Error tracking** to view detected issues for each Sentry project. At the top of the page, see a list of Sentry projects associated with an entity. Each project listed in Cortex links back to the [project details page in Sentry](https://docs.sentry.io/product/projects/project-details/).

Under the **Issues** header on the **Error tracking** page, you'll find a list of all issues related to the projects that Cortex detected in Sentry. Each issue in the list links back to that [issue's details page in Sentry](https://docs.sentry.io/product/issues/issue-details/). Cortex will pull in the title and tags for each issue.

**Events**

Sentry issues and events will also appear in an entity's event timeline, found under **Events** in the sidebar. This allows users to contextualize Sentry issues with other key data - like deploys or errors discovered from other integrations - during incidents or migrations.

### Using the Cortex Slack Bot with Sentry

If you have also configured the [Slack integration](https://docs.cortex.io/ingesting-data-into-cortex/integrations/slack), you can use the command `/cortex sentry <tag>` in [Slack](https://docs.cortex.io/ingesting-data-into-cortex/integrations/slack) to get a list of all recent Sentry issues for a given entity. `tag` is the [Cortex tag](https://docs.cortex.io/entities#cortex-tag).

### Scorecards and CQL

With the Sentry integration, you can create Scorecard rules and write CQL queries based on Sentry projects.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

<details>

<summary>Check if Sentry project is set</summary>

Check if entity has a registered Sentry project.

**Definition:** `sentry (==/!=) null`

**Example**

For a production readiness Scorecard, you can use this expression to make sure entities are linked to a Sentry project.

```
sentry != null
```

This can also serve as a way to confirm that entities are synced with Sentry and reporting frequently.

</details>

<details>

<summary>Number of events</summary>

Counts Sentry events for a given [custom query](https://docs.sentry.io/concepts/search/#query-syntax) **to a max of 1,000**.

If no query is provided, the rule will count `unresolved` events by default.

**Definition:** `sentry.numOfIssueEvents((<query>))`

**Example**

For a Scorecard focused on operational maturity, you can check for any unresolved issues that were first seen within a week.

```
sentry.numOfIssueEvents("is:unresolved firstSeen:-1w") <= 10
```

</details>

<details>

<summary>Number of issues</summary>

Counts Sentry issues for a given custom query **to a max of 300**.

If no query is provided, the rule will count `unresolved` issues by default.

**Definition:** `sentry.numOfIssues((<query>))`

**Example**

For a Scorecard focused on operational maturity, you can pull in the number of Sentry issues to make sure entities are functioning as expected.

```
sentry.numOfIssues() < 100
```

For a Scorecard focused on code quality, you can write a more focused rule to make sure there haven't been any issues in production environments in the last week.

```
sentry.numOfIssues("is:unresolved environment:[production,prod] lastSeen:-1w") < 2
```

\\

</details>

{% hint style="warning" %}
The maximum number of Sentry events fetched for any query is 1,000, while the maximum number of issues fetched is 300.
{% endhint %}

### View integration logs <a href="#still-need-help" id="still-need-help"></a>

{% hint style="info" %}
This feature is available to Cortex cloud customers.
{% endhint %}

On the integration settings page, click the **Logs** tab to view logs from the last 7 days. Learn more in [Troubleshooting with integration logs](https://docs.cortex.io/ingesting-data-into-cortex/integrations/..#troubleshooting-with-integration-logs).

## Still need help?[​](https://docs.cortex.io/docs/reference/integrations/aws#still-need-help) <a href="#still-need-help" id="still-need-help"></a>

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: <help@cortex.io>, or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.