From a165bdee62d1414addb6316fbda42a3de85ceb06 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Mon, 27 May 2024 09:51:04 +0200 Subject: [PATCH 1/3] feat(js): Update docs for custom integrations --- .../configuration/integrations/custom.mdx | 53 +++++++++++++------ 1 file changed, 37 insertions(+), 16 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/integrations/custom.mdx b/docs/platforms/javascript/common/configuration/integrations/custom.mdx index fc5ed3a7be8d5b..ba4f4520c124e8 100644 --- a/docs/platforms/javascript/common/configuration/integrations/custom.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/custom.mdx @@ -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,42 @@ 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 hooks 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; + }, +}; +``` + +### `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. From f81aa0a443c79c1277e2ee7f47e1359477429a79 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Mon, 27 May 2024 11:09:46 +0200 Subject: [PATCH 2/3] add `preprocessEvent` and `afterAllSetup` to docs --- .../configuration/integrations/custom.mdx | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/docs/platforms/javascript/common/configuration/integrations/custom.mdx b/docs/platforms/javascript/common/configuration/integrations/custom.mdx index ba4f4520c124e8..46189e95eb4f34 100644 --- a/docs/platforms/javascript/common/configuration/integrations/custom.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/custom.mdx @@ -62,7 +62,59 @@ const integration = { }; ``` +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); + }, +}; +``` From 8acd9e880f5ffcdbcae1e413325baa042f15f4bd Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Mon, 27 May 2024 11:10:04 +0200 Subject: [PATCH 3/3] Update docs/platforms/javascript/common/configuration/integrations/custom.mdx Co-authored-by: Andrei <168741329+andreiborza@users.noreply.github.com> --- .../javascript/common/configuration/integrations/custom.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/configuration/integrations/custom.mdx b/docs/platforms/javascript/common/configuration/integrations/custom.mdx index 46189e95eb4f34..121aa54046e5d8 100644 --- a/docs/platforms/javascript/common/configuration/integrations/custom.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/custom.mdx @@ -45,7 +45,7 @@ const integration = { ### `processEvent` -This hooks 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. +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 = {