diff --git a/develop-docs/sdk/telemetry/scopes.mdx b/develop-docs/sdk/telemetry/scopes.mdx index a236394393ba3..d0186f7f7a85d 100644 --- a/develop-docs/sdk/telemetry/scopes.mdx +++ b/develop-docs/sdk/telemetry/scopes.mdx @@ -58,11 +58,11 @@ Data from all three scope types MUST be merged in a specific order before being 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: +Attributes are key-value pairs where each value is either a an attribute value or an object containing: -- `type`: The data type (`"string"`, `"integer"`, `"double"`, `"boolean"`, `"string[]"`, `"integer[]"` and `"double[]"`) - `value`: The actual attribute value, which MUST match the specified type -- `unit` (optional): The unit of measurement (e.g., `"ms"`, `"s"`, `"bytes"`, `"count"`, `"percent"`) +- `unit` (optional): The unit of measurement (e.g., `"ms"`, `"s"`, `"bytes"`, `"count"`, `"percent"` or any other string value). SDKs MAY NOT add support for units for the moment, but MUST be able to do so at a later date without a breaking change. +- `type` (optional): The type of the attribute. SDKs SHOULD NOT expose this to users if they can reliably infer the type from the value. If not, SDKs MAY allow or require users to set the `type` explicitly. #### Example Usage @@ -70,7 +70,6 @@ Attributes are key-value pairs where each value is an object containing: Sentry.getGlobalScope().setAttributes({ "app.feature_flag.enabled": true, "app.session_duration": { - type: "integer", value: 3600, unit: "s" } @@ -81,7 +80,6 @@ Sentry.getGlobalScope().setAttributes({ sentry_sdk.get_global_scope().set_attributes({ "app.feature_flag.enabled": True, "app.session_duration": { - "type": "integer", "value": 3600, "unit": "s" } @@ -92,7 +90,8 @@ sentry_sdk.get_global_scope().set_attributes({ 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 +- Values are either directly values or attribute objects/dictionaries with `value`, and optionally `unit` properties (see [example](#example-usage)). +- The SDK SHOULD infer the `type` of the attribute at serialization time to spare users from setting a (potentially incorrect) `type`. Depending on platform or constraints, the SDK MAY instead also allow or require users to set the `type` explicitly. #### Behavior @@ -101,6 +100,7 @@ The method SHOULD accept a dictionary/map/object where: - Attributes set on the current scope MUST be applied only to the current log and current metric - When the same attribute key exists in multiple scopes, the more specific scope's value takes precedence (current > isolation > global) - When the same attribute key exists on the current log or metric, it MUST take precedence over an attribute with the same key set on any scope (log/metric > current > isolation > global) +- The SDK SHOULD keep the attribute format consistent with the user-set format until user-provided processing callbacks like `before_send_log` have been called. This ensures compatibility with already existing callbacks and avoids unexpected changes to the attribute format. 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.