From b53075b5ff36dbd1339d725d7a2551477327814a Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 24 Jun 2026 19:07:39 +0200 Subject: [PATCH 1/2] feat(js): Add documentation for `Sentry.setAttribute(s)` APIs --- .../javascript/common/configuration/apis.mdx | 56 ++++++++++++++++++- .../javascript/common/logs/index.mdx | 24 +++++--- .../javascript/guides/nextjs/logs/index.mdx | 23 ++++---- .../metrics/default-attributes/javascript.mdx | 2 +- .../metrics/usage/javascript.mdx | 10 ++-- 5 files changed, 90 insertions(+), 25 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/apis.mdx b/docs/platforms/javascript/common/configuration/apis.mdx index e1ea5a3540a6a7..c2b0b941eb92b9 100644 --- a/docs/platforms/javascript/common/configuration/apis.mdx +++ b/docs/platforms/javascript/common/configuration/apis.mdx @@ -302,7 +302,7 @@ Messages show up as issues on your issue stream, with the message as the issue n -## Enriching Events +## Enriching Telemetry + | Array | Array", + required: true, + description: + "The attribute value. Supported types are strings, numbers, booleans, and arrays of these.", + }, + ]} +> +Set a single attribute. Unlike tags, attributes are applied to your logs, metrics, and streamed spans (rather than errors). + +```javascript +Sentry.setAttribute("is_admin", true); +Sentry.setAttribute("render_duration", 150); +``` + + + + | Array | Array>", + required: true, + description: "An object of key-value pairs to set as attributes.", + }, + ]} +> +Set multiple attributes at once. This is the attribute equivalent of [`setTags`](#setTags). See [`setAttribute`](#setAttribute) for details on how attributes are applied. + +```javascript +Sentry.setAttributes({ + is_admin: true, + payment_selection: "credit_card", + render_duration: 150, +}); +``` + + + -## Scope Attributes +## Shared Attributes -Set attributes on a scope to automatically include them in all logs within that context. Requires SDK version `10.32.0` or above. +Use `Sentry.setAttribute` and `Sentry.setAttributes` to attach attributes that are automatically included in all logs (as well as your metrics and streamed spans). These work just like `Sentry.setTag` and `Sentry.setTags`, but they accept `string`, `number`, and `boolean` values or arrays of these. `Sentry.setTag(s)` requires SDK version `10.61.0` or above. -Use global scope for app-wide attributes, and isolation scope for request-specific context. Only `string`, `number`, and `boolean` attribute values are supported. +To attach attributes to a broader or narrower context, set them on a specific scope instead (requires SDK version `10.32.0` or above). Use the global scope for app-wide attributes and the current scope for a single operation. ```javascript +// Applied to all logs, metrics, and spans +Sentry.setAttributes({ + org_id: user.orgId, + user_tier: user.tier, +}); +Sentry.setAttribute("service", "checkout"); + // Global scope - shared across entire app Sentry.getGlobalScope().setAttributes({ service: "checkout", version: "2.1.0", }); -// Isolation scope - unique per request -Sentry.getIsolationScope().setAttributes({ - org_id: user.orgId, - user_tier: user.tier, -}); - // Current scope - single operation Sentry.withScope((scope) => { scope.setAttribute("request_id", req.id); @@ -217,6 +218,11 @@ Everything in Sentry is linked by trace. When you're viewing a log, you can jump +### Shared Attributes + +Any attributes set via `Sentry.setAttribute()` / `Sentry.setAttributes()` (or directly on a scope) are automatically included on all logs. The top-level APIs require SDK version `10.61.0` or above. See [Attributes](#shared-attributes) above for details. + + ## Related Features - Tracing — Logs are automatically linked to traces, so you can see logs in the context of the request or operation that produced them. diff --git a/docs/platforms/javascript/guides/nextjs/logs/index.mdx b/docs/platforms/javascript/guides/nextjs/logs/index.mdx index 3fc934aa5c326f..76190fc3f5ec64 100644 --- a/docs/platforms/javascript/guides/nextjs/logs/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/logs/index.mdx @@ -131,13 +131,13 @@ Sentry.logger.info(Sentry.logger.fmt`User ${userId} purchased ${productName}`); -### Scope Attributes +### Shared Attributes -Set attributes on a scope to automatically include them in all logs within that context. +Use `Sentry.setAttribute` and `Sentry.setAttributes` to attach attributes that are automatically included in all logs (as well as your metrics and streamed spans). They work just like `Sentry.setTag` and `Sentry.setTags`, but accept `string`, `number`, and `boolean` values. The top-level APIs require SDK version `10.61.0` or above. To target a specific scope, use the scope APIs (version `10.32.0`+). -Scopes don't propagate between Next.js runtimes. To include attributes on logs from all three runtimes, call `getIsolationScope().setAttribute()` in each (client, edge, server). Use isolation scope (not global) to prevent data leaking between concurrent requests. For server-side code, set context before any try/catch blocks so errors include it. +Scopes don't propagate between Next.js runtimes. To include attributes on logs from all three runtimes, call `Sentry.setAttribute()` or `Sentry.setAttributes()` in each one (client, edge, server). Avoid `Sentry.getGlobalScope()` for request-specific data, since it's shared across concurrent requests. For server-side code, set context before any try/catch blocks so errors include it. @@ -147,19 +147,19 @@ See Diffe ```typescript -// setAttribute() or setAttributes() +// Applied to all logs, metrics, and spans +Sentry.setAttributes({ + org_id: user.orgId, + user_tier: user.tier, +}); +Sentry.setAttribute("service", "checkout"); + // Global scope - shared across entire app Sentry.getGlobalScope().setAttributes({ service: "checkout", version: "2.1.0", }); -// Isolation scope - unique per request -Sentry.getIsolationScope().setAttributes({ - org_id: user.orgId, - user_tier: user.tier, -}); - // Current scope - single operation Sentry.withScope((scope) => { scope.setAttribute("request_id", req.id); @@ -385,6 +385,9 @@ Sentry automatically adds these attributes to every log: } ``` +Any attributes set via `Sentry.setAttribute()` / `Sentry.setAttributes()` (or directly on a scope) are automatically included on all logs. The top-level APIs require SDK version `10.61.0` or above. See [Shared Attributes](#shared-attributes) above for details. + + ## Troubleshooting ### Logs not appearing diff --git a/platform-includes/metrics/default-attributes/javascript.mdx b/platform-includes/metrics/default-attributes/javascript.mdx index 2596b0220384e1..025b406ede7cfd 100644 --- a/platform-includes/metrics/default-attributes/javascript.mdx +++ b/platform-includes/metrics/default-attributes/javascript.mdx @@ -9,4 +9,4 @@ Sentry automatically attaches these attributes to every metric: | `user.id`, `user.name`, `user.email` | User identifiers | If user set | | `browser.name`, `browser.version` | Browser info | Client-side | | `sentry.replay_id` | Session replay ID | Client-side | -| `server.address` | Server hostname | Server-side | +| `server.address` | Server hostname | Server-side | \ No newline at end of file diff --git a/platform-includes/metrics/usage/javascript.mdx b/platform-includes/metrics/usage/javascript.mdx index b2831c6cd8ddf8..0f7c26720c6bfd 100644 --- a/platform-includes/metrics/usage/javascript.mdx +++ b/platform-includes/metrics/usage/javascript.mdx @@ -70,21 +70,23 @@ Sentry.metrics.count("api_calls", 1, { -#### Scope Attributes +#### Shared Attributes -With version `10.33.0`+, use scope APIs to set attributes that apply to all metrics while the scope is active. +Use `Sentry.setAttribute` and `Sentry.setAttributes` to attach attributes that apply to all metrics (as well as your logs and streamed spans). These work just like `Sentry.setTag` and `Sentry.setTags`, but accept `string`, `number`, and `boolean` values. The top-level APIs require version `10.61.0`+. -Supported types: `string`, `number`, `boolean` +To target a specific scope instead, use the scope APIs (version `10.33.0`+). ```javascript -Sentry.getGlobalScope().setAttributes({ +// Applied to all metrics, logs, and spans +Sentry.setAttributes({ is_admin: true, auth_provider: "google", }); +// Set on a specific scope instead Sentry.withScope((scope) => { scope.setAttribute("step", "authentication"); From 3ed7d335ca8c93a2f20a72b0a103b2a0d15d56cd Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 24 Jun 2026 19:21:37 +0200 Subject: [PATCH 2/2] Apply suggestion from @Lms24 --- docs/platforms/javascript/common/logs/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/logs/index.mdx b/docs/platforms/javascript/common/logs/index.mdx index b2215eb53e212a..ee1b207ccdeb75 100644 --- a/docs/platforms/javascript/common/logs/index.mdx +++ b/docs/platforms/javascript/common/logs/index.mdx @@ -103,7 +103,7 @@ Sentry.logger.info(Sentry.logger.fmt`User ${userId} purchased ${productName}`); ## Shared Attributes -Use `Sentry.setAttribute` and `Sentry.setAttributes` to attach attributes that are automatically included in all logs (as well as your metrics and streamed spans). These work just like `Sentry.setTag` and `Sentry.setTags`, but they accept `string`, `number`, and `boolean` values or arrays of these. `Sentry.setTag(s)` requires SDK version `10.61.0` or above. +Use `Sentry.setAttribute` and `Sentry.setAttributes` to attach attributes that are automatically included in all logs (as well as your metrics and streamed spans). These work just like `Sentry.setTag` and `Sentry.setTags`, but they accept `string`, `number`, and `boolean` values or arrays of these. `Sentry.setAttribute(s)` requires SDK version `10.61.0` or above. To attach attributes to a broader or narrower context, set them on a specific scope instead (requires SDK version `10.32.0` or above). Use the global scope for app-wide attributes and the current scope for a single operation.