Skip to content

Commit 60ec829

Browse files
authored
Restructure Node SDK docs.
1 parent 0cb25fb commit 60ec829

File tree

21 files changed

+574
-572
lines changed

21 files changed

+574
-572
lines changed

src/platform-includes/capture-error/node.mdx

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1-
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 stacktrace can be recorded.
1+
You can pass an `Error` object to `captureException()` to get it captured as event. It's also possible to pass non-Error objects and strings, but be aware that the resulting events in Sentry may be missing a stacktrace.
22

33
```javascript
4+
import * as Sentry from '@sentry/node';
5+
46
try {
5-
// ...
7+
aFunctionThatMightFail()
68
} catch (e) {
79
Sentry.captureException(e);
810
}
Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
`event`
2+
3+
: For breadcrumbs created from browser events, the Sentry SDK often supplies the event to the breadcrumb as a hint. This, for instance, can be used to extract data from the target DOM element into a breadcrumb.
4+
5+
`level` / `input`
6+
7+
: For breadcrumbs created from console log interceptions. This holds the original console log level and the original input data to the log function.
8+
9+
`response` / `input`
10+
11+
: For breadcrumbs created from HTTP requests. This holds the response object (from the fetch API) and the input parameters to the fetch function.
12+
13+
`request` / `response` / `event`
14+
15+
: For breadcrumbs created from HTTP requests. This holds the request and response object (from the node HTTP API) as well as the node event (`response` or `error`).
16+
17+
`xhr`
18+
19+
: For breadcrumbs created from HTTP requests done via the legacy `XMLHttpRequest` API. This holds the original xhr object.
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
`level` / `input`
2+
3+
: For breadcrumbs created from console log interceptions, this holds the original console log level and the original input data to the log function.
4+
5+
`request` / `response` / `event`
6+
7+
: For breadcrumbs created from HTTP requests, this holds the request and response object
8+
(from the node HTTP API) as well as the node event (`response` or `error`).

src/platform-includes/configuration/decluttering/javascript.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ You can also use `denyUrls` if you want to block specific URLs forever.
1212

1313
<Alert level="warning" title="Note">
1414

15-
Prior to version 5.17.0, `allowUrls` and `denyUrls` were called `whitelistUrls` and `blacklistUrls` respectively. These options are still supported for backwards compatibility reasons, but they will be removed in version 7.0. For more information, please see our [Inclusive Language Policy](https://develop.sentry.dev/inclusion/).
15+
Previously, `allowUrls` and `denyUrls` were called `whitelistUrls` and `blacklistUrls` respectively. These options are removed in version 7.0. For more information, please see our [Inclusive Language Policy](https://develop.sentry.dev/inclusion/).
1616

1717
</Alert>
1818

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
System integrations are enabled by default to integrate into the standard library or the interpreter itself. They are documented so you can be both aware of what they do and disable them if they cause issues.
2+
3+
## Enabled by Default
4+
5+
### InboundFilters
6+
7+
_Import name: `Sentry.Integrations.InboundFilters`_
8+
9+
This integration allows you to ignore specific errors based on the type,
10+
message, or URLs in a given exception.
11+
12+
It ignores errors that start with `Script error` or `Javascript error: Script error` by default.
13+
14+
To configure this integration, use `ignoreErrors`, `denyUrls`,
15+
and `allowUrls` SDK options directly. Keep in mind that `denyURLs` and `allowURLs`
16+
work only for captured exceptions, not raw message events.
17+
18+
### FunctionToString
19+
20+
_Import name: `Sentry.Integrations.FunctionToString`_
21+
22+
This integration allows the SDK to provide original functions and method names, even when our error or breadcrumbs handlers wrap them.
23+
24+
### TryCatch
25+
26+
_Import name: `Sentry.Integrations.TryCatch`_
27+
28+
This integration wraps native time and events APIs (`setTimeout`, `setInterval`, `requestAnimationFrame`, `addEventListener/removeEventListener`) in `try/catch` blocks to handle async exceptions.
29+
30+
### Breadcrumbs
31+
32+
_Import name: `Sentry.Integrations.Breadcrumbs`_
33+
34+
This integration wraps native APIs to capture breadcrumbs. By default, the Sentry SDK wraps all APIs.
35+
36+
Available options:
37+
38+
```javascript
39+
{
40+
// Log calls to `console.log`, `console.debug`, etc
41+
console: boolean;
42+
43+
// Log all click and keypress events
44+
// - When an object with `serializeAttribute` key is provided,
45+
// Breadcrumbs integration will look for given attribute(s) in DOM elements,
46+
// while generating the breadcrumb trails.
47+
// Matched elements will be followed by their custom attributes,
48+
// instead of their `id`s or `class` names.
49+
dom: boolean | { serializeAttribute: string | string[] };
50+
51+
// Log HTTP requests done with the Fetch API
52+
fetch: boolean;
53+
54+
// Log calls to `history.pushState` and friends
55+
history: boolean;
56+
57+
// Log whenever we send an event to the server
58+
sentry: boolean;
59+
60+
// Log HTTP requests done with the XHR API
61+
xhr: boolean;
62+
}
63+
```
64+
65+
### GlobalHandlers
66+
67+
_Import name: `Sentry.Integrations.GlobalHandlers`_
68+
69+
This integration attaches global handlers to capture uncaught exceptions and unhandled rejections.
70+
71+
Available options:
72+
73+
```javascript
74+
{
75+
onerror: boolean;
76+
onunhandledrejection: boolean;
77+
}
78+
```
79+
80+
### LinkedErrors
81+
82+
_Import name: `Sentry.Integrations.LinkedErrors`_
83+
84+
This integration allows you to configure linked errors. They’ll be recursively read up to a specified limit and lookup will be performed by a specific key. By default, the Sentry SDK sets the limit to five and the key used is `cause`.
85+
86+
Available options:
87+
88+
```javascript
89+
{
90+
key: string;
91+
limit: number;
92+
}
93+
```
94+
95+
Here is a code example of how this could be implemented:
96+
97+
```javascript
98+
document
99+
.querySelector("#get-reviews-btn")
100+
.addEventListener("click", async event => {
101+
const movie = event.target.dataset.title;
102+
try {
103+
const reviews = await fetchMovieReviews(movie);
104+
renderMovieReviews(reviews);
105+
} catch (e) {
106+
const fetchError = new Error(`Failed to fetch reviews for: ${movie}`);
107+
fetchError.cause = e;
108+
Sentry.captureException(fetchError);
109+
renderMovieReviewsError(fetchError);
110+
}
111+
});
112+
```
113+
114+
### HttpContext (previously: UserAgent)
115+
116+
_Import name: `Sentry.Integrations.HttpContext`_
117+
118+
<Note>
119+
120+
Before version 7.0.0 of the Sentry SDK, this integration was called `UserAgent`.
121+
It was renamed because the integration handles more than just user-agent data.
122+
123+
_Import name: `Sentry.Integrations.UserAgent`_
124+
125+
</Note>
126+
127+
This integration attaches HTTP request information, such as URL, user-agent, referrer and other headers to the event.
128+
It allows us to correctly catalog and tag events with specific OS, browser, and version information.
129+
130+
### Dedupe
131+
132+
_Import name: `Sentry.Integrations.Dedupe`_
133+
134+
This integration deduplicates certain events. It can be helpful if you are receiving many duplicate errors. Note that Sentry will only compare stack traces and fingerprints. This integration is enabled by default for Browser.
135+
136+
<PlatformContent includePath="configuration/dedupe" />
137+
138+
## Modifying System Integrations
139+
140+
To disable system integrations set `defaultIntegrations: false` when calling `init()`.
141+
142+
To override their settings, provide a new instance with your config to `integrations` option. For example, to turn off browser capturing console calls:
143+
144+
```javascript
145+
Sentry.init({
146+
dsn: '___PUBLIC_DSN___',
147+
148+
integrations: [
149+
new Sentry.Integrations.Breadcrumbs({
150+
console: false
151+
})
152+
]
153+
});
154+
```
155+
156+
### Removing an Integration
157+
158+
This example removes the default-enabled integration for adding breadcrumbs to the event:
159+
160+
```javascript
161+
Sentry.init({
162+
// ...
163+
164+
integrations: function(integrations) {
165+
// integrations will be all default integrations
166+
return integrations.filter(function(integration) {
167+
return integration.name !== "Breadcrumbs";
168+
});
169+
},
170+
});
171+
```
Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
System integrations are enabled by default to integrate into the standard library or the interpreter itself. They are documented so you can be both aware of what they do and disable them if they cause issues.
2+
3+
## Enabled by Default
4+
5+
### InboundFilters
6+
7+
_Import name: `Sentry.Integrations.InboundFilters`_
8+
9+
This integration allows developers to ignore specific errors based on the error message or the URL from which the exception originated.
10+
11+
To configure it, use the `ignoreErrors`, `denyUrls`, and `allowUrls` SDK options directly.
12+
(Keep in mind that `denyUrls` and `allowUrls` only work for captured exceptions, not raw message events.)
13+
14+
### FunctionToString
15+
16+
_Import name: `Sentry.Integrations.FunctionToString`_
17+
18+
This integration allows the SDK to provide original function and method names, even when those functions or methods
19+
are wrapped by our error or breadcrumb handlers.
20+
21+
## Node-specific
22+
23+
### Console
24+
25+
_Import name: `Sentry.Integrations.Console`_
26+
27+
This integration wraps the `console` module in order to record all of its calls as breadcrumbs.
28+
29+
### Http
30+
31+
_Import name: `Sentry.Integrations.Http`_
32+
33+
This integration wraps `http` and `https` modules to capture all network requests as breadcrumbs and/or tracing spans.
34+
35+
Available options:
36+
37+
```javascript
38+
{
39+
breadcrumbs: boolean; // default: true
40+
tracing: boolean; // default: false
41+
}
42+
```
43+
44+
### OnUncaughtException
45+
46+
_Import name: `Sentry.Integrations.OnUncaughtException`_
47+
48+
This integration attaches a global uncaught exception handler. It can be modified to provide a custom shutdown function.
49+
The `onFatalError` option is meant to perform a cleanup before the process exits, not fully prevent it from exiting.
50+
51+
<Alert level="warning" title="Note">
52+
53+
Be aware that if you overwrite this setting, you will lose the default implementation, which handles draining queued events before exiting. If you want to examine how it works in order to be able to recreate it in your code, see the implementation of the [`logAndExitProcess`](https://github.com/getsentry/sentry-javascript/blob/master/packages/node/src/integrations/utils/errorhandling.ts) function.
54+
55+
</Alert>
56+
57+
Available options:
58+
59+
```javascript
60+
{
61+
onFatalError: (firstError: Error, secondError?: Error) => void;
62+
}
63+
```
64+
65+
### OnUnhandledRejection
66+
67+
_Import name: `Sentry.Integrations.OnUnhandledRejection`_
68+
69+
This integration attaches a global unhandled rejection handler. By default, all unhandled rejections trigger a warning and log the error. You can change this behavior using the `mode` option, which is in line with Node's CLI options: https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode.
70+
71+
Available options:
72+
73+
```javascript
74+
{
75+
mode: "none" | "warn" | "strict"; // default: "warn"
76+
}
77+
```
78+
79+
### ContextLines
80+
81+
_Import name: `Sentry.Integrations.ContextLines`_
82+
83+
_(Available in version 6.18.0 and above)_
84+
85+
This integration adds source file context to stack frames for captured exceptions
86+
87+
Available options:
88+
89+
```javascript
90+
{
91+
// The number of context lines to include with each frame
92+
frameContextLines: number;
93+
}
94+
```
95+
96+
### LinkedErrors
97+
98+
_Import name: `Sentry.Integrations.LinkedErrors`_
99+
100+
This integration allows you to configure linked errors. They'll be recursively read up to a specified limit and lookup will be performed by a specific key. By default, the limit is set to 5 and the key used is `"cause"`.
101+
102+
Available options:
103+
104+
```javascript
105+
{
106+
key: string; // default: "cause"
107+
limit: number; // default: 5
108+
}
109+
```
110+
111+
### Modules
112+
113+
_(New in version 7.13.0.)_
114+
115+
_Import name: `Sentry.Integrations.Modules`_
116+
117+
This integration fetches names of all currently installed Node modules and attaches the list to the event. Once fetched, Sentry will cache the list for later reuse.
118+
119+
## Modifying System Integrations
120+
121+
To disable system integrations set `defaultIntegrations: false` when calling `init()`.
122+
123+
To override an integration's settings, provide a new instance to the `integrations` option when calling `init()`. For example, to change the fatal error handler:
124+
125+
```javascript
126+
Sentry.init({
127+
dsn: '___PUBLIC_DSN___',
128+
integrations: [
129+
new Sentry.Integrations.OnUncaughtException({
130+
onFatalError: () => {
131+
// your implementation
132+
},
133+
}),
134+
],
135+
});
136+
```
137+
138+
### Removing an Integration
139+
140+
This example removes the default-enabled `Console` integration:
141+
142+
```javascript
143+
Sentry.init({
144+
// ...
145+
146+
integrations: function(integrations) {
147+
// integrations will be all default integrations
148+
return integrations.filter(integration => integration.name !== 'Console');
149+
},
150+
});
151+
```

0 commit comments

Comments
 (0)