From a961230d5ca168aaa3bd8026b7cd61e3f9ab343a Mon Sep 17 00:00:00 2001 From: Vjeran Grozdanic Date: Wed, 8 Apr 2026 16:44:59 +0200 Subject: [PATCH 1/2] docs(sdk): Add span groups develop docs Document the sentry.span_group attribute namespace for logical grouping of spans across trace boundaries. Covers protocol, naming convention, baggage propagation, and SDK implementation. Co-Authored-By: Claude --- .../sdk/telemetry/spans/span-groups.mdx | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 develop-docs/sdk/telemetry/spans/span-groups.mdx diff --git a/develop-docs/sdk/telemetry/spans/span-groups.mdx b/develop-docs/sdk/telemetry/spans/span-groups.mdx new file mode 100644 index 0000000000000..fb0270d241b64 --- /dev/null +++ b/develop-docs/sdk/telemetry/spans/span-groups.mdx @@ -0,0 +1,98 @@ +--- +title: Span Groups +--- + + + 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. + + +Span groups provide logical grouping of spans that can cross trace boundaries. While traces represent a single causal chain of operations, span groups connect spans that share a logical relationship — such as belonging to the same AI conversation or user session — even when those spans live in different traces. + +## Motivation + +Traces are the only built-in grouping mechanism in OpenTelemetry, but many real-world concepts don't map cleanly to a single trace: + +- **AI conversations** can span multiple sessions and traces, and multiple conversations can exist within the same trace. +- **User sessions** (e.g. a single visit to a webpage) may produce multiple traces, or a single trace may cover multiple sessions. + +These relationships require a lightweight, extensible grouping concept that works across trace boundaries without infrastructure changes. + +## Protocol + +Span groups are regular span attributes under the `sentry.span_group` namespace. Each group is identified by a key (the concept) and a value (the group ID): + +```json +{ + "sentry.span_group.conversation_id": "conv_88234", + "sentry.span_group.session_id": "sess_00192" +} +``` + +A span **MAY** belong to multiple groups simultaneously. + +### Attribute Format + +In the Span v2 wire format, span group attributes follow the standard [attribute encoding](/sdk/foundations/state-management/scopes/attributes/): + +```json +{ + "attributes": { + "sentry.span_group.conversation_id": { + "type": "string", + "value": "conv_88234" + }, + "sentry.span_group.session_id": { + "type": "string", + "value": "sess_00192" + } + } +} +``` + +### Naming Convention + +New span group concepts **MUST** use a `_id` suffix under the `sentry.span_group` namespace. For example: + +| Concept | Attribute Key | +|---|---| +| Conversation | `sentry.span_group.conversation_id` | +| Session | `sentry.span_group.session_id` | + +Values **MUST** be non-empty strings. + +## Propagation + +Span groups **SHOULD** be propagated between services via the `baggage` header, following the same mechanism as [trace propagation](/sdk/telemetry/spans/span-trace-propagation/): + +``` +baggage: sentry.span_group.conversation_id=conv_88234,sentry.span_group.session_id=sess_00192 +``` + +When a downstream service receives span group entries in baggage, it **SHOULD** apply them to all spans created within that context. + +## SDK Implementation + +SDKs **MUST** allow users to set span group attributes via the standard span attributes API. No dedicated public API is required — span groups are just attributes. + +```js {tabTitle:JavaScript} +Sentry.startSpan( + { + name: "ai.chat", + attributes: { + "sentry.span_group.conversation_id": "conv_88234", + "sentry.span_group.session_id": "sess_00192", + }, + }, + () => { + // ... + } +); +``` + +```python {tabTitle:Python} +with sentry_sdk.start_span(name="ai.chat") as span: + span.set_attribute("sentry.span_group.conversation_id", "conv_88234") + span.set_attribute("sentry.span_group.session_id", "sess_00192") +``` From 31744a373d050a71e0681ec905afe8698aff4e00 Mon Sep 17 00:00:00 2001 From: Vjeran Grozdanic Date: Thu, 9 Apr 2026 10:39:55 +0200 Subject: [PATCH 2/2] docs(sdk): Clarify conversation_id and session_id semantics Conversation ID comes from the model provider and must be stringified. Session ID is early-phase and shown only as an example, not a definition. Co-Authored-By: Claude --- develop-docs/sdk/telemetry/spans/span-groups.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/telemetry/spans/span-groups.mdx b/develop-docs/sdk/telemetry/spans/span-groups.mdx index fb0270d241b64..7ce8be1151cbe 100644 --- a/develop-docs/sdk/telemetry/spans/span-groups.mdx +++ b/develop-docs/sdk/telemetry/spans/span-groups.mdx @@ -55,10 +55,10 @@ In the Span v2 wire format, span group attributes follow the standard [attribute New span group concepts **MUST** use a `_id` suffix under the `sentry.span_group` namespace. For example: -| Concept | Attribute Key | -|---|---| -| Conversation | `sentry.span_group.conversation_id` | -| Session | `sentry.span_group.session_id` | +| Concept | Attribute Key | Notes | +|---|---|---| +| Conversation | `sentry.span_group.conversation_id` | The conversation ID originates from the model provider and can be any type. It **MUST** be stringified before being set as an attribute. | +| Session | `sentry.span_group.session_id` | Session grouping is still in an early phase. It is listed here as an example of how the namespace extends, not as a formal definition of what a session is. | Values **MUST** be non-empty strings.