diff --git a/develop-docs/sdk/telemetry/scopes.mdx b/develop-docs/sdk/telemetry/scopes.mdx index affe84819137c..ab60069d6e083 100644 --- a/develop-docs/sdk/telemetry/scopes.mdx +++ b/develop-docs/sdk/telemetry/scopes.mdx @@ -51,6 +51,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"`) +- `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 + }, + "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.