Add metadata to traces

By default, Openlayer captures inputs, outputs, latency, tokens, and other information from your system. Often you will want to attach custom metadata — such as business context, IDs, or debug information — so you can later filter, search, or correlate traces inside the platform. This guide shows you how to do it.

Want to record user or session IDs? See the Track users and sessions guide.

Trace-level metadata

Use update_current_trace() to attach metadata to the entire trace (i.e., the full request lifecycle).

from openlayer.lib import trace, update_current_trace

@trace()
def my_function(scenario_type: str) -> str:
    # Add metadata that applies to the full request
    update_current_trace(
        scenario_type=scenario_type,   # e.g., "checkout" vs "search"
        model_version="0.1.0"          # track which model version handled it
    )

    return "Some answer"

These key-value pairs appear in the trace metadata and can be filtered in the Openlayer UI.

Promote inputs and outputs onto the trace

update_current_trace() expects you to name every value by hand. When the value you want is already a function argument or a field of what the function returns, pass promote to @trace() instead: Openlayer lifts it onto the trace as a top-level column you can filter on and write tests against. Pass a list to keep the original names:

from openlayer.lib import trace

@trace(promote=["score", "confidence"])
def evaluate(text: str) -> dict:
    return {"score": 0.95, "confidence": 0.87, "explanation": "Well-structured."}

Each name resolves against the function inputs first, and then against the output — which can be a dict, a Pydantic model, or a dataclass. Both names above come from the returned dict, so the trace gains a score and a confidence column while explanation stays where it is. Pass a dict to rename the columns as you promote them:

from pydantic import BaseModel

from openlayer.lib import trace


class AgentResult(BaseModel):
    answer: str
    tool_call_count: int


@trace(promote={
    "user_query": "agent_input_query",      # from the input
    "tool_call_count": "agent_tool_calls",  # from the output
})
def run_agent(user_query: str) -> AgentResult:
    return AgentResult(answer="Paris is the capital of France.", tool_call_count=2)

A nested step promotes onto the trace it belongs to, not onto itself, so a child step’s fields become top-level columns too. Alias them with the dict form when a parent and a child expose the same field name and would otherwise collide.

A name that matches neither an input nor an output field is skipped with a warning, as is an output that is not a dict, Pydantic model, or dataclass. @trace_async() takes promote with the same semantics.

Step-level metadata

Use update_current_step() to attach metadata to individual steps inside a trace. This is useful for logging retrieval parameters, generation settings, or intermediate results.

from openlayer.lib import trace, update_current_step

@trace()
def retrieve_context(query: str) -> str:
    # Perform retrieval
    results = vector_search(query, top_k=5)

    # Add metadata about this retrieval step
    update_current_step(
        metadata={
            "retrieval_method": "vector_search",
            "top_k": 5,
            "num_results_found": len(results),
        }
    )

    return format_context(results)

@trace()
def generate_answer(query: str, context: str) -> str:
    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": f"{query}\n\nContext: {context}"}],
        temperature=0.7
    )

    # Add generation-specific metadata
    update_current_step(
        metadata={
            "context_length": len(context),
            "response_length": len(response.choices[0].message.content)
        }
    )

    return response.choices[0].message.content

Get started

Workspace setup

Governance

Observability

Offline testing

Tests

Gateway

Data quality monitoring

Administration

Notifications

Other resources

Add metadata to traces

Trace-level metadata

Promote inputs and outputs onto the trace

Step-level metadata

​Trace-level metadata

​Promote inputs and outputs onto the trace

​Step-level metadata

Trace-level metadata

Promote inputs and outputs onto the trace

Step-level metadata