Skip to main content

BugSnag

Scorecards

BugSnag is an application stability monitoring platform that provides error tracking and analytics. By integrating BugSnag with Cortex, you can view errors alongside other key metrics and gain greater understanding into your entities' operational maturity.

In this guide, you'll learn how to set up and use the BugSnag integration to drive insights into values such as:

  • Outstanding errors
  • Error frequency

Setup and configuration

Getting started

In order to connect Cortex to your BugSnag instance, you’ll first need to create a BugSnag auth token in the My Account section of BugSnag settings.

Configuration

Once you've created the auth token, you can configure the integration in Cortex from the BugSnag page in settings.

caution

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.

To configure the integration, provide the following information:

  • Auth token: Auth token generated from BugSnag
  • Organization slug: BugSnag organization for your instance; you can find this in settings or in your BugSnag URL (https://app.bugsnag.com/organizations/{SLUG}/stability-center)
  • Host (optional): URL for your BugSnag instance without the API path (e.g. bugsnag.getcortexapp.com)
    • This is only needed if you're using a custom/self-hosted BugSnag instance

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.”

caution

If you're using a self-hosted instance of BugSnag, you'll need to verify that your Cortex instance is able to reach the BugSnag 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 BugSnag instance.

Registration

Discovery

By default, Cortex will use the entity tag (e.g. my-entity) as the "best guess" for the BugSnag project key. For example, if your entity tag is my-entity, then the corresponding project key in BugSnag should also be my-entity.

If your BugSnag project keys 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-bugsnag:
project: my-project # projectKey in BugSnag

The value for project should be the project key as defined in BugSnag.

Expected results

Entity pages

Once the integration with BugSnag is established, you'll be able to pull in error data to an entity's details page. You can find the total number of detected errors and a full list on the BugSnag page under Integrations in the side panel.

Each error in the list will display with an Error, Info, or Warning tag based on the severity applied to a given error in BugSnag.

Scorecards and CQL

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

  • Check if BugSnag is set: Checks if an entity has a registered BugSnag project
  • Number of issues: Counts all unresolved issues in BugSnag or counts number of issues for a given query

Real-world examples

For a Scorecard focused on operational maturity, you can pull in error data from BugSnag to make sure your entities have no or few errors.

bugsnag.numOfIssues() < 2

To set a more specific standard, you can also create a rule based on a filter.

bugsnag.numOfIssues("filters[error.status][][type]=example")

You can also define a rule to make sure each entity has a registered BugSnag project - this is a good way to double-check that the integration is synced and reporting frequently.

bugsnag != null

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.