chore(hybrid-cloud): Add troubleshooting docs for integrations (#5396)

leeandher · web-flow · commit 1cd4179d6731 · 2022-08-09T11:43:44.000-07:00
See API-2842

This PR makes a lot of changes that are necessary for troubleshooting org slug changes in integrations.

    It adds an alert to each integration which may be affected by org slug changes
    It adds pages for integrations which are affected, but have no existing page (i.e. Segment, FullStory, OpenReplay and SourceGraph)
    It adds the troubleshooting page which provides more context and lists the affected integrations
    It updates index pages which list integrations and their categories.

If this is difficult to review I can break it into two PRs, though since all the callouts link back to the troubleshooting page, I'd prefer not to.

In the future, we can also add to the troubleshooting page with:

    Integrations that depend on project slugs
    Integrations that depend on a Sentry URL (which will experience latency once we set up region.sentry.io redirects)
diff --git a/src/docs/product/integrations/data-visualization/grafana.mdx b/src/docs/product/integrations/data-visualization/grafana.mdx
@@ -4,4 +4,10 @@ sidebar_order: 1
 description: "Learn about Sentry's Grafana integration."
 ---
 
+<Alert level="warning">
+
+If you make changes to your organization slug, you will have to update your configuration on this integration. Find out more in the [troubleshooting guide](/product/integrations/troubleshooting).
+
+</Alert>
+
 Visualize your Sentry [Issues](/product/issues/) and [Stats](/product/stats/) data in Grafana with the Sentry [data source plugin](https://grafana.com/grafana/plugins/grafana-sentry-datasource/). Once installed, you can combine Sentry data with that of other sources, like your infrastructure data through Prometheus or your business data from your data warehouse, in a single dashboard.
diff --git a/src/docs/product/integrations/data-visualization/index.mdx b/src/docs/product/integrations/data-visualization/index.mdx
@@ -8,5 +8,5 @@ Learn more about Sentry's data and visualization integrations:
 
 - [Amazon SQS](/product/integrations/data-visualization/amazon-sqs/)
 - [Grafana](/product/integrations/data-visualization/grafana/)
-- Segment
+- [Segment](/product/integrations/data-visualization/segment/)
 - [Splunk](/product/integrations/data-visualization/splunk/)
diff --git a/src/docs/product/integrations/data-visualization/segment/index.mdx b/src/docs/product/integrations/data-visualization/segment/index.mdx
@@ -0,0 +1,33 @@
+---
+title: Segment
+sidebar_order: 1
+redirect_from:
+  - /product/integrations/segment/
+description: "Learn about Sentry's Segment integration."
+---
+
+<Alert level="warning">
+
+If you make changes to your organization slug, you will have to update your configuration on this integration. Find out more in the [troubleshooting guide](/product/integrations/troubleshooting).
+
+</Alert>
+
+Segment is useful for collecting, responsibly managing and integrating your customer data with many other applications, including Sentry.
+
+This integration needs to be set up in each project for which you wish to use it. It is maintained and supported by the [Sentry community](https://open.sentry.io/).
+
+## Install and Configure
+
+<Note>
+
+Sentry owner, manager, or admin permissions are required to install this integration.
+
+</Note>
+
+Navigate to **Settings > Integrations > Segment**
+
+![Install Segment integration](segment.png)
+
+### Data Forwarding
+
+Configure [Data Forwarding](/platform-redirect/?next=/data-management/data-forwarding/) in **[Project] > Settings > Data Forwarding**, and provide the required information for the given integration.
diff --git a/src/docs/product/integrations/data-visualization/segment/segment.png b/src/docs/product/integrations/data-visualization/segment/segment.png
diff --git a/src/docs/product/integrations/data-visualization/splunk/index.mdx b/src/docs/product/integrations/data-visualization/splunk/index.mdx
@@ -117,7 +117,7 @@ We’ll now begin forwarding all new events into your Splunk instance.
 
 <Note>
 
-Sentry will internally limit the maximum number of events sent to your Splunk instance to 50 per second.
+Sentry will internally limit the maximum number of events sent to your Splunk instance to 1000 per second.
 
 </Note>
 
diff --git a/src/docs/product/integrations/deployment/vercel/index.mdx b/src/docs/product/integrations/deployment/vercel/index.mdx
@@ -8,6 +8,12 @@ redirect_from:
 description: "Learn more about Sentry's Vercel integration and how you can connect your Sentry and Vercel projects to automatically upload source maps and notify Sentry of release deployment."
 ---
 
+<Alert level="warning">
+
+If you make changes to your organization slug, you will have to update your configuration on this integration. Find out more in the [troubleshooting guide](/product/integrations/troubleshooting).
+
+</Alert>
+
 Vercel is an all-in-one platform with Global CDN supporting static and JAMstack deployment and Serverless Functions. Connect your Sentry and Vercel projects to automatically upload source maps and notify Sentry of release deployment. To learn more about using Sentry in your Next.js app, check out the [Next.js SDK](/platforms/javascript/guides/nextjs/).
 
 ## Install
diff --git a/src/docs/product/integrations/feature-flag/split/index.mdx b/src/docs/product/integrations/feature-flag/split/index.mdx
@@ -8,6 +8,12 @@ redirect_from:
 description: "Learn more about Sentry's Split integration and how it quickly processes and displays Sentry exception data in the Split platform as track events for analysis. You can control what environments and traffic types you're capturing exceptions for in the Split dashboard without having to touch any code."
 ---
 
+<Alert level="warning">
+
+If you make changes to your organization slug, you will have to update your configuration on this integration. Find out more in the [troubleshooting guide](/product/integrations/troubleshooting).
+
+</Alert>
+
 The Split integration quickly processes and displays Sentry exception data in the Split platform as track events for analysis. You can control what environments and traffic types you're capturing exceptions for in the Split dashboard without having to touch any code.
 
 This integration is maintained and supported by the company that created it. For more details, check out our [Integration Platform documentation](/product/integrations/integration-platform/).
diff --git a/src/docs/product/integrations/index.mdx b/src/docs/product/integrations/index.mdx
@@ -11,7 +11,7 @@ redirect_from:
 description: "Learn more about the wide variety of apps and services integrated with Sentry."
 ---
 
-Sentry integrates with your favorite apps and services. Each integration offers features that help track and triage your errors.
+Sentry integrates with your favorite apps and services. Each integration offers features that help track and triage your errors. If you're experiencing issues with some integrations after making changes to your Sentry instance or organization, check out our [troubleshooting guide](/product/integrations/troubleshooting/).
 
 ## Integration Platform
 
@@ -23,14 +23,13 @@ For more details, see the [full Integration Platform documentation](/product/int
 
 | Integration                                                              | Issue alerts | Metric alerts | Link Unfurling |
 | ------------------------------------------------------------------------ | ------------ | ------------- | -------------- |
-| [Amixr](/product/integrations/notification-incidents/amixr/)             | X            |               |                |
-| Datadog                                                                  | X            |               |                |
+| [Datadog](https://docs.datadoghq.com/integrations/sentry/)               | X            |               |                |
 | [Microsoft Teams](/product/integrations/notification-incidents/msteams/) | X            | X             |                |
 | OpsGenie                                                                 | X            |               |                |
 | [PagerDuty](/product/integrations/notification-incidents/pagerduty/)     | X            | X             |                |
 | Pushover                                                                 | X            |               |                |
 | [Slack](/product/integrations/notification-incidents/slack/)             | X            | X             | X              |
-| [Spike.sh](/product/integrations/notification-incidents/spikesh/)        | X            | X             |                |
+| [Spike.sh](/product/integrations/notification-incidents/spikesh/)        | X            | X             |
 | [Threads](/product/integrations/notification-incidents/threads/)         | X            | X             |                |
 | Twilio                                                                   | X            |               |                |
 | VictorOps                                                                | X            |               |                |
@@ -62,6 +61,7 @@ For more details, see the [full Integration Platform documentation](/product/int
 | Pivotal Tracker                                                                   | X                      |                          |
 | Redmine                                                                           | X                      |                          |
 | [Shortcut](/product/integrations/issue-tracking/shortcut/)                        | X                      |                          |
+| [SourceGraph](/product/integrations/issue-tracking/sourcegraph/)                  | X                      |                          |
 | [Teamwork](/product/integrations/issue-tracking/teamwork/)                        | X                      |                          |
 | Trello                                                                            | X                      |                          |
 
@@ -83,16 +83,16 @@ For more details, see the [full Integration Platform documentation](/product/int
 | ------------------------------------------------------------------ | --------------- |
 | [Amazon SQS](/product/integrations/data-visualization/amazon-sqs/) | X               |
 | [Grafana](/product/integrations/data-visualization/grafana/)       | X               |
-| Segment                                                            | X               |
+| [Segment](/product/integrations/data-visualization/segment/)       | X               |
 | [Splunk](/product/integrations/data-visualization/splunk/)         | X               |
 
 ## Session Replay
 
-| Integration                                                   | Link Issue to user sessions |
-| ------------------------------------------------------------- | --------------------------- |
-| [Atlas](/product/integrations/session-replay/atlas/)          | X                           |
-| [FullStory](https://www.npmjs.com/package/@sentry/fullstory)  | X                           |
-| [OpenReplay](https://docs.openreplay.com/integrations/sentry) | X                           |
+| Integration                                                    | Link Issue to user sessions |
+| -------------------------------------------------------------- | --------------------------- |
+| [Atlas](/product/integrations/session-replay/atlas/)           | X                           |
+| [FullStory](/product/integrations/session-replay/fullstory/)   | X                           |
+| [OpenReplay](/product/integrations/session-replay/openreplay/) | X                           |
 
 ## Debugging
 
diff --git a/src/docs/product/integrations/issue-tracking/index.mdx b/src/docs/product/integrations/issue-tracking/index.mdx
@@ -3,7 +3,7 @@ title: Issue Tracking
 sidebar_order: 40
 description: "Learn more about Sentry's issue tracking integrations."
 redirect_from:
-- /product/integrations/project-mgmt/
+  - /product/integrations/project-mgmt/
 ---
 
 Learn more about Sentry’s issue tracking integrations:
@@ -22,5 +22,6 @@ Learn more about Sentry’s issue tracking integrations:
 - Pivotal Tracker
 - Redmine
 - [Shortcut](/product/integrations/issue-tracking/shortcut/)
+- [SourceGraph](/product/integrations/issue-tracking/sourcegraph/)
 - [Teamwork](/product/integrations/issue-tracking/teamwork/)
 - Trello
diff --git a/src/docs/product/integrations/issue-tracking/sourcegraph.mdx b/src/docs/product/integrations/issue-tracking/sourcegraph.mdx
@@ -0,0 +1,17 @@
+---
+title: SourceGraph
+sidebar_order: 1
+redirect_from:
+  - /product/integrations/sourcegraph/
+description: "Learn about Sentry's SourceGraph integration."
+---
+
+<Alert level="warning">
+
+If you make changes to your organization slug, you will have to update your configuration on this integration. Find out more in the [troubleshooting guide](/product/integrations/troubleshooting).
+
+</Alert>
+
+This integration renders "View issues in Sentry" links next to error throwing statements in Sourcegraph. The links direct to the corresponding issues pages in Sentry. Sourcegraph is a universal code search and intelligence platform that helps developers understand, fix, and automate changes across their entire codebase.
+
+You can find [installation instructions here](https://github.com/sourcegraph/sourcegraph-sentry)
diff --git a/src/docs/product/integrations/notification-incidents/amixr/amixr.png b/src/docs/product/integrations/notification-incidents/amixr/amixr.png
diff --git a/src/docs/product/integrations/notification-incidents/amixr/index.mdx b/src/docs/product/integrations/notification-incidents/amixr/index.mdx
diff --git a/src/docs/product/integrations/notification-incidents/index.mdx b/src/docs/product/integrations/notification-incidents/index.mdx
@@ -6,8 +6,7 @@ description: "Learn more about Sentry's notification and incidents integrations.
 
 Learn more about Sentry's notification and incidents integrations:
 
-- [Amixr](/product/integrations/notification-incidents/amixr/)
-- Datadog
+- [Datadog](https://docs.datadoghq.com/integrations/sentry/)
 - [Microsoft Teams](/product/integrations/notification-incidents/msteams/)
 - OpsGenie
 - [PagerDuty](/product/integrations/notification-incidents/pagerduty/)
diff --git a/src/docs/product/integrations/notification-incidents/spikesh/amixr.png b/src/docs/product/integrations/notification-incidents/spikesh/amixr.png
diff --git a/src/docs/product/integrations/session-replay/fullstory.mdx b/src/docs/product/integrations/session-replay/fullstory.mdx
@@ -0,0 +1,17 @@
+---
+title: FullStory
+sidebar_order: 1
+redirect_from:
+  - /product/integrations/fullstory/
+description: "Learn about Sentry's FullStory integration."
+---
+
+<Alert level="warning">
+
+If you make changes to your organization slug, you will have to update your configuration on this integration. Find out more in the [troubleshooting guide](/product/integrations/troubleshooting).
+
+</Alert>
+
+The Sentry-FullStory integration seamlessly integrates the Sentry and FullStory platforms. When you look at a browser error in Sentry, you will see a link to the FullStory session replay at that exact moment in time. When you are watching a FullStory replay and your user experiences an error, you will see a link that will take you to that error in Sentry.
+
+You can find [installation instructions here](https://www.npmjs.com/package/@sentry/fullstory).
diff --git a/src/docs/product/integrations/session-replay/index.mdx b/src/docs/product/integrations/session-replay/index.mdx
@@ -7,5 +7,5 @@ description: "Learn more about Sentry's session replay integrations."
 Learn more about Sentry's session replay integrations:
 
 - [Atlas](/product/integrations/session-replay/atlas/)
-- [FullStory](https://www.npmjs.com/package/@sentry/fullstory)
-- [OpenReplay](https://docs.openreplay.com/integrations/sentry)
+- [FullStory](/product/integrations/session-replay/fullstory/)
+- [OpenReplay](/product/integrations/session-replay/openreplay/)
diff --git a/src/docs/product/integrations/session-replay/openreplay.mdx b/src/docs/product/integrations/session-replay/openreplay.mdx
@@ -0,0 +1,17 @@
+---
+title: OpenReplay
+sidebar_order: 1
+redirect_from:
+  - /product/integrations/openreplay/
+description: "Learn about Sentry's OpenReplay integration."
+---
+
+<Alert level="warning">
+
+If you make changes to your organization slug, you will have to update your configuration on this integration. Find out more in the [troubleshooting guide](/product/integrations/troubleshooting).
+
+</Alert>
+
+OpenReplay is a session replay tool for developers. Replay each user session alongside your front/backend logs and other data spread across your stack so you can immediately find, reproduce and fix bugs faster.
+
+You can find [installation instructions here](https://docs.openreplay.com/integrations/sentry).
diff --git a/src/docs/product/integrations/troubleshooting.mdx b/src/docs/product/integrations/troubleshooting.mdx
@@ -0,0 +1,25 @@
+---
+title: Troubleshooting Integrations
+sidebar_order: 5000
+description: "Learn more about troubleshooting and repairing your integrations"
+---
+
+Sentry integrates with many third party services to make your development experience easier. Unfortunately, we can’t always automatically update some of these services when critical data within Sentry is changed. This document is meant to help you navigate any odd behaviour that is to be expected when these settings are changed. In some cases, we may need your team’s manual intervention to get the integration working smoothly again.
+
+## If you've changed your organization slug
+
+- Any integration that create links directly to Sentry issues will continue creating correct links going forward, **but existing links will no longer work as expected**.
+  - For example, Slack notifications containing links to Sentry alerts, and Jira tickets which link to Sentry issues
+- Most [deployment integrations](https://docs.sentry.io/product/integrations/#deployment) use [Sentry CLI](https://github.com/getsentry/sentry-cli) under the hood, which requires providing your organization slug via the `SENTRY_ORG` environment variable. For these integrations to continue working, **you must manually update this variable on the appropriate service**.
+- If you are using any of the following integrations, you will have to have to manually update the organization slug to maintain functionality:
+
+  - [Bitbucket Pipelines](/product/releases/setup/release-automation/bitbucket-pipelines/)
+  - [GitHub Actions](/product/releases/setup/release-automation/github-actions/)
+  - [Netlify](/product/releases/setup/release-automation/netlify/)
+  - [Vercel](/product/integrations/deployment/vercel/)
+  - [Grafana](/product/integrations/data-visualization/grafana/)
+  - [Split](/product/integrations/feature-flag/split/)
+  - [Segment](/product/integrations/data-visualization/segment/)
+  - [FullStory](/product/integrations/session-replay/fullstory/)
+  - [OpenReplay](/product/integrations/session-replay/openreplay/)
+  - [SourceGraph](/product/integrations/issue-tracking/sourcegraph/)
diff --git a/src/docs/product/releases/setup/release-automation/bitbucket-pipelines/index.mdx b/src/docs/product/releases/setup/release-automation/bitbucket-pipelines/index.mdx
@@ -5,6 +5,12 @@ redirect_from:
 description: "Learn how Sentry and Bitbucket Pipelines automate release management and help identify suspect commits."
 ---
 
+<Alert level="warning">
+
+If you make changes to your organization slug, you will have to update your configuration on this integration. Find out more in the [troubleshooting guide](/product/integrations/troubleshooting).
+
+</Alert>
+
 The [Sentry Release Pipe](https://bitbucket.org/sentryio/sentry-new-release) automates Sentry release management in Bitbucket Pipelines with just one step. After sending Sentry release information, you'll be able to identify suspect commits that are likely the culprit for new errors. You'll also be able to apply source maps to see the original code in Sentry.
 
 For more details about Sentry release management concepts, see the full documentation on [releases](/product/releases/).
diff --git a/src/docs/product/releases/setup/release-automation/github-actions/index.mdx b/src/docs/product/releases/setup/release-automation/github-actions/index.mdx
@@ -5,6 +5,12 @@ redirect_from:
 description: "Learn how Sentry and GitHub Actions automate release management and help identify suspect commits."
 ---
 
+<Alert level="warning">
+
+If you make changes to your organization slug, you will have to update your configuration on this integration. Find out more in the [troubleshooting guide](/product/integrations/troubleshooting).
+
+</Alert>
+
 The [Sentry Release GitHub Action](https://github.com/marketplace/actions/sentry-release) automates Sentry release management in GitHub with just one step. After sending Sentry release information, you'll be able to identify suspect commits that are likely the culprit for new errors. Additionally, releases are used for applying source maps to view original, untransformed source code.
 
 For more details about Sentry release management concepts, see the full documentation on [releases](/product/releases/).
diff --git a/src/docs/product/releases/setup/release-automation/netlify/index.mdx b/src/docs/product/releases/setup/release-automation/netlify/index.mdx
@@ -5,6 +5,12 @@ redirect_from:
 description: "Learn how Sentry and Netlify automate release management and help identify suspect commits."
 ---
 
+<Alert level="warning">
+
+If you make changes to your organization slug, you will have to update your configuration on this integration. Find out more in the [troubleshooting guide](/product/integrations/troubleshooting).
+
+</Alert>
+
 The [Sentry Netlify build plugin](https://github.com/getsentry/sentry-netlify-build-plugin) automates Sentry release management in Netlify with just one step. After sending Sentry release information, you'll be able to identify suspect commits that are likely the culprit for new errors. You'll also be able to apply source maps to see the original code in Sentry.
 
 For more details about Sentry release management concepts, see the full documentation on [releases](/product/releases/).
