Skip to content

Conversation

vblagoje
Copy link
Member

@vblagoje vblagoje commented Sep 9, 2025

Why

This PR migrates the Langfuse integration from Langfuse v2 to v3. Langfuse v3 is built on OpenTelemetry (OTel), which differs from v2's trace creation model. The migration introduces an expected extra root span level due to OTel's requirement that trace attributes must be held by a span, unlike v2's direct trace creation capability.
TLDR - you'll see an extra nested root span.

Proposed Changes

  • Complete migration from Langfuse v2 to v3 API
  • User's will not notice any difference in traces (other than the extra root)

How did you test it?

  • Updated existing unit tests to work with v3 API
  • Adjusted some tests to work with extra root span
  • Manually tested in complex multi-agent itinerary setup. Here is the trace. Note the double top nested root span. Here is how the trace looks like in v2 . Hassieb from Lanfguse told me: "exactly, it is expected that there is one root span under the trace, as OTel does not have a concept of a trace that holds attributes (whereas Langfuse does). So the behavior you are seeing is expected"

Notes for the reviewer

The extra root span level is expected behavior in v3 due to OTel's architecture - it's not a bug but a fundamental difference from v2. Some tests needed to be updated to account for this.

@github-actions github-actions bot added integration:langfuse type:documentation Improvements or additions to documentation labels Sep 9, 2025
@vblagoje vblagoje marked this pull request as ready for review September 10, 2025 09:35
@vblagoje vblagoje requested a review from a team as a code owner September 10, 2025 09:35
@vblagoje vblagoje requested review from julian-risch and removed request for a team September 10, 2025 09:35
@vblagoje
Copy link
Member Author

vblagoje commented Sep 10, 2025

@LastRemote would you please, at your convenience, try out this PR on your async setup we used to previously test #2207 It would be amazing to nail this transition to v3 without regressions and additional cleanups. 🙏

@sjrl
Copy link
Contributor

sjrl commented Sep 11, 2025

@vblagoje just so you are aware I also opened a PR here #2257 that enabled linting on the examples and tests folder. Given that you reworked the langfuse integration in this PR feel free to close mine if it no longer makes sense.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
integration:langfuse type:documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Update Langfuse integration for Python SDK v3
2 participants