Tagging Traces

Tags allow you to categorize and filter traces. You can tag traces (1) when they are created using the Langfuse SDKs and integrations or (2) from the Langfuse UI. To tag a trace, add a list of tags to the tags field of the trace object. Tags are strings and a trace may have multiple tags.

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 my_function():
    # ... processing logic ...
    # Add tags to the trace
    langfuse.update_current_trace(tags=["tag-1", "tag-2"])

When creating spans or generations directly:

from langfuse import Langfuse
langfuse = Langfuse()
 
# Add tags when creating the root span
with langfuse.start_as_current_span(
    name="my-operation"
) as root_span:
    # Add tags to the trace
    root_span.update_trace(tags=["tag-1", "tag-2"])
 
    # You can add more tags later from any span in the same trace
    with root_span.start_as_current_generation(name="llm-call", model="gpt-4o") as gen:
        # Processing...
        gen.update_trace(tags=["llm-gen"])  # Adds another tag to the same trace

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

with langfuse.start_as_current_span(name="another-operation"):
    # ... processing ...
    langfuse.update_current_trace(tags=["processing", "beta-feature"])

When using the @observe() decorator:

from langfuse.decorators import langfuse_context, observe
 
@observe()
def fn():
    langfuse_context.update_current_trace(
        tags=["tag-1", "tag-2"]
    )
 
fn()

When using the low-level SDK:

from langfuse import Langfuse
langfuse = Langfuse()
 
trace = langfuse.trace(
    tags=["tag-1", "tag-2"]
)

import { Langfuse } from "langfuse";
const langfuse = new Langfuse();
 
const trace = langfuse.trace({
  tags: ["tag-1", "tag-2"],
});

See JS/TS SDK docs for more details.

When using the OpenAI SDK Integration, pass tags 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 tags as additional argument
  tags=["tag-1", "tag-2"]
)

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

from langfuse.decorators import langfuse_context, observe
from langfuse.openai import openai
 
@observe()
def fn():
    langfuse_context.update_current_trace(
        tags=["tag-1", "tag-2"]
    )
 
    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 tags as a keyword argument:

handler = CallbackHandler(
  tags=["tag-1", "tag-2"]
)

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

from langfuse.callback import CallbackHandler
 
handler = CallbackHandler()
tags = ["tag-1", "tag-2"]
 
chain.invoke(
    {"animal": "dog"},
    config={
        "callbacks": [handler],
        "tags": tags,
    },
)

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

from langfuse.decorators import langfuse_context, observe
 
@observe()
def fn():
    langfuse_context.update_current_trace(
        tags=["tag-1", "tag-2"]
    )
 
    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 tags to the constructor:

const handler = new CallbackHandler({
  tags: ["tag-1", "tag-2"],
});

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

const langfuseHandler = new CallbackHandler()
const tags = ["tag-1", "tag-2"];
 
// Your existing Langchain code to create the chain
...
 
// Pass config to the chain invocation to be parsed as Langfuse trace attributes
await chain.invoke({ input: "<user_input>" }, { callbacks: [langfuseHandler], tags: tags });

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

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

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

from langfuse.llama_index import LlamaIndexInstrumentor
 
instrumentor = LlamaIndexInstrumentor()
 
with instrumentor.observe(tags=["tag-1", "tag-2"]):
    # ... 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 tags 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):s
    # Update context
    langfuse_context.update_current_trace(tags=["tag-1", "tag-2"])
 
    # 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

When using the (deprecated) LlamaIndex Callback Integration, set the tags via set_trace_params. All LlamaIndex traces created after set_trace_params will include the tags. 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(
  tags=["tag-1", "tag-2"]
)

When using the integration with the @observe() decorator (see interop docs), set the tags 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(
        tags=["tag-1", "tag-2"]
    )
 
    # 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

Working with tags

Tags enable you to flexibly add metadata to your traces. You can filter for tags in the Langfuse UI and GET API.

When choosing tags, consider what aspects of the traces you might want to filter for or group by in your analysis. You may use tags to indicate specific versions of your app (‘app-v1’, ‘app-v2’), specific LLM techniques you used (‘rag’, ‘one-shot’, ‘few-shot’), or the environment of your app (‘local’, ‘staging’, ‘prod’). See Intent Classification Notebook for an end-to-end example on how tags can be created programmatically.

Tagging Traces

Working with tags

GitHub Discussions

Was this page useful?

Questions? We're here to help

Subscribe to updates