Pluggable Integrations
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.
How to Enable
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.
For example:
import * as Sentry from "@sentry/browser";
import { ReportingObserver as ReportingObserverIntegration } from "@sentry/integrations";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [new ReportingObserverIntegration()],
});
Alternatively, you can add integrations lazily via client.addIntegration()
.
This is useful if you only want to enable an integration in a specific environment or if you want to lazy-load an integration.
For all other cases, we recommend you use the integrations
option.
import * as Sentry from "@sentry/browser";
import { ReportingObserver as ReportingObserverIntegration } from "@sentry/integrations";
Sentry.init({
integrations: [],
});
const client = Sentry.getCurrentHub().getClient();
if (client) {
client.addIntegration(new ReportingObserverIntegration());
}
ExtraErrorData
Import name: Sentry.Integrations.ExtraErrorData
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.
Available options:
import * as Sentry from "@sentry/browser";
import { ExtraErrorData as ExtraErrorDataIntegration } from "@sentry/integrations";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [
new ExtraErrorDataIntegration({
// Limit of how deep the object serializer should go. Anything deeper than limit will
// be replaced with standard Node.js REPL notation of [Object], [Array], [Function] or
// a primitive value. Defaults to 3.
depth: number,
}),
],
});
CaptureConsole
Import name: Sentry.Integrations.CaptureConsole
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:
import * as Sentry from "@sentry/browser";
import { CaptureConsole as CaptureConsoleIntegration } from "@sentry/integrations";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [new CaptureConsoleIntegration(
{
// array of methods that should be captured
// defaults to ['log', 'info', 'warn', 'error', 'debug', 'assert']
levels: string[];
}
)],
});
Debug
Import name: Sentry.Integrations.Debug
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.
Note that this is different than setting debug: true
in your Sentry.init
options, which will enable debug logging in the console.
Available options:
import * as Sentry from "@sentry/browser";
import { Debug as DebugIntegration } from "@sentry/integrations";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [new DebugIntegration(
{
// trigger DevTools debugger instead of using console.log
debugger: boolean;
// stringify event before passing it to console.log
stringify: boolean;
}
)],
});
HttpClient
(New in version 7.30.0)
Import name: Sentry.Integrations.HttpClient
This integration captures errors on failed requests from Fetch and XHR and attaches request and response information.
By default, error events don't contain header or cookie data. You can change this behavior by setting the sendDefaultPii
option to true
.
Available options:
import * as Sentry from "@sentry/browser";
import { HttpClient as HttpClientIntegration } from "@sentry/integrations";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [
new HttpClientIntegration({
// This array can contain tuples of `[begin, end]` (both inclusive),
// single status codes, or a combination of both.
// default: [[500, 599]]
failedRequestStatusCodes: [[500, 505], 507],
// This array can contain Regexes, strings, or a combination of both.
// default: [/.*/]
failedRequestTargets: [
"http://example.com/api/test",
/(staging\.)?mypage\.com/,
],
}),
],
// This option is required for capturing headers and cookies.
sendDefaultPii: true,
});
Note
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.
RewriteFrames
Import name: Sentry.Integrations.RewriteFrames
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.
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.
Available options:
import * as Sentry from "@sentry/browser";
import { RewriteFrames as RewriteFramesIntegration } from "@sentry/integrations";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [new RewriteFramesIntegration(
{
// root path that will be stripped from the current frame's filename by the default iteratee if the filename is an absolute path
root: string;
// a custom prefix that will be used by the default iteratee (default: `app://`)
prefix: string;
// function that takes the frame, applies a transformation, and returns it
iteratee: (frame) => frame;
}
)],
});
Usage Examples
For example, if the full path to your file is /www/src/app/file.js
:
Usage | Path in Stack Trace | Description |
---|---|---|
RewriteFrames() | app:///file.js | The default behavior is to replace the absolute path, except the filename, and prefix it with the default prefix (app:/// ). |
RewriteFrames({prefix: 'foo/'}) | foo/file.js | Prefix foo/ is used instead of the default prefix app:/// . |
RewriteFrames({root: '/www'}) | app:///src/app/file.js | root is defined as /www , so only that part is trimmed from beginning of the path. |
ReportingObserver
Import name: Sentry.Integrations.ReportingObserver
This integration hooks into the ReportingObserver API and sends captured events through to Sentry. It can be configured to handle only specific issue types.
Available options:
import * as Sentry from "@sentry/browser";
import { ReportingObserver as ReportingObserverIntegration } from "@sentry/integrations";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [new ReportingObserverIntegration(
{
types: <'crash'|'deprecation'|'intervention'>[];
}
)],
});
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").
- Package:
- npm:@sentry/browser
- Version:
- 7.54.0
- Repository:
- https://github.com/getsentry/sentry-javascript