Skip to main content
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.

​
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