---
title: "Attributes"
description: "Typed key-value pairs that live on scopes and are applied to telemetry at capture time — structure, types, units, and precedence."
url: https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes/
---

# Attributes

This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in

<!-- -->

[RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.

Statusstable

Version`1.6.0`[(changelog)](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#changelog)

## [Overview](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#overview)

Attributes are typed key-value pairs that live on [scopes](https://develop.sentry.dev/sdk/foundations/state-management/scopes.md). When telemetry (spans, logs, metrics) is captured, the SDK merges attributes from the scope chain and applies them to the outgoing event. This spec defines the attribute data model (wire format), the SDK API for setting and removing attributes, and the precedence rules when merging across scopes.

Related specs:

* [Scopes](https://develop.sentry.dev/sdk/foundations/state-management/scopes.md) — scope propagation and forking
* [Sentry Conventions](https://github.com/getsentry/sentry-conventions/) — the full attribute registry

***

## [Wire Format](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#wire-format)

### [Attribute Object Structure](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#attribute-object-structure)

Stablespecified since

<!-- -->

1.0.0

Attributes are stored as key-value pairs where each value is an object with type information.

```json
{
  "my_attribute": {
    "value": "some value",
    "type": "string"
  },
  "response_time": {
    "value": 123,
    "unit": "millisecond",
    "type": "integer"
  },
  "my_list": {
    "value": [1, 2, 3],
    "type": "array"
  }
}
```

| Property | Type   | Required | Description                                                                                                                   |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `type`   | string | Yes      | The data type of the attribute value.                                                                                         |
| `value`  | any    | Yes      | The actual attribute value, **MUST** match the specified type.                                                                |
| `unit`   | string | No       | The unit of measurement. See [Units](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#units). |

### [Primitive Types](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#primitive-types)

Stablespecified since

<!-- -->

1.0.0

The following primitive types are supported:

* `string`
* `boolean`
* `integer` (64-bit signed integer)
* `double` (64-bit floating point number)

**Note on Integers:** Integers should be 64-bit signed integers. For 64-bit unsigned integers, use the `string` type to avoid overflow issues until unsigned integers are natively supported.

### [Complex Types](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#complex-types)

Stablespecified since

<!-- -->

1.6.0

Sentry currently only supports ingesting **homogeneous arrays** of **primitive** types as attribute values, using the `array` type.

Objects and mixed/nested arrays are not supported and will be dropped, but will eventually be supported.

At this time attributes with the 'array' type are not yet visible in the Sentry UI.

### [Units](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#units)

Stablespecified since

<!-- -->

1.0.0

Units are currently not supported and not visible in the product.

#### [Duration Units](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#duration-units)

* `nanosecond`
* `microsecond`
* `millisecond`
* `second`
* `minute`
* `hour`
* `day`
* `week`

#### [Information Units](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#information-units)

* `bit`
* `byte`
* `kilobyte`
* `kibibyte`
* `megabyte`
* `mebibyte`
* `gigabyte`
* `gibibyte`
* `terabyte`
* `tebibyte`
* `petabyte`
* `pebibyte`
* `exabyte`
* `exbibyte`

#### [Fraction Units](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#fraction-units)

* `ratio`
* `percent`

***

## [Behavior](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#behavior)

### [Setting Attributes](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#setting-attributes)

Stablespecified since

<!-- -->

1.2.0

Users **MUST** be able to attach attributes to any [scope](https://develop.sentry.dev/sdk/foundations/state-management/scopes.md) using a dedicated method (e.g., `scope.setAttributes()` or `scope.setAttribute()`).

From the user's perspective, attribute values are either primitives or objects containing:

* `value`: The attribute value, **MUST** match the specified type
* `unit` *(optional)*: Unit of measurement (see [Units](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#units)). SDKs **MAY** delay adding support for units, but **MUST** be able to do so at a later date without a breaking change.
* `type` *(optional)*: Attribute type. SDKs **SHOULD NOT** expose this to users if type can be reliably inferred from the value. (since 1.4.0)

#### [Method Signature](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#method-signature)

The method **SHOULD** accept a dictionary/map/object where:

* Keys are attribute names (strings)
* Values are either directly values or attribute objects/dictionaries with `value`, and optionally `unit` properties
* 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. (since 1.4.0)

### [Removing Attributes](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#removing-attributes)

Stablespecified since

<!-- -->

1.3.0

Users **MUST** be able to remove attributes from any scope using a dedicated method, e.g., `scope.removeAttribute()`.

Calling `scope.clear()` **MUST** remove all attributes from the corresponding scope.

### [Scope Precedence](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#scope-precedence)

Stablespecified since

<!-- -->

1.3.0

When the same attribute key exists in multiple scopes, the more specific scope's value takes precedence:

```bash
telemetry item > current scope > isolation scope > global scope
```

* Attributes set on the **global scope** **MUST** be applied to all logs and metrics.
* Attributes set on the **isolation scope** **MUST** be applied to all logs and metrics in that execution context.
* Attributes set on the **current scope** **MUST** be applied only while that scope is active.
* When the same attribute key exists on the telemetry item itself (log, metric), it **MUST** take precedence over scope attributes.

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 existing callbacks and avoids unexpected changes to the attribute format. (since 1.5.0)

***

## [Public API](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#public-api)

### [Setting Attributes on Scopes](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#setting-attributes-on-scopes)

| Function                           | Target Scope    | Description                                          |
| ---------------------------------- | --------------- | ---------------------------------------------------- |
| `Sentry.setAttributes(attributes)` | Isolation scope | Top-level convenience for setting attributes.        |
| `scope.setAttributes(attributes)`  | Any scope       | Set attributes on a specific scope instance.         |
| `scope.setAttribute(key, value)`   | Any scope       | Set a single attribute on a specific scope instance. |

### [Removing Attributes](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#removing-attributes-1)

| Function                     | Description                                            |
| ---------------------------- | ------------------------------------------------------ |
| `scope.removeAttribute(key)` | Remove a single attribute from the scope.              |
| `scope.clear()`              | Remove all attributes (and other data) from the scope. |

***

## [Examples](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#examples)

### [JavaScript](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#javascript)

```javascript
// Set attributes on the global scope — applied to everything
Sentry.getGlobalScope().setAttributes({
  "app.feature_flag.enabled": true,
  "app.session_duration": {
    value: 3600,
    unit: "second",
  },
});

// Set attributes on the isolation scope via top-level API
Sentry.setAttributes({
  "request.id": "abc-123",
});

// Remove an attribute
Sentry.getGlobalScope().removeAttribute("app.feature_flag.enabled");
```

### [Python](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#python)

```python
import sentry_sdk

# Set attributes on the global scope — applied to everything
sentry_sdk.get_global_scope().set_attributes({
    "app.feature_flag.enabled": True,
    "app.session_duration": {
        "value": 3600,
        "unit": "second"
    }
})

# Set attributes on the isolation scope via top-level API
sentry_sdk.set_attributes({
    "request.id": "abc-123",
})

# Remove an attribute
sentry_sdk.get_global_scope().remove_attribute('app.feature_flag.enabled')
```

***

## [Semantic Conventions](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#semantic-conventions)

See [Sentry Conventions](https://github.com/getsentry/sentry-conventions/) for the full list of supported attribute keys.

***

## [Changelog](https://develop.sentry.dev/sdk/foundations/state-management/scopes/attributes.md#changelog)

| Version | Date       | Summary                                                                                    |
| ------- | ---------- | ------------------------------------------------------------------------------------------ |
| `1.6.0` | 2026-02-03 | Clarified array and unit support                                                           |
| `1.5.0` | 2025-12-19 | Clarified current scope attribute application wording                                      |
| `1.4.0` | 2025-11-18 | Removed explicit type from user-facing API, SDKs SHOULD infer type at serialization        |
| `1.3.0` | 2025-11-11 | Added scope attribute precedence rules, removeAttribute method, telemetry-level precedence |
| `1.2.0` | 2025-11-03 | Added scope attribute behavior (setAttributes, setAttribute, per-scope application rules)  |
| `1.1.0` | 2025-11-25 | Extracted from Scopes spec into dedicated Attributes spec                                  |
| `1.0.0` | 2025-10-17 | Initial spec — attribute object structure, primitive and complex types, units              |