Tags
Tags allow you to categorize and filter observations and traces in Langfuse.
Tags are strings (max 200 characters each) and an observation may have multiple tags. If a tag exceeds 200 characters, it will be dropped.
The full set of tags applied across all observations in a trace are automatically aggregated and added to the trace object in Langfuse.
Choosing between tags and metadata
For new instrumentation, prefer metadata for structured attributes. Use tags for a small, stable set of independent labels. Both can help you filter observations, but their structure and aggregation behavior differ.
| Metadata | Tags | |
|---|---|---|
| Structure | Named key-value pairs | A set of string labels |
| Example | {"workflow": "checkout", "customer_id": "123"} | ["billing", "priority"] |
| Choose it for | Attributes with a clear name and value, including identifiers and request context | Membership in several categories |
| Design consideration | A field can have many distinct values, making some aggregations expensive | Labels can overlap, making breakdowns and totals harder to interpret |
Use dedicated fields such as environment, user ID, and session ID when they match the information you are recording.
Filtering and grouping are different
Filtering answers "show observations for customer 123." Grouping answers "show costs for every customer." A field can be useful for filtering without being available or efficient as a dashboard grouping dimension.
Before choosing a field specifically for reporting, check the supported dimensions in Custom dashboards and the Metrics API. Metadata filtering does not imply support for arbitrary metadata breakdowns.
Plan for distinct values and overlapping categories
Cardinality is the number of distinct values. A workflow field might have ten values; a customer ID might have millions. Prefer metadata for such identifiers rather than creating a tag for each value. Metadata preserves their structure, but does not remove the cost of aggregating many distinct values.
Tags introduce another consideration: one observation can belong to several categories. Grouping by individual labels and grouping by complete tag combinations answer different questions. Check the breakdown behavior before interpreting or adding together category totals.
In the Langfuse UI
Once observations have tags assigned, you can:
- Filter the traces and observations tables by one or more tags, including from the filter search bar (
tags:(billing AND urgent)). - Segment custom dashboards and metrics by tag, for example cost or latency of
checkoutversussupport-bot. - Organize traces by feature, endpoint, or workflow without mixing those categories into environment, user, or session.
![]()
Tags cannot be changed later
Because Langfuse uses an immutable data model for observations, tags can't be added or edited in the UI after they're created.
Implementation
Use propagate_attributes() to apply tags to a group of observations within a context.
When using the @observe() decorator:
from langfuse import observe, propagate_attributes
@observe()
def my_function():
# Apply tags to all child observations
with propagate_attributes(
tags=["tag-1", "tag-2"]
):
# All nested observations automatically have these tags
result = process_data()
return resultWhen creating observations directly:
from langfuse import get_client, propagate_attributes
langfuse = get_client()
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as root_span:
# Apply tags to all child observations
with propagate_attributes(tags=["tag-1", "tag-2"]):
# All observations created here automatically have these tags
with root_span.start_as_current_observation(
as_type="generation",
name="llm-call",
model="gpt-4o"
) as gen:
# This generation automatically has the tags
passWhen using the context manager:
import { startActiveObservation, propagateAttributes } from "@langfuse/tracing";
await startActiveObservation("context-manager", async (span) => {
span.update({
input: { query: "What is the capital of France?" },
});
// Apply tags to all child observations
await propagateAttributes(
{
tags: ["tag-1", "tag-2"],
},
async () => {
// All observations created here automatically have these tags
// ... your logic ...
}
);
});When using the observe wrapper:
import { observe, propagateAttributes } from "@langfuse/tracing";
const processData = observe(
async (data: string) => {
// Apply tags to all child observations
return await propagateAttributes(
{ tags: ["tag-1", "tag-2"] },
async () => {
// All nested observations automatically have these tags
const result = await performProcessing(data);
return result;
}
);
},
{ name: "process-data" }
);
const result = await processData("input");See JS/TS SDK docs for more details.
from langfuse import get_client, propagate_attributes
from langfuse.openai import openai
langfuse = get_client()
with langfuse.start_as_current_observation(as_type="span", name="openai-call"):
# Apply tags to all observations including OpenAI generation
with propagate_attributes(
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,
)Alternatively, when using OpenAI without an enclosing observation:
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,
metadata={"langfuse_tags": ["tag-1", "tag-2"]}
)import OpenAI from "openai";
import { observeOpenAI } from "@langfuse/openai";
import { startActiveObservation, propagateAttributes } from "@langfuse/tracing";
await startActiveObservation("openai-call", async () => {
// Apply tags to all observations
await propagateAttributes(
{
tags: ["tag-1", "tag-2"],
},
async () => {
const res = await observeOpenAI(new OpenAI()).chat.completions.create({
messages: [{ role: "system", content: "Tell me a story about a dog." }],
model: "gpt-3.5-turbo",
max_tokens: 300,
});
}
);
});from langfuse import get_client, propagate_attributes
from langfuse.langchain import CallbackHandler
langfuse = get_client()
langfuse_handler = CallbackHandler()
with langfuse.start_as_current_observation(as_type="span", name="langchain-call"):
# Apply tags to all child observations
with propagate_attributes(
tags=["tag-1", "tag-2"]
):
response = chain.invoke(
{"topic": "cats"},
config={"callbacks": [langfuse_handler]}
)Alternatively, use metadata in chain invocation:
from langfuse.langchain import CallbackHandler
handler = CallbackHandler()
chain.invoke(
{"animal": "dog"},
config={
"callbacks": [handler],
"metadata": {"langfuse_tags": ["tag-1", "tag-2"]},
},
)import { startActiveObservation, propagateAttributes } from "@langfuse/tracing";
import { CallbackHandler } from "@langfuse/langchain";
const langfuseHandler = new CallbackHandler();
// Apply tags to all child observations
await propagateAttributes(
{
tags: ["tag-1", "tag-2"],
},
async () => {
await chain.invoke(
{ input: "<user_input>" },
{ callbacks: [langfuseHandler] }
);
}
);Alternatively, when using the CallbackHandler, you can pass tags to the constructor:
const handler = new CallbackHandler({
tags: ["tag-1", "tag-2"],
});Or set tags dynamically via the runnable configuration in the chain invocation:
const langfuseHandler = new CallbackHandler()
const tags = ["tag-1", "tag-2"];
// Pass config to the chain invocation to be parsed as Langfuse trace attributes
await chain.invoke({ input: "<user_input>" }, { callbacks: [langfuseHandler], tags: tags });Note on Attribute Propagation
- Values must be strings ≤200 characters
- Call early in your trace to ensure all observations are covered. This way you make sure that all Metrics in Langfuse are accurate.
- Invalid values are dropped with a warning
Related resources
- Filter search bar — filter observations and traces by tags with typed queries such as
tags:(billing AND urgent) - Metadata — use named attributes for structured context
- Environments — separate production, staging, and development data
- Custom dashboards — break down metrics by tag
- Metrics API — query aggregated usage and cost filtered by tags
- Scores vs tags — choose scores when you need to classify or evaluate after tracing
- What does a good trace look like? — choose attributes for filtering and reporting
GitHub Discussions
Last updated on