Skip to content

Commit 3b421d2

Browse files
ryan953michellewzhangc298leecoolguyzone
authored
docs(toolbar): Update Toolbar setup docs (#12566)
* docs(toolbar): Update Toolbar setup docs * Apply suggestions from code review Co-authored-by: Michelle Zhang <[email protected]> Co-authored-by: Catherine Lee <[email protected]> * notes from code review * better setup flow * remove link to prev section * Apply suggestions from code review Co-authored-by: Alex Krawiec <[email protected]> --------- Co-authored-by: Michelle Zhang <[email protected]> Co-authored-by: Catherine Lee <[email protected]> Co-authored-by: Alex Krawiec <[email protected]>
1 parent 641000a commit 3b421d2

File tree

2 files changed

+131
-77
lines changed

2 files changed

+131
-77
lines changed

‎docs/product/dev-toolbar/img/sentry-project-settings-toolbar.png

17.5 KB
Loading

‎docs/product/dev-toolbar/setup.mdx

Lines changed: 131 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: "Set Up"
2+
title: "Set Up Dev Toolbar"
33
sidebar_order: 10
44
description: "Get started with Sentry's Dev Toolbar, bringing critical Sentry insights and tools into your web app to help your team troubleshoot more effectively."
55
---
@@ -9,50 +9,84 @@ description: "Get started with Sentry's Dev Toolbar, bringing critical Sentry in
99
[GitHub](https://github.com/getsentry/sentry-toolbar/issues) if you have any feedback or concerns.
1010
</Alert>
1111

12-
## Set Up Your Web App
12+
## Pre-Requisites
1313

14-
<Alert level="warning">
15-
[Enabling tracing](/platforms/javascript/tracing/) is a prerequisite to using the Dev Toolbar. Tracing is used to collect page-specific issues and feedback through transactions.
16-
</Alert>
14+
For the Sentry Dev Toolbar to work best, [enable tracing](/platforms/javascript/tracing/) in your app. With tracing enabled, the Dev Toolbar will be able to associate issues and feedback with the current URL in the browser location.
1715

18-
You need to complete two steps to get the toolbar rendered on the page:
19-
1. Add or dynamically inject the following script into your web app:
20-
```html
21-
<script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>
22-
```
23-
It is recommended that you add the script tag at the bottom of the page so it doesn’t block other critical JavaScript.
24-
25-
2. Call `window.SentryToolbar.init(initConfig)` to set up a toolbar instance on each page where you want to see the Dev Toolbar. Take care to also [conditionally load the toolbar in your production environment](#deploying-to-production-environments).
26-
```html
27-
<html>
28-
<head>...</head>
29-
<body>
30-
...
31-
<script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>
32-
<script>
33-
window.SentryToolbar.init({ ... });
34-
</script>
35-
</body>
36-
</html>
37-
```
38-
39-
3. Edit [Project Settings](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/) in Sentry so the Toolbar is allowed to connect from your dev, staging, and production domains.
40-
![Sentry's Dev Toolbar Settings Page](./img/sentry-project-settings-toolbar.png)
41-
42-
43-
### Unmounting The Toolbar
44-
45-
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.
46-
```javascript
47-
const unmountToolbar = window.SentryToolbar.init({ ... });
16+
## 1. Choose Deploy Environments
4817

49-
// sometime later...
50-
unmountToolbar();
18+
Since the Dev Toolbar will be visible to users within your app, it's important to consider which environments should render it.
19+
20+
In dev and staging environments, include the Toolbar so that all developers and testers can use it and quickly go from the page they're looking at back to Sentry for further debugging.
21+
22+
In production environments, the Dev Toolbar can make it easier to reproduce real issues your users are having. However the Toolbar should not be rendered for all users of the site -- only when an employee/engineer/etc visits.
23+
24+
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 dev team is set up.
25+
26+
For example, the conditions to show show the Toolbar in dev and staging might look like this:
27+
28+
```typescript
29+
const env = process.env.SENTRY_ENVIRONMENT || 'development';
30+
31+
const isDev = env === 'development' || env === 'staging';
32+
if (isDev) {
33+
// Enable the Dev Toolbar here...
34+
}
5135
```
5236

53-
## Init Configuration Options
37+
Or if your web application requires authentication to access, you could add a conditional where the Dev Toolbar is shown always when deployed to development **and** staging, but in production only show the Toolbar **if** an employee is logged in.
38+
39+
## 2. Allow Domains
40+
41+
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 by configuring your dev, staging, and production domains. Only add domains that you trust and control to this list.
42+
43+
![Sentry's Dev Toolbar Settings Page](./img/sentry-project-settings-toolbar.png)
44+
45+
## 3. Install
5446

55-
The following options can be passed into the `.init()` function.
47+
Next you must include the Toolbar code in your app:
48+
49+
```html {tabTitle: CDN}
50+
<!--
51+
Put this at the bottom of your page
52+
so it doesn’t block other critical JavaScript.
53+
-->
54+
<script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>
55+
```
56+
```typescript {tabTitle: React}
57+
// An NPM package is under development
58+
// In the meantime, go here for instructions to create a React hook manually:
59+
// https://github.com/getsentry/sentry-toolbar/blob/main/docs/conditional-script.md
60+
```
61+
62+
Remember to conditionally include the Toolbar code only in environments that need it. This will help reduce network traffic for your users who do not have the credentials needed to login.
63+
64+
## 4. Configure
65+
66+
Finally, call `SentryToolbar.init(initConfig)` to render a Toolbar instance on each page where you want to see the Dev Toolbar. This will prompt any visitor to the page to login to your Sentry organization.
67+
68+
```html {tabTitle: CDN}
69+
<html>
70+
<head>...</head>
71+
<body>
72+
...
73+
<script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>
74+
<script>
75+
window.SentryToolbar.init({ ... });
76+
</script>
77+
</body>
78+
</html>
79+
```
80+
```typescript {tabTitle:React}
81+
// An NPM package is under development
82+
// In the meantime, go here for instructions to create a React hook manually:
83+
// https://github.com/getsentry/sentry-toolbar/blob/main/docs/conditional-script.md
84+
```
85+
86+
If the toolbar `<script>` is included on your site, and `SentryToolbar.init()` is called, then a "Login to Sentry" button will be visible to the public. This is not ideal, but your data in Sentry will still be safe as users outside of your Sentry organization will not be able to login.
87+
88+
89+
### Init Configuration Options
5690

5791
At minimum, you should be calling `.init()` with these two options:
5892
```javascript
@@ -61,29 +95,78 @@ window.SentryToolbar.init({
6195
projectIdOrSlug: 'website',
6296
});
6397
```
64-
And you can include any additional options from this list:
98+
99+
And you can also include any additional options from this list:
65100

66101
| Option | Type | Description | Default Value |
67102
| ----- | ----- | ----- | ----- |
68103
| `organizationSlug` | `string` | The organization that users should login to. For example \'acme\' | *Required Value* |
69104
| `projectIdOrSlug` | `string \| number` | The project for which this website/webapp is associated. | *Required Value* |
70105
| `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` |
71-
| `placement (optional)` | `'right-edge' \| 'bottom-right-corner'` | Where to render the toolbar on the screen. | `'right-edge'` |
106+
| `placement (optional)` | `'right-edge' \| 'bottom-right-corner'` | Where to render the Toolbar on the screen. | `'right-edge'` |
72107
| `theme (optional)` | `'system' \| 'dark' \| 'light'` | Whether to use dark or light mode. | `'system'` |
73-
| `featureFlags (optional)` | `FeatureFlagAdapter \| undefined` | See [Implement FeatureFlagAdapter](/product/dev-toolbar/setup//#implement-feature-flag-adapter) below | `undefined` |
108+
| `featureFlags (optional)` | `FeatureFlagAdapter \| undefined` | See [Feature Flag Panel](/product/dev-toolbar/setup//#feature-flag-Panel) below | `undefined` |
74109
| `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'` |
75-
| `domId (optional)` | `string \| undefined` | The `id` given to the \<div\> that is created to contain the toolbar html. | `'sentry-toolbar'` |
110+
| `domId (optional)` | `string \| undefined` | The `id` given to the \<div\> that is created to contain the Toolbar html. | `'sentry-toolbar'` |
76111
| `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` |
77-
| `mountPoint (optional)` | `HTMLElement \| () => HTMLElement \| undefined` | Where to mount the toolbar in the DOM. | `document.body` |
112+
| `mountPoint (optional)` | `HTMLElement \| () => HTMLElement \| undefined` | Where to mount the Toolbar in the DOM. | `document.body` |
113+
114+
### Unmounting the Toolbar
115+
116+
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.
117+
```javascript
118+
const unmountToolbar = window.SentryToolbar.init({ ... });
78119

79-
## Implement Feature Flag Adapter
120+
// sometime later...
121+
unmountToolbar();
122+
```
123+
124+
## Feature Flag Panel
125+
126+
<Alert>
127+
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.
128+
</Alert>
129+
130+
In order to integrate your feature flagging platform with the Dev 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.
131+
132+
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.
133+
134+
```html {tabTitle: CDN}
135+
<script>
136+
// Define your provider
137+
const provider = new FlagdWebProvider({...});
80138
81-
In order to integrate your feature flagging platform with the Dev Toolbar, you will need an adapter that can read flag data from your provider, and also store and retrieve a list of overrides to apply to your local browser session.
139+
// Set the provider into the OpenFeature SDK
140+
OpenFeature.setProvider(provider);
82141
83-
We plan to [create adapters for OpenFeature and LaunchDarkly](https://github.com/getsentry/sentry-toolbar/issues/150) soon.
142+
window.SentryToolbar.init({
143+
...
144+
// Set the provider into the OpenFeatureAdapter
145+
featureFlags: window.SentryToolbar.OpenFeatureAdapter({provider})
146+
});
147+
</script>
148+
```
149+
```typescript {tabTitle: React}
150+
import {OpenFeature} from '@openfeature/web-sdk';
151+
import {FlagdWebProvider} from '@openfeature/flagd-web-provider';
152+
153+
// Define your provider
154+
const provider = new FlagdWebProvider({...});
155+
156+
// Set the provider into the OpenFeature SDK
157+
OpenFeature.setProvider(provider);
158+
159+
window.SentryToolbar.init({
160+
...
161+
// Set the provider into the OpenFeatureAdapter
162+
featureFlags: window.SentryToolbar.OpenFeatureAdapter({provider})
163+
});
164+
```
165+
166+
You can also create your own adapter by implementing the [`FeatureFlagAdapter` interface](https://github.com/getsentry/sentry-toolbar/blob/main/src/lib/types/featureFlags.ts).
84167

85168
The adapter interface is:
86-
```javascript
169+
```typescript
87170
type FlagValue = boolean | string | number | undefined;
88171
type FlagMap = Record<string, FlagValue>;
89172
interface FeatureFlagAdapter {
@@ -116,32 +199,3 @@ interface FeatureFlagAdapter {
116199
```
117200

118201
[MockFeatureFlagAdapter.tsx](https://github.com/getsentry/sentry-toolbar/blob/main/src/env/demo/MockFeatureFlagAdapter.tsx) is an example adapter to use as a reference.
119-
120-
121-
## Deploying To Dev and Staging Environments
122-
Since the Dev Toolbar is deployed onto specific pages, it's strongly recommended that you consider which environments the toolbar should apply to.
123-
124-
In dev and staging environments, you might want to *unconditionally* include the toolbar so that all developers and testers can use it and quickly go from the page they're looking at back to Sentry for further debugging.
125-
126-
The code might look like this:
127-
```javascript
128-
const env = process.env.SENTRY_ENVIRONMENT || 'development';
129-
130-
const isDev = env === 'development' || env === 'staging';
131-
if (isDev ) {
132-
SentryToolbar.init({ ... });
133-
}
134-
```
135-
136-
## Deploying to Production Environments
137-
138-
In production, it's strongly recommended to *conditionally* include the Dev Toolbar `<script>` tag so that only members of your Sentry organization can see it. The specific implementation for conditionally including the Dev Toolbar is something you'll need to write based on how your app works and how your dev team is set up.
139-
140-
For example, if your web application requires authentication to access, you could add a conditional where the Dev Toolbar is shown always when deployed to development **and** staging, but in production only show the toolbar **if** an employee is logged in.
141-
142-
If the toolbar `<script>` is accidentally included on your site, and `SentryToolbar.init()` is called, then a "Login to Sentry" button will be visible to the public. This is not ideal, but your data in Sentry will still be safe as users outside of your Sentry organization will not be able to authenticate themselves.
143-
144-
## Conditionally Inserting Script Tag
145-
146-
It's possible to dynamically insert the script tag inside a single-page app, prior to calling `SentryToolbar.init()`, so that it’s only visible to authorized users. See [`docs/conditional-script.md`](https://github.com/getsentry/sentry-toolbar/blob/main/docs/conditional-script.md) for example code. This will help reduce network traffic for your users because they do not have the credentials needed to login.
147-
This example code will be eventually implemented as an NPM package, but for now it can be done manually.

0 commit comments

Comments
 (0)