From d6fbcbdc63eaf8609ea3e1da2a13afeebe492233 Mon Sep 17 00:00:00 2001 From: k-fish Date: Fri, 24 Jun 2022 15:11:03 -0400 Subject: [PATCH] fix(ember): Update README docs to match sentry-docs There were quite a few updates especially around how config is preferred to be set, this cleans up the README to clarify and match with sentry-docs to avoid confusion. --- packages/ember/README.md | 65 ++++++++++++++++++++++------------------ 1 file changed, 36 insertions(+), 29 deletions(-) diff --git a/packages/ember/README.md b/packages/ember/README.md index 0b801a071ad4..9b87d13a8499 100644 --- a/packages/ember/README.md +++ b/packages/ember/README.md @@ -21,28 +21,41 @@ This package is an Ember addon that wraps `@sentry/browser`, with added function As with other Ember addons, run: `ember install @sentry/ember` -Then add the following config to `config/environment.js` +Then add the following to your `/app.js` ```javascript - ENV['@sentry/ember'] = { - sentry: { - dsn: '__DSN__' // replace __DSN__ with your DSN, - tracesSampleRate: 1.0, // Be sure to lower this for your production environment - } - }; + import * as Sentry from "@sentry/ember"; + + Sentry.init({ + dsn: '__DSN__' // replace __DSN__ with your DSN, + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for performance monitoring. + // We recommend adjusting this value in production, + tracesSampleRate: 1.0, + }); ``` + ### Usage -To use this SDK, call `InitSentryForEmber` before the application is initialized, in `app.js`. This will load Sentry config from `environment.js` for you. +To use this SDK, call `Sentry.init` before the application is initialized, in `app.js`. This will allow Sentry to capture information while your app is starting. +Any additional SDK settings can be modified via the usual config in `environment.js` for you, see the Additional Configuration section for more details. ```javascript import Application from '@ember/application'; import Resolver from 'ember-resolver'; import loadInitializers from 'ember-load-initializers'; import config from './config/environment'; -import { InitSentryForEmber } from '@sentry/ember'; +import * as Sentry from "@sentry/ember"; -InitSentryForEmber(); +Sentry.init({ + dsn: '__DSN__' // replace __DSN__ with your DSN, + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for performance monitoring. + // We recommend adjusting this value in production, + tracesSampleRate: 1.0, +}); export default class App extends Application { modulePrefix = config.modulePrefix; @@ -75,27 +88,12 @@ ENV['@sentry/ember'] = { // All component definitions will be added as spans. enableComponentDefinition: true, - - // See sentry-javascript configuration https://docs.sentry.io/error-reporting/configuration/?platform=javascript - sentry: {} }; ``` -You can also pass additional configuration for sentry-javascript directly to the `InitSentryForEmber` method. -This configuration will be merged with `ENV['@sentry/ember'].sentry`: - -```javascript -InitSentryForEmber({ - ignoreErrors: [ - /You appear to be offline/, - ], -}) -``` - -It is recommended to pass all static sentry-javascript configuration directly to `InitSentryForEmber`, and only keeping configuration that depends on the build environment/secrets in `config/environment.js`. Please note that due to how the environment config is serialized, any non-JSON-serializable config (like a regex) will not work properly when being kept in `config/environment.js`. - #### Disabling Performance + `@sentry/ember` captures performance by default, if you would like to disable the automatic performance instrumentation, you can add the following to your `config/environment.js`: ```javascript @@ -106,7 +104,9 @@ ENV['@sentry/ember'] = { ### Performance + #### Routes + If you would like to capture `beforeModel`, `model`, `afterModel` and `setupController` times for one of your routes, you can import `instrumentRoutePerformance` and wrap your route with it. @@ -124,11 +124,13 @@ export default instrumentRoutePerformance(MyRoute); ``` #### Runloop + The runloop queue durations are instrumented by default, as long as they are longer than a threshold (by default 5ms). This helps (via the render queue) capturing the entire render in case component render times aren't fully instrumented, such as when using glimmer components. If you would like to change the runloop queue threshold, add the following to your config: + ```javascript ENV['@sentry/ember'] = { minimumRunloopQueueDuration: 0, // All runloop queue durations will be added as spans. @@ -136,9 +138,11 @@ ENV['@sentry/ember'] = { ``` #### Components + Non-glimmer component render times will automatically get captured. If you would like to disable component render being instrumented, add the following to your config: + ```javascript ENV['@sentry/ember'] = { disableInstrumentComponents: true, // Will disable automatic instrumentation for components. @@ -147,6 +151,7 @@ ENV['@sentry/ember'] = { Additionally, components whose render time is below a threshold (by default 2ms) will not be included as spans. If you would like to change this threshold, add the following to your config: + ```javascript ENV['@sentry/ember'] = { minimumComponentRenderDuration: 0, // All (non-glimmer) component render durations will be added as spans. @@ -154,9 +159,11 @@ ENV['@sentry/ember'] = { ``` #### Glimmer components + Currently glimmer component render durations can only be captured indirectly via the runloop instrumentation. You can optionally enable a setting to show component definitions (which will indicate which components are being rendered) be adding the following to your config: + ```javascript ENV['@sentry/ember'] = { enableComponentDefinition: true, // All component definitions will be added as spans. @@ -165,7 +172,7 @@ ENV['@sentry/ember'] = { ### Supported Versions -`@sentry/ember` currently supports Ember **3.8+** for error monitoring. +`@sentry/ember` currently supports Ember **4.0+** for error monitoring. ### Previous Integration @@ -174,8 +181,8 @@ this Ember addon to offer more Ember-specific error and performancing monitoring ## Testing -You can find example instrumentation in the `dummy` application, which is also used for testing. To test with the dummy -application, you must pass the dsn as an environment variable. +For this package itself, you can find example instrumentation in the `dummy` application, which is also used for testing. +To test with the dummy application, you must pass the dsn as an environment variable. ```javascript SENTRY_DSN=__DSN__ ember serve