Skip to content

Commit

Permalink
feat(js): Update docs for custom integrations (#10150)
Browse files Browse the repository at this point in the history
---------

Co-authored-by: Andrei <168741329+andreiborza@users.noreply.github.com>
  • Loading branch information
mydea and andreiborza authored May 27, 2024
1 parent 483da29 commit 8c34620
Showing 1 changed file with 89 additions and 16 deletions.
105 changes: 89 additions & 16 deletions docs/platforms/javascript/common/configuration/integrations/custom.mdx
Original file line number Diff line number Diff line change
@@ -14,8 +14,9 @@ A custom integration can be created and added to the SDK as follows:
function myAwesomeIntegration() {
return {
name: "MyAwesomeIntegration",
setupOnce() {
setup(client) {
// Do something when the SDK is initialized
// The client that is being setup is passed to the hook
},
};
}
@@ -26,22 +27,94 @@ Sentry.init({
});
```

The JavaScript Core Package (`@sentry/core`) also exports a helper function called `defineIntegration` to help with type-safety:
All hooks on an integration are optional. The only required field is the `name`. You can use one or multiple of the following hooks in a custom integration:

```typescript
import { defineIntegration } from "@sentry/core";
### `setup`

const myAwesomeIntegration = defineIntegration(() => {
return {
name: "MyAwesomeIntegration",
setupOnce() {
// Do something when the SDK is initialized
},
};
});
The `setup` hook is called when the SDK is initialized. It receives the client instance as an argument.
You should use this if you want to run some code on initialization.

Sentry.init({
// ...
integrations: [myAwesomeIntegration()],
});
```javascript
const integration = {
name: "MyAwesomeIntegration",
setup(client) {
setupCustomSentryListener(client);
},
};
```

### `processEvent`

This hook can be used to modify events before they are sent to Sentry. It receives the event as an argument and should return the modified event. The hook also receives a hint object that may hold additional event metadata, and the client that is sending the event. You can also return `null` to drop the event from being sent.

```javascript
const integration = {
name: "MyAwesomeIntegration",
processEvent(event, hint, client) {
event.extra = {
...event.extra,
myCustomTag: "value",
};
// Return the modified event,
// or return `null` to drop the event
return event;
},
};
```

You can also return a promise that resolves with an event or `null`. However, this is not recommended and should be avoided wherever possible, because it can delay event sending.

### `preprocessEvent`

This hook is similar to `processEvent`, but it is called before the event is passed to any other `processEvent` hook. It can be used in places where the order of processing is important.

In most cases, you should just use `processEvent`. Only use `preprocessEvent` if you need to ensure that your hook is called before any other `processEvent` hook.

Similar to `processEvent`, this hooks receives the event, hint, and client as arguments. However, this hook does not allow to return a modified event or `null` to drop the event - instead, you can only mutate the passed in event in this hook:

```javascript
const integration = {
name: "MyAwesomeIntegration",
preprocessEvent(event, hint, client) {
event.extra = {
...event.extra,
myCustomTag: "value",
};
// Nothing to return, just mutate the event
},
};
```

### `setupOnce`

This hook is similar to `setup`, but it is only run once, even if the SDK is re-initialized. It does not receive any arguments.
You should probably not use this, but use `setup` instead. The only reason to use `setupOnce` is e.g. when you may be calling `Sentry.init()` multiple times and you want to ensure a certain piece of code is only run once.

```javascript
const integration = {
name: "MyAwesomeIntegration",
setupOnce() {
wrapLibrary();
},
};
```

### `afterAllSetup`

This hook is triggered after `setupOnce()` and `setup()` have been called for all integrations.
You can use it if it is important that all other integrations have been run before.

In most cases, you should not need to use this hook, and should use `setup` instead.

The hook receives the `client` that is being set up as the first argument.

```javascript
const integration = {
name: "MyAwesomeIntegration",
afterAllSetup(client) {
// We can be sure that all other integrations
// have run their `setup` and `setupOnce` hooks now
startSomeThing(client);
},
};
```

0 comments on commit 8c34620

Please sign in to comment.