Skip to content

Commit d90cff2

Browse files
krystofwoldrichlizokmgetsantry[bot]
authored
Share Integrations docs with JS and RN (#7009)
Co-authored-by: Liza Mock <liza.mock@sentry.io> Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
1 parent 2757bf6 commit d90cff2

File tree

22 files changed

+620
-431
lines changed

22 files changed

+620
-431
lines changed

‎src/includes/platforms/configuration/integrations/custom.mdx

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Add a custom integration to your JavaScript using the following format:
2+
3+
```javascript
4+
// All integrations that come with an SDK can be found on Sentry.Integrations object
5+
// Custom integration must conform to the Integration interface: https://github.com/getsentry/sentry-javascript/blob/master/packages/types/src/integration.ts
6+
7+
Sentry.init({
8+
// ...
9+
integrations: [new MyAwesomeIntegration()],
10+
});
11+
```

‎src/includes/platforms/configuration/integrations/default.mdx

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
The below system integrations are part of the standard library or the interpreter itself and are enabled by default. To understand what they do and how to disable them if they cause issues, read on.
2+
3+
## What's 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+
By default, it'll ignore errors that start with `Script error` or `Javascript error: Script error`.
13+
14+
To configure this integration, use the `ignoreErrors`, `ignoreTransactions`, `denyUrls`,
15+
and `allowUrls` SDK options directly. Keep in mind that `denyURLs` and `allowURLs`
16+
only work 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 those functions or methods are wrapped by our error or breadcrumb handlers.
23+
24+
<PlatformSection notSupported={["react-native"]}>
25+
26+
### TryCatch
27+
28+
_Import name: `Sentry.Integrations.TryCatch`_
29+
30+
This integration wraps native time and events APIs (`setTimeout`, `setInterval`, `requestAnimationFrame`, `addEventListener/removeEventListener`) in `try/catch` blocks to handle async exceptions.
31+
32+
</PlatformSection>
33+
34+
### Breadcrumbs
35+
36+
_Import name: `Sentry.Integrations.Breadcrumbs`_
37+
38+
This integration wraps native APIs to capture breadcrumbs. By default, the Sentry SDK wraps all APIs.
39+
40+
Available options:
41+
42+
```javascript
43+
{
44+
// Log calls to `console.log`, `console.debug`, etc
45+
console: boolean;
46+
47+
// Log all click and keypress events
48+
// - When an object with `serializeAttribute` key is provided,
49+
// Breadcrumbs integration will look for given attribute(s) in DOM elements,
50+
// while generating the breadcrumb trails.
51+
// Matched elements will be followed by their custom attributes,
52+
// instead of their `id`s or `class` names.
53+
dom: boolean | { serializeAttribute: string | string[] };
54+
55+
// Log HTTP requests done with the Fetch API
56+
fetch: boolean;
57+
58+
// Log calls to `history.pushState` and friends
59+
history: boolean;
60+
61+
// Log whenever we send an event to the server
62+
sentry: boolean;
63+
64+
// Log HTTP requests done with the XHR API
65+
xhr: boolean;
66+
}
67+
```
68+
69+
<PlatformSection notSupported={["react-native"]}>
70+
71+
### GlobalHandlers
72+
73+
_Import name: `Sentry.Integrations.GlobalHandlers`_
74+
75+
This integration attaches global handlers to capture uncaught exceptions and unhandled rejections.
76+
77+
Available options:
78+
79+
```javascript
80+
{
81+
onerror: boolean;
82+
onunhandledrejection: boolean;
83+
}
84+
```
85+
86+
</PlatformSection>
87+
88+
### LinkedErrors
89+
90+
_Import name: `Sentry.Integrations.LinkedErrors`_
91+
92+
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"`.
93+
94+
Available options:
95+
96+
```javascript
97+
{
98+
key: string;
99+
limit: number;
100+
}
101+
```
102+
103+
Here is a code example of how this could be implemented:
104+
105+
<PlatformContent includePath="configuration/linked-errors" />
106+
107+
### HttpContext
108+
109+
_(Previously: `UserAgent`)_
110+
111+
_Import name: `Sentry.Integrations.HttpContext`_
112+
113+
<PlatformSection notSupported={["react-native"]}>
114+
115+
<Note>
116+
117+
Before version 7.0.0 of the Sentry SDK, this integration was called `UserAgent`.
118+
It was renamed because the integration handles more than user-agent data.
119+
120+
_Import name: `Sentry.Integrations.UserAgent`_
121+
122+
</Note>
123+
124+
</PlatformSection>
125+
126+
This integration attaches HTTP request information, such as URL, user-agent, referrer, and other headers to the event.
127+
It allows us to correctly catalog and tag events with specific OS, browser, and version information.
128+
129+
### Dedupe
130+
131+
_Import name: `Sentry.Integrations.Dedupe`_
132+
133+
This integration is enabled by default for Browser, but only deduplicates certain events. It can be helpful if you're receiving many duplicate errors. Note, that Sentry only compares stack traces and fingerprints.
134+
135+
<PlatformContent includePath="configuration/dedupe" />
136+
137+
<PlatformSection supported={["javascript.nextjs", "javascript.remix"]}>
138+
139+
### RequestData
140+
141+
_(New in version 7.17.1.)_
142+
143+
_Import name: `Sentry.Integrations.RequestData`_
144+
145+
This integration adds data from incoming requests to transaction and error events that occur during request handling done by the backend.
146+
147+
Available options:
148+
149+
```javascript
150+
{
151+
// Controls what types of data are added to the event
152+
include: {
153+
cookies: boolean // default: true,
154+
data: boolean // default: true,
155+
headers: boolean // default: true,
156+
ip: boolean // default: false,
157+
query_string: boolean // default: true,
158+
url: boolean // default: true,
159+
user: boolean | {
160+
id: boolean // default: true,
161+
username: boolean // default: true,
162+
email: boolean // default: true,
163+
},
164+
},
165+
// Controls how the transaction will be reported. Options are 'path' (`/some/route`),
166+
// 'methodPath' (`GET /some/route`), and 'handler' (the name of the route handler
167+
// function, if available)
168+
transactionNamingScheme: string // default: 'methodPath',
169+
};
170+
```
171+
172+
</PlatformSection>
173+
174+
## Modifying System Integrations
175+
176+
To disable system integrations, set `defaultIntegrations: false` when calling `init()`.
177+
178+
To override their settings, provide a new instance with your config to the `integrations` option. For example, to turn off browser capturing console calls:
179+
180+
```javascript
181+
Sentry.init({
182+
dsn: "___PUBLIC_DSN___",
183+
184+
integrations: [
185+
new Sentry.Integrations.Breadcrumbs({
186+
console: false,
187+
}),
188+
],
189+
});
190+
```
191+
192+
### Removing an Integration
193+
194+
This example removes the default-enabled integration for adding breadcrumbs to the event:
195+
196+
```javascript
197+
Sentry.init({
198+
// ...
199+
integrations: function (integrations) {
200+
// integrations will be all default integrations
201+
return integrations.filter(function (integration) {
202+
return integration.name !== "Breadcrumbs";
203+
});
204+
},
205+
});
206+
```

‎src/includes/platforms/configuration/integrations/plugin.mdx

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
The below pluggable integrations are snippets of code that augment functionality for specific applications and/or frameworks. Read on to understand what they do and how to enable them.
2+
3+
## How to Enable
4+
5+
Install the `@sentry/integrations` package and provide a new instance with your config to the `integrations` option. Include the plugin after the SDK has been loaded.
6+
7+
For example:
8+
9+
<PlatformContent includePath="configuration/enable-pluggable-integrations" />
10+
11+
Alternatively, you can add integrations lazily via `client.addIntegration()`.
12+
This is useful if you only want to enable an integration in a specific environment or if you want to lazy-load an integration.
13+
For all other cases, we recommend you use the `integrations` option.
14+
15+
<PlatformContent includePath="configuration/enable-pluggable-integrations-lazy" />
16+
17+
<PlatformSection notSupported={["react-native"]}>
18+
19+
<PlatformSection supported={["javascript"]}>
20+
21+
### ExtraErrorData
22+
23+
_Import name: `Sentry.Integrations.ExtraErrorData`_
24+
25+
This integration extracts all non-native attributes from the `error` object and attaches them to the event as `extra` data. If the error object has a `.toJSON()` method, the `ExtraErrorData` integration will run it to extract additional information.
26+
27+
Available options:
28+
29+
<PlatformContent includePath="configuration/extra-error-data" />
30+
31+
</PlatformSection>
32+
33+
### CaptureConsole
34+
35+
_Import name: `Sentry.Integrations.CaptureConsole`_
36+
37+
This integration captures all `Console API` calls and redirects them to Sentry using the SDK's `captureMessage` or `captureException` call, depending on the log level. It then re-triggers to preserve default native behavior:
38+
39+
<PlatformContent includePath="configuration/capture-console" />
40+
41+
### Debug
42+
43+
_Import name: `Sentry.Integrations.Debug`_
44+
45+
This integration allows you to inspect the contents of a processed event and `hint` object that gets passed to `beforeSend` or `beforeSendTransaction`. It will _always_ run as the last integration, no matter when it was registered.
46+
47+
Note that this is different than setting `debug: true` in your `Sentry.init` options, which will enable debug logging in the console.
48+
49+
Available options:
50+
51+
<PlatformContent includePath="configuration/debug" />
52+
53+
</PlatformSection>
54+
55+
### HttpClient
56+
57+
<PlatformSection notSupported={["react-native"]}>
58+
59+
_(New in version 7.30.0)_
60+
61+
</PlatformSection>
62+
63+
<PlatformSection supported={["react-native"]}>
64+
65+
_(New in version 5.3.0)_
66+
67+
</PlatformSection>
68+
69+
_Import name: `Sentry.Integrations.HttpClient`_
70+
71+
This integration captures errors on failed requests from Fetch and XHR and attaches request and response information.
72+
73+
By default, error events don't contain header or cookie data. You can change this behavior by setting the `sendDefaultPii` option to `true`.
74+
75+
Available options:
76+
77+
<PlatformContent includePath="configuration/http-client" />
78+
79+
<Alert level="warning" title="Note">
80+
81+
Due to the limitations of both the Fetch and XHR API, the cookie and header collection for both requests and responses is based on best effort. Certain headers may be missing in the event created by the integration.
82+
83+
</Alert>
84+
85+
### RewriteFrames
86+
87+
_Import name: `Sentry.Integrations.RewriteFrames`_
88+
89+
This integration allows you to apply a transformation to each frame of the stack trace. In the streamlined scenario, it can be used to change the name of the file frame it originates from, or it can be fed with an iterated function to apply any arbitrary transformation.
90+
91+
On Windows machines, you have to use Unix paths and skip the volume letter in the `root` option to enable it. For example, `C:\\Program Files\\Apache\\www` won’t work, however, `/Program Files/Apache/www` will.
92+
93+
Available options:
94+
95+
<PlatformContent includePath="configuration/rewrite-frames" />
96+
97+
<PlatformSection notSupported={["react-native"]}>
98+
99+
### ReportingObserver
100+
101+
_Import name: `Sentry.Integrations.ReportingObserver`_
102+
103+
This integration hooks into the ReportingObserver API and sends captured events through to Sentry. It can be configured to handle only specific issue types.
104+
105+
Available options:
106+
107+
<PlatformContent includePath="configuration/reporting-observer" />
108+
109+
</PlatformSection>

0 commit comments

Comments
 (0)