Skip to content

Commit bd7fea7

Browse files
inventarSarahinventarSarah
committed
update guide to TS and create new step for Error Capturing
1 parent 3c54163 commit bd7fea7

File tree

4 files changed

+165
-141
lines changed

4 files changed

+165
-141
lines changed

‎docs/platforms/javascript/guides/nestjs/index.mdx‎

Lines changed: 157 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,160 @@ categories:
99
- server-node
1010
---
1111

12-
<PlatformContent includePath="getting-started-node" />
12+
<PlatformContent includePath="getting-started-prerequisites" />
13+
14+
## Step 1: Install
15+
16+
Choose the features you want to configure, and this guide will show you how:
17+
18+
<OnboardingOptionButtons
19+
options={["error-monitoring", "performance", "profiling"]}
20+
/>
21+
22+
<PlatformContent includePath="getting-started-features-expandable" />
23+
24+
### Install the Sentry SDK
25+
26+
Run the command for your preferred package manager to add the Sentry SDK to your application:
27+
28+
<PlatformContent includePath="getting-started-install" />
29+
30+
## Step 2: Configure
31+
32+
### Initialize the Sentry SDK
33+
34+
To import and initialize Sentry, create a file named `instrument.ts` in the root directory of your project and add the following code:
35+
36+
<PlatformContent includePath="getting-started-config" />
37+
38+
### Apply Instrumentation to Your App
39+
40+
<PlatformContent includePath="getting-started-use" />
41+
42+
## Step 3: Capture Nest.js Errors
43+
44+
By default, Sentry only captures unhandled exceptions that aren't caught by an error filter.
45+
Additionally, `HttpException`s (including [derivatives](https://docs.nestjs.com/exception-filters#built-in-http-exceptions)) aren't captured by default because they mostly act as control flow vehicles.
46+
47+
To make sure Sentry captures all your app's errors, configure error handling based on how your application manages exceptions:
48+
49+
### Using a Global Catch-All Exception Filter
50+
51+
If you have a global catch-all exception filter, add a `@SentryExceptionCaptured()` decorator to the filter's `catch()` method:
52+
53+
```typescript {2, 6}
54+
import { Catch, ExceptionFilter } from "@nestjs/common";
55+
import { SentryExceptionCaptured } from "@sentry/nestjs";
56+
57+
@Catch()
58+
export class YourCatchAllExceptionFilter implements ExceptionFilter {
59+
@SentryExceptionCaptured()
60+
catch(exception, host): void {
61+
// your implementation here
62+
}
63+
}
64+
```
65+
66+
### Not Using a Global Catch-All Exception Filter
67+
68+
If you don't have a global catch-all exception filter, add the `SentryGlobalFilter` to the providers of your main module, **before** any other exception filters:
69+
70+
```typescript {2-3, 7-10}
71+
import { Module } from "@nestjs/common";
72+
import { APP_FILTER } from "@nestjs/core";
73+
import { SentryGlobalFilter } from "@sentry/nestjs/setup";
74+
75+
@Module({
76+
providers: [
77+
{
78+
provide: APP_FILTER,
79+
useClass: SentryGlobalFilter,
80+
},
81+
// ..other providers
82+
],
83+
})
84+
export class AppModule {}
85+
```
86+
87+
### Using Error Filters for Specific Exception Types
88+
89+
If you have error filters for specific types of exceptions (for example, `@Catch(HttpException)`) and you want to report these errors to Sentry, you need to capture them in the `catch()` handler using `Sentry.captureException()`:
90+
91+
```typescript {4,9}
92+
import { ArgumentsHost, BadRequestException, Catch } from "@nestjs/common";
93+
import { BaseExceptionFilter } from "@nestjs/core";
94+
import { ExampleException } from "./example.exception";
95+
import * as Sentry from "@sentry/nestjs";
96+
97+
@Catch(ExampleException)
98+
export class ExampleExceptionFilter extends BaseExceptionFilter {
99+
catch(exception: unknown, host: ArgumentsHost) {
100+
Sentry.captureException(exception);
101+
return super.catch(new BadRequestException(exception.message), host);
102+
}
103+
}
104+
```
105+
106+
<Expandable title="Are you using Microservices?">
107+
If you're using `@nestjs/microservices` make sure to handle errors in RPC contexts correctly by providing your own `RpcExceptionFilter` (see [Nest.js Microservices documentation](https://docs.nestjs.com/microservices/exception-filters)).
108+
`SentryGlobalFilter` in a [hybrid application](https://docs.nestjs.com/faq/hybrid-application) doesn't extend `BaseRpcExceptionFilter` since this depends on `@nestjs/microservices`.
109+
110+
Use `Sentry.captureException(exception)` in your custom filter in case you want to send these errors to Sentry:
111+
112+
```typescript
113+
import { Catch, RpcExceptionFilter, ArgumentsHost } from "@nestjs/common";
114+
import { Observable, throwError } from "rxjs";
115+
import { RpcException } from "@nestjs/microservices";
116+
import * as Sentry from "@sentry/nestjs";
117+
118+
@Catch(RpcException)
119+
export class ExceptionFilter implements RpcExceptionFilter<RpcException> {
120+
catch(exception: RpcException, host: ArgumentsHost): Observable<any> {
121+
Sentry.captureException(exception); // optional
122+
return throwError(() => exception.getError());
123+
}
124+
}
125+
```
126+
127+
</Expandable>
128+
129+
## Step 4: Add Readable Stack Traces With Source Maps (Optional)
130+
131+
The stack traces in your Sentry errors probably won't look like your actual code. To fix this, upload your source maps to Sentry.
132+
The easiest way to do this is by using the Sentry Wizard:
133+
134+
```bash
135+
npx @sentry/wizard@latest -i sourcemaps
136+
```
137+
138+
## Step 5: Verify Your Setup
139+
140+
Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.
141+
142+
<PlatformContent includePath="getting-started-verify" />
143+
144+
### View Captured Data in Sentry
145+
146+
Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear).
147+
148+
<PlatformContent includePath="getting-started-verify-locate-data" />
149+
150+
## Next Steps
151+
152+
At this point, you should have integrated Sentry into your Nest.js application and should already be sending data to your Sentry project.
153+
154+
Now's a good time to customize your setup and look into more advanced topics.
155+
Our next recommended steps for you are:
156+
157+
- Extend Sentry to your frontend using one of our [frontend SDKs](/)
158+
- Learn how to [manually capture errors](/platforms/javascript/guides/nestjs/usage/)
159+
- Continue to [customize your configuration](/platforms/javascript/guides/nestjs/configuration/)
160+
- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts
161+
162+
<Expandable permalink={false} title="Are you having problems setting up the SDK?">
163+
164+
- Check out alternative <PlatformLink to="/install">installation methods</PlatformLink>
165+
- Find various topics in <PlatformLink to="/troubleshooting">Troubleshooting</PlatformLink>
166+
- [Get support](https://sentry.zendesk.com/hc/en-us/)
167+
168+
</Expandable>

‎platform-includes/getting-started-config/javascript.nestjs.mdx‎

Lines changed: 1 addition & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,4 @@
1-
```javascript {tabTitle:ESM} {filename: instrument.mjs}
2-
import * as Sentry from "@sentry/nestjs";
3-
// ___PRODUCT_OPTION_START___ profiling
4-
import { nodeProfilingIntegration } from "@sentry/profiling-node";
5-
// ___PRODUCT_OPTION_END___ profiling
6-
7-
// Ensure to call this before importing any other modules!
8-
Sentry.init({
9-
dsn: "___PUBLIC_DSN___",
10-
11-
// Adds request headers and IP for users, for more info visit:
12-
// https://docs.sentry.io/platforms/javascript/guides/nestjs/configuration/options/#sendDefaultPii
13-
sendDefaultPii: true,
14-
15-
// ___PRODUCT_OPTION_START___ profiling
16-
integrations: [
17-
// Add our Profiling integration
18-
nodeProfilingIntegration(),
19-
],
20-
// ___PRODUCT_OPTION_END___ profiling
21-
// ___PRODUCT_OPTION_START___ performance
22-
23-
// Set tracesSampleRate to 1.0 to capture 100%
24-
// of transactions for tracing.
25-
// We recommend adjusting this value in production
26-
// Learn more at
27-
// https://docs.sentry.io/platforms/javascript/guides/nestjs/configuration/options/#tracesSampleRate
28-
tracesSampleRate: 1.0,
29-
// ___PRODUCT_OPTION_END___ performance
30-
// ___PRODUCT_OPTION_START___ profiling
31-
32-
// Set profilesSampleRate to 1.0 to profile 100%
33-
// of sampled transactions.
34-
// This is relative to tracesSampleRate
35-
// Learn more at
36-
// https://docs.sentry.io/platforms/javascript/guides/nestjs/configuration/options/#profilesSampleRate
37-
profilesSampleRate: 1.0,
38-
// ___PRODUCT_OPTION_END___ profiling
39-
});
40-
```
41-
42-
```javascript {tabTitle:CommonJS} {filename: instrument.js}
1+
```typescript {filename: instrument.ts}
432
const Sentry = require("@sentry/nestjs");
443
// ___PRODUCT_OPTION_START___ profiling
454
const { nodeProfilingIntegration } = require("@sentry/profiling-node");

‎platform-includes/getting-started-use/javascript.nestjs.mdx‎

Lines changed: 4 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
1-
<PlatformContent includePath="getting-started-config" />
1+
Make sure to import the `instrument.ts` file before any other modules:
22

3-
You need to require or import the `instrument.js` file before requiring any other modules in your application. This is necessary to ensure that Sentry can automatically instrument all modules in your application:
4-
5-
```javascript {filename: main.ts} {1-2}
3+
```typescript {filename: main.ts} {1-2}
64
// Import this first!
75
import "./instrument";
86

@@ -18,9 +16,9 @@ async function bootstrap() {
1816
bootstrap();
1917
```
2018

21-
Afterwards, add the `SentryModule` as a root module to your main module:
19+
Afterward, add the `SentryModule` as a root module to your main module:
2220

23-
```javascript {filename: app.module.ts} {2, 8}
21+
```typescript {filename: app.module.ts} {2, 8}
2422
import { Module } from "@nestjs/common";
2523
import { SentryModule } from "@sentry/nestjs/setup";
2624
import { AppController } from "./app.controller";
@@ -36,84 +34,3 @@ import { AppService } from "./app.service";
3634
})
3735
export class AppModule {}
3836
```
39-
40-
If you're using a global catch-all exception filter (which is either a filter registered with `app.useGlobalFilters()` or a filter registered in your app module providers annotated with a `@Catch()` decorator without arguments), add a `@SentryExceptionCaptured()` decorator to the filter's `catch()` method.
41-
This decorator will report all unexpected errors that are received by your global error filter to Sentry:
42-
43-
```javascript {2, 6}
44-
import { Catch, ExceptionFilter } from '@nestjs/common';
45-
import { SentryExceptionCaptured } from '@sentry/nestjs';
46-
47-
@Catch()
48-
export class YourCatchAllExceptionFilter implements ExceptionFilter {
49-
@SentryExceptionCaptured()
50-
catch(exception, host): void {
51-
// your implementation here
52-
}
53-
}
54-
```
55-
56-
By default, only unhandled exceptions that are not caught by an error filter are reported to Sentry.
57-
`HttpException`s (including [derivatives](https://docs.nestjs.com/exception-filters#built-in-http-exceptions)) are also not captured by default because they mostly act as control flow vehicles.
58-
59-
If you don't have a global catch-all exception filter, add the `SentryGlobalFilter` to the providers of your main module.
60-
This filter will report any unhandled errors that aren't caught by other error filters to Sentry.
61-
**Important:** The `SentryGlobalFilter` needs to be registered before any other exception filters.
62-
63-
```javascript {2-3, 7-10}
64-
import { Module } from "@nestjs/common";
65-
import { APP_FILTER } from "@nestjs/core";
66-
import { SentryGlobalFilter } from "@sentry/nestjs/setup";
67-
68-
@Module({
69-
providers: [
70-
{
71-
provide: APP_FILTER,
72-
useClass: SentryGlobalFilter,
73-
},
74-
// ..other providers
75-
],
76-
})
77-
export class AppModule {}
78-
```
79-
80-
<Expandable title="Are you using Microservices?">
81-
82-
If you're using `@nestjs/microservices` make sure to handle errors in RPC contexts correctly by providing your own `RpcExceptionFilter` (see https://docs.nestjs.com/microservices/exception-filters).
83-
`SentryGlobalFilter` in a [hybrid application](https://docs.nestjs.com/faq/hybrid-application) does not extend `BaseRpcExceptionFilter` since this depends on `@nestjs/microservices`.
84-
85-
Use `Sentry.captureException(exception)` in your custom filter in case you want to send these errors to Sentry:
86-
87-
```typescript
88-
import { Catch, RpcExceptionFilter, ArgumentsHost } from "@nestjs/common";
89-
import { Observable, throwError } from "rxjs";
90-
import { RpcException } from "@nestjs/microservices";
91-
import * as Sentry from "@sentry/nestjs";
92-
93-
@Catch(RpcException)
94-
export class ExceptionFilter implements RpcExceptionFilter<RpcException> {
95-
catch(exception: RpcException, host: ArgumentsHost): Observable<any> {
96-
Sentry.captureException(exception); // optional
97-
return throwError(() => exception.getError());
98-
}
99-
}
100-
```
101-
102-
</Expandable>
103-
104-
If you have error filters for specific types of exceptions (for example `@Catch(HttpException)`, or any other `@Catch(...)` with arguments) and you want to capture errors caught by these filters, capture the errors in the `catch()` handler with `Sentry.captureException()`:
105-
106-
```javascript {4,9}
107-
import { ArgumentsHost, BadRequestException, Catch } from '@nestjs/common';
108-
import { BaseExceptionFilter } from '@nestjs/core';
109-
import { ExampleException } from './example.exception';
110-
import * as Sentry from '@sentry/nestjs';
111-
112-
@Catch(ExampleException)
113-
export class ExampleExceptionFilter extends BaseExceptionFilter {
114-
catch(exception: unknown, host: ArgumentsHost) {
115-
Sentry.captureException(exception);
116-
return super.catch(new BadRequestException(exception.message), host)
117-
}
118-
}
119-
```

‎platform-includes/getting-started-verify/javascript.nestjs.mdx‎

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,11 @@
11
### Issues
22

3-
First, let's verify that Sentry captures errors and creates issues in your Sentry project. Add the following route to your application, which will call an undefined function, triggering an error that Sentry will capture:
3+
First, let's verify that Sentry captures errors and creates issues in your Sentry project. Add the following route to your application, which will trigger an error that Sentry will capture:
44

55
```javascript
66
@Get("/debug-sentry")
77
getError() {
8-
try {
9-
foo();
10-
} catch (e) {
11-
Sentry.captureException(e);
12-
}
8+
throw new Error("My first Sentry error!");
139
}
1410
```
1511

@@ -28,11 +24,7 @@ To test your tracing configuration, update the previous code snippet by starting
2824
},
2925
() => {
3026
setTimeout(() => {
31-
try {
32-
foo();
33-
} catch (e) {
34-
Sentry.captureException(e);
35-
}
27+
throw new Error("My first Sentry error!");
3628
}, 99);
3729
},
3830
);

0 commit comments

Comments
 (0)