Sentry

Sentry 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, giving you insight into your entity's operational maturity

• Pull a list of recent Sentry issues directly in Slack, using the Cortex Slack Bot

• Create Scorecards that include rules related to Sentry errors

How to configure Sentry with Cortex

Prerequisites

Before getting started:

• Create a Sentry user auth token in your Sentry user settings.

  • The user auth token requires Read permissions for the Issue & Event and Project scopes.

Configure the integration in Cortex

1. In Cortex, navigate to the Sentry settings page:

   1. In Cortex, click your avatar in the lower left corner, then click Settings.

   2. Under "Integrations," click Sentry.

2. Click Add configuration.

3. Configure the integration form:

   • Auth token: Enter the auth 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 entity tag (e.g., my-entity) as the best guess for Sentry projects. For example, if your entity 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 entity tag, you can override this in the Cortex entity descriptor.

Editing the entity descriptor

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

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

Field	Description	Required
name	Project name as defined in Sentry	✓

Using the Sentry integration

Viewing Sentry errors on an entity

Error data will appear on an entity's details page. 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.

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. 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, you can use the command /cortex sentry <tag> in Slack to get a list of all recent Sentry issues for a given entity. tag is the entity tag in Cortex.

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 in Cortex.

Check if Sentry project is set

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.

Number of events

Counts Sentry events for a given custom query 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

Number of issues

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

The maximum number of Sentry events fetched for any query is 1,000, while the maximum number of issues fetched is 300.

Still need help?​

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

• Email: [e-mail], or open a support ticket in the in app Resource Center
• Chat: Available in the 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.