feat(client): propagate trace attributes onto all child spans on update

[hassiebp]

Important

Introduces propagate_attributes() to propagate trace-level attributes to child spans, deprecates older methods, and adds comprehensive tests, with a critical bug identified in baggage handling.

• Behavior:
  • Adds propagate_attributes() context manager in propagation.py to propagate trace-level attributes to child spans.
  • Deprecates update_current_trace() and update_trace() methods.
  • Implements LangfuseSpanProcessor.on_start() in span_processor.py to apply propagated attributes to new spans.
  • Identifies a bug in _get_span_key_from_baggage_key() in propagation.py affecting baggage handling.
• Tests:
  • Adds test_propagate_attributes.py with 50+ tests for propagation scenarios, including threading, async, and cross-tracer contexts.
  • Tests cover validation, nesting, and timing of attribute propagation.
• Misc:
  • Updates imports and constants in client.py and constants.py.
  • Adds opentelemetry-instrumentation-threading to pyproject.toml.

^{This description was created by for 854026a. You can customize this summary. It will automatically update as commits are pushed.}

---

Disclaimer: Experimental PR review

Greptile Overview

Updated On: 2025-10-21 15:07:10 UTC

Summary

Implements attribute propagation for trace-level attributes (user_id, session_id, metadata) to automatically propagate to all child spans within a context.

Key Changes:

• Adds new propagate_attributes() context manager that sets attributes on the current span AND propagates them to all child spans via OpenTelemetry context
• Implements LangfuseSpanProcessor.on_start() to read propagated attributes from context and apply them to new spans
• Deprecates update_current_trace() and update_trace() methods with comprehensive migration guidance
• Includes 50+ comprehensive tests covering propagation timing, validation, nesting, threading, and cross-tracer scenarios
• Optional baggage support for cross-service propagation (via as_baggage=True)

Motivation:
The old update_trace() methods only set attributes on a single span, causing gaps in Langfuse aggregation queries (e.g., filtering by user_id or calculating costs per session_id) because child spans didn't inherit the attributes.

Confidence Score: 3/5

• PR has one critical bug in baggage handling but core functionality works correctly
• The core propagation mechanism using OTel context is sound and well-tested with 50+ test cases. However, there's a critical logical bug in _get_span_key_from_baggage_key() (line 322) that uses substring matching instead of exact equality checks, which will cause incorrect attribute mapping when metadata keys contain "user_id" or "session_id". The bug only affects the optional baggage feature (when as_baggage=True) which isn't tested. The main propagation path (via OTel context) works correctly.
• langfuse/_client/propagation.py requires immediate fix to _get_span_key_from_baggage_key() function

Important Files Changed

File Analysis

Filename	Score	Overview
langfuse/_client/propagation.py	2/5	New file implementing attribute propagation - critical bug found in _get_span_key_from_baggage_key() at line 322 with substring matching logic
langfuse/_client/span_processor.py	4/5	Implements on_start() to propagate attributes to child spans - clean implementation, inherits baggage bug from propagation.py
tests/test_propagate_attributes.py	4/5	Comprehensive test suite with 50+ tests covering propagation scenarios - notably missing tests for as_baggage=True functionality

Sequence Diagram

sequenceDiagram
    participant User
    participant propagate_attributes
    participant OTel Context
    participant Span Processor
    participant Child Span
    
    User->>propagate_attributes: Call with user_id, session_id, metadata
    propagate_attributes->>propagate_attributes: Validate string values (≤200 chars)
    propagate_attributes->>OTel Context: Set context values (langfuse.propagated.*)
    propagate_attributes->>Current Span: Set attributes directly
    alt as_baggage=True
        propagate_attributes->>OTel Context: Set baggage (langfuse_user_id, etc)
    end
    propagate_attributes->>OTel Context: Attach context
    
    User->>Child Span: Create child span
    Child Span->>Span Processor: on_start(span, parent_context)
    Span Processor->>OTel Context: _get_propagated_attributes_from_context()
    OTel Context-->>Span Processor: Return propagated attributes
    Span Processor->>Child Span: span.set_attributes(propagated_attributes)
    Child Span-->>User: Span with inherited attributes
    
    User->>propagate_attributes: Exit context
    propagate_attributes->>OTel Context: Detach context

Loading

[greptile-apps]

_{10 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}