diff --git a/docs/platforms/javascript/common/apis.mdx b/docs/platforms/javascript/common/apis.mdx index 35b362916fe446..7627cf0dc6810f 100644 --- a/docs/platforms/javascript/common/apis.mdx +++ b/docs/platforms/javascript/common/apis.mdx @@ -111,14 +111,17 @@ client enabled for continued use. promise, but it is recommended to use this only when necessary as it slows down event processing. - - Event processors added via `Sentry.addEventProcessor()` will be applied to all events in your application. - If you want to add an event processor that only applies to certain events, you can also add one to a scope as follows: - + + Event processors added via `Sentry.addEventProcessor()` will be applied to all + events in your application. If you want to add an event processor that only + applies to certain events, you can also add one to a scope as follows: + Event processors added via `Sentry.addEventProcessor()` will be applied to all events in your current request. - If you want to add an event processor that only applies to certain events, you can also add one to a scope as follows: + +If you want to add an event processor that only applies to certain events, you can also add one to a scope as follows: + ```javascript @@ -136,6 +139,7 @@ Sentry.withScope((scope) => { `beforeSend` and `beforeSendTransaction` are guaranteed to be run last, after all other event processors, (which means they get the final version of the event right before it's sent, hence the name). Event processors added with `addEventProcessor` are run in an undetermined order, which means changes to the event may still be made after the event processor runs. There can only be a single `beforeSend` / `beforeSendTransaction` processor, but you can add multiple event processors via `addEventProcessor()`. + @@ -322,7 +326,30 @@ Messages show up as issues on your issue stream, with the message as the issue n signature="function setContext(name: string, context: Record): void" parameters={[]} > - Set a context to be sent with Sentry events. + Set a context to be sent with Sentry events. Custom contexts allow you to attach arbitrary data to an event. + You cannot search these, but they are viewable on the issue page - if you + need to be able to filter for certain data, use [tags](./#setTag) instead. + + There are no restrictions on context name. In the context object, all keys are allowed except for `type`, which is used internally. + +By default, Sentry SDKs normalize nested structured context data up to three levels deep. +Any data beyond this depth will be trimmed and marked using its type instead. +To adjust this default, use the `normalizeDepth` SDK option. + +Learn more about conventions for common contexts in the [contexts interface developer documentation](https://develop.sentry.dev/sdk/data-model/event-payloads/contexts/). + + + Context data is structured and can contain any data you want: + + ```javascript + Sentry.setContext("character", { + name: "Mighty Fighter", + age: 19, + attack_type: "melee", + }); + ``` + + - Set a user to be sent with Sentry events. Set to `null` to unset the user. + Set a user to be sent with Sentry events. Set to `null` to unset the user. In + addition to the specified properties of the `User` object, you can also add + additional arbitrary key/value pairs. + + + + On the server, the IP address will be inferred from the incoming HTTP request, if available. + This is automatically done if you have configured `sendDefaultPii: true` in your SDK configuration. + + + + On the browser, if the users' `ip_address` is set to `"{{ auto }}"`, Sentry + will infer the IP address from the connection between your app and Sentrys' + server. `{{auto}}` is automatically set if you have configured `sendDefaultPii: + true` in your SDK configuration. + + + To ensure your users' IP addresses are never stored in your event data, you can go to your project settings, click on "Security & Privacy", and enable "Prevent Storing of IP Addresses" or use Sentry's [server-side data scrubbing](/security-legal-pii/scrubbing/) to remove `$user.ip_address`. Adding such a rule ultimately overrules any other logic. + + + + + + + + `Sentry.setUser()` will set the user for the currently active request - see Request Isolation for more information. For example, if you want to set the user for a single request, you can do this like this: + + + + Or if you want to set the user for all requests, you could use a middleware like this: + + + + + + - The DSN tells the SDK where to send the events. If this is not set, the SDK will not send any events. Learn more about [DSN utilization](/product/sentry-basics/dsn-explainer/#dsn-utilization). - - + The DSN tells the SDK where to send the events. If this is not set, the SDK will not send any events. + Learn more about [DSN utilization](/product/sentry-basics/dsn-explainer/#dsn-utilization). + @@ -63,6 +63,12 @@ Sets the URL that will be used to transport captured events. This can be used to + + +Set this option to `true` to send default PII data to Sentry. Among other things, enabling this will enable automatic IP address collection on events. + + + This variable controls the total amount of breadcrumbs that should be captured. You should be aware that Sentry has a [maximum payload size](https://develop.sentry.dev/sdk/data-model/envelopes/#size-limits) and any events exceeding that payload size will be dropped. @@ -305,8 +311,9 @@ When enabled, all props of the Vue component where the error was thrown in are a to capture Vue exceptions and report them to Sentry. When `attachErrorHandler` is set to `false`, automatic error reporting is disabled. - Usually, this option should stay enabled, unless you want to set up Sentry error reporting yourself. - For example, the Sentry Nuxt SDK does not attach an error handler as it's capturing errors through the error hooks provided by Nuxt. +Usually, this option should stay enabled, unless you want to set up Sentry error reporting yourself. +For example, the Sentry Nuxt SDK does not attach an error handler as it's capturing errors through the error hooks provided by Nuxt. + diff --git a/docs/platforms/javascript/common/enriching-events/context/index.mdx b/docs/platforms/javascript/common/enriching-events/context/index.mdx deleted file mode 100644 index c39a461affdf33..00000000000000 --- a/docs/platforms/javascript/common/enriching-events/context/index.mdx +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Context -description: "Custom contexts allow you to attach arbitrary data (strings, lists, dictionaries) to an event." ---- - -Custom contexts allow you to attach arbitrary data to an event. Often, this context is shared among any issue captured in its lifecycle. You cannot search these, but they are viewable on the issue page: - - - - - -If you need to be able to search on custom data, [use tags](../tags) instead. - - - -## Structured Context - -The best way to attach custom data is with a structured context. A context must always be an object and its values can be arbitrary. - -You'll first need to import the SDK, as usual: - - - -Then, use and give the context a unique name: - - - -There are no restrictions on context name. In the context object, all keys are allowed except for `type`, which is used internally. - -By default, Sentry SDKs normalize nested structured context data up to three levels deep. Any data beyond this depth will be trimmed and marked using its type instead. To adjust this default, use the `normalizeDepth` SDK option. - -Learn more about conventions for common contexts in the [contexts interface developer documentation](https://develop.sentry.dev/sdk/data-model/event-payloads/contexts/). - -## Size Limitations - -When sending context, _consider payload size limits_. Sentry does not recommend sending the entire application state and large data blobs in contexts. If you exceed the maximum payload size, Sentry will respond with HTTP error `413 Payload Too Large` and reject the event. When `keepalive: true` is used, the request may additionally stay pending forever. - -The Sentry SDK will try its best to accommodate the data you send and trim large context payloads. Some SDKs can truncate parts of the event; for more details, see the [developer documentation on SDK data handling](https://develop.sentry.dev/sdk/expected-features/data-handling/). - -## Passing Context Directly - -Some contextual data can be provided directly to `captureException` and `captureMessage` calls. Provided data will be merged with the one that is already stored inside the current scope, unless explicitly cleared using a callback method. - -This functionality works in three different variations: - -1. Plain object containing updatable attributes -2. Scope instance from which we will extract the attributes -3. Callback function that will receive the current scope as an argument and allow for modifications - -We allow the following context keys to be passed: `tags`, `extra`, `contexts`, `user`, `level`, `fingerprint`. - -### Example Usages - -```javascript -Sentry.captureException(new Error("something went wrong"), { - tags: { - section: "articles", - }, -}); -``` - -Explicitly clear what has been already stored on the scope: - -```javascript -Sentry.captureException(new Error("clean as never"), (scope) => { - scope.clear(); - scope.setTag("clean", "slate"); - return scope; -}); -``` - -Use Scope instance to pass the data (its attributes will still merge with the global scope): - -```javascript -const scope = new Sentry.Scope(); -scope.setTag("section", "articles"); -Sentry.captureException(new Error("something went wrong"), scope); -``` - -Use Scope instance to pass the data and ignore globally configured Scope attributes: - -```javascript -const scope = new Sentry.Scope(); -scope.setTag("section", "articles"); -Sentry.captureException(new Error("something went wrong"), () => scope); -``` - -## Clearing Context - -Context is held in the current scope and thus is cleared when the scope is removed ("popped"). You can push and pop your own scopes to apply context data to a specific code block or function. - - - - -For Node.js backend frameworks, the SDK will create a separate scope for each incoming request. Modifying the context of the current scope in a request handler will therefore only affect events related to the request being handled. - - - - -Sentry supports two different ways for unsetting context: - -1. Modifying, overwriting or clearing values on the current scope. -2. Creating a temporary scope for capturing exceptions. - -With the following snippet, the `user` context will be updated for all future events on the current scope: - -```javascript -Sentry.setUser(someUser); -``` - -If you want to remove all data from the current scope, you can call: - -```javascript -Sentry.getCurrentScope().clear(); -``` - -The following will only configure the `user` context for the error captured inside the `withScope` callback. The context will be automatically restored to the previous state afterwards: - -```javascript -Sentry.withScope(function (scope) { - scope.setUser(someUser); - Sentry.captureException(error); -}); -``` - -To learn more about setting the Scope, see our documentation on [Scopes and Hubs](../scopes/). - -## Additional Data - -**Additional Data is deprecated** in favor of structured contexts. - -Sentry used to support adding unstructured "Additional Data" via . diff --git a/docs/platforms/javascript/common/enriching-events/identify-user/index.mdx b/docs/platforms/javascript/common/enriching-events/identify-user/index.mdx deleted file mode 100644 index a3dd7f6b0a616d..00000000000000 --- a/docs/platforms/javascript/common/enriching-events/identify-user/index.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Users -description: "Learn how to configure the SDK to capture the user and gain critical pieces of information that construct a unique identity in Sentry." ---- - -Users consist of a few critical pieces of information that construct a unique identity in Sentry. Each of these is optional, but one **must** be present for the Sentry SDK to capture the user: - - - -### `id` - -Your internal identifier for the user. - -### `username` - -The username. Typically used as a better label than the internal id. - -### `email` - -An alternative, or addition, to the username. Sentry is aware of email addresses and can display things such as Gravatars and unlock messaging capabilities. - -### `ip_address` - -The user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user. -Serverside SDKs that instrument incoming requests will attempt to pull the IP address from the HTTP request data (`request.env.REMOTE_ADDR` field in JSON), if available. This requires you to set the `include.ip` option to `true` in the [`RequestData`](/platforms/javascript/guides/connect/configuration/integrations/default-integrations/#requestdata) integration. - -If the user's `ip_address` is set to `"{{auto}}"`, Sentry will infer the IP address from the connection between your app and Sentry's server. - -If the field is omitted, the default value is `"{{auto}}"`. SDKs and other clients should not rely on this behavior and should set IP addresses or `"{{auto}}"` explicitly. - -To ensure your users' IP addresses are never stored in your event data, you can go to your project settings, click on "Security & Privacy", and enable "Prevent Storing of IP Addresses" or use Sentry's [server-side data scrubbing](/security-legal-pii/scrubbing/) to remove `$user.ip_address`. Adding such a rule ultimately overrules any other logic. - - - -Additionally, you can provide arbitrary key/value pairs beyond the reserved names, and the Sentry SDK will store those with the user. - -## Setting the User - -You can set the user by calling the `setUser` method on the Sentry SDK: - - - -You can also clear the currently set user: - - - - - -`Sentry.setUser()` will set the user for the currently active request - see Request Isolation for more information. For example, if you want to set the user for a single request, you can do this like this: - - - -Or if you want to set the user for all requests, you could use a middleware like this: - - - diff --git a/docs/platforms/javascript/common/enriching-events/index.mdx b/docs/platforms/javascript/common/enriching-events/index.mdx index a96a76ffdf3d08..050223cad6110e 100644 --- a/docs/platforms/javascript/common/enriching-events/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/index.mdx @@ -1,7 +1,77 @@ --- title: Enriching Events -description: Add additional context to your events to make them easier to debug. +description: Add additional data to your events to make them easier to debug. sidebar_order: 5 --- - +In addition to the data that the Sentry SDK automatically captures, you can add additional data to events to help you debug them. + +## Adding Additional Event Data + +There are many ways to enrich events with additional data: + +### Identifying Users + +You can add user information to events to help you identify the user that is experiencing an issue. +See setUser to learn how to to set the user on Sentry events. + +### Setting Tags + +Tags are a way to add additional metadata to events. They can be used to filter events in the Sentry UI. See Tags to learn more about tags, or setTag & setTags to learn how to set tags on Sentry events. + +### Setting Context + +Context is a way to add additional metadata to events. +While you cannot filter by contexts in the Sentry UI, context information is displayed in the event details. +See setContext to learn how to set context data on Sentry events. + +### Adding Breadcrumbs + +Breadcrumbs are a way to add information about steps that happened prior to an event. +See Breadcrumbs to learn how to add breadcrumbs to Sentry events. + +### Adding Attachments + +Attachments are a way to add additional files to events. +See Attachments to learn how to add attachments to Sentry events. + +### Event Processors + +Event processors are a way to mutate events before they are sent to Sentry. +See Event Processors to learn how to use event processors. + +## Adding Additional Event Data To Certain Events Only + + + All APIs described above will attach data to all events for the current + request. + + + + All APIs described above will attach data to all events for the current page. + + +If you only want to attach data to certain events, you can use withScope to create a new scope and attach data to that scope only. + +## Custom Fingerprinting + +All events have a fingerprint. Events with the same fingerprint are grouped together into an issue. If the default grouping for a specific type of event does not work for you, you can customize this by setting a custom fingerprint. See Event Fingerprinting to learn how to set a custom fingerprint. + +## Scopes + +When an event is captured and sent to Sentry, SDKs will merge that event data with extra information from the current scope. SDKs will typically automatically manage the scopes for you in the framework integrations and you don't need to think about them. However, if you want to better understand how scopes work and how you can leverage them for your use case, you can learn more about scopes. + + + +## Request Isolation + +Learn more about how to isolate requests +in order to ensure that set data does not leak between requests. + + + +## Size Limitations + +When sending context, _consider payload size limits_. Sentry does not recommend sending the entire application state and large data blobs in contexts. If you exceed the maximum payload size, Sentry will respond with HTTP error `413 Payload Too Large` and reject the event. When `keepalive: true` is used, the request may additionally stay pending forever. + +The Sentry SDK will try its best to accommodate the data you send and trim large context payloads. Some SDKs can truncate parts of the event; for more details, see the [developer documentation on SDK data handling](https://develop.sentry.dev/sdk/expected-features/data-handling/). diff --git a/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx b/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx index d23f40d5448f81..cc7eff4c40b534 100644 --- a/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx @@ -17,6 +17,7 @@ supported: - javascript.astro - javascript.remix - javascript.tanstackstart-react + - javascript.react-router notSupported: - javascript --- diff --git a/docs/platforms/javascript/common/tracing/span-metrics/index.mdx b/docs/platforms/javascript/common/tracing/span-metrics/index.mdx index 24073f2e51b777..dc2cc1754f6349 100644 --- a/docs/platforms/javascript/common/tracing/span-metrics/index.mdx +++ b/docs/platforms/javascript/common/tracing/span-metrics/index.mdx @@ -70,7 +70,7 @@ For detailed examples of how to implement span metrics in common scenarios, see ## Adding Metrics to All Spans -To consistently add metrics across all spans in your application, you can use the `beforeSendTransaction` callback: +To consistently add metrics across all spans in your application, you can use the `beforeSendSpan` callback: ```javascript Sentry.init({ diff --git a/redirects.js b/redirects.js index 606ec8f626ab1f..ec680f483b5237 100644 --- a/redirects.js +++ b/redirects.js @@ -506,6 +506,22 @@ const userDocsRedirects = [ source: '/platforms/javascript/guides/:guide/configuration/draining/', destination: '/platforms/javascript/guides/:guide/apis/#flush', }, + { + source: '/platforms/javascript/enriching-events/identify-user/', + destination: '/platforms/javascript/apis/#setUser', + }, + { + source: '/platforms/javascript/guides/:guide/enriching-events/identify-user/', + destination: '/platforms/javascript/guides/:guide/apis/#setUser', + }, + { + source: '/platforms/javascript/enriching-events/context/', + destination: '/platforms/javascript/apis/', + }, + { + source: '/platforms/javascript/guides/:guide/enriching-events/context/', + destination: '/platforms/javascript/guides/:guide/enriching-events/', + }, { source: '/platforms/:platform/context/', destination: '/platforms/:platform/enriching-events/context/',