Skip to content

feat(js): Add documentation for Sentry.setAttribute(s) APIs #18539

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Lms24 merged 4 commits into from
Jun 29, 2026
+90 −25
Merged

feat(js): Add documentation for Sentry.setAttribute(s) APIs #18539

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b53075b
feat(js): Add documentation for `Sentry.setAttribute(s)` APIs
Lms24 Jun 24, 2026
3ed7d33
Apply suggestion from @Lms24
Lms24 Jun 24, 2026
373937a
remove mentioning streamed spans for now
Lms24 Jun 29, 2026
8451347
rm "spans"
Lms24 Jun 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 55 additions & 1 deletion docs/platforms/javascript/common/configuration/apis.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -302,7 +302,7 @@ Messages show up as issues on your issue stream, with the message as the issue n

</SdkApi>

## Enriching Events
## Enriching Telemetry

<SdkApi
name="setTag"
Expand All @@ -324,6 +324,60 @@ Set a tag to be sent with Sentry events.
Set multiple tags to be sent with Sentry events.
</SdkApi>

<SdkApi
name="setAttribute"
signature="function setAttribute(key: string, value: string | number | boolean | Array<string> | Array<number> | Array<boolean>): void"
availableSince="10.61.0"
parameters={[
{
name: "key",
type: "string",
required: true,
description: "The name of the attribute.",
},
{
name: "value",
type: "string | number | boolean | Array<string> | Array<number> | Array<boolean>",
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 and metrics (rather than errors).

```javascript
Sentry.setAttribute("is_admin", true);
Sentry.setAttribute("render_duration", 150);
```

</SdkApi>

<SdkApi
name="setAttributes"
signature="function setAttributes(attributes: Record<string, string | number | boolean | Array<string> | Array<number> | Array<boolean>>): void"
availableSince="10.61.0"
parameters={[
{
name: "attributes",
type: "Record<string, string | number | boolean | Array<string> | Array<number> | Array<boolean>>",
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,
});
```

</SdkApi>

<SdkApi
name="setContext"
signature="function setContext(name: string, context: Record<string, unknown>): void"
Expand Down
24 changes: 15 additions & 9 deletions docs/platforms/javascript/common/logs/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,28 +101,29 @@ Sentry.logger.info(Sentry.logger.fmt`User ${userId} purchased ${productName}`);
<SplitSection>
<SplitSectionText>

## 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). These work just like <PlatformLink to="/apis/#setTag">`Sentry.setTag` and `Sentry.setTags`</PlatformLink>, but they accept `string`, `number`, and `boolean` values or arrays of these. `Sentry.setAttribute(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.

</SplitSectionText>
<SplitSectionCode>

```javascript
// Applied to all logs and metrics
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);
Expand Down Expand Up @@ -217,6 +218,11 @@ Everything in Sentry is linked by trace. When you're viewing a log, you can jump

<PlatformContent includePath="logs/default-attributes" />

### 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

- <PlatformLink to="/tracing/">Tracing</PlatformLink> — Logs are automatically linked to traces, so you can see logs in the context of the request or operation that produced them.
Expand Down
23 changes: 13 additions & 10 deletions docs/platforms/javascript/guides/nextjs/logs/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,13 +131,13 @@ Sentry.logger.info(Sentry.logger.fmt`User ${userId} purchased ${productName}`);
<SplitSection>
<SplitSectionText>

### 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). They work just like <PlatformLink to="/apis/#setTag">`Sentry.setTag` and `Sentry.setTags`</PlatformLink>, 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`+).

<Alert>

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.

</Alert>

Expand All @@ -147,19 +147,19 @@ See <PlatformLink to="/enriching-events/scopes/#different-kinds-of-scopes">Diffe
<SplitSectionCode>

```typescript
// setAttribute() or setAttributes()
// Applied to all logs and metrics
Sentry.setAttributes({
org_id: user.orgId,
user_tier: user.tier,
});
Sentry.setAttribute("service", "checkout");
Comment on lines +150 to +155

@sentry sentry Bot Jun 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The comment // Applied to all logs and metrics for Sentry.setAttributes() is misleading. It applies to the isolation scope (per-runtime in Next.js), not globally across all runtimes.
Severity: MEDIUM

Suggested Fix

Update the comment to clarify the scope. For example, change it to // Applied to all logs and metrics in this execution context (runtime) to make it clear that the attributes are not global across the entire application.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: docs/platforms/javascript/guides/nextjs/logs/index.mdx#L150-L155

Potential issue: The code comment `// Applied to all logs and metrics` accompanying
`Sentry.setAttributes()` is misleading within the Next.js guide. While technically
correct that attributes are applied to all events within an isolation scope, it fails to
clarify that in Next.js, each runtime (client, edge, server) has its own separate
isolation scope. This could lead developers to incorrectly assume that setting
attributes in one place applies them globally across the entire application, resulting
in missing attributes on logs and metrics from other runtimes.

Also affects:

  • docs/platforms/javascript/common/logs/index.mdx:114~119


// 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);
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion platform-includes/metrics/default-attributes/javascript.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
10 changes: 6 additions & 4 deletions platform-includes/metrics/usage/javascript.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,21 +70,23 @@ Sentry.metrics.count("api_calls", 1, {
<SplitSection>
<SplitSectionText>

#### 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). These work just like <PlatformLink to="/apis/#setTag">`Sentry.setTag` and `Sentry.setTags`</PlatformLink>, 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`+).

</SplitSectionText>
<SplitSectionCode>

```javascript
Sentry.getGlobalScope().setAttributes({
// Applied to all metrics and logs
Sentry.setAttributes({
is_admin: true,
auth_provider: "google",
});

// Set on a specific scope instead
Sentry.withScope((scope) => {
scope.setAttribute("step", "authentication");

Expand Down
Loading