Skip to content

Commit c8f9a87

Browse files
committed
Document global attributes
1 parent 809467e commit c8f9a87

File tree

1 file changed

+57
-0
lines changed

1 file changed

+57
-0
lines changed

develop-docs/sdk/telemetry/scopes.mdx

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,63 @@ 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"`, or `"boolean"`)
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": {
72+
type: "boolean",
73+
value: true
74+
},
75+
"app.session_duration": {
76+
type: "integer",
77+
value: 3600,
78+
unit: "s"
79+
}
80+
});
81+
```
82+
83+
```python
84+
sentry_sdk.get_global_scope().set_attributes({
85+
"app.feature_flag.enabled": {
86+
"type": "boolean",
87+
"value": True
88+
},
89+
"app.session_duration": {
90+
"type": "integer",
91+
"value": 3600,
92+
"unit": "s"
93+
}
94+
})
95+
```
96+
97+
#### Method Signature
98+
99+
The method SHOULD accept a dictionary/map/object where:
100+
- Keys are attribute names (strings)
101+
- Values are attribute objects with `type`, `value`, and optionally `unit` properties
102+
103+
#### Behavior
104+
105+
- Attributes set on the global scope MUST be applied to all logs
106+
- Attributes set on the isolation scope MUST be applied to all logs in that execution context
107+
- Attributes set on the current scope MUST be applied only to the current log
108+
- When the same attribute key exists in multiple scopes, the more specific scope's value takes precedence (current > isolation > global)
109+
110+
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.
111+
55112
## Related Documents
56113

57114
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)