Skip to content

Commit f1e06ae

Browse files
authored
Document global attributes (#15279)
1 parent 08640da commit f1e06ae

File tree

1 file changed

+51
-0
lines changed

1 file changed

+51
-0
lines changed

develop-docs/sdk/telemetry/scopes.mdx

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,57 @@ Data from all three scope types MUST be merged in a specific order before being
5252

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

55+
## Scope Methods
56+
57+
### Setting Attributes
58+
59+
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).
60+
61+
Attributes are key-value pairs where each value is an object containing:
62+
63+
- `type`: The data type (`"string"`, `"integer"`, `"double"`, `"boolean"`, `"string[]"`, `"integer[]"` and `"double[]"`)
64+
- `value`: The actual attribute value, which MUST match the specified type
65+
- `unit` (optional): The unit of measurement (e.g., `"ms"`, `"s"`, `"bytes"`, `"count"`, `"percent"`)
66+
67+
#### Example Usage
68+
69+
```javascript
70+
Sentry.getGlobalScope().setAttributes({
71+
"app.feature_flag.enabled": true,
72+
"app.session_duration": {
73+
type: "integer",
74+
value: 3600,
75+
unit: "s"
76+
}
77+
});
78+
```
79+
80+
```python
81+
sentry_sdk.get_global_scope().set_attributes({
82+
"app.feature_flag.enabled": True,
83+
"app.session_duration": {
84+
"type": "integer",
85+
"value": 3600,
86+
"unit": "s"
87+
}
88+
})
89+
```
90+
91+
#### Method Signature
92+
93+
The method SHOULD accept a dictionary/map/object where:
94+
- Keys are attribute names (strings)
95+
- Values are attribute objects with `type`, `value`, and optionally `unit` properties
96+
97+
#### Behavior
98+
99+
- Attributes set on the global scope MUST be applied to all logs
100+
- Attributes set on the isolation scope MUST be applied to all logs in that execution context
101+
- Attributes set on the current scope MUST be applied only to the current log
102+
- When the same attribute key exists in multiple scopes, the more specific scope's value takes precedence (current > isolation > global)
103+
104+
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.
105+
55106
## Related Documents
56107

57108
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.

0 commit comments

Comments
 (0)