Skip to content

Commit 6957209

Browse files
PeloWriterdcramerHazAT
authored
Global Getting Started (#2336)
* Update JS index page and JS includes * Create common page for Getting Started * Add Angular includes and remove Angular getting ststarted index page * Update src/platforms/common/usage/index.mdx Co-authored-by: David Cramer <[email protected]> * fix: Dont error in GuideGrid when using a guide itself * create test content, apply code review comments * update angular includes * move content into troubleshooting * Update src/includes/getting-started-config/javascript.angular.mdx Co-authored-by: Daniel Griesser <[email protected]> * fix heading * Create tabs to allow selection of errors or errors and performance * Add sample rate configuration note * update configuration of sample rate * Remove tab idea as the design won't scale * fix: Angular verify * edits to clarify * edits to enable next step page display * edits from review * Update src/includes/getting-started-config/javascript.angular.mdx Co-authored-by: Daniel Griesser <[email protected]> Co-authored-by: David Cramer <[email protected]> Co-authored-by: David Cramer <[email protected]> Co-authored-by: Daniel Griesser <[email protected]>
1 parent 35c345e commit 6957209

File tree

20 files changed

+220
-344
lines changed

20 files changed

+220
-344
lines changed

‎src/components/guideGrid.tsx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ type Props = {
1010

1111
export default ({ platform }: Props): JSX.Element => {
1212
const currentPlatform = getPlatform(platform) as Platform;
13+
// platform might actually not be a platform, so lets handle that case gracefully
14+
if (!currentPlatform.guides) {
15+
return null;
16+
}
1317

1418
return (
1519
<ul>

‎src/includes/capture-error/javascript.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,5 @@ try {
99
Sentry.captureException(err);
1010
}
1111
```
12+
13+
Learn more about how to manually capture errors or enable message capture with Sentry's SDK in <PlatformLink to="/usage/">our documentation on Usage</PlatformLink>.

‎src/includes/framework-list/_default.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<GuideGrid />

‎src/includes/framework-list/javascript.mdx

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Using a framework? Take a look at our specific guides to get started.
2+
3+
<GuideGrid platform="javascript" />

‎src/includes/getting-started-config/javascript.angular.mdx

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
This snippet includes automatic instrumentation to [monitor the performance](/platforms/javascript/performance/) of your application, which registers and configures the Tracing integration, including custom Angular routing instrumentation.
2+
3+
**Note:** To reduce the volume of performance data captured, or disable it entirely, change `tracesSampleRate` to a value between 0 and 1 in production.
4+
5+
```javascript
6+
import { enableProdMode } from "@angular/core";
7+
import { platformBrowserDynamic } from "@angular/platform-browser-dynamic";
8+
import * as Sentry from "@sentry/angular";
9+
import { Integrations } from "@sentry/tracing";
10+
import { AppModule } from "./app/app.module";
11+
12+
Sentry.init({
13+
dsn: "___PUBLIC_DSN___" ,
14+
integrations: [
15+
new Integrations.BrowserTracing({
16+
tracingOrigins: ["localhost", "https://yourserver.io/api"],
17+
routingInstrumentation: Sentry.routingInstrumentation,
18+
}),
19+
],
20+
tracesSampleRate: 1.0, // We recommend adjusting this in production
21+
});
22+
23+
24+
platformBrowserDynamic()
25+
.bootstrapModule(AppModule)
26+
.then(success => console.log(`Bootstrap success`))
27+
.catch(err => console.error(err));
28+
```
29+
30+
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.
31+
32+
`@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.
33+
34+
### Automatically Send Errors with `ErrorHandler`
35+
36+
`@sentry/angular` exports a function to instantiate an `ErrorHandler` provider that will automatically send JavaScript errors captured by the Angular's error handler.
37+
38+
```javascript
39+
import { NgModule, ErrorHandler } from "@angular/core";
40+
import * as Sentry from "@sentry/angular";
41+
42+
@NgModule({
43+
// ...
44+
providers: [
45+
{
46+
provide: ErrorHandler,
47+
useValue: Sentry.createErrorHandler({
48+
showDialog: true,
49+
}),
50+
},
51+
],
52+
// ...
53+
})
54+
export class AppModule {}
55+
```
56+
57+
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).
58+
59+
### Register `TraceService`
60+
61+
In Angular's DI system, register `TraceService` as a provider with a `Router` as its dependency:
62+
63+
```javascript
64+
import { NgModule } from "@angular/core";
65+
import { Router } from "@angular/router";
66+
import * as Sentry from "@sentry/angular";
67+
68+
@NgModule({
69+
// ...
70+
providers: [
71+
{
72+
provide: Sentry.TraceService,
73+
deps: [Router],
74+
},
75+
],
76+
// ...
77+
})
78+
export class AppModule {}
79+
```
80+
Then, either require the `TraceService` from inside `AppModule` or use `APP_INITIALIZER` to force instantiate Tracing.
81+
```javascript
82+
@NgModule({
83+
// ...
84+
})
85+
export class AppModule {
86+
constructor(trace: Sentry.TraceService) {}
87+
}
88+
```
89+
90+
or
91+
92+
```javascript
93+
import { APP_INITIALIZER } from "@angular/core";
94+
@NgModule({
95+
// ...
96+
providers: [
97+
{
98+
provide: APP_INITIALIZER,
99+
useFactory: () => () => {},
100+
deps: [Sentry.TraceService],
101+
multi: true,
102+
},
103+
],
104+
// ...
105+
})
106+
export class AppModule {}
107+
```

‎src/includes/getting-started-config/javascript.mdx

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,22 @@
1-
You should `init` the Sentry Browser SDK as soon as possible during your page load:
1+
This snippet:
2+
- Uses `process.env.npm_package_version` to configure the version of your application. Learn more about [releases](/product/releases/) and how they are used with [source maps](/platforms/javascript/sourcemaps/).
3+
- Instruments your SDK to [monitor the performance](/platforms/javascript/performance/) of browser applications.
24

3-
```javascript {tabTitle:ESM}
4-
import * as Sentry from "@sentry/browser";
5+
<Note>
6+
<markdown>
57

6-
Sentry.init({
7-
dsn: "___PUBLIC_DSN___",
8-
});
9-
```
8+
To reduce the volume of performance data captured, or disable it entirely, change `tracesSampleRate` to a value between 0 and 1 in production.
9+
10+
</markdown>
11+
</Note>
1012

11-
```javascript {tabTitle:CDN}
13+
```javascript {tabTitle: ESM}
14+
import * as Sentry from "@sentry/browser";
15+
import { Integrations } from "@sentry/tracing";
1216
Sentry.init({
1317
dsn: "___PUBLIC_DSN___",
18+
release: "my-project-name@" + process.env.npm_package_version, // To set your release version
19+
integrations: [new Integrations.BrowserTracing()],
20+
tracesSampleRate: 1.0, // We recommend adjusting this in production
1421
});
1522
```

‎src/includes/getting-started-install/javascript.angular.mdx

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
```bash {tabTitle:npm}
2+
npm install --save @sentry/angular
3+
```
4+
5+
```bash {tabTitle:Yarn}
6+
yarn add @sentry/angular
7+
```

‎src/includes/getting-started-install/javascript.mdx

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,14 @@
1-
Add the `@sentry/browser` dependency:
2-
31
```bash {tabTitle: ESM}
42
# Using yarn
5-
$ yarn add @sentry/browser
6-
3+
$ yarn add @sentry/browser @sentry/tracing
74
# Using npm
8-
$ npm install @sentry/browser
5+
$ npm install --save @sentry/browser @sentry/tracing
96
```
107

11-
```html {tabTitle: CDN}
12-
<script
13-
src="https://browser.sentry-cdn.com/{{ packages.version('sentry.javascript.browser') }}/bundle.min.js"
14-
integrity="sha384-{{ packages.checksum('sentry.javascript.browser', 'bundle.min.js', 'sha384-base64') }}"
15-
crossorigin="anonymous"
16-
></script>
17-
```
8+
<Note>
9+
<markdown>
10+
11+
We also support alternate [installation methods](/platforms/javascript/install/).
12+
13+
</markdown>
14+
</Note>

‎src/includes/getting-started-next-steps/javascript.mdx

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎src/includes/getting-started-verify/javascript.mdx

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,3 @@
1-
One way to verify your setup is by intentionally causing an error that breaks your application.
2-
3-
Calling an undefined function will throw an exception:
4-
5-
```js
1+
```javascript
62
myUndefinedFunction();
73
```
8-
9-
You can verify the function caused an error by checking your browser console.

‎src/platforms/common/index.mdx

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
On this page, we get you up and running with Sentry's SDK, so that it will automatically report errors and exceptions in your application.
2+
3+
<Note>
4+
<markdown>
5+
6+
If you don't already have an account and Sentry project established, head over to [sentry.io](https://sentry.io/signup/), then return to this page.
7+
8+
</markdown>
9+
</Note>
10+
11+
<PlatformContent includePath="framework-list" />
12+
13+
## Install
14+
15+
Sentry captures data by using an SDK within your application’s runtime:
16+
17+
<PlatformContent includePath="getting-started-install" />
18+
19+
## Initialize
20+
21+
`init` Sentry as soon as possible in your app. Once this is done, the Sentry SDK captures all unhandled exceptions.
22+
23+
<PlatformContent includePath="getting-started-config" />
24+
25+
<Note><markdown>
26+
27+
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.
28+
29+
</markdown></Note>
30+
31+
## Verify
32+
33+
This snippet includes an intentional error, so you can test that everything is working as soon as you set it up:
34+
35+
<PlatformContent includePath="getting-started-verify" />
36+
37+
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.
38+
39+
<PageGrid header="Next Steps" nextSteps />

‎src/platforms/common/usage/index.mdx

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,19 @@ notSupported:
1212

1313
Sentry's SDK hooks into your runtime environment and automatically reports errors, exceptions, and rejections.
1414

15+
<Note>
16+
<markdown>
17+
18+
Key terms:
19+
20+
- An _event_ is one instance of sending data to Sentry. Generally, this data is an error or exception.
21+
- An _issue_ is a grouping of similar events.
22+
- The reporting of an event is called _capturing_.
23+
When an event is captured, it’s sent to Sentry.
24+
25+
</markdown>
26+
</Note>
27+
1528
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.
1629

1730
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-events/breadcrumbs/).

‎src/platforms/javascript/common/install/index.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: Installation Methods
33
sidebar_order: 1
4+
description: "Review our alternate installation methods."
45
---
56

67
<PageGrid />

‎src/platforms/javascript/common/integrations/index.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: Integrations
33
sidebar_order: 200
4+
description: "Learn more about how integrations extend the functionality of our SDK to cover common libraries and environments automatically."
45
---
56

67
<PageGrid />

‎src/platforms/javascript/common/troubleshooting/index.mdx

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: Troubleshooting
3+
description: "Troubleshoot and resolve edge cases."
34
excerpt: ""
45
sidebar_order: 1000
56
---
@@ -221,3 +222,9 @@ hub2.run(currentHub => {
221222
});
222223
});
223224
```
225+
226+
## Third Party Promise Libraries
227+
228+
When you include and configure Sentry, our JavaScript SDK automatically attaches global handlers to _capture_ uncaught exceptions and unhandled promise rejections. 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.
229+
230+
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.

‎src/platforms/javascript/guides/angular/angular1.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: AngularJS 1.x
3+
description: "Learn how to use Sentry's AngularJS integration if you're using AngularJS 1.x."
34
redirect_from:
45
- /clients/javascript/integrations/angular/
56
---

‎src/platforms/javascript/guides/angular/components/index.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
---
22
title: Components
3+
description: "Learn more about how to track Angular components as part of your transactions."
34
excerpt: ""
45
---
56

6-
The Sentry React SDK exposes custom components for first class integration with the React framework.
7+
The Sentry SDK exposes custom components for first class integration with the framework.
78

89
- **[Trace Helpers](./tracehelpers/)**
910

‎src/platforms/javascript/guides/angular/config.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
title: Angular
2+
categories:
3+
- browser
4+
redirect_from:
5+
- /clients/javascript/integrations/angular2/
6+
- /clients/javascript/integrations/angularjs/
7+
- /platforms/javascript/angular/

0 commit comments

Comments
 (0)