Releases & Versioning

You can track the effect of changes to your LLM app on metrics in Langfuse. This allows you to:

Run experiments (A/B tests) in production and measure the impact on costs, latencies and quality.
- Example: “What is the impact of switching to a new model?”
Explain changes to metrics over time.
- Example: “Why did latency in this chain increase?”

Releases

A release tracks the overall version of your application. Commonly it is set to the semantic version or git commit hash of your application.

The SDKs look for a release in the following order:

SDK initialization
Environment variable
Automatically on popular platforms

SDK initialization

The Python SDK v3 allows you to set the release when initializing the client:

from langfuse import Langfuse
 
# Set the release when initializing the client
langfuse = Langfuse(release="v2.1.24")

You can also update the trace’s release after creation:

from langfuse import observe, get_client
 
@observe()
def process_data():
    # Get the client and update the current trace
    langfuse = get_client()
    langfuse.update_current_trace(release="v2.1.24")
    # ...
 
# With context managers
with langfuse.start_as_current_span(name="my-operation") as span:
    span.update_trace(release="v2.1.24")

Decorators

from langfuse.decorators import langfuse_context, observe
 
@observe()
def fn():
    langfuse_context.update_current_trace(
        release="<release_tag>"
    )
 
fn()

Low-level SDK

from langfuse import Langfuse
 
langfuse = Langfuse(
  release="<release_tag>"
)

import { Langfuse } from "langfuse";
 
langfuse = new Langfuse({
  release: "<release_tag>",
});

When using the Python SDK v3, the release provided on client initialization will apply to all event inputs and outputs regardless of the Langfuse-maintained integration you are using.

See the Python SDK v3 tab for more details.

from langfuse.callback import CallbackHandler
 
handler = CallbackHandler(release="<release_tag>")

import { CallbackHandler } from "langfuse-langchain";
 
const handler = new CallbackHandler({
  release: "<release_tag>",
});

Via environment variable

The SDKs will look for a LANGFUSE_RELEASE environment variable. Use it to configure the release e.g. in your CI/CD pipeline.

LANGFUSE_RELEASE = "<release_tag>" # <- github sha or other identifier

Automatically on popular platforms

If no other release is set, the Langfuse SDKs default to a set of known release environment variables.

Supported platforms include: Vercel, Heroku, Netlify. See the full list of support environment variables for JS/TS and Python.

Versions

The version parameter can be added to traces and all observation types (span, generation, event). Thereby, you can track the effect of a new version on the metrics of an object with a specific name using Langfuse analytics.

The v3 SDK is currently in beta. Please check out the SDK v3 for more details.

When using the @observe() decorator:

from langfuse import observe, get_client
 
langfuse = get_client()
 
@observe()
def process_data():
    # Set version at trace level
    langfuse.update_current_trace(version="1.0")
 
    # Set version at observation level
    langfuse.update_current_span(version="1.0")

When creating spans directly:

from langfuse import Langfuse
 
langfuse = Langfuse()
 
# Set version when creating a span
with langfuse.start_as_current_span(
    name="process-data",
    version="1.0"
) as span:
    # Processing...
 
    # Create a generation with version
    with span.start_as_current_generation(
        name="guess-countries",
        model="gpt-4o",
        version="1.0"
    ) as generation:
        # Generation code...
        pass

The version parameter can be included in both spans and generations, and can be set either during creation or updated later.

Decorators

from langfuse.decorators import langfuse_context, observe
 
@observe()
def fn():
    # trace level
    langfuse_context.update_current_trace(
        version="1.0",
    )
 
    # observation level
    langfuse_context.update_current_observation(
        version="1.0",
    )
fn()

Low-level SDK

langfuse.generation(
  name="guess-countries",
  version="1.0",
)

langfuse.trace(), langfuse.span() and langfuse.event() also take an optional version parameter.

langfuse.generation({
  name: "guess-countries",
  version: "1.0",
});

langfuse.trace(), langfuse.span() and langfuse.event() also take an optional version parameter.

from langfuse.callback import CallbackHandler
 
handler = CallbackHandler(version="1.0")

import { CallbackHandler } from "langfuse-langchain";
 
const handler = new CallbackHandler({
  version: "1.0",
});

Version parameter in Langfuse interface

Version on single generation

Multi-Modality & Attachments Sampling

Was this page useful?

Questions? We're here to help

GitHub Q&AEmail Talk to sales