feat!: prepare v5 release

[hassiebp]

Important

This PR introduces breaking changes for v5, refactoring trace-level attribute handling in the Langfuse SDK to improve OpenTelemetry context propagation.

• Breaking API Changes:
  • Removed updateTrace() from observation objects, replaced with propagateAttributes().
  • Renamed updateActiveTrace() to setActiveTraceIO() and deprecated it.
  • Added publishActiveTrace() to make traces public.
  • Changed startObservation to startActiveObservation in CallbackHandler.ts with endOnExit: false.
• New API Pattern:
  • Trace attributes must be set via propagateAttributes() before creating observations.
  • Uses OpenTelemetry context propagation for attribute inheritance.
• Backward Compatibility:
  • Deprecated setTraceIO() and setActiveTraceIO() for legacy evaluators.
  • Created LangfuseTraceIOAttributes type for input/output only.
• Testing:
  • Updated tests to demonstrate migration from v4 to v5 API.
  • Both e2e and integration tests validate new patterns.

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

---

Disclaimer: Experimental PR review

Greptile Overview

Greptile Summary

This PR introduces breaking changes for v5 by refactoring how trace-level attributes are set in the Langfuse SDK.

Key Changes:

• Breaking API Changes:

  • Removed updateTrace() method from observation objects - replaced with propagateAttributes() function that must be called before creating observations
  • Renamed updateActiveTrace() to setActiveTraceIO() and deprecated it (now only handles input/output for legacy platform features)
  • Added new publishActiveTrace() function to make traces public (replaces updateTrace({public: true}))
  • Changed startObservation to startActiveObservation in CallbackHandler.ts with endOnExit: false option

• New API Pattern:

  • Trace attributes (userId, sessionId, tags, metadata, version) must now be set via propagateAttributes() before creating observations
  • Uses OpenTelemetry context propagation to inherit attributes, ensuring all child spans receive trace-level metadata
  • This architectural change ensures proper attribute propagation in distributed tracing scenarios

• Backward Compatibility:

  • Added deprecated setTraceIO() and setActiveTraceIO() methods for legacy LLM-as-a-judge evaluators that rely on trace-level I/O
  • Created new LangfuseTraceIOAttributes type (restricted to input/output only)
  • Updated all integration points (LangChain, OpenAI) to use new patterns

• Testing:

  • Comprehensive test updates demonstrate migration path from v4 to v5 API
  • Both e2e and integration tests updated to validate new patterns

Confidence Score: 4/5

• Breaking changes are well-documented and tests are comprehensive, but requires careful migration planning for existing users
• The implementation is solid with proper deprecation warnings and extensive test coverage. The breaking changes are necessary for architectural improvements (proper OTel context propagation). Score is 4 instead of 5 due to the scope of breaking changes that will require significant migration effort from users.
• Check that CallbackHandler.ts properly handles the callback return value from propagateAttributes, and verify endOnExit: false behavior is correctly documented

Important Files Changed

Filename	Overview
packages/tracing/src/index.ts	Breaking change: replaced updateActiveTrace with setActiveTraceIO (deprecated) and publishActiveTrace; exports propagateAttributes from core
packages/tracing/src/spanWrapper.ts	Breaking change: replaced updateTrace method with setTraceIO (deprecated) and publishTrace methods
packages/langchain/src/CallbackHandler.ts	Refactored to use propagateAttributes and startActiveObservation instead of updateTrace; changed from startObservation to startActiveObservation with endOnExit: false
packages/openai/src/traceMethod.ts	Wrapped method execution in propagateAttributes to set trace-level attributes before creating observations

Sequence Diagram

sequenceDiagram
    participant User
    participant propagateAttributes
    participant OTelContext
    participant startActiveObservation
    participant Observation
    participant Span

    Note over User,Span: v5 Breaking Changes: propagateAttributes replaces updateTrace

    User->>propagateAttributes: propagateAttributes({userId, sessionId, tags, metadata})
    activate propagateAttributes
    propagateAttributes->>OTelContext: Set context with trace attributes
    Note over OTelContext: Attributes propagated via OpenTelemetry context
    
    propagateAttributes->>startActiveObservation: Execute callback function
    activate startActiveObservation
    startActiveObservation->>Span: Create OTEL span with active context
    Note over Span: Span inherits trace attributes from context
    
    startActiveObservation->>Observation: Wrap span in LangfuseObservation
    activate Observation
    
    User->>Observation: observation.update({input, output, metadata})
    Observation->>Span: Set observation-level attributes
    
    User->>Observation: observation.publishTrace()
    Note over Observation,Span: New method replaces updateTrace({public: true})
    Observation->>Span: Set TRACE_PUBLIC attribute
    
    User->>Observation: observation.setTraceIO({input, output})
    Note over Observation,Span: Deprecated method for legacy platform features
    Observation->>Span: Set trace I/O attributes
    
    Observation-->>User: Return observation
    deactivate Observation
    
    startActiveObservation-->>propagateAttributes: Return result
    deactivate startActiveObservation
    
    propagateAttributes-->>User: Return result
    deactivate propagateAttributes
    
    Note over User,Span: Key Change: Trace attributes must be set BEFORE creating observations

Loading

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-js	Ready	Preview	Feb 11, 2026 1:59pm

[greptile-apps]

_{4 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}