Trace IDs & Distributed Tracing

Langfuse allows you to bring your own trace IDs (e.g., messageId, traceId, correlationId) for

distributed tracing
and linking traces across services for lookups between services.

💡

By default, Langfuse assigns random IDs (uuid, cuid) to all logged events. For the new OTEL-based SDKs (Python v3), Langfuse assigns random 32 hexchar trace IDs and 16 hexchar observation IDs.

It is recommended to use your own domain specific IDs (e.g., messageId, traceId, correlationId) as it helps with downstream use cases like:

deeplinking to the trace from your own ui or logs
evaluating and adding custom metrics to the trace
fetching the trace from the API

Data Model

Trace IDs in Langfuse:

Must be unique within a project
Are used to identify and group related observations
Can be used for distributed tracing across services
Support upsert operations (creating or updating based on ID)
For the new OTEL-based SDKs (Python v3), trace IDs are 32 hexchar lowercase strings and observation IDs are 16 hexchar lowercase strings

Usage

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

The Python SDK v3 uses W3C Trace Context IDs by default, which are:

32-character lowercase hexadecimal string for trace IDs
16-character lowercase hexadecimal string for observation (span) IDs

Using the Decorator

from langfuse import observe
import uuid
 
@observe()
def process_user_request(user_id, request_data):
    # Function logic here
    pass
 
# Use custom trace ID by passing it as special keyword argument
external_trace_id = "custom-" + str(uuid.uuid4())
 
# Get a consistent trace ID for the same user
trace_id = langfuse.create_trace_id(seed=external_trace_id) # 32 hexchar lowercase string, deterministic with seed
 
process_user_request(
    user_id="user_123",
    request_data={"query": "hello"},
    langfuse_trace_id=trace_id
)

Deterministic Trace IDs

You can generate deterministic trace IDs from any string using create_trace_id():

from langfuse import Langfuse
 
langfuse = Langfuse()
 
# Generate deterministic trace ID from an external ID
external_id = "request_12345"
trace_id = langfuse.create_trace_id(seed=external_id)
 
# Use this trace ID in a span
with langfuse.start_as_current_span(
    name="process-request",
    trace_context={"trace_id": trace_id}
) as span:
    # Your code here
    pass

Manually Creating Spans with Custom Trace Context

from langfuse import Langfuse
 
langfuse = Langfuse()
 
# Use a predefined trace ID with trace_context parameter
with langfuse.start_as_current_span(
    name="my-operation",
    trace_context={
        "trace_id": "abcdef1234567890abcdef1234567890",  # Must be 32 hex chars
        "parent_span_id": "fedcba0987654321"  # Optional, 16 hex chars
    }
) as span:
    print(f"This span has trace_id: {span.trace_id}")
    # Your code here

Accessing Current Trace ID

from langfuse import Langfuse
 
langfuse = Langfuse()
 
with langfuse.start_as_current_span(name="outer-operation") as span:
    # Access the trace ID of the current span
    current_trace_id = langfuse.get_current_trace_id()
    current_span_id = langfuse.get_current_observation_id()
 
    print(f"Current trace ID: {current_trace_id}")
    print(f"Direct access: {span.trace_id}")

When using the @observe() decorator:

from langfuse.decorators import langfuse_context, observe
import uuid
 
@observe()
def process_user_request(user_id, request_data, **kwargs):
    # Function logic here
    pass
 
def main():
    # Custom trace ID
    custom_trace_id = "custom-" + str(uuid.uuid4())
 
    # Pass id as kwarg
    # Can be passed to multiple functions
    process_user_request(
        user_id=user_id,
        request_data=request_data,
        langfuse_parent_trace_id=custom_trace_id,
    )

When using the low-level SDK:

from langfuse import Langfuse
 
# Set custom trace ID during creation
trace = langfuse.trace(
    id="my-custom-trace-id",
    name="Rap Battle",
)

import { Langfuse } from "langfuse";
import { v4 as uuidv4 } from "uuid";
 
const langfuse = new Langfuse();
 
// Create trace with custom ID
const traceId = uuidv4();
const trace = langfuse.trace({
  id: traceId,
  name: "chat-app-session",
  userId: "user_123456789",
  metadata: { user: "user@langfuse.com" },
  tags: ["production"],
});
 
// Create observations with custom IDs
const span = trace.span({
  id: "custom-span-id",
  name: "chat-interaction",
});
 
const generation = trace.generation({
  id: "custom-generation-id",
  name: "chat-completion",
});

When using OpenTelemetry, trace IDs are handled automatically by the OpenTelemetry SDK. You can access and set trace IDs using the OpenTelemetry context:

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode
 
tracer = trace.get_tracer(__name__)
 
with tracer.start_as_current_span("my-operation") as span:
    # Get the trace ID
    trace_id = format(span.get_span_context().trace_id, "032x")
 
    # Set custom attributes
    span.set_attribute("custom.trace_id", trace_id)

When using the OpenAI SDK Integration, you have two options for working with trace IDs:

Directly set the trace_id in the completion call:

from langfuse.openai import openai
 
# Set trace_id directly in the completion call
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 = "}
    ],
    trace_id="my-custom-trace-id"  # Set your custom trace ID
)

Use the @observe() decorator for automatic trace management:

from langfuse.decorators import langfuse_context, observe
from langfuse.openai import openai
 
@observe()
def calculate_sum(a: int, b: int, **kwargs):
    # Get the current trace ID if needed
    trace_id = langfuse_context.get_current_trace_id()
 
    completion = openai.chat.completions.create(
        name="calculator",
        model="gpt-3.5-turbo",
        messages=[
            {"role": "system", "content": "You are a calculator. Only output the numeric result."},
            {"role": "user", "content": f"{a} + {b} = "}
        ]
    )
 
    # The completion will automatically be added to the current trace
    return completion.choices[0].message.content, trace_id
 
# Use with custom trace ID
result, trace_id = calculate_sum(5, 3, langfuse_observation_id="my-custom-trace-id")

The decorator approach is recommended when you want to:

Group multiple OpenAI calls into a single trace
Add additional context or metadata to the trace
Track the entire function execution, not just the OpenAI call

import OpenAI from "openai";
import { observeOpenAI } from "langfuse";
 
// Create a trace with custom ID
const trace = langfuse.trace({
  id: "custom-trace-id",
  name: "openai-chat",
});
 
const openai = observeOpenAI(new OpenAI(), {
  parent: trace, // Link OpenAI calls to the trace
});
 
const completion = await openai.chat.completions.create({
  model: "gpt-3.5-turbo",
  messages: [{ role: "user", content: "Hello!" }],
});

When using Langchain with Langfuse, you have two options for working with trace IDs:

Using the CallbackHandler and langchain run config:

from langfuse.callback import CallbackHandler
import uuid
 
predefined_run_id = str(uuid.uuid4())
 
langfuse_handler = CallbackHandler()
 
# Pass run_id to the chain invocation
chain.invoke(
    {"input": "test"},
    config={
        "callbacks": [langfuse_handler],
        "run_id": predefined_run_id,  # This becomes the trace ID
    },
)

Using the @observe() decorator for automatic trace management:

from langfuse.decorators import langfuse_context, observe
from langchain_openai import ChatOpenAI
from langchain.prompts import ChatPromptTemplate
from langchain.schema import StrOutputParser
 
prompt = ChatPromptTemplate.from_template("what is the city {person} is from?")
model = ChatOpenAI()
chain = prompt | model | StrOutputParser()
 
@observe()
def get_person_city(person: str, **kwargs):
    # Get the Langchain handler from the current context
    langfuse_handler = langfuse_context.get_current_langchain_handler()
 
    # The handler is automatically scoped to the current trace
    response = chain.invoke(
        {"person": person},
        config={"callbacks": [langfuse_handler]}
    )
 
    # Get trace ID if needed
    trace_id = langfuse_context.get_current_trace_id()
    return response, trace_id
 
# Use with custom trace ID
result, trace_id = get_person_city(
    "Einstein",
    langfuse_observation_id="my-custom-trace-id"
)

The decorator approach is recommended when you want to:

Group multiple Langchain operations into a single trace
Combine Langchain with other integrations (OpenAI, LlamaIndex, etc.)
Add additional context or metadata to the trace
Track the entire function execution, not just the Langchain operations

import { CallbackHandler } from "langfuse-langchain";
 
// Create a trace with custom ID
const trace = langfuse.trace({ id: "special-id" });
 
// CallbackHandler will use the trace with the specified ID
const langfuseHandler = new CallbackHandler({ root: trace });
 
// Use the handler in your chain
const chain = new LLMChain({
  llm: model,
  prompt,
  callbacks: [langfuseHandler],
});

When using LiteLLM:

from litellm import completion
 
# Set custom trace ID and other parameters
response = completion(
  model="gpt-3.5-turbo",
  messages=[
    {"role": "user", "content": "Hi 👋"}
  ],
  metadata={
      "generation_name": "test-generation",
      "generation_id": "gen-id",
      "trace_id": "trace-id",
      "trace_user_id": "user-id",
      "session_id": "session-id",
      "tags": ["tag1", "tag2"]
  },
)

Trace IDs & Distributed Tracing

Data Model

Usage

Using the Decorator

Deterministic Trace IDs

Manually Creating Spans with Custom Trace Context

Accessing Current Trace ID

Was this page useful?

Questions? We're here to help

Subscribe to updates