feat(dev-toolbar): Dev Toolbar Docs #12117
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
2 Skipped Deployments
|
Bundle ReportChanges will increase total bundle size by 1.8kB (0.01%) ⬆️. This is within the configured threshold ✅ Detailed changes
|
There was a problem hiding this comment.
super nit but looks like there's a bit of a black border on the images
| @@ -0,0 +1,50 @@ | |||
| --- | |||
| title: Dev Toolbar | |||
There was a problem hiding this comment.
| title: Dev Toolbar | |
| title: Developer Toolbar |
should we use the full name for the title?
There was a problem hiding this comment.
we want to use Dev Toolbar I think cc @jas-kas
There was a problem hiding this comment.
I believe we settled on Dev Toolbar moving forward
| --- | ||
| title: Dev Toolbar | ||
| sidebar_order: 120 | ||
| description: "Bring critical Sentry insights and tools directly into your web app for easier troubleshooting with the Dev Toolbar." |
There was a problem hiding this comment.
| description: "Bring critical Sentry insights and tools directly into your web app for easier troubleshooting with the Dev Toolbar." | |
| description: "Bring critical Sentry insights and tools directly into your web app for easier troubleshooting with the Developer Toolbar." |
|
|
||
|
|
||
| ## Deploying To Production & Dev Environments | ||
| Since the Dev Toolbar is deployed onto specific pages, it's strongly recommended that you consider which environments your app is deployed to should have the toolbar available. |
There was a problem hiding this comment.
| Since the Dev Toolbar is deployed onto specific pages, it's strongly recommended that you consider which environments your app is deployed to should have the toolbar available. | |
| Since the Dev Toolbar is deployed onto specific pages, it's strongly recommended that you consider which environments the toolbar should apply to. |
the wording is a bit confusing, don't 100% love my suggestion though
There was a problem hiding this comment.
I agree. I tried to come up with another wording but couldn't find anything better than what you suggested.
| | ----- | ----- | ----- | ----- | | ||
| | `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` | |
There was a problem hiding this comment.
Can you fix all these magic-quotes that got brought in from gdrive?
inside code snippets we should use ' and " instead of ”” and ‘’
and all quote marks should be consistent, i like ' for js strings.
There was a problem hiding this comment.
don't escape the backticks in any of the fields here, we're talking about some code thing, the backticks are markdown to make it look like code.
| | `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` | | |
| | `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` | |
| | `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 [Implement FeatureFlagAdapter](/product/dev-toolbar/setup//#implement-feature-flag-adapter) above | `undefined` | |
There was a problem hiding this comment.
Why did "Implement FeatureFlagAdapter" go above?
There was a problem hiding this comment.
Jasmin and I think that it makes more sense since you need to set up the feature flags adapter before you run the init (at least if you inject). Open to moving it back down if you have a differing opinion tho!
There was a problem hiding this comment.
Flip it back.
the way you're manually injecting it is a development thing, users won't do that in real life. and even if they did, they'd need to do it every time they opened a new browser window.
It's not a scenario that's in the docs, or that should happen often. We should organize the docs to someone can follow from steps 1 to N top to bottom. When a question pops up then it should be answered in the next section. Flag adaopters are optional, so should be lower down.
| </Alert> | ||
|
|
||
| You need to complete two steps to get the toolbar rendered on the page: | ||
| 1. Add or dynamically inject `<script defer src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>` into your web app. This script uses the `defer` attribute so that it does not block document parsing. The script tag can be inserted at the bottom of the page so it doesn’t block other critical Javascript. |
There was a problem hiding this comment.
| 1. Add or dynamically inject `<script defer src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>` into your web app. This script uses the `defer` attribute so that it does not block document parsing. The script tag can be inserted at the bottom of the page so it doesn’t block other critical Javascript. | |
| 1. Add or dynamically inject `<script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script>` into your web app. This script uses the `defer` attribute so that it does not block document parsing. The script tag can be inserted at the bottom of the page so it doesn’t block other critical Javascript. |
There was a problem hiding this comment.
This code feels long enough to just be a small snippet instead of inline.
There was a problem hiding this comment.
So are you saying that toolbar.min.js uses defer so is that why you removed it from the script tag?
There was a problem hiding this comment.
I removed defer because I think the following inline script could be messed up by that. Haven't tested defer or async attribute, so removed it for now.
|
|
||
| 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. | ||
| ```html | ||
| <script defer src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script> |
There was a problem hiding this comment.
| <script defer src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script> | |
| <script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script> |
| <head>...</head> | ||
| <body> | ||
| … | ||
| <script async src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script> |
There was a problem hiding this comment.
| <script async src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script> | |
| <script src="https://browser.sentry-cdn.com/sentry-toolbar/latest/toolbar.min.js"></script> |
| * this specific flag. | ||
| */ | ||
| urlTemplate?: undefined | ((name: string) => string | URL | 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 [Implement FeatureFlagAdapter](/product/dev-toolbar/setup//#implement-feature-flag-adapter) above | `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"` | |
There was a problem hiding this comment.
| | `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"` | | |
| | `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"` | |
| organizationSlug: ‘acme’, | ||
| projectIdOrSlug: ‘website’, | ||
| environment: ‘production’ |
There was a problem hiding this comment.
more quotes
| organizationSlug: ‘acme’, | |
| projectIdOrSlug: ‘website’, | |
| environment: ‘production’ | |
| organizationSlug: 'acme', | |
| projectIdOrSlug: 'website', | |
| environment: 'production' |
if i spotted these we should check everything again to make sure none others are still hanging around.
If it's a code related thing, then we should use backticks or regular quotes, but contractions like that's or it's can use the magic quotes because it's english language.
| If it's your first time setting up the Dev Toolbar, there will be a button with a link to Sentry's Dev Toolbar settings page to configure your domain. | ||
|  | ||
|
|
||
| You'll need to add your domain URL to Allowed Origins on Sentry's Dev Toolbar settings page. |
There was a problem hiding this comment.
| You'll need to add your domain URL to Allowed Origins on Sentry's Dev Toolbar settings page. | |
| You'll need to add your domain URL to Allowed Origins on Sentry's Settings > Project > Dev Toolbar page. |
something like that, i just want to mention that it's a Project specific settings page so people can find it. If it wasn't project specific i'd also suggest that we deep link to that page, but because it's project specific idk if we can make the link.
| You'll need to add your domain URL to Allowed Origins on Sentry's Dev Toolbar settings page. | ||
|  | ||
|
|
||
| Learn more about [deploying the toolbar to different environments](/product/dev-toolbar/setup/#deploying-to-production--dev-environments), and [conditionally inserting the toolbar script tag](/product/dev-toolbar/setup/#conditionally-inserting-script-tag). |
There was a problem hiding this comment.
These links go to the bottom sections of the next page, which seems weird. Why not the top?
It looks like this, there is is a link "Next: Set Up"
I feel like, we should link people to the top of the next page, and use the sentence here as a teaser for what sections are on that page...
| Learn more about [deploying the toolbar to different environments](/product/dev-toolbar/setup/#deploying-to-production--dev-environments), and [conditionally inserting the toolbar script tag](/product/dev-toolbar/setup/#conditionally-inserting-script-tag). | |
| Learn more about [setting up the toolbar](/project/-dev-toolbar/setup/) including configuring a feature flag provider and including the toolbar in different environments. |
maybe with all the links... but def the first link to the top of the page.
There was a problem hiding this comment.
Do we have a reason to believe people don't click on "Next Set Up >>" and that's why we are adding the link to this sentence? I think we shouldn't have any link because then I would be wondering if the link in the sentence takes me to the same place as the button.
| Learn more about [deploying the toolbar to different environments](/product/dev-toolbar/setup/#deploying-to-production--dev-environments), and [conditionally inserting the toolbar script tag](/product/dev-toolbar/setup/#conditionally-inserting-script-tag). | |
| Learn more about setting up the toolbar including configuring a feature flag provider and including the toolbar in different environments on the next page. |
| @@ -0,0 +1,50 @@ | |||
| --- | |||
| title: Dev Toolbar | |||
There was a problem hiding this comment.
I believe we settled on Dev Toolbar moving forward
| [GitHub](https://github.com/getsentry/sentry-toolbar/issues) if you have any feedback or concerns. | ||
| </Alert> | ||
|
|
||
| Developers spend a lot of time troubleshooting their web apps on local, staging, and production environments. The Sentry Dev 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 Dev 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. |
There was a problem hiding this comment.
| Developers spend a lot of time troubleshooting their web apps on local, staging, and production environments. The Sentry Dev 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 Dev 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. | |
| Developers spend a lot of time troubleshooting their web apps on local, staging, and production environments. The Sentry Dev 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 Dev 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. |
|
|
||
| Developers spend a lot of time troubleshooting their web apps on local, staging, and production environments. The Sentry Dev 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 Dev 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. | ||
|
|
||
|  |
There was a problem hiding this comment.
We should zoom in a bit on this screenshot and call out the Dev Toolbar, it's very hidden.
There was a problem hiding this comment.
I would say if possible this could even be a gif instead, so that the idea is to emphasize that it shouldn't get in the way of you browsing your site, but when you hover over it opens up (or is it when you click?)
|
|
||
| ## Issues Panel | ||
|
|
||
| The issues panel shows you your highest priority frontend [issues](https://docs.sentry.io/product/issues/) for the page you are currently viewing. From the Dev Toolbar, you can quickly jump into specific issues in Sentry to get more detailed information and take action (for example, 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. |
There was a problem hiding this comment.
| The issues panel shows you your highest priority frontend [issues](https://docs.sentry.io/product/issues/) for the page you are currently viewing. From the Dev Toolbar, you can quickly jump into specific issues in Sentry to get more detailed information and take action (for example, 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. | |
| The issues panel shows you your highest priority frontend [issues](https://docs.sentry.io/product/issues/) for the page you are currently viewing. From the Dev Toolbar, you can quickly jump into specific issues in Sentry to get more detailed information (e.g. Sentry project, issue title and description, and when the issue was first and last seen) and take action (e.g. 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. |
I don't know if the details I added are correct, but we should definitely be zooming into the issues panel and calling out what the information is in that image. I can't read a thing and on the Sentry one I actually don't know what all of the information is referring to.
There was a problem hiding this comment.
We also aren't mentioning here that just clicking on the Issue title will take you to your Issue in Sentry, I think that is important to call out here.
|
|
||
| ## 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 user feedback. The feedback can include misleading UX, broken links, typos, and so on, covering more bugs and suboptimal experiences than code-thrown errors. The feedback panel works by pulling feedback messages from [Sentry’s User Feedback Widget](https://docs.sentry.io/product/user-feedback/#user-feedback-widget). |
There was a problem hiding this comment.
| The feedback panel shows you the most recent user feedback messages for the page you are on, so you can more easily contextualize user feedback. The feedback can include misleading UX, broken links, typos, and so on, covering more bugs and suboptimal experiences than code-thrown errors. The feedback panel works by pulling feedback messages from [Sentry’s User Feedback Widget](https://docs.sentry.io/product/user-feedback/#user-feedback-widget). | |
| The feedback panel shows you the most recent user feedback messages for the page you are on, so you can more easily contextualize user feedback. 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](https://docs.sentry.io/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. |
| } | ||
| ``` | ||
|
|
||
| [MockFeatureFlagIntegration.tsx](https://github.com/getsentry/sentry-toolbar/blob/301c31d561a81e3fd8ffc9532aad3a60af685916/src/env/demo/MockFeatureFlagIntegration.tsx) is an example adapter to use as a reference. |
There was a problem hiding this comment.
This feels like it needs to be above the interface but I can't think of how I would word it.
| The following fields can be passed into the `.init()` function. | ||
|
|
||
| For example, a minimal configuration looks like: | ||
| ```javascript | ||
| window.SentryToolbar.init({ | ||
| organizationSlug: ‘acme’, | ||
| projectIdOrSlug: ‘website’, | ||
| environment: ‘production’ | ||
| }); | ||
| ``` |
There was a problem hiding this comment.
| The following fields can be passed into the `.init()` function. | |
| For example, a minimal configuration looks like: | |
| ```javascript | |
| window.SentryToolbar.init({ | |
| organizationSlug: ‘acme’, | |
| projectIdOrSlug: ‘website’, | |
| environment: ‘production’ | |
| }); | |
| ``` | |
| At minimum, you should be calling `.init()` with these three fiels: | |
| ```javascript | |
| window.SentryToolbar.init({ | |
| organizationSlug: ‘acme’, | |
| projectIdOrSlug: ‘website’, | |
| environment: ‘production’ | |
| }); |
And you can include any additional fields from this list:
| | `mountPoint (optional)` | `HTMLElement \| () => HTMLElement \| undefined` | Where to mount the toolbar in the DOM. | `document.body` | | ||
|
|
||
|
|
||
| ## Deploying To Production & Dev Environments |
There was a problem hiding this comment.
| ## Deploying To Production & Dev Environments | |
| ## Deploying To Dev, Staging, and Production Environments |
|
|
||
|
|
||
| ## Deploying To Production & Dev Environments | ||
| Since the Dev Toolbar is deployed onto specific pages, it's strongly recommended that you consider which environments your app is deployed to should have the toolbar available. |
There was a problem hiding this comment.
I agree. I tried to come up with another wording but couldn't find anything better than what you suggested.
|
|
||
| ## Conditionally Inserting Script Tag | ||
|
|
||
| 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`](http://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. |
There was a problem hiding this comment.
I'm assuming we just haven't made this page yet?
Product docs for the dev toolbar
Fixes #12097