Sentry
Sentry is an application monitoring platform that helps developers identify, debug, and resolve issues. Integrating Sentry with Cortex allows you to contextualize issues with other events, track errors, measure quality, and drive performance improvements across entities.
In this guide, you'll learn how to set up and configure the Sentry integration in Cortex to enhance visibility into events and issues.
Setup and configuration
Getting started
In order to connect Cortex to your Sentry instance, you’ll need to create a Sentry user auth token from Sentry user settings.
For the integration to work successfully, the user auth token requires Read permissions for the Issue & Event and Project scopes.
Configuration
Once you've created the auth token, add it on the Sentry page in settings. The configuration has three fields:
- Auth token: The user auth token created in Sentry.
- Organization slug: Slug for your Sentry organization, which can be found in Sentry settings and in the URL for your instance (e.g.
https://sentry.io/organizations/{SLUG}/issues/). - Host: Optional host name for self-hosted Sentry instances. Do not include the
/apiprefix.
If you do not see the settings page you're looking for, you likely don't have the proper permissions and need to contact your admin.
If you’ve set everything up correctly, you’ll see the option to Remove Integration in settings.
You can also use the Test configuration button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”
If you're using a self-hosted instance of Sentry, you'll need to
verify that your Cortex instance is able to reach the Sentry instance.
We route our requests through a static IP address. Reach out to support at
help@cortex.io to receive details about our static IP.
If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Sentry instance.
Registration
Discovery
By default, Cortex will use the entity tag (e.g. my-entity) as the "best guess" for the Sentry project name. For example, if your entity tag is my-entity, then the corresponding project name in Sentry should also be my-entity.
If your Sentry project names don’t cleanly match the Cortex entity tag, you can override this in the Cortex entity descriptor.
Entity descriptor
If you need to override automatic discovery, you can define the following block in your Cortex entity descriptor.
x-cortex-sentry:
projects:
- name: my-project
- name: my-second-project
| Field | Description | Required |
|---|---|---|
name | Project name as defined in Sentry | ✓ |
Expected results
Entity pages
Once the integration with Sentry is established, you'll be able to find key data about errors and issues on an entity's details page. Navigate to the Sentry page under the Integrations tab in the side panel to find detected issues for each project.
At the top of the page, you'll find 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, you'll find a list of all issues related to the project(s) 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 side panel. This allows users to contextualize Sentry issues with other key data - like deploys or errors discovered from other integrations - during incidents or migrations.
Scorecards and CQL
With the Sentry integration, you can create Scorecard rules and write CQL queries based on Sentry projects.
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.
Cortex Slackbot
You can use the /cortex sentry <tag> command in Slack, where <tag> is the entity tag in Cortex, to get a list of all recent Sentry issues for a given entity.
Still need help?
The following are all the ways to get assistance from our customer engineering team. Please use the option that is best for your users:
- Email: help@cortex.io, 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.