Skip to content

Document global attributes #15279

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

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Document global attributes #15279

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
57 changes: 57 additions & 0 deletions develop-docs/sdk/telemetry/scopes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,63 @@ Data from all three scope types MUST be merged in a specific order before being

![Scope Inheritance](scope-inheritance.png)

## Scope Methods

### Setting Attributes

Users MUST be able to attach attributes to any scope using a dedicated method (e.g., `scope.setAttributes()` or `scope.setAttribute()`). These attributes follow the structure defined in the [Span Protocol](/sdk/telemetry/spans/span-protocol/#attribute-object-properties).

Attributes are key-value pairs where each value is an object containing:

- `type`: The data type (`"string"`, `"integer"`, `"double"`, or `"boolean"`)
Copy link
Member

Choose a reason for hiding this comment

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

I think we can be less strict here. If we allow for more types, we can cast complex types to string and still allow them to be set. I think this makes it an easier API for users to use, and feels very easy to transition from contexts.

- `value`: The actual attribute value, which MUST match the specified type
- `unit` (optional): The unit of measurement (e.g., `"ms"`, `"s"`, `"bytes"`, `"count"`, `"percent"`)

#### Example Usage

```javascript
Sentry.getGlobalScope().setAttributes({
"app.feature_flag.enabled": {
type: "boolean",
value: true
},
Comment on lines +71 to +74
Copy link
Member

Choose a reason for hiding this comment

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

IMO we should allow for an API that allows for the SDK to infer the type for the user. Otherwise this becomes more annoying for the dynamic language sdks.

The attributes API currently in logs doesn't allow for users to specify the type.

"app.session_duration": {
type: "integer",
value: 3600,
unit: "s"
}
});
```

```python
sentry_sdk.get_global_scope().set_attributes({
"app.feature_flag.enabled": {
"type": "boolean",
"value": True
},
"app.session_duration": {
"type": "integer",
"value": 3600,
"unit": "s"
}
})
```

#### Method Signature

The method SHOULD accept a dictionary/map/object where:
- Keys are attribute names (strings)
- Values are attribute objects with `type`, `value`, and optionally `unit` properties

#### Behavior

- Attributes set on the global scope MUST be applied to all logs
- Attributes set on the isolation scope MUST be applied to all logs in that execution context
- Attributes set on the current scope MUST be applied only to the current log
- When the same attribute key exists in multiple scopes, the more specific scope's value takes precedence (current > isolation > global)

See [Span Protocol - Common Attribute Keys](/sdk/telemetry/spans/span-protocol/#common-attribute-keys) for a list of standard attributes and [Sentry Conventions](https://github.com/getsentry/sentry-conventions/) for the complete attribute registry.

## Related Documents

This document provides a concise summary of the [Hub & Scope Refactoring](/sdk/miscellaneous/hub_and_scope_refactoring/), focusing on implementation details and expected features. The original document remains unchanged, offering additional historical context and migration strategies.
Loading