Traces

A trace groups together multiple observations that are part of the same request or operation.

For example, when a user asks a question to a chatbot, that interaction, from the user’s question to the bot’s response, is captured as one trace. It contains the overall input and output of the function, as well as metadata about the request ( i.e. user, session, tags, etc.).

Most integrations will automatically create a trace for you. However, you can also create a trace manually using the Langfuse SDK.

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 OTEL-based SDKs, 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 OTEL-based SDKs, trace IDs are 32 hexchar lowercase strings and observation IDs are 16 hexchar lowercase strings

Usage

The Python SDK 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

You can inspect and reuse these IDs programmatically:

langfuse.get_current_trace_id() returns the trace ID of the active observation.
langfuse.get_current_observation_id() returns the observation (span) ID of the active observation.
span.trace_id and span.id expose the IDs on any LangfuseSpan/LangfuseGeneration returned from start_as_current_observation.
Langfuse.create_trace_id(seed: Optional[str] = None) is a static helper to deterministically pre-generate trace IDs before a trace exists (e.g., to correlate an external request ID).

Using the Decorator

from langfuse import observe, get_client
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
langfuse = get_client()
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 get_client
 
langfuse = get_client()
 
# 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_observation(
    as_type="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 get_client
 
langfuse = get_client()
 
# Use a predefined trace ID with trace_context parameter
with langfuse.start_as_current_observation(
    as_type="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 & Observation IDs

from langfuse import get_client
 
langfuse = get_client()
 
with langfuse.start_as_current_observation(as_type="span", name="outer-operation") as span:
    # Access the IDs of the current span
    current_trace_id = langfuse.get_current_trace_id()
    current_span_id = langfuse.get_current_observation_id()
 
    print(f"Trace ID from helper: {current_trace_id}")
    print(f"Observation ID from helper: {current_span_id}")
    print(f"Trace ID from object: {span.trace_id}")
    print(f"Observation ID from object: {span.id}")

Pre-generating Trace IDs

Use the static helper when you need a trace ID before creating any spans (for example, to pass IDs between services or to link later scores to a trace that does not yet exist):

from langfuse import get_client, Langfuse
 
langfuse = get_client()
 
external_request_id = "req_12345"
deterministic_trace_id = Langfuse.create_trace_id(seed=external_request_id)
print(f"Deterministic Trace ID for {external_request_id}: {deterministic_trace_id}")
 
# Later, start a span that adopts that trace ID
with langfuse.start_as_current_observation(
    as_type="span",
    name="process-request",
    trace_context={"trace_id": deterministic_trace_id}
) as span:
    # Your code here

The Python SDK 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

Accessing the current trace ID

You may access the current active trace ID via the getActiveTraceId function:

import { startObservation, getActiveTraceId } from "@langfuse/tracing";
 
await startObservation("run", async (span) => {
  const traceId = getActiveTraceId();
  console.log(`Current trace ID: ${traceId}`);
});

Deterministic trace IDs

When starting a new trace with a predetermined traceId, you must also provide an arbitrary parent-spanId for the parent observation. The parent span ID value is irrelevant as long as it is a valid 16-hexchar string as the span does not actually exist within the trace but is only used for trace ID inheritance of the created observation.

You can create valid, deterministic trace IDs from a seed string using createTraceId. This is useful for correlating Langfuse traces with IDs from external systems, like a support ticket ID.

import { createTraceId, startObservation } from "@langfuse/tracing";
 
const externalId = "support-ticket-54321";
 
// Generate a valid, deterministic traceId from the external ID
const langfuseTraceId = await createTraceId(externalId);
 
// You can now start a new trace with this ID
const rootSpan = startObservation(
  "process-ticket",
  {},
  {
    parentSpanContext: {
      traceId: langfuseTraceId,
      spanId: "0123456789abcdef", // A valid 16 hexchar string; value is irrelevant as parent span does not exist but only used for inheritance
      traceFlags: 1, // mark trace as sampled
    },
  }
);
 
// Later, you can regenerate the same traceId to score or retrieve the trace
const scoringTraceId = await createTraceId(externalId);
// scoringTraceId will be the same as langfuseTraceId

Setting a parentSpanContext will detach the created span from the active span context as it no longer inherits from the current active span in the context.

Learn more in the JS/TS SDK docs.

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-4o",
    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 import observe, get_client
from langfuse.openai import openai
import uuid
 
@observe()
def process_user_request(user_id, request_data):
    completion = openai.chat.completions.create(
        name="calculator",
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "You are a calculator. Only output the numeric result."},
            {"role": "user", "content": f"{a} + {b} = "}
        ]
    )
    return completion.choices[0].message.content
 
# 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
langfuse = get_client()
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
)

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/openai";
 
// 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!" }],
});

To pass a custom trace ID to a Langchain execution, you can wrap the execution in a span that sets a predefined trace ID. You can also retrieve the last trace ID a callback handler has created via langfuse_handler.last_trace_id.

from langfuse import get_client, Langfuse
from langfuse.langchain import CallbackHandler
 
langfuse = get_client()
 
# Generate deterministic trace ID from external system
external_request_id = "req_12345"
predefined_trace_id = Langfuse.create_trace_id(seed=external_request_id)
 
langfuse_handler = CallbackHandler()
 
# Use the predefined trace ID with trace_context
with langfuse.start_as_current_observation(
    as_type="span",
    name="langchain-request",
    trace_context={"trace_id": predefined_trace_id}
) as span:
 
    with propagate_attributes(
    span.update_trace(
        input={"person": "Ada Lovelace"}
    )
 
    # LangChain execution will be part of this trace
    response = chain.invoke(
        {"person": "Ada Lovelace"},
        config={"callbacks": [langfuse_handler]}
    )
 
    span.update_trace(output={"response": response})
 
print(f"Trace ID: {predefined_trace_id}")  # Use this for scoring later
print(f"Trace ID: {langfuse_handler.last_trace_id}") # Care needed in concurrent environments where handler is reused

import { CallbackHandler, Langfuse } from "langfuse-langchain";
 
const langfuse = new Langfuse();
 
// 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"]
  },
)

Observations Sessions

Was this page helpful?

Support