From c7f8b5a0bb62efa1ca3067a8c801d37f2d67f459 Mon Sep 17 00:00:00 2001 From: Fiona Artiaga Date: Mon, 14 Sep 2020 14:59:07 -0700 Subject: [PATCH 1/7] minimize getting started --- src/includes/capture-error/javascript.mdx | 8 +- src/includes/configure-verify/javascript.mdx | 24 ++++ src/includes/install-package/javascript.mdx | 7 ++ .../common/configuration/capture.mdx | 13 ++ src/platforms/javascript/index.mdx | 118 ++++-------------- 5 files changed, 75 insertions(+), 95 deletions(-) create mode 100644 src/includes/configure-verify/javascript.mdx create mode 100644 src/includes/install-package/javascript.mdx diff --git a/src/includes/capture-error/javascript.mdx b/src/includes/capture-error/javascript.mdx index 58f48d18b96b1..8e4c37b8dbd03 100644 --- a/src/includes/capture-error/javascript.mdx +++ b/src/includes/capture-error/javascript.mdx @@ -1,6 +1,8 @@ -In JavaScript you can pass an error object to `captureException()` to get it captured -as event. It's possible to throw strings as errors in which case no traceback -can be recorded. +By including and configuring Sentry, our JavaScript SDK automatically attaches global handlers to _capture_ uncaught exceptions and unhandled promise rejections, as described in the official ECMAScript 6 standard. You can disable this default behavior by changing the `onunhandledrejection` option to `false` in your GlobalHandlers integration and manually hook into each event handler, then call `Sentry.captureException` or `Sentry.captureMessage` directly. + +You may also need to manage your configuration if you are using a third-party library to implement promises. Also, remember that browsers often implement security measures that can block error reporting when serving script files from different origins. + +In JavaScript you can pass an error object to `captureException()` to get it captured as event. It's possible to throw strings as errors in which case no traceback can be recorded. ```javascript try { diff --git a/src/includes/configure-verify/javascript.mdx b/src/includes/configure-verify/javascript.mdx new file mode 100644 index 0000000000000..363b30bd33992 --- /dev/null +++ b/src/includes/configure-verify/javascript.mdx @@ -0,0 +1,24 @@ +```javascript {tabTitle: ESM} +import * as Sentry from "@sentry/browser"; +import { Integrations } from "@sentry/tracing"; +Sentry.init({ + dsn: "___PUBLIC_DSN___", + myUndefinedFunction(); // To test your setup + release: "my-project-name@" + process.env.npm_package_version, // To set your release version + integrations: [new Integrations.BrowserTracing()], + tracesSampleRate: 1.0, // Be sure to lower this in production +}); + + +``` + +```javascript {tabTitle: ESM} +import * as Sentry from "@sentry/browser"; +import { Integrations } from "@sentry/tracing"; +Sentry.init({ + dsn: "___PUBLIC_DSN___", + release: "my-project-name@" + process.env.npm_package_version, + integrations: [new Integrations.BrowserTracing()], + tracesSampleRate: 1.0, // Be sure to lower this in production +}); +``` diff --git a/src/includes/install-package/javascript.mdx b/src/includes/install-package/javascript.mdx new file mode 100644 index 0000000000000..91a1d81e6924c --- /dev/null +++ b/src/includes/install-package/javascript.mdx @@ -0,0 +1,7 @@ +```bash {tabTitle: ESM} +# Using yarn +$ yarn add @sentry/browser @sentry/tracing + +# Using npm +$ npm install --save @sentry/browser @sentry/tracing +``` diff --git a/src/platforms/common/configuration/capture.mdx b/src/platforms/common/configuration/capture.mdx index 3d0ff2cb15657..ee27da57bc383 100644 --- a/src/platforms/common/configuration/capture.mdx +++ b/src/platforms/common/configuration/capture.mdx @@ -7,6 +7,19 @@ description: "Learn more about automatically reporting errors, exceptions, and r Sentry's SDK hooks into your runtime environment and automatically reports errors, exceptions, and rejections. + + + +Key terms: + +- An _event_ is one instance of sending data to Sentry. Generally, this data is an error or exception. +- An _issue_ is a grouping of similar events. +- The reporting of an event is called _capturing_. + When an event is captured, it’s sent to Sentry. + + + + The most common form of capturing is to capture errors. What can be captured as an error varies by platform. In general, if you have something that looks like an exception it can be captured. For some SDKs you can also omit the argument to `capture_exception` and Sentry will attempt to capture the current exception. It can also be useful to manually report errors or messages to Sentry. Separately to capturing you can also record the breadcrumbs that lead up to an event. Breadcrumbs are different from events: they will not create an event in Sentry, but will be buffered until the next event is sent. Learn more about breadcrumbs in our [Breadcrumbs documentation](/platforms/javascript/enriching-error-data/breadcrumbs/). diff --git a/src/platforms/javascript/index.mdx b/src/platforms/javascript/index.mdx index cc4f50ff32cb7..2120d2d51844f 100644 --- a/src/platforms/javascript/index.mdx +++ b/src/platforms/javascript/index.mdx @@ -23,119 +23,53 @@ Using a framework? Take a look at our specific guides to get started. ## Install the Package -Sentry captures data by using an SDK within your application’s runtime. Add the Sentry SDK to your application: +Sentry captures data by using an SDK within your application’s runtime: -```bash {tabTitle: ESM} -# Using yarn -$ yarn add @sentry/browser + -# Using npm -$ npm install --save @sentry/browser -``` - - - - -If prefer to use CDN to install our SDK, please see our documentation for [installing with CDN](/platforms/javascript/configuration/install-cdn). - - - - -## Configure and Verify - -`init` Sentry as soon as possible in your app, to make sure it can monitor everything that follows it. Once this is done, all unhandled exceptions are automatically captured by Sentry. - -The snippet below includes an intentional error, so you can test that everything is working as soon as you set it up. To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. - -```javascript {tabTitle: ESM} -import * as Sentry from "@sentry/browser"; - -Sentry.init({ dsn: "___PUBLIC_DSN___" }); - -myUndefinedFunction(); // To test your setup -``` - -## Capture Errors - - - -Key terms: - -- An _event_ is one instance of sending data to Sentry. Generally, this data is an error or exception. -- An _issue_ is a grouping of similar events. -- The reporting of an event is called _capturing_. - When an event is captured, it’s sent to Sentry. - - - - -By including and configuring Sentry, our JavaScript SDK automatically attaches global handlers to _capture_ uncaught exceptions and unhandled promise rejections, as described in the official ECMAScript 6 standard. You can disable this default behavior by changing the `onunhandledrejection` option to `false` in your GlobalHandlers integration and manually hook into each event handler, then call `Sentry.captureException` or `Sentry.captureMessage` directly. - -You may also need to manage your configuration if you are using a third-party library to implement promises. Also, remember that browsers often implement security measures that can block error reporting when serving script files from different origins. - -Learn more about how to manually capture errors or enable message capture with Sentry's JavaScript SDK in [Advanced Usage](/platforms/javascript/configuration/capture). - -### Automatically Enrich Error Data - -Events sent by the JavaScript SDK to Sentry are enriched with data that helps identify the source of the event. Much of this data is sent automatically - including the error context and environment - as well as the trail of events that led up to the event, which we call breadcrumbs. You don't need to configure these, though you may modify them. + -Learn more about the data sent to with events in [Event Context](/platforms/javascript/enriching-error-data/additional-data/). +If you are using our CDN, please see our documentation for [installing with CDN](/platforms/javascript/configuration/install-cdn). -### Set the Release Version + -When you configure Sentry to include the version of your application, Sentry can tell you about regressions as well as detailed information about the suspect commit. You will also need releases for source maps. +## Initialize -Use the `process.env.npm_package_version`: +`init` Sentry as soon as possible in your app. Once this is done, all unhandled exceptions are automatically captured by Sentry. -```JavaScript -Sentry.init({ - dsn: '___PUBLIC_DSN___', - release: 'my-project-name@' + process.env.npm_package_version, -}); -``` +This snippet includes: +- an intentional error as a test that everything is working as soon as you set it up. +- the [release](/product/releases/) of your application, using `process.env.npm_package_version`, which both enables [source maps](/platforms/javascript/sourcemaps/) as well as tracking of regressions and suspect commits. +- our [performance monitoring](/product/performance/) package. -Learn more about what releases can do in [our documentation for releases](/product/releases/). + -### Upload Source Maps + -We **highly recommend** you incorporate source maps to receive the full benefit of error tracking and monitoring. See our [source maps documentation](/platforms/javascript/sourcemaps/) to learn more. +We'll automatically assign you a Data Source Name (DSN), which looks like a standard URL. It's required by Sentry and configures the protocol, public key, server address, and project identifier. If you forget it, view _Settings -> Projects -> Client Keys (DSN)_ in sentry.io. -## Monitor Performance + -Install performance monitoring using Sentry’s JavaScript SDK using both the `@sentry/browser` and `@sentry/tracing` packages: +To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. Explore [Performance](/product/performance/) by selecting it from the sidebar, then viewing the homepage. -```bash {tabTitle: ESM} -# Using yarn -$ yarn add @sentry/browser @sentry/tracing -# Using npm -$ npm install --save @sentry/browser @sentry/tracing -``` +## Next Steps - +- **[Upload Source Maps](/platforms/javascript/sourcemaps/)** -If you are using our CDN, please see our documentation for [installing with CDN](/platforms/javascript/configuration/install-cdn). + We **highly recommend** you incorporate source maps to receive the full benefit of error tracking and monitoring. - +- **[Configure `tracesSampleRate`](/platforms/javascript/configuration/filtering/)** -Initialize the integration in your call to `Sentry.init`: + The example configuration will transmit 100% of captured transactions; lower this value in production to avoid consuming your quota too quickly. -```javascript {tabTitle: ESM} -import * as Sentry from "@sentry/browser"; -import { Integrations } from "@sentry/tracing"; -Sentry.init({ - dsn: "___PUBLIC_DSN___", - release: "my-project-name@" + process.env.npm_package_version, - integrations: [new Integrations.BrowserTracing()], - tracesSampleRate: 1.0, // Be sure to lower this in production -}); -``` +- **[Learn More About Releases](/product/releases/)** -Performance data is transmitted using a new event type called “transactions”, which you can learn about in [Distributed Tracing](/product/performance/distributed-tracing/). To capture transactions, install the performance package and configure your SDK to set the `tracesSampleRate` configuration to a nonzero value. The example configuration above will transmit 100% of captured transactions; lower this value in production to avoid consuming your quota too quickly. + Releases help you track regressions introduced in a new release, predict which commit caused an issue, and more. Releases are also used for applying source maps to minified JavaScript to view original, untransformed source code. -Learn more about sampling in [Filtering Events Reported to Sentry](/platforms/javascript/configuration/filtering). +- **[Learn More About Performance Monitoring](/product/performance/)** -## Next Steps + Performance monitoring gives your team full-stack visibility to trace slow-loading pages back to its API call as well as surface all related errorsand resolve bottlenecks. - **[Manage Configuration Options](./configuration/)** @@ -149,7 +83,7 @@ Learn more about sampling in [Filtering Events Reported to Sentry](/platforms/ja Integrations extend the functionality of our JavaScript SDK to cover common libraries and environments automatically. Learn more about our default and pluggable integrations. -- **[Troubleshooting](./troubleshooting/)** +- **[Review Troubleshooting](./troubleshooting/)** If you need help solving issues with Sentry's JavaScript SDK, you can read the edge cases documented here. From f6cdf34c6e61f70a5e4083d5e5e9c49fa60d95b1 Mon Sep 17 00:00:00 2001 From: Fiona Artiaga Date: Mon, 14 Sep 2020 17:05:26 -0700 Subject: [PATCH 2/7] move test into its own snippet --- src/includes/configure-verify/javascript.mdx | 24 ------------------- .../initialize-configure/javascript.mdx | 10 ++++++++ src/includes/test-verify/javascript.mdx | 7 ++++++ src/platforms/javascript/index.mdx | 10 +++++--- 4 files changed, 24 insertions(+), 27 deletions(-) delete mode 100644 src/includes/configure-verify/javascript.mdx create mode 100644 src/includes/initialize-configure/javascript.mdx create mode 100644 src/includes/test-verify/javascript.mdx diff --git a/src/includes/configure-verify/javascript.mdx b/src/includes/configure-verify/javascript.mdx deleted file mode 100644 index 363b30bd33992..0000000000000 --- a/src/includes/configure-verify/javascript.mdx +++ /dev/null @@ -1,24 +0,0 @@ -```javascript {tabTitle: ESM} -import * as Sentry from "@sentry/browser"; -import { Integrations } from "@sentry/tracing"; -Sentry.init({ - dsn: "___PUBLIC_DSN___", - myUndefinedFunction(); // To test your setup - release: "my-project-name@" + process.env.npm_package_version, // To set your release version - integrations: [new Integrations.BrowserTracing()], - tracesSampleRate: 1.0, // Be sure to lower this in production -}); - - -``` - -```javascript {tabTitle: ESM} -import * as Sentry from "@sentry/browser"; -import { Integrations } from "@sentry/tracing"; -Sentry.init({ - dsn: "___PUBLIC_DSN___", - release: "my-project-name@" + process.env.npm_package_version, - integrations: [new Integrations.BrowserTracing()], - tracesSampleRate: 1.0, // Be sure to lower this in production -}); -``` diff --git a/src/includes/initialize-configure/javascript.mdx b/src/includes/initialize-configure/javascript.mdx new file mode 100644 index 0000000000000..2128cae407164 --- /dev/null +++ b/src/includes/initialize-configure/javascript.mdx @@ -0,0 +1,10 @@ +```javascript {tabTitle: ESM} +import * as Sentry from "@sentry/browser"; +import { Integrations } from "@sentry/tracing"; +Sentry.init({ + dsn: "___PUBLIC_DSN___", + release: "my-project-name@" + process.env.npm_package_version, // To set your release version + integrations: [new Integrations.BrowserTracing()], + tracesSampleRate: 1.0, // Remember to lower this in production +}); +``` diff --git a/src/includes/test-verify/javascript.mdx b/src/includes/test-verify/javascript.mdx new file mode 100644 index 0000000000000..215ea9f985f00 --- /dev/null +++ b/src/includes/test-verify/javascript.mdx @@ -0,0 +1,7 @@ +```JavaScript {tabTitle: ESM} +import * as Sentry from "@sentry/browser"; + +Sentry.init({ dsn: "https://bc367fd982144d75923219dca8f35ad1@o1.ingest.sentry.io/2783252" }); + +myUndefinedFunction(); // To test your setup +``` diff --git a/src/platforms/javascript/index.mdx b/src/platforms/javascript/index.mdx index 2120d2d51844f..9bb6124686098 100644 --- a/src/platforms/javascript/index.mdx +++ b/src/platforms/javascript/index.mdx @@ -38,11 +38,10 @@ If you are using our CDN, please see our documentation for [installing with CDN] `init` Sentry as soon as possible in your app. Once this is done, all unhandled exceptions are automatically captured by Sentry. This snippet includes: -- an intentional error as a test that everything is working as soon as you set it up. - the [release](/product/releases/) of your application, using `process.env.npm_package_version`, which both enables [source maps](/platforms/javascript/sourcemaps/) as well as tracking of regressions and suspect commits. - our [performance monitoring](/product/performance/) package. - + @@ -50,8 +49,13 @@ We'll automatically assign you a Data Source Name (DSN), which looks like a stan -To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. Explore [Performance](/product/performance/) by selecting it from the sidebar, then viewing the homepage. +# Test + +The snippet below includes an intentional error, so you can test that everything is working as soon as you set it up. + + +To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. Explore [Performance](/product/performance/) by selecting it from the sidebar, then viewing the homepage. ## Next Steps From b40de312837abd08a168f4559afcbd5cc693adfd Mon Sep 17 00:00:00 2001 From: Fiona <61481573+PeloWriter@users.noreply.github.com> Date: Mon, 14 Sep 2020 18:16:09 -0700 Subject: [PATCH 3/7] Update src/includes/test-verify/javascript.mdx Co-authored-by: Adam McKerlie --- src/includes/test-verify/javascript.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/includes/test-verify/javascript.mdx b/src/includes/test-verify/javascript.mdx index 215ea9f985f00..0e1b44c6f522e 100644 --- a/src/includes/test-verify/javascript.mdx +++ b/src/includes/test-verify/javascript.mdx @@ -1,7 +1,7 @@ ```JavaScript {tabTitle: ESM} import * as Sentry from "@sentry/browser"; -Sentry.init({ dsn: "https://bc367fd982144d75923219dca8f35ad1@o1.ingest.sentry.io/2783252" }); +Sentry.init({ dsn: "___PUBLIC_DSN___" }); myUndefinedFunction(); // To test your setup ``` From 8686c9d83ea1245710c02ee97d18a5b21464d457 Mon Sep 17 00:00:00 2001 From: Fiona <61481573+PeloWriter@users.noreply.github.com> Date: Tue, 15 Sep 2020 09:11:08 -0700 Subject: [PATCH 4/7] Update src/platforms/javascript/index.mdx Co-authored-by: Daniel Griesser --- src/platforms/javascript/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/javascript/index.mdx b/src/platforms/javascript/index.mdx index 9bb6124686098..a12603b5b11b3 100644 --- a/src/platforms/javascript/index.mdx +++ b/src/platforms/javascript/index.mdx @@ -49,7 +49,7 @@ We'll automatically assign you a Data Source Name (DSN), which looks like a stan -# Test +## Test The snippet below includes an intentional error, so you can test that everything is working as soon as you set it up. From b5b2d9987c1eb7e916c3b823c47afc345a8b6651 Mon Sep 17 00:00:00 2001 From: Fiona <61481573+PeloWriter@users.noreply.github.com> Date: Tue, 15 Sep 2020 09:11:58 -0700 Subject: [PATCH 5/7] Update src/includes/test-verify/javascript.mdx Co-authored-by: Daniel Griesser --- src/includes/test-verify/javascript.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/includes/test-verify/javascript.mdx b/src/includes/test-verify/javascript.mdx index 0e1b44c6f522e..decdfd544d9f7 100644 --- a/src/includes/test-verify/javascript.mdx +++ b/src/includes/test-verify/javascript.mdx @@ -1,7 +1,3 @@ ```JavaScript {tabTitle: ESM} -import * as Sentry from "@sentry/browser"; - -Sentry.init({ dsn: "___PUBLIC_DSN___" }); - myUndefinedFunction(); // To test your setup ``` From 64c4d612acb1c2c9c2dedb617a4331315df68c6b Mon Sep 17 00:00:00 2001 From: Fiona <61481573+PeloWriter@users.noreply.github.com> Date: Tue, 15 Sep 2020 09:13:07 -0700 Subject: [PATCH 6/7] Update src/platforms/javascript/index.mdx Co-authored-by: Daniel Griesser --- src/platforms/javascript/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/javascript/index.mdx b/src/platforms/javascript/index.mdx index a12603b5b11b3..50caa12c03ae1 100644 --- a/src/platforms/javascript/index.mdx +++ b/src/platforms/javascript/index.mdx @@ -21,7 +21,7 @@ Using a framework? Take a look at our specific guides to get started. -## Install the Package +## Install Sentry captures data by using an SDK within your application’s runtime: From cbb72e0474d9fa53fc4c0d1408483a4bad94e299 Mon Sep 17 00:00:00 2001 From: Fiona Artiaga Date: Wed, 16 Sep 2020 16:57:41 -0700 Subject: [PATCH 7/7] Create Angular includes --- src/includes/initialize-configure/angular.mdx | 108 ++++++++++++++++++ src/includes/install-package/angular.mdx | 7 ++ 2 files changed, 115 insertions(+) create mode 100644 src/includes/initialize-configure/angular.mdx create mode 100644 src/includes/install-package/angular.mdx diff --git a/src/includes/initialize-configure/angular.mdx b/src/includes/initialize-configure/angular.mdx new file mode 100644 index 0000000000000..6728c951ba413 --- /dev/null +++ b/src/includes/initialize-configure/angular.mdx @@ -0,0 +1,108 @@ +This snippet includes our [performance monitoring](/product/performance/) package, which register and configures the Tracing integration, including custom Angular routing instrumentation: + +```javascript +import { enableProdMode } from "@angular/core"; +import { platformBrowserDynamic } from "@angular/platform-browser-dynamic"; +import * as Sentry from "@sentry/angular"; +import { Integrations } from "@sentry/tracing"; + +import { AppModule } from "./app/app.module"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___" , + integrations: [ + new Integrations.BrowserTracing({ + tracingOrigins: ["localhost", "https://yourserver.io/api"], + routingInstrumentation: Sentry.routingInstrumentation, + }), + ], + tracesSampleRate: 1.0, // Be sure to lower this in production + +enableProdMode(); +platformBrowserDynamic() + .bootstrapModule(AppModule) + .then(success => console.log(`Bootstrap success`)) + .catch(err => console.error(err)); +``` + +You can also configure `@sentry/angular` to catch any Angular-specific exceptions reported through the [@angular/core/ErrorHandler](https://angular.io/api/core/ErrorHandler) provider. + +`@sentry/angular` exports a Trace Service, Directive, and Decorators that leverages the `@sentry/tracing`, Sentry's Tracing integration, to add Angular-related spans to transactions. The service itself tracks route changes and durations, where directive and decorators are tracking component initializations. + +### Automatically Send Errors with `ErrorHandler` + +`@sentry/angular` exports a function to instantiate an `ErrorHandler` provider that will automatically send JavaScript errors captured by the Angular's error handler. + +```javascript +import { NgModule, ErrorHandler } from "@angular/core"; +import * as Sentry from "@sentry/angular"; + +@NgModule({ + // ... + providers: [ + { + provide: ErrorHandler, + useValue: Sentry.createErrorHandler({ + showDialog: true, + }), + }, + ], + // ... +}) +export class AppModule {} +``` + +You can configure the behavior of `createErrorHandler`. For more details see the `ErrorHandlerOptions` interface in [our repository](https://github.com/getsentry/sentry-javascript/blob/master/packages/angular/src/errorhandler.ts). + +### Register `TraceService` + +In Angular's DI system, register `TraceService` as a provider with a `Router` as its dependency: + +```javascript +import { NgModule } from "@angular/core"; +import { Router } from "@angular/router"; +import * as Sentry from "@sentry/angular"; + +@NgModule({ + // ... + providers: [ + { + provide: Sentry.TraceService, + deps: [Router], + }, + ], + // ... +}) +export class AppModule {} +``` + +Then, either require the `TraceService` from inside `AppModule` or use `APP_INITIALIZER` to force instantiate Tracing. + +```javascript +@NgModule({ + // ... +}) +export class AppModule { + constructor(trace: Sentry.TraceService) {} +} +``` + +or + +```javascript +import { APP_INITIALIZER } from "@angular/core"; + +@NgModule({ + // ... + providers: [ + { + provide: APP_INITIALIZER, + useFactory: () => () => {}, + deps: [Sentry.TraceService], + multi: true, + }, + ], + // ... +}) +export class AppModule {} +``` diff --git a/src/includes/install-package/angular.mdx b/src/includes/install-package/angular.mdx new file mode 100644 index 0000000000000..ebf23b59a47fc --- /dev/null +++ b/src/includes/install-package/angular.mdx @@ -0,0 +1,7 @@ +```bash {tabTitle:npm} +npm install --save @sentry/angular +``` + +```bash {tabTitle:Yarn} +yarn add @sentry/angular +```