feat(client): allow propagating trace name

[hassiebp]

Important

Add support for propagating trace_name in propagate_attributes() with validation and comprehensive tests.

• Behavior:
  • Add trace_name to propagate_attributes() in propagation.py to propagate trace names to all child spans.
  • trace_name must be a US-ASCII string, ≤200 characters. Non-string or overly long values are dropped with a warning.
  • Supports propagation through OpenTelemetry baggage when as_baggage=True.
• Tests:
  • Add TestPropagateAttributesTraceName in test_propagate_attributes.py to verify trace_name propagation to child and grandchild spans.
  • Test trace_name with other attributes like user_id, session_id, version, and metadata.
  • Validate behavior for nested contexts, baggage propagation, and invalid trace_name values.

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

Disclaimer: Experimental PR review

Greptile Summary

Added trace_name parameter to the propagate_attributes() context manager, enabling users to set a consistent trace name for all spans created within a context.

Key Changes:

• Added trace_name to PropagatedKeys literal type and propagated_keys list
• Added trace_name parameter to propagate_attributes() and _propagate_attributes() functions with proper documentation
• Mapped trace_name to LangfuseOtelSpanAttributes.TRACE_NAME in _get_propagated_span_key()
• Validation automatically enforces: string type, ≤200 characters (matches existing attribute validation)
• Comprehensive test suite (11 tests) covering: propagation to children/grandchildren, combination with other attributes (user_id, session_id, version, metadata), validation edge cases, nested contexts, baggage propagation

Implementation Quality:

• Follows established patterns exactly (mirroring user_id, session_id, version, tags)
• All imports properly placed at module top
• No code duplication or unnecessary complexity
• Maintains backward compatibility (new optional parameter)

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Score reflects high-quality implementation following established patterns exactly, comprehensive test coverage (11 tests covering all edge cases), proper validation and documentation, no breaking changes, and adherence to all coding standards
• No files require special attention

Important Files Changed

Filename	Overview
langfuse/_client/propagation.py	Added trace_name parameter to propagation system following existing patterns for user_id, session_id, version, and tags. Includes validation, documentation, and proper integration with OpenTelemetry context.
tests/test_propagate_attributes.py	Comprehensive test suite for trace_name propagation covering all edge cases: child/grandchild propagation, combination with other attributes, validation (200 char limit, non-string), nested contexts, and baggage propagation.

Sequence Diagram

sequenceDiagram
    participant User
    participant PropagateAttrs as propagate_attributes
    participant Context as OpenTelemetry Context
    participant Validation as _validate_propagated_value
    participant CurrentSpan as Current Span
    participant ChildSpan as Child Spans

    User->>PropagateAttrs: propagate_attributes(trace_name="my-trace")
    PropagateAttrs->>Context: get_current()
    PropagateAttrs->>CurrentSpan: get_current_span()
    
    PropagateAttrs->>Validation: validate trace_name
    alt valid (≤200 chars, string)
        Validation-->>PropagateAttrs: validated value
        PropagateAttrs->>Context: set_value("langfuse.propagated.trace_name")
        PropagateAttrs->>CurrentSpan: set_attribute("langfuse.trace.name")
        PropagateAttrs->>Context: attach(context)
        
        loop for each child span
            User->>ChildSpan: start_span()
            ChildSpan->>Context: get_propagated_attributes()
            Context-->>ChildSpan: trace_name="my-trace"
            ChildSpan->>ChildSpan: set_attribute("langfuse.trace.name")
        end
        
        PropagateAttrs->>Context: detach(token)
    else invalid (>200 chars or non-string)
        Validation-->>PropagateAttrs: None (dropped with warning)
    end

Loading