Sessions

Many interactions with LLM applications span multiple traces. Sessions in Langfuse are a way to group these traces together and see a simple session replay of the entire interaction. Get started by adding a sessionId when creating a trace.

Add a sessionId when creating/updating a trace. This can be any string that you use to identify the session. All traces with the same sessionId will be grouped together.

When using the @observe() decorator:

from langfuse import observe, get_client
 
@observe()
def process_request():
    # Get the client
    langfuse = get_client()
 
    # Add to the current trace
    langfuse.update_current_trace(session_id="your-session-id")
 
    # ...your processing logic...
    return result

When creating spans directly:

from langfuse import get_client
 
langfuse = get_client()
 
# You can set the session_id when creating the root span
with langfuse.start_as_current_span(
    name="process-chat-message"
) as root_span:
    # Add session_id to the trace
    root_span.update_trace(session_id="chat-session-123")
 
    # All spans in this trace will belong to the same session
    with root_span.start_as_current_generation(
        name="generate-response",
        model="gpt-4o"
    ) as gen:
        # ...generate response...
        pass

You can also update the session_id of the current trace without a direct reference to a span:

with langfuse.start_as_current_span(name="another-operation"):
    # Add to the current trace
    langfuse.update_current_trace(session_id="your-session-id")

When using the @observe() decorator:

from langfuse.decorators import langfuse_context, observe
 
@observe()
def fn():
    langfuse_context.update_current_trace(
        session_id="your-session-id"
    )
 
fn()

When using the low-level SDK:

from langfuse import Langfuse
langfuse = Langfuse()
 
trace = langfuse.trace(
    session_id="your-session-id"
)

import { Langfuse } from "langfuse";
const langfuse = new Langfuse();
 
const trace = langfuse.trace({
  sessionId: "your-session-id",
});

See JS/TS SDK docs for more details.

When using the OpenAI SDK Integration, pass the session_id as an additional argument:

from langfuse.openai import openai
 
completion = openai.chat.completions.create(
  name="test-chat",
  model="gpt-3.5-turbo",
  messages=[
    {"role": "system", "content": "You are a calculator."},
    {"role": "user", "content": "1 + 1 = "}],
  temperature=0,
 
  # add session_id as additional argument
  session_id="your-session-id"
)

When using the integration with the @observe() decorator (see interop docs), set the session_id via the langfuse_context:

from langfuse.decorators import langfuse_context, observe
from langfuse.openai import openai
 
@observe()
def fn():
    langfuse_context.update_current_trace(
        session_id="your-session-id"
    )
 
    completion = openai.chat.completions.create(
      name="test-chat",
      model="gpt-3.5-turbo",
      messages=[
        {"role": "system", "content": "You are a calculator."},
        {"role": "user", "content": "1 + 1 = "}],
      temperature=0,
    )
 
fn()

When using the CallbackHandler, you can pass the session_id as a keyword argument:

handler = CallbackHandler(
  session_id="your-session-id"
)

You can also set the session_id dynamically via the runnable configuration in the chain invocation:

from langfuse.callback import CallbackHandler
 
handler = CallbackHandler()
 
# Your existing Langchain code to create the chain
...
 
# Pass langfuse_session_id as metadata to the chain invocation to be parsed as the Langfuse session_id
chain.invoke(
    {"animal": "dog"},
    config={
        "callbacks": [handler],
        "metadata": {
            "langfuse_session_id": "your-session-id",
        },
    },
)

When using the integration with the @observe() decorator (see interop docs), set the session_id via the langfuse_context:

from langfuse.decorators import langfuse_context, observe
 
@observe()
def fn():
    langfuse_context.update_current_trace(
        session_id="your-session-id"
    )
 
    langfuse_handler = langfuse_context.get_current_langchain_handler()
 
    # Pass handler to invoke of your langchain chain/agent
    chain.invoke({"person": person}, config={"callbacks":[langfuse_handler]})
 
fn()

When using the CallbackHandler, you can pass the sessionId to the constructor:

const handler = new CallbackHandler({
  sessionId: "your-session-id",
});

You can also set the session_id dynamically via the runnable configuration in the chain invocation:

import { CallbackHandler } from "langfuse-langchain";
 
const langfuseHandler = new CallbackHandler();
 
// Your existing Langchain code to create the chain
...
 
// Pass langfuseSessionId as metadata to the chain invocation to be parsed as the Langfuse session_id
await chain.invoke(
  { input: "<user_input>" },
  { callbacks: [langfuseHandler], metadata: { langfuseSessionId: "your-session-id" } }
);

When using the integration with the JS SDK (see interop docs), set the sessionId via langfuse.trace():

import { CallbackHandler, Langfuse } from "langfuse-langchain";
const langfuse = new Langfuse();
 
const trace = langfuse.trace({
  sessionId: "your-session-id",
});
const langfuseHandler = new CallbackHandler({ root: trace });
 
// Add Langfuse handler as callback to your langchain chain/agent
await chain.invoke({ input: "<user_input>" }, { callbacks: [langfuseHandler] });

The LlamaIndex integration is not supported in the Python SDK v3. Please use a community-maintained OTEL-based integration instead.

When using the LlamaIndex Integration, set the session_id via the instrumentor.observe() context manager:

from langfuse.llama_index import LlamaIndexInstrumentor
 
instrumentor = LlamaIndexInstrumentor()
 
with instrumentor.observe(session_id="my-session"):
    # ... your LlamaIndex index creation ...
 
    index.as_query_engine().query("What is the capital of France?")
 
instrumentor.flush()

When using the integration with the @observe() decorator (see interop docs), set the session_id via the langfuse_context:

from langfuse.decorators import langfuse_context, observe
from langfuse.llama_index import LlamaIndexInstrumentor
 
instrumentor = LlamaIndexInstrumentor()
 
@observe()
def llama_index_fn(question: str):
    # Update context
    langfuse_context.update_current_trace(session_id="your-session-id")
 
    # Get IDs
    current_trace_id = langfuse_context.get_current_trace_id()
    current_observation_id = langfuse_context.get_current_observation_id()
 
    # Pass to instrumentor
    with instrumentor.observe(
        trace_id=current_trace_id,
        parent_observation_id=current_observation_id,
        update_parent=False
    ) as trace:
        # ... your LlamaIndex index creation ...
 
        index.as_query_engine().query("What is the capital of France?")
 
        # Run application
        index = VectorStoreIndex.from_documents([doc1, doc2])
        response = index.as_query_engine().query(question)
 
        return response

The LlamaIndex callback integration is not supported in the Python SDK v3. Please use a community-maintained OTEL-based integration instead.

When using the (deprecated) LlamaIndex Callback Integration, set the session_id via set_trace_params. All LlamaIndex traces created after set_trace_params will include the session_id. Learn more about set_trace_params here.

from llama_index.core import Settings
from llama_index.core.callbacks import CallbackManager
from langfuse import langfuse
 
# Instantiate a new LlamaIndexCallbackHandler and register it in the LlamaIndex Settings
langfuse_callback_handler = LlamaIndexCallbackHandler()
Settings.callback_manager = CallbackManager([langfuse_callback_handler])
 
langfuse_callback_handler.set_trace_params(
  session_id="session-abc",
)

When using the integration with the @observe() decorator (see interop docs), set the session_id via the langfuse_context:

from langfuse.decorators import langfuse_context, observe
from llama_index.core import Document, VectorStoreIndex
from llama_index.core import Settings
from llama_index.core.callbacks import CallbackManager
 
@observe()
def llama_index_fn(question: str):
    langfuse_context.update_current_trace(
        session_id="your-session-id"
    )
 
    # Set callback manager for LlamaIndex, will apply to all LlamaIndex executions in this function
    langfuse_handler = langfuse_context.get_current_llama_index_handler()
    Settings.callback_manager = CallbackManager([langfuse_handler])
 
    # Run application
    index = VectorStoreIndex.from_documents([doc1,doc2])
    response = index.as_query_engine().query(question)
    return response

Example

Try this feature using the public example project.

Example session spanning multiple traces

Session view

Other features

Publish a session to share with others as a public link (example)
Bookmark a session to easily find it later
Annotate sessions by adding scores via the Langfuse UI to record human-in-the-loop evaluations

GitHub Discussions

Sampling Tags

Was this page helpful?

Support