Skip to content

Commit b15824c

Browse files
kamilogorekkamilogorek
authored
feat: Add @sentry/angular (#2787)
1 parent ddf1062 commit b15824c

File tree

12 files changed

+1423
-0
lines changed

12 files changed

+1423
-0
lines changed

‎packages/angular/.npmignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
*
2+
!/dist/**/*
3+
!/esm/**/*
4+
*.tsbuildinfo

‎packages/angular/LICENSE

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2020, Sentry
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6+
7+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8+
9+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎packages/angular/README.md

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
<p align="center">
2+
<a href="https://sentry.io" target="_blank" align="center">
3+
<img src="https://sentry-brand.storage.googleapis.com/sentry-logo-black.png" width="280">
4+
</a>
5+
<br />
6+
</p>
7+
8+
# Official Sentry SDK for Angular
9+
10+
## Links
11+
12+
- [Official SDK Docs](https://docs.sentry.io/platforms/javascript/angular/)
13+
- [TypeDoc](http://getsentry.github.io/sentry-javascript/)
14+
15+
## General
16+
17+
This package is a wrapper around `@sentry/browser`, with added functionality related to Angular. All methods available
18+
in `@sentry/browser` can be imported from `@sentry/angular`.
19+
20+
To use this SDK, call `Sentry.init(options)` before you bootstrap your Angular application.
21+
22+
```javascript
23+
import { enableProdMode } from '@angular/core';
24+
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
25+
import { init } from '@sentry/angular';
26+
27+
import { AppModule } from './app/app.module';
28+
29+
init({
30+
dsn: '__DSN__',
31+
// ...
32+
});
33+
34+
// ...
35+
36+
enableProdMode();
37+
platformBrowserDynamic()
38+
.bootstrapModule(AppModule)
39+
.then(success => console.log(`Bootstrap success`))
40+
.catch(err => console.error(err));
41+
```
42+
43+
### ErrorHandler
44+
45+
`@sentry/angular` exports a function to instantiate ErrorHandler provider that will automatically send Javascript errors
46+
captured by the Angular's error handler.
47+
48+
```javascript
49+
import { NgModule, ErrorHandler } from '@angular/core';
50+
import { createErrorHandler } from '@sentry/angular';
51+
52+
@NgModule({
53+
// ...
54+
providers: [
55+
{
56+
provide: ErrorHandler,
57+
useValue: createErrorHandler({
58+
showDialog: true,
59+
}),
60+
},
61+
],
62+
// ...
63+
})
64+
export class AppModule {}
65+
```
66+
67+
Additionally, `createErrorHandler` accepts a set of options that allows you to configure its behaviour. For more details
68+
see `ErrorHandlerOptions` interface in `src/errorhandler.ts`.
69+
70+
### Tracing
71+
72+
`@sentry/angular` exports a Trace Service, Directive and Decorators that leverage the `@sentry/tracing` Tracing
73+
integration to add Angular related spans to transactions. If the Tracing integration is not enabled, this functionality
74+
will not work. The service itself tracks route changes and durations, where directive and decorators are tracking
75+
components initializations.
76+
77+
#### Install
78+
79+
Registering a Trace Service is a 3 steps process.
80+
81+
1. Register and configure `@sentry/tracing` `BrowserTracing` integration, including custom Angular routing
82+
instrumentation:
83+
84+
```javascript
85+
import { init, routingInstrumentation } from '@sentry/angular';
86+
import { Integrations as TracingIntegrations } from '@sentry/tracing';
87+
88+
init({
89+
dsn: '__DSN__',
90+
integrations: [
91+
new TracingIntegrations.BrowserTracing({
92+
tracingOrigins: ['localhost', 'https://yourserver.io/api'],
93+
routingInstrumentation: routingInstrumentation,
94+
}),
95+
],
96+
tracesSampleRate: 1,
97+
});
98+
```
99+
100+
2. Register `SentryTrace` as a provider in Angular's DI system, with a `Router` as its dependency:
101+
102+
```javascript
103+
import { NgModule } from '@angular/core';
104+
import { Router } from '@angular/router';
105+
import { TraceService } from '@sentry/angular';
106+
107+
@NgModule({
108+
// ...
109+
providers: [
110+
{
111+
provide: TraceService,
112+
deps: [Router],
113+
},
114+
],
115+
// ...
116+
})
117+
export class AppModule {}
118+
```
119+
120+
3. Either require the `TraceService` from inside `AppModule` or use `APP_INITIALIZER` to force instantiate Tracing.
121+
122+
```javascript
123+
@NgModule({
124+
// ...
125+
})
126+
export class AppModule {
127+
constructor(trace: TraceService) {}
128+
}
129+
```
130+
131+
or
132+
133+
```javascript
134+
import { APP_INITIALIZER } from '@angular/core';
135+
136+
@NgModule({
137+
// ...
138+
providers: [
139+
{
140+
provide: APP_INITIALIZER,
141+
useFactory: () => () => {},
142+
deps: [TraceService],
143+
multi: true,
144+
},
145+
],
146+
// ...
147+
})
148+
export class AppModule {}
149+
```
150+
151+
#### Use
152+
153+
To track Angular components as part of your transactions, you have 3 options.
154+
155+
_TraceDirective:_ used to track a duration between `OnInit` and `AfterViewInit` lifecycle hooks in template:
156+
157+
```javascript
158+
import { TraceDirective } from '@sentry/angular';
159+
160+
@NgModule({
161+
// ...
162+
declarations: [TraceDirective],
163+
// ...
164+
})
165+
export class AppModule {}
166+
```
167+
168+
Then inside your components template (keep in mind that directive name attribute is required):
169+
170+
```html
171+
<app-header [trace]="'header'"></app-header>
172+
<articles-list [trace]="'articles-list'"></articles-list>
173+
<app-footer [trace]="'footer'"></app-footer>
174+
```
175+
176+
_TraceClassDecorator:_ used to track a duration between `OnInit` and `AfterViewInit` lifecycle hooks in components:
177+
178+
```javascript
179+
import { Component } from '@angular/core';
180+
import { TraceClassDecorator } from '@sentry/angular';
181+
182+
@Component({
183+
selector: 'layout-header',
184+
templateUrl: './header.component.html',
185+
})
186+
@TraceClassDecorator()
187+
export class HeaderComponent {
188+
// ...
189+
}
190+
```
191+
192+
_TraceMethodDecorator:_ used to track a specific lifecycle hooks as point-in-time spans in components:
193+
194+
```javascript
195+
import { Component, OnInit } from '@angular/core';
196+
import { TraceMethodDecorator } from '@sentry/angular';
197+
198+
@Component({
199+
selector: 'app-footer',
200+
templateUrl: './footer.component.html',
201+
})
202+
export class FooterComponent implements OnInit {
203+
@TraceMethodDecorator()
204+
ngOnInit() {}
205+
}
206+
```
207+
208+
You can also add your own custom spans by attaching them to the current active transaction using `getActiveTransaction`
209+
helper. For example, if you'd like to track the duration of Angular boostraping process, you can do it as follows:
210+
211+
```javascript
212+
import { enableProdMode } from '@angular/core';
213+
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
214+
import { init, getActiveTransaction } from '@sentry/angular';
215+
216+
import { AppModule } from './app/app.module';
217+
218+
// ...
219+
220+
const activeTransaction = getActiveTransaction();
221+
const boostrapSpan =
222+
activeTransaction &&
223+
activeTransaction.startChild({
224+
description: 'platform-browser-dynamic',
225+
op: 'angular.bootstrap',
226+
});
227+
228+
platformBrowserDynamic()
229+
.bootstrapModule(AppModule)
230+
.then(() => console.log(`Bootstrap success`))
231+
.catch(err => console.error(err));
232+
.finally(() => {
233+
if (bootstrapSpan) {
234+
boostrapSpan.finish();
235+
}
236+
})
237+
```

‎packages/angular/package.json

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
{
2+
"name": "@sentry/angular",
3+
"version": "5.20.1",
4+
"description": "Offical Sentry SDK for Angular",
5+
"repository": "git://github.com/getsentry/sentry-javascript.git",
6+
"homepage": "https://github.com/getsentry/sentry-javascript/tree/master/packages/angular",
7+
"author": "Sentry",
8+
"license": "MIT",
9+
"engines": {
10+
"node": ">=6"
11+
},
12+
"main": "dist/index.js",
13+
"module": "esm/index.js",
14+
"types": "dist/index.d.ts",
15+
"publishConfig": {
16+
"access": "public"
17+
},
18+
"dependencies": {
19+
"@angular/common": "^10.0.3",
20+
"@angular/core": "^10.0.3",
21+
"@angular/router": "^10.0.3",
22+
"@sentry/browser": "5.19.1",
23+
"@sentry/types": "5.19.1",
24+
"@sentry/utils": "5.19.1",
25+
"rxjs": "^6.6.0",
26+
"tslib": "^1.9.3"
27+
},
28+
"devDependencies": {
29+
"npm-run-all": "^4.1.2",
30+
"prettier": "^1.17.0",
31+
"prettier-check": "^2.0.0",
32+
"rimraf": "^2.6.3",
33+
"tslint": "^5.16.0",
34+
"typescript": "^3.5.1"
35+
},
36+
"scripts": {
37+
"build": "run-p build:es5 build:esm",
38+
"build:es5": "tsc -p tsconfig.build.json",
39+
"build:esm": "tsc -p tsconfig.esm.json",
40+
"build:watch": "run-p build:watch:es5 build:watch:esm",
41+
"build:watch:es5": "tsc -p tsconfig.build.json -w --preserveWatchOutput",
42+
"build:watch:esm": "tsc -p tsconfig.esm.json -w --preserveWatchOutput",
43+
"clean": "rimraf dist coverage build esm",
44+
"link:yarn": "yarn link",
45+
"lint": "run-s lint:prettier lint:tslint",
46+
"lint:prettier": "prettier-check \"{src,test}/**/*.{ts,tsx}\"",
47+
"lint:tslint": "tslint -t stylish -p .",
48+
"lint:tslint:json": "tslint --format json -p . | tee lint-results.json",
49+
"fix": "run-s fix:tslint fix:prettier",
50+
"fix:prettier": "prettier --write \"{src,test}/**/*.{ts,tsx}\"",
51+
"fix:tslint": "tslint --fix -t stylish -p ."
52+
},
53+
"sideEffects": false
54+
}

0 commit comments

Comments
 (0)