diff --git a/docs/product/sentry-toolbar/faq.mdx b/docs/product/sentry-toolbar/faq.mdx deleted file mode 100644 index bb4eace96a38b..0000000000000 --- a/docs/product/sentry-toolbar/faq.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: FAQ -sidebar_order: 30 -description: "Frequently asked questions about the Sentry Toolbar." ---- - - - -Since the Sentry Toolbar will be visible to users within your app, it's important to consider which environments should render it. - -If your web application requires authentication to access: -- In development and staging, always initialize the Sentry Toolbar. -- In production, conditionally initialize the Sentry Toolbar when an employee is logged in. - -If you web application does not require authentication: -- In development and staging environments, initialize the Toolbar at all times. -- In production environments, do not initialize the Toolbar. - -Initializing the Sentry Toolbar allows all developers and testers to quickly go from the page they're looking at, back to Sentry for further debugging. -In production it can make it easier for developers to reproduce issues, but it should not be initialized for all users of the site -- only when an employee/engineer/etc visits. - -Once you decide where and when you want the Toolbar to appear, you'll write those conditions into your codebase. The specific implementation is something you'll need to write based on how your app works and how your team is set up. - - - - - -Implementing the specific conditions for initializing the Toolbar will vary from app to app and whichever framework or template library is in use. - -For example, the conditions to show the Toolbar in development and staging might look like this, if written in JavaScript: - -```html {tabTitle:CDN} {mdExpandTabs} - -``` -```javascript {tabTitle:React} -const env = process.env.ENVIRONMENT || 'development'; -const isDev = env === 'development' || env === 'staging'; - -useSentryToolbar({ - enabled: isDev, - initProps: { - ... - }, -}) -``` - - - - -If you're seeing the message "Connecting to ...' in the Toolbar, it means that the Toolbar is unable to connect to the Sentry server. This can happen for a few reasons: - -1. Check your browser console for a message like `Refused to frame 'https://my-org.sentry.io/toolbar/sentry/javascript/iframe/' because it violates the following Content Security Policy directive: "frame-src 'self'".` This means your site is not allowing the toolbar's iframe to load. To fix this you can add your sentry domain into the [`frame-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-src) directive in your CSP. The result would be a response header that says `Content-Security-Policy: frame-src my-org.sentry.io;` - -2. The Sentry server is down or unreachable. If this is the case check the following: - - Check the [Sentry status page](https://status.sentry.io/) to see if there are any issues. - - If the Sentry server is down, you can try again later. - - If the Sentry server is unreachable, you can try again later. - - - - -The [Sentry Toolbar](https://github.com/getsentry/sentry-toolbar) and the [JavaScript SDK](https://github.com/getsentry/sentry-javascript) are distinct features that we intentionally keep separated. - -Some of the differences between the two include: - - The Toolbar is a UI product focused on making it easier to find and take action on existing data, while the SDK functions as infrastructure to collect and send data to the server. - - The Toolbar has a different set of [dependencies](https://github.com/getsentry/sentry-toolbar/blob/main/package.json) and uses different browser APIs that the JavaScript SDK does not use. For example: the Toolbar will interact with things like cookies and local storage. By keeping these pieces of code separate, it's easier to audit the [SDK code on GitHub](https://github.com/getsentry/sentry-javascript) to verify that it is not persisting information inside end-users' browsers. - - The setup and deploy instruction are very different. The SDK is best deployed on staging and production environments, and can be configured easily with environment variables. The Sentry Toolbar requires special considerations to deploy it into production, usually by creating a condition so that it's only included for members of your own Sentry organization. - - - diff --git a/docs/product/sentry-toolbar/img/configure-domain.png b/docs/product/sentry-toolbar/img/configure-domain.png deleted file mode 100644 index 7b15ad79bd6db..0000000000000 Binary files a/docs/product/sentry-toolbar/img/configure-domain.png and /dev/null differ diff --git a/docs/product/sentry-toolbar/img/feature-flags-panel.png b/docs/product/sentry-toolbar/img/feature-flags-panel.png deleted file mode 100644 index d7047084a5b4c..0000000000000 Binary files a/docs/product/sentry-toolbar/img/feature-flags-panel.png and /dev/null differ diff --git a/docs/product/sentry-toolbar/img/feedback-panel.png b/docs/product/sentry-toolbar/img/feedback-panel.png deleted file mode 100644 index 17d63833ee4d3..0000000000000 Binary files a/docs/product/sentry-toolbar/img/feedback-panel.png and /dev/null differ diff --git a/docs/product/sentry-toolbar/img/issues-panel.png b/docs/product/sentry-toolbar/img/issues-panel.png deleted file mode 100644 index dc2d4c37b2f5f..0000000000000 Binary files a/docs/product/sentry-toolbar/img/issues-panel.png and /dev/null differ diff --git a/docs/product/sentry-toolbar/img/login-button.png b/docs/product/sentry-toolbar/img/login-button.png deleted file mode 100644 index c263bcf844f97..0000000000000 Binary files a/docs/product/sentry-toolbar/img/login-button.png and /dev/null differ diff --git a/docs/product/sentry-toolbar/img/login-popup.png b/docs/product/sentry-toolbar/img/login-popup.png deleted file mode 100644 index 85836e4380366..0000000000000 Binary files a/docs/product/sentry-toolbar/img/login-popup.png and /dev/null differ diff --git a/docs/product/sentry-toolbar/img/sentry-project-settings-toolbar.png b/docs/product/sentry-toolbar/img/sentry-project-settings-toolbar.png deleted file mode 100644 index 859c57cfd7e62..0000000000000 Binary files a/docs/product/sentry-toolbar/img/sentry-project-settings-toolbar.png and /dev/null differ diff --git a/docs/product/sentry-toolbar/img/toolbar-collapsed.png b/docs/product/sentry-toolbar/img/toolbar-collapsed.png deleted file mode 100644 index b58aff3c64a62..0000000000000 Binary files a/docs/product/sentry-toolbar/img/toolbar-collapsed.png and /dev/null differ diff --git a/docs/product/sentry-toolbar/index.mdx b/docs/product/sentry-toolbar/index.mdx deleted file mode 100644 index 43d92f08d2ccf..0000000000000 --- a/docs/product/sentry-toolbar/index.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Sentry Toolbar -sidebar_order: 510 -sidebar_section: platform -description: >- - Bring critical Sentry insights and tools directly into your web app for easier - troubleshooting with the Sentry Toolbar. -og_image: /og-images/product-sentry-toolbar.png ---- - - - The Sentry Toolbar is currently in **beta**. Beta features are still in progress and may have bugs. Please reach out on - [GitHub](https://github.com/getsentry/sentry-toolbar/issues) if you have any feedback or concerns. - - -Developers spend a lot of time troubleshooting their web apps on local, staging, and production environments. The Sentry Toolbar pulls data from [sentry.io](http://sentry.io) and surfaces relevant, actionable issues to you when you have the most context for understanding it: as you browse your own site. The Sentry Toolbar is a floating widget in your web app, offering meaningful Sentry insights for the specific page being viewed through three different **page-aware** panels: Issues, Feedback, and Feature Flags. - -![Collapsed Toolbar in context of a website](./img/toolbar-collapsed.png) - -## Issues Panel - -The issues panel shows you your highest priority frontend [issues](/product/issues/) for the page you are currently viewing. From the Sentry Toolbar, you can quickly jump into specific issues in Sentry to get more detailed information (examples: Sentry project, issue title, description, and when the issue was first and last seen) and take action (examples: assign to a team member or mark as resolved). With the issues panel, you can browse the pages that are most important to your business and understand the top issues impacting your user base. - -![Toolbar with the Issues Panel open](./img/issues-panel.png) - -## Feedback Panel - -The feedback panel shows you the most recent user feedback messages for the page you are on, so you can more easily contextualize it. The feedback often describes suboptimal experiences that are not strictly code-thrown errors, such as misleading UX, broken links, and typos. The feedback panel works by pulling feedback messages from [Sentry’s User Feedback Widget](/product/user-feedback/#user-feedback-widget). Just like with the Issues panel, clicking on a particular user feedback will take you to the full detailed User Feedback page within Sentry. - -![Toolbar with the Feedback Panel open](./img/feedback-panel.png) - -## Feature Flags Panel - -Feature flags are a powerful tool that allow you to control the visibility of features in your app, enabling you to ship, test, and experiment with confidence. The feature flag panel allows you to quickly view and override feature flags locally. You can override any feature flag to be `true` or `false` for your browser session, so you can verify its behavior and observe the impact it might have on errors. Learn more about how to [configure the feature flag panel](/product/sentry-toolbar/setup/#implement-feature-flag-adapter) and [what data Sentry can track](/product/issues/issue-details/feature-flags/) related to your feature flagging system. - - -![Toolbar with the Feature Flags Panel open](./img/feature-flags-panel.png) - -## Login Flow - -After setting up the Sentry Toolbar you’ll see a “Login to Sentry” button floating in the center of the page. To access any information from your Sentry organization, you have to click this button and login to Sentry. -![Toolbar login button](./img/login-button.png) - -After clicking the button, you will see a pop-up window for logging in to Sentry. -![Sentry log in pop up](./img/login-popup.png) - -If it's your first time [setting up the Sentry Toolbar](/product/sentry-toolbar/setup) , there will be a button with a link to Sentry's Toolbar settings page to configure your domain. -![Toolbar configure domains button](./img/configure-domain.png) - -Learn more about setting up the Toolbar, including configuring a feature flag provider and integrating the toolbar in different environments, on the next page. diff --git a/docs/product/sentry-toolbar/setup.mdx b/docs/product/sentry-toolbar/setup.mdx deleted file mode 100644 index c60a056ea6153..0000000000000 --- a/docs/product/sentry-toolbar/setup.mdx +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: Set Up Sentry Toolbar -sidebar_order: 10 -description: >- - Get started with Sentry's Toolbar, bringing critical Sentry insights and tools - into your web app to help your team troubleshoot more effectively. -og_image: /og-images/product-sentry-toolbar-setup.png ---- - - - The Sentry Toolbar is currently in **beta**. Beta features are still in progress and may have bugs. Please reach out on - [GitHub](https://github.com/getsentry/sentry-toolbar/issues) if you have any feedback or concerns. - - -## Pre-Requisites - -For the Sentry Toolbar to work best, [enable tracing](/platforms/javascript/tracing/) in your app. With tracing enabled, the Sentry Toolbar will be able to associate issues and feedback with the current URL in the browser location. - -## 1. Allow Domains - -Since the Sentry Toolbar will be visible to users within your app, it's important to consider which environments should render it. See the [FAQ: _"In what environments should I enable the Sentry Toolbar?"_](/product/sentry-toolbar/faq/#in-what-environments-should-i-enable-the-dev-toolbar) for tips. - -You will need to edit the [Project Settings](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/) page to allow the Toolbar to connect to Sentry. Add any production, staging, or development domains to the list. Only add domains that you trust and control to this list. - -![Sentry's Toolbar Settings Page](./img/sentry-project-settings-toolbar.png) - -You may also need to add your Sentry domain to the [`frame-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-src) directive in your CSP response headers. See the [FAQ: _"Why is the Toolbar stuck saying 'Connecting to ...'?"_](/product/sentry-toolbar/faq/#why-is-the-toolbar-stuck-saying-connecting-to-) for more information. - -## 2. Install - -If you are developing a React based application, it's time to add the Toolbar into your `package.json` file. - -Or, you can skip ahead to the next step to find the CDN configuration instructions. - -```bash {tabTitle: npm} -npm install --save @sentry/toolbar -``` -```bash {tabTitle: yarn} -yarn add @sentry/toolbar -``` - -## 3. Configure - -Finally, whether you have a React application or are loading the Toolbar from the CDN, you need to initialize the Toolbar using JavaScript. This will prompt any visitor to login to your Sentry organization. - -```javascript {tabTitle: React} {mdExpandTabs} -import {useSentryToolbar} from '@sentry/toolbar'; - -useSentryToolbar({ - // Remember to conditionally enable the Toolbar. - // This will reduce network traffic for users - // who do not have credentials to login to Sentry. - enabled, - - initProps: { - organizationSlug: 'acme', - projectIdOrSlug: 'website', - }, -}) -``` -```html {tabTitle: CDN} - -... - - ... - - - - - -``` - -See the [FAQ: _"How can I conditionally initialize the Toolbar?"_](/product/sentry-toolbar/faq/#how-can-i-conditionally-initialize-the-toolbar) for help implementing conditions for different environments. - -### Init Configuration Options - -At minimum, you must set `organizationSlug` and `projectIdOrSlug`. - -The complete list of options is here: - -| Option | Type | Description | Default Value | -| ------ | ---- | ----------- | ------------- | -| `organizationSlug` | `string` | The organization that users should login to. For example \'acme\' | *Required Value* | -| `projectIdOrSlug` | `string \| number` | The project for which this website/webapp is associated. | *Required Value* | -| `environment (optional)` | `string \| string[] \| undefined` | The environment of this deployment. Used to narrow search results in the Toolbar UI. Set to `undefined` or `""` or `[]` if you want to see results from all environments. | `undefined` | -| `placement (optional)` | `'right-edge' \| 'bottom-right-corner'` | Where to render the Toolbar on the screen. | `'right-edge'` | -| `theme (optional)` | `'system' \| 'dark' \| 'light'` | Whether to use dark or light mode. | `'system'` | -| `featureFlags (optional)` | `FeatureFlagAdapter \| undefined` | See [Feature Flag Panel](/product/sentry-toolbar/setup//#feature-flag-Panel) below | `undefined` | -| `sentryOrigin (optional)` | `string \| undefined` | The origin where Sentry can be found. Used for loading the connection to Sentry, and generating links to the website. For example: `'https://acme.sentry.io'` | `'https://sentry.io'` | -| `domId (optional)` | `string \| undefined` | The `id` given to the \ that is created to contain the Toolbar html. | `'sentry-toolbar'` | -| `debug (optional)` | `string \| undefined` | A comma separated string of debug targets to enable. Example: `'logging,state'`. If the list contains 'all' or 'true' then all targets will be enabled. Valid targets: `'logging' 'login-success' 'settings' 'state'` | `undefined` | -| `mountPoint (optional)` | `HTMLElement \| () => HTMLElement \| undefined` | Where to mount the Toolbar in the DOM. | `document.body` | -| `transactionToSearchTerm (optional)` | `(transactionName: string) => string` | Hook to transform transactionName into a search term | See [transactionToSearchTerm.ts](https://github.com/getsentry/sentry-toolbar/blob/main/src/lib/utils/transactionToSearchTerm.ts) | - -### Extra React Hook Options - -The React hook supports some other top-level options. The defaults values are: - -```javascript {tabTitle:React} -useSentryToolbar({ - initProps: { - organizationSlug: 'acme', - projectIdOrSlug: 'website', - }, - - // Optional: - enabled: true, - - // Optional: Either `version` or `cdn` - // If both are set then `cdn` will override `version` - version: 'latest', - cdn: 'https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js', -}) -``` - -| Options | Type | Description | Default Value | -| ------- | ---- | ----------- | ------------- | -| `enabled` | `boolean (optional)` | Conditionally initialize the toolbar. Set this to false to avoid requesting the toolbar code on the browser, or to safely unmount an existing toolbar instance | `true` | -| `version` | `string (optional)` | Request a speicifc version of the toolbar from the CDN. It's recommended to use `latest` for automatic updates. See https://github.com/getsentry/sentry-toolbar/releases for a list of available release tags. | `'latest'` | -| `cdn` | `string (optional)` | Overrides the `version` field above. Setting the CDN is useful if you want to self-host a specific version of the Toolbar. | `'https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js'` | - - -### Unmounting the Toolbar - -If you have called `SentryToolbar.init({...})` to render the Toolbar, but now want to manually remove or unmount it from the page, you can call the cleanup function that is returned from `init()`. This will unmount all the injected HTML and CSS. Login credentials will not be removed, so you can re-insert the toolbar and still be authenticated. - -If you are using the React hook, then the toolbar will unmount when the React component is unmounted. Or if you set `enabled: false`. - -```javascript -const unmountToolbar = window.SentryToolbar.init({ ... }); - -// sometime later... -unmountToolbar(); -``` -```javascript {tabTitle:React} -useSentryToolbar({ - enabled: false, // The toolbar will not be mounted - initProps: { - ... - }, -}) -``` - -## Feature Flag Panel - - - If you're using feature flags inside your product then also setup [Feature Flag Evaluation and Change Tracking](/platforms/javascript/feature-flags/) within your SDK. - - -In order to integrate your feature flagging platform with the Sentry Toolbar, you will need an adapter that can read flag data from your provider. It will also store and retrieve a list of overrides to apply to your local browser session. - -There is a built-in `OpenFeatureAdapter` that is compatible with the [open-feature/js-sdk-contrib](https://github.com/open-feature/js-sdk-contrib). To use it, call the `SentryToolbar.OpenFeatureAdapter` implementation. - -```html {tabTitle: CDN} {mdExpandTabs} - -``` -```typescript {tabTitle: React} -import {OpenFeature} from '@openfeature/web-sdk'; -import {FlagdWebProvider} from '@openfeature/flagd-web-provider'; - -// Define your provider -const provider = new FlagdWebProvider({...}); - -// Set the provider into the OpenFeature SDK -OpenFeature.setProvider(provider); - -window.SentryToolbar.init({ - ... - // Set the provider into the OpenFeatureAdapter - featureFlags: window.SentryToolbar.OpenFeatureAdapter({provider}) -}); -``` - -You can also create your own adapter by implementing the [`FeatureFlagAdapter` interface](https://github.com/getsentry/sentry-toolbar/blob/main/packages/toolbar/src/types/featureFlags.ts). - -The adapter interface is: -```typescript -type FlagValue = boolean | string | number | undefined; -type FlagMap = Record; -interface FeatureFlagAdapter { - /** - * All known flag names and their evaluated values. - */ - getFlagMap: () => Promise; - - /** - * Any overridden or manually set flags and values. - */ - getOverrides: () => Promise; - - /** - * Manually set a flag to be a specific value, overriding the evaluated value. - */ - setOverride: (name: string, override: FlagValue) => void; - - /** - * A callback to clear all overrides from this browser. - */ - clearOverrides: () => void; - - /** - * Deeplink into your external feature-flag provider and find out more about - * this specific flag. - */ - urlTemplate?: undefined | ((name: string) => string | URL | undefined); -} -``` - -[MockFeatureFlagAdapter.tsx](https://github.com/getsentry/sentry-toolbar/blob/main/src/env/demo/MockFeatureFlagAdapter.tsx) is an example adapter to use as a reference. diff --git a/redirects.js b/redirects.js index 8fc319734b57a..635c2a623020a 100644 --- a/redirects.js +++ b/redirects.js @@ -933,7 +933,11 @@ const userDocsRedirects = [ }, { source: '/product/dev-toolbar/:path*', - destination: '/product/sentry-toolbar/:path*', + destination: 'https://github.com/getsentry/sentry-toolbar', + }, + { + source: '/product/sentry-toolbar/:path*', + destination: 'https://github.com/getsentry/sentry-toolbar', }, { source: '/organization/integrations/launchdarkly/',