diff --git a/docs/organization/integrations/feature-flag/launchdarkly/img/ff-integration-ui.png b/docs/organization/integrations/feature-flag/launchdarkly/img/ff-integration-ui.png new file mode 100644 index 00000000000000..faddb9def476ae Binary files /dev/null and b/docs/organization/integrations/feature-flag/launchdarkly/img/ff-integration-ui.png differ diff --git a/docs/organization/integrations/feature-flag/launchdarkly/index.mdx b/docs/organization/integrations/feature-flag/launchdarkly/index.mdx index a2c7bcc3aea943..a01ab69f3e9df7 100644 --- a/docs/organization/integrations/feature-flag/launchdarkly/index.mdx +++ b/docs/organization/integrations/feature-flag/launchdarkly/index.mdx @@ -1,12 +1,43 @@ --- title: LaunchDarkly sidebar_order: 1 -description: Learn about Sentry's LaunchDarkly integration. LaunchDarkly enables organizations to use Sentry errors as a metric in their LaunchDarkly experiments. +description: Learn about Sentry's LaunchDarkly integrations. --- +## Evaluation Tracking + +Sentry can track flag evaluations as they happen within your application. Flag evaluations will appear in the "Feature Flag" section of Issue Details page as a table, with "suspect" flag predictions highlighted in yellow. Learn more about how to interact with feature flag insights within the Sentry UI by reading the [Issue Details page documentation](/product/issues/issue-details/#feature-flags). + +### Set Up Evaluation Tracking + +To set up evaluation tracking visit one of our supported languages pages: +* [JavaScript](/platforms/javascript/configuration/integrations/launchdarkly/) +* [Python](/platforms/python/integrations/launchdarkly/) + +## Change Tracking + +Sentry can track changes to feature flag definitions and report suspicious feature flag edits. + +### Set Up Change Tracking + +Enabling Change Tracking is a two step process. To get started visit the [feature-flags settings page](https://sentry.io/orgredirect/organizations/:orgslug/settings/feature-flags/) in a new tab. Then follow the steps listed below. + +1. **Register the webhook URL**. + - Under the "Integrate Feature Flag Service" heading a Sentry webhook URL has been provided. + - Copy the Sentry webhook URL revealed in the fly out and paste it into LaunchDarkly within their [webhook integration UI](https://app.launchdarkly.com/settings/integrations/webhooks/new). +2. **Set the Signing Secret**. + - In the LaunchDarkly webhook UI check the box that says "Sign this webhook". + - Copy the signing secret in the revealed input box and paste it into the input box labeled "Secret" on the Sentry fly out. + - Save the secret by clicking "Save Secret" in the Sentry fly out. + - Save the webhook by clicking "Save Settings" in LaunchDarkly. + +Once saved Sentry will now accept and authenticate all inbound hooks to your organization's feature flag webhook endpoint. + +## Metrics Integration + This integration is maintained and supported by the company that created it. For more details or questions, feel free to contact rrosefigura@launchdarkly.com. -## Install and Configure +### Install and Configure diff --git a/docs/platforms/javascript/common/configuration/integrations/launchdarkly.mdx b/docs/platforms/javascript/common/configuration/integrations/launchdarkly.mdx new file mode 100644 index 00000000000000..6282d700e6b930 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/launchdarkly.mdx @@ -0,0 +1,77 @@ +--- +title: LaunchDarkly +description: "Learn how to use Sentry with LaunchDarkly." +notSupported: + - javascript.aws-lambda + - javascript.azure-functions + - javascript.bun + - javascript.capacitor + - javascript.cloudflare + - javascript.connect + - javascript.cordova + - javascript.deno + - javascript.electron + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.koa + - javascript.nestjs + - javascript.nodejs + - javascript.wasm +--- + + + + + +This integration only works inside a browser environment. + + + +The [LaunchDarkly](https://launchdarkly.com/) integration tracks feature flag evaluations produced by the LaunchDarkly SDK. These evaluations are held in memory, and in the event an error occurs, sent to Sentry for review and analysis. **At the moment, we only support boolean flag evaluations.** + +_Import names: `Sentry.launchDarklyIntegration` and `Sentry.buildLaunchDarklyFlagUsedHandler`_ + +## Install + +Install [`@sentry/browser`](https://www.npmjs.com/package/@sentry/browser) and [`launchdarkly-js-client-sdk`](https://www.npmjs.com/package/launchdarkly-js-client-sdk) from npm. + +## Configure + +```JavaScript +import * as Sentry from '@sentry/browser'; +import * as LaunchDarkly from 'launchdarkly-js-client-sdk'; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [Sentry.launchDarklyIntegration()] +}); + +const ldClient = LaunchDarkly.initialize( + 'my-client-ID', + {kind: 'user', key: 'my-user-context-key'}, + {inspectors: [Sentry.buildLaunchDarklyFlagUsedHandler()]} +); +``` + +Learn more about the [LaunchDarkly SDK](https://docs.launchdarkly.com/sdk/client-side/javascript). At the moment, **we aren't officially supporting framework-specific LaunchDarkly SDKs.** However, you may reuse the setup code for [React](https://www.npmjs.com/package/launchdarkly-react-client-sdk) and [client-side Node.js](https://www.npmjs.com/package/launchdarkly-node-client-sdk). + +## Verify + +The integration is tested by evaluating a feature flag with your LaunchDarkly SDK before capturing an exception. + +```JavaScript +import * as Sentry from '@sentry/browser'; +import * as LaunchDarkly from 'launchdarkly-js-client-sdk'; + +// Evaluate a flag with a default value, with the ldClient from the Configure step. +// You may have to wait for your client to initialize before doing this. +ldClient?.variation("hello", false); + +Sentry.captureException(Exception("Something went wrong!")) +``` + +Visit the Sentry website and confirm that your error event has recorded the feature flag "hello" and its value "false". + + diff --git a/docs/platforms/javascript/common/configuration/integrations/openfeature.mdx b/docs/platforms/javascript/common/configuration/integrations/openfeature.mdx new file mode 100644 index 00000000000000..0b42e668a32b90 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/openfeature.mdx @@ -0,0 +1,81 @@ +--- +title: OpenFeature +description: "Learn how to use Sentry with OpenFeature." +notSupported: + - javascript.aws-lambda + - javascript.azure-functions + - javascript.bun + - javascript.capacitor + - javascript.cloudflare + - javascript.connect + - javascript.cordova + - javascript.deno + - javascript.electron + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.koa + - javascript.nestjs + - javascript.nodejs + - javascript.wasm +--- + + + + + +This integration only works inside a browser environment. + + + +The [OpenFeature](https://openfeature.dev/) integration tracks feature flag evaluations produced by the OpenFeature SDK. These evaluations are held in memory, and in the event an error occurs, sent to Sentry for review and analysis. **At the moment, we only support boolean flag evaluations.** + +_Import name: `Sentry.openFeatureIntegration` and `Sentry.OpenFeatureIntegrationHook`_ + +## Install + +Install [`@sentry/browser`](https://www.npmjs.com/package/@sentry/browser) and [`@openfeature/web-sdk`](https://www.npmjs.com/package/@openfeature/web-sdk) from npm. + +## Configure + +```JavaScript +import * as Sentry from '@sentry/browser'; +import { OpenFeature } from '@openfeature/web-sdk'; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [Sentry.openFeatureIntegration()] +}); + +OpenFeature.setProvider(new MyProviderOfChoice()); + +// Option 1: track all OpenFeature evaluations. +OpenFeature.addHooks(new Sentry.OpenFeatureIntegrationHook()); + +// Option 2: only track evaluations by a specific client. +const client = OpenFeature.getClient(); +client.addHooks(new Sentry.OpenFeatureIntegrationHook()); +``` + +Learn more about OpenFeature providers [here](https://openfeature.dev/docs/reference/concepts/provider). + +## Verify + +The integration is tested by evaluating a feature flag with your OpenFeature SDK before capturing an exception. + +```JavaScript +import * as Sentry from '@sentry/browser'; +import { OpenFeature } from '@openfeature/web-sdk'; + +// Evaluate a flag with a default value. If you added the hook to a client in +// the Configure step, make sure to use the same client here. +const client = OpenFeature.getClient(); +const result = client.getBooleanValue('hello', false); + +Sentry.captureException(Exception("Something went wrong!")) +``` + +Visit the Sentry website and confirm that your error event has recorded the feature flag "hello" and its value "false". + + diff --git a/docs/platforms/javascript/common/feature-flags/index.mdx b/docs/platforms/javascript/common/feature-flags/index.mdx new file mode 100644 index 00000000000000..b8bda352ae0128 --- /dev/null +++ b/docs/platforms/javascript/common/feature-flags/index.mdx @@ -0,0 +1,37 @@ +--- +title: Set Up Feature Flags +sidebar_order: 7000 +notSupported: + - javascript.aws-lambda + - javascript.azure-functions + - javascript.bun + - javascript.capacitor + - javascript.cloudflare + - javascript.connect + - javascript.cordova + - javascript.deno + - javascript.electron + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.koa + - javascript.nestjs + - javascript.nodejs + - javascript.wasm +description: With Feature Flags, Sentry tracks feature flag evaluations in your application, keeps an audit log feature flag changes, and reports any suspicious updates that may have caused an error. +--- + + + +## Prerequisites + +* You have the JavaScript SDK installed (version 8.41.0-beta.1). + +## Enable Evaluation Tracking + +Evaluation tracking requires enabling an SDK integration. Integrations are provider specific. Documentation for supported providers is listed below. +- [OpenFeature](/platforms/javascript/configuration/integrations/openfeature/) +- [LaunchDarkly](/platforms/javascript/configuration/integrations/launchdarkly/) + + diff --git a/docs/platforms/python/feature-flags/index.mdx b/docs/platforms/python/feature-flags/index.mdx new file mode 100644 index 00000000000000..2fdef511f1adeb --- /dev/null +++ b/docs/platforms/python/feature-flags/index.mdx @@ -0,0 +1,20 @@ +--- +title: Set Up Feature Flags +sidebar_order: 7000 +description: With Feature Flags, Sentry tracks feature flag evaluations in your application, keeps an audit log feature flag changes, and reports any suspicious updates that may have caused an error. +--- + + + +## Prerequisites + +* You have the Python SDK installed (version 2.18.0 or higher). + +## Enable Evaluation Tracking + +Evaluation tracking requires enabling an SDK integration. Integrations are provider specific. Documentation for supported providers is listed below. + +- [OpenFeature](/platforms/python/integrations/openfeature/) +- [LaunchDarkly](/platforms/python/integrations/launchdarkly/) + + diff --git a/docs/platforms/python/integrations/launchdarkly/index.mdx b/docs/platforms/python/integrations/launchdarkly/index.mdx index 15e30d19710efb..ebf6b1f21e94c4 100644 --- a/docs/platforms/python/integrations/launchdarkly/index.mdx +++ b/docs/platforms/python/integrations/launchdarkly/index.mdx @@ -1,9 +1,11 @@ --- title: LaunchDarkly -description: "Learn about the LaunchDarkly integration and how to add it to your integrations list." +description: "Learn how to use Sentry with LaunchDarkly." --- -The [LaunchDarkly](https://launchdarkly.com/) integration tracks feature flag evaluations produced by the LaunchDarkly SDK. These evaluations are held in memory and, in the event an error occurs, sent to Sentry for review and analysis. + + +The [LaunchDarkly](https://launchdarkly.com/) integration tracks feature flag evaluations produced by the LaunchDarkly SDK. These evaluations are held in memory and sent to Sentry for review and analysis if an error occurs. **At the moment, we only support boolean flag evaluations.** ## Install @@ -44,3 +46,5 @@ sentry_sdk.capture_exception(Exception("Something went wrong!")) ``` Visit the Sentry website and confirm that your error event has recorded the feature flag "hello" and its value "false". + + diff --git a/docs/platforms/python/integrations/openfeature/index.mdx b/docs/platforms/python/integrations/openfeature/index.mdx index 0f287aa539bd51..6c86cefee6c5e0 100644 --- a/docs/platforms/python/integrations/openfeature/index.mdx +++ b/docs/platforms/python/integrations/openfeature/index.mdx @@ -1,9 +1,11 @@ --- title: OpenFeature -description: "Learn about the OpenFeature integration and how to add it to your integrations list." +description: "Learn how to use Sentry with OpenFeature." --- -The [OpenFeature](https://openfeature.dev/) integration tracks feature flag evaluations produced by the OpenFeature SDK. These evaluations are held in memory and, in the event an error occurs, sent to Sentry for review and analysis. + + +The [OpenFeature](https://openfeature.dev/) integration tracks feature flag evaluations produced by the OpenFeature SDK. These evaluations are held in memory and sent to Sentry for review and analysis if an error occurs. **At the moment, we only support boolean flag evaluations.** ## Install @@ -19,7 +21,7 @@ Add `OpenFeatureIntegration()` to your `integrations` list: ```python import sentry_sdk -from sentry_sdk.integrations.OpenFeature import OpenFeatureIntegration +from sentry_sdk.integrations.openfeature import OpenFeatureIntegration sentry_sdk.init( dsn="___PUBLIC_DSN___", @@ -44,3 +46,5 @@ sentry_sdk.capture_exception(Exception("Something went wrong!")) ``` Visit the Sentry website and confirm that your error event has recorded the feature flag "hello" and its value "false". + + diff --git a/docs/product/explore/feature-flags/index.mdx b/docs/product/explore/feature-flags/index.mdx new file mode 100644 index 00000000000000..8734a6af2dc802 --- /dev/null +++ b/docs/product/explore/feature-flags/index.mdx @@ -0,0 +1,28 @@ +--- +title: "Feature Flags" +sidebar_order: 100 +description: "Learn how to set up and interact with Sentry's feature flag evaluation tracking and feature flag change tracking." +--- + + + +Enabling a feature flag integration provides deep insights into the state of your application prior to an error. A list of flags and their evaluation results are displayed on each error event in the order of evaluation. Integrating Sentry with your feature flag provider enables Sentry to correlate feature flag changes with new error events and mark certain changes as suspicious. + +## Evaluation Tracking + +Flag evaluations will appear in the "Feature Flag" section of Issue Details page as a table, with "suspect" flag predictions highlighted in yellow. Learn more about how to interact with feature flag insights within the Sentry UI by reading the [Issue Details page documentation](/product/issues/issue-details/#feature-flags). + +### Set Up Evaluation Tracking + +To set up evaluation tracking visit your provider's integration documentation page: +* [JavaScript](/platforms/javascript/feature-flags/) +* [Python](/platforms/python/feature-flags/) + +## Change Tracking + +Change tracking enables Sentry to listen for additions, removals, and modifications to your feature flags. On change, we'll record the change event in the audit log. The audit log appears in the "event volume" chart and presents itself as a "release" line. If the change is responsible for a new error event, we'll notify you by marking the feature flag as "suspect" on the Issue Details page. Learn more about how to interact with feature flag insights within the Sentry UI by reading the [Issue Details documentation](/product/issues/issue-details/#feature-flags). + +### Set Up Change Tracking + +To set up change tracking visit your provider's integration documentation page: +* [LaunchDarkly](/organization/integrations/feature-flag/launchdarkly/#change-tracking) diff --git a/docs/product/issues/issue-details/img/feature-flags.png b/docs/product/issues/issue-details/img/feature-flags.png deleted file mode 100644 index 4df355e3ea33bd..00000000000000 Binary files a/docs/product/issues/issue-details/img/feature-flags.png and /dev/null differ diff --git a/docs/product/issues/issue-details/img/ff-release.png b/docs/product/issues/issue-details/img/ff-release.png new file mode 100644 index 00000000000000..54f1031bf23ba8 Binary files /dev/null and b/docs/product/issues/issue-details/img/ff-release.png differ diff --git a/docs/product/issues/issue-details/img/ff-table.png b/docs/product/issues/issue-details/img/ff-table.png new file mode 100644 index 00000000000000..b5b54eb0b1b0b0 Binary files /dev/null and b/docs/product/issues/issue-details/img/ff-table.png differ diff --git a/docs/product/issues/issue-details/img/suspect-flags-table.png b/docs/product/issues/issue-details/img/suspect-flags-table.png deleted file mode 100644 index 33ed6541a691d6..00000000000000 Binary files a/docs/product/issues/issue-details/img/suspect-flags-table.png and /dev/null differ diff --git a/docs/product/issues/issue-details/img/suspect-flags-timeline.png b/docs/product/issues/issue-details/img/suspect-flags-timeline.png deleted file mode 100644 index 3cfddd34a7b23a..00000000000000 Binary files a/docs/product/issues/issue-details/img/suspect-flags-timeline.png and /dev/null differ diff --git a/docs/product/issues/issue-details/index.mdx b/docs/product/issues/issue-details/index.mdx index 7003b62afc365e..5a1b26a4ed48e7 100644 --- a/docs/product/issues/issue-details/index.mdx +++ b/docs/product/issues/issue-details/index.mdx @@ -142,3 +142,15 @@ The Contexts section contains related key/value items (not just strings) that yo The issue details page only displays context for the individual event, and context cannot be searched. If you require searching for your data, use [Tags](#tags) instead. You can set up your own context items to collect useful debugging information in your next event, as described in Structured Context. + +## Feature Flags + +Enabling one or more of our [evaluation tracking integrations](/product/explore/feature-flags/#evaluation-tracking) will reveal the feature flag evaluation table. Here you can see an ordered list (in order of evaluation) of all the flags evaluated and their evaluation results prior to the error event. + +![Feature Flag Table](./img/ff-table.png) + +Enabling a [change tracking integration](/product/explore/feature-flags/#change-tracking) will enable annotations on the event volume chart. These lines mark feature flag changes and can help identify regressions caused by a feature flag definition change. + +![Feature Flag Release Chart](./img/ff-release.png) + +Enabling both a change tracking integration and a evaluation tracking integration will enable suspect feature flag detection. Sentry will attempt to identify feature flags which might have caused an error event and highlight them for review. diff --git a/platform-includes/feature-flags/change-tracking-cta-launchdarkly/_default.mdx b/platform-includes/feature-flags/change-tracking-cta-launchdarkly/_default.mdx new file mode 100644 index 00000000000000..6cdee2d5b10269 --- /dev/null +++ b/platform-includes/feature-flags/change-tracking-cta-launchdarkly/_default.mdx @@ -0,0 +1,9 @@ +## Change Tracking + +Sentry can track changes to feature flag definitions and report suspicious feature flag edits. To enable the change tracking integration click the "Set Up Integration" button on the feature flag table contained within the Issue Details page. This will trigger a fly out which will guide you through the two step process. + +![Integration UI](./img/ff-integration-ui.png) + +Under the "Integrate Feature Flag Service" heading a Sentry webhook URL has been provided. Additionally, a link to LaunchDarkly's webhook registration interface has been provided. Paste the Sentry webhook URL into the input box labeled "URL" within the LaunchDarkly webhook registration UI. + +Next a signing secret must be created. Check the box that says "Sign this webhook". This will reveal an input element which contains your signing secret. Copy and paste this signing secret into the input box labeled "Secret" on the Sentry fly out. Click "Save Secret" in the Sentry UI, then click "Save Settings" in the LaunchDarkly UI, and you're done. Sentry will now accept and authenticate all inbound hooks to your organization's feature flag webhook endpoint. diff --git a/platform-includes/feature-flags/change-tracking-cta-launchdarkly/img/ff-integration-ui.png b/platform-includes/feature-flags/change-tracking-cta-launchdarkly/img/ff-integration-ui.png new file mode 100644 index 00000000000000..faddb9def476ae Binary files /dev/null and b/platform-includes/feature-flags/change-tracking-cta-launchdarkly/img/ff-integration-ui.png differ diff --git a/platform-includes/feature-flags/enable-change-tracking/_default.mdx b/platform-includes/feature-flags/enable-change-tracking/_default.mdx new file mode 100644 index 00000000000000..6d03036a6cfd4c --- /dev/null +++ b/platform-includes/feature-flags/enable-change-tracking/_default.mdx @@ -0,0 +1,3 @@ +## Enable Change Tracking + +Change tracking requires registering a Sentry webhook with your feature flag provider. Set up varies by provider and is documented in detail [here](/product/explore/feature-flags/#change-tracking). diff --git a/platform-includes/feature-flags/next-steps/_default.mdx b/platform-includes/feature-flags/next-steps/_default.mdx new file mode 100644 index 00000000000000..3aaa89ab9cd66e --- /dev/null +++ b/platform-includes/feature-flags/next-steps/_default.mdx @@ -0,0 +1,6 @@ + + +- **Track feature flag evaluations in other parts of your codebase.** If needed, you can set up evaluation tracking for more than one SDK. [Read the docs](/product/explore/feature-flags/#set-up-evaluation-tracking) to learn more. +- **Set up your change tracking webhook.** In order to take full advantage of the feature flag capabilities Sentry offers there is an additional setup step needed. Your feature flag provider needs to notify Sentry when a feature flag definition has changed. A Sentry webhook URL can be registered with your provider. Learn [how](/product/explore/feature-flags/#set-up-change-tracking). + + diff --git a/platform-includes/feature-flags/prerelease-alert/_default.mdx b/platform-includes/feature-flags/prerelease-alert/_default.mdx new file mode 100644 index 00000000000000..30f9be37162271 --- /dev/null +++ b/platform-includes/feature-flags/prerelease-alert/_default.mdx @@ -0,0 +1,5 @@ + + +Feature flag change tracking and feature flag evaluation tracking is currently in open beta. + +