No results for ""
EXPAND ALL
  • Home
  • API docs

GIVE DOCS FEEDBACK

Sentry

Read time: 4 minutes
Last edited: May 20, 2024
This feature is for Early Access Program customers only

The Sentry integration is only available to members of LaunchDarkly's Early Access Program (EAP). If you want access to this feature, join the EAP.

Overview

This topic explains how to use the LaunchDarkly Sentry integration. Sentry is an application performance monitoring and error tracking tool. You can connect Sentry error events to LaunchDarkly to use with LaunchDarkly metrics.

An installed Sentry integration.
An installed Sentry integration.

To use the Sentry integration, you must complete the following steps:

  1. Install Sentry
  2. Configure the integration
  3. Create a LaunchDarkly metric
  4. Attach LaunchDarkly contexts to Sentry error events

Install Sentry

To install the Sentry integration:

  1. Log in to LaunchDarkly.
  2. Navigate to the public integrations directory in Sentry's application.
  3. Click Install.

You are redirected to the Sentry integration panel in LaunchDarkly.

Configure the integration

There are two pieces of configuration required for the Sentry integration to work:

  • setting the event key, and
  • mapping the environments.

Set the event key

Sentry uses the event key to aggregate events. We recommend using a Metric event key of sentry-errors or similar, but you can use any event key you like.

The "Metric event key" section of the integration panel.
The "Metric event key" section of the integration panel.

A LaunchDarkly metric must exist with the designated event key for the integration to work in a given project. If there is not an existing custom conversion/binary metric with the chosen event key, create a custom conversion/binary metric with that event key. To learn how, read Create a LaunchDarkly metric.

When you set a metric event key, a green check mark appears in the integration panel.

Metric keys and event keys are different

LaunchDarkly automatically generates a metric key when you create a metric. You can use the metric key to identify the metric in API calls. To learn more, read Creating metrics.

Custom conversion/binary and custom numeric metrics also require an event key. You can set the event key to anything you want. Adding this event key to your codebase lets your SDK track actions customers take in your app as events. To learn more, read Sending custom events.

Map environments

The Sentry integration requires you to map Sentry environments to LaunchDarkly environments. This lets you send Sentry errors to different LaunchDarkly environments. For example, you can send errors from your production Sentry environment to your production LaunchDarkly environment, and errors from your staging Sentry environment to your staging LaunchDarkly environment.

To map Sentry environments to LaunchDarkly environments:

  1. Navigate to the Integrations page in LaunchDarkly.
  2. Open the Sentry integration panel.
  3. In the "Environment mappings" section, choose a LaunchDarkly project and environment from the Project - Environment menu.
  4. Choose a Sentry project and environment from the Sentry Project - Environment menu.
  5. Click Create.

The sets of projects and environments are now mapped to each other.

Sentry environment mappings.
Sentry environment mappings.

If an environment mapping is highlighted in red, it means that there is no metric for the event key in that LaunchDarkly project.

You can map any number of Sentry project environments to a LaunchDarkly environment. However, you cannot map multiple LaunchDarkly environments to a single Sentry environment.

Create a LaunchDarkly metric

To create a LaunchDarkly metric, follow the procedure at Custom conversion/binary metrics.

Here are two example metrics we recommend.

Percentage of end users that experienced an error

Event information:

  • Metric type: Custom conversion/binary
  • Event key: sentry-errors
  • Success criteria: Lower than baseline

Metric analysis options:

  • Unit of aggregation: User
  • Unit aggregation method: Average individual unit values
  • Analysis method: Mean

Here is what the metric setup looks like:

The metric creation dialog.
The metric creation dialog.

Average number of errors per request

Event information:

  • Metric type: Custom conversion/binary
  • Event key: sentry-errors
  • Success criteria: Lower than baseline

Metric analysis options:

  • Unit of aggregation: Request
  • Unit aggregation method: Sum individual unit values
  • Analysis method: Mean

Here is what the metric setup looks like:

The metric creation dialog.
The metric creation dialog.

After you create your metrics, return to the Sentry integration configuration panel and set the Sentry integration event key if you have not already done so.

Attach LaunchDarkly contexts to Sentry error events

Sentry custom contexts are not the same as LaunchDarkly custom contexts

Sentry provides functionality called "custom contexts." These are distinct from LaunchDarkly's custom contexts. In this section, "custom contexts" refers to the Sentry functionality.

Sentry provides custom contexts which let you attach arbitrary data to a Sentry event. To use the Sentry integration, you must name the Sentry custom context launchdarklyContext and then attach LaunchDarkly contexts to error events. To learn how, read Sentry's Context docs.

You must name the Sentry custom context launchdarklyContext

In Sentry, you must name the Sentry custom context launchdarklyContext. If the Sentry custom context is not present or you have named it something else, LaunchDarkly will ignore the error event.

Using the integration

After you create the environment mappings, set the metric event key, create metrics for your desired projects, and add LaunchDarkly contexts to the Sentry SDK, you can use the metric in LaunchDarkly the same way as any other metric. When you configure a metric to use Sentry errors, error events will flow from Sentry into that metric.