Struct TraceGrouping 

#[non_exhaustive]
pub struct TraceGrouping {
    pub session_id: Option<String>,
    pub end_user_hash: Option<String>,
    pub tags: Vec<String>,
    pub environment: Option<String>,
    pub release: Option<String>,
}

Vendor-neutral grouping of spans: which session, which end user, which tags, which environment, which release.

LLM observability backends filter at the level of the individual span, not only at the trace root, so the grouping has to reach every span rather than sit on the first one. Two ways to make that happen:

• Without the otel feature, TraceGrouping::stamp fills the grouping fields — which every span this crate opens declares empty — on whichever span you hand it, and TraceGrouping::scope_span opens a parent span that carries them for a subscriber that flattens ancestors.
• With the otel feature, crate::otel::attach_grouping puts the same values in OpenTelemetry baggage on the current context, where a baggage-copying span processor in the application’s SDK setup stamps them onto every span that starts underneath. The processor itself lives in the adopter’s code because it needs opentelemetry_sdk, which this crate does not depend on; crate::otel::grouping_from_baggage gives it the key/values to copy.

The end-user reference is always a digest — build it with TraceGrouping::with_account, which hashes the account id, or supply your own digest with TraceGrouping::with_end_user_hash. There is no constructor that takes a raw account or user identifier.

A backend that insists on its own attribute names is a renaming function over TraceGrouping::fields in the adopter’s code, not something this crate hardcodes.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

session_id: Option<String>

The session, recorded as session.id. Turnframe uses the conversation.

end_user_hash: Option<String>

Digest of the end user, recorded as user.id. Never a raw identifier.

tags: Vec<String>

Free-form grouping labels the application chose.

environment: Option<String>

Deployment environment, e.g. production.

release: Option<String>

Release or build of the running service.

Implementations

impl TraceGrouping

pub fn for_conversation(conversation_id: ConversationId) -> Self

Groups spans by conversation, which is the session a backend shows.

pub fn with_account(self, account_id: &AccountId) -> Self

Adds the end user as the digest of an account id. The raw id is hashed by account_hash and never stored on the grouping.

pub fn with_end_user_hash(self, hash: impl Into<String>) -> Self

Adds an end-user reference the caller has already hashed.

pub fn with_tag(self, tag: impl Into<String>) -> Self

Adds a grouping label.

pub fn with_environment(self, environment: impl Into<String>) -> Self

Sets the deployment environment.

pub fn with_release(self, release: impl Into<String>) -> Self

Sets the release or build.

pub fn fields(&self) -> Vec<(&'static str, String)>

The grouping as (attribute key, value) pairs in a stable order, omitting what is unset. Testable without a subscriber, and the set an adopter renames for a backend with its own spelling.

pub fn stamp(&self, span: &Span)

Records the grouping on span.

Every span this crate opens declares the grouping fields empty, so this fills them in. Recording on a span that did not declare them is a no-op rather than an error.

pub fn stamp_current(&self)

Records the grouping on the span that is currently entered.

pub fn scope_span(&self) -> Span

Opens a span that carries the grouping and becomes the parent of every span opened while it is entered.

use turnframe_core::ids::{AccountId, ConversationId};
use turnframe_telemetry::tracing::TraceGrouping;

let grouping = TraceGrouping::for_conversation(ConversationId::nil())
    .with_account(&AccountId::from("acct-1"))
    .with_environment("production")
    .with_release("v0.1.0")
    .with_tag("trip");

let span = grouping.scope_span();
let _entered = span.enter();

Trait Implementations

impl Clone for TraceGrouping

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TraceGrouping

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TraceGrouping

fn default() -> Self

Returns the “default value” for a type.

impl Eq for TraceGrouping

impl PartialEq for TraceGrouping

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for TraceGrouping