> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add metadata to traces

> Learn how to add metadata to traces sent to Openlayer

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.

<Note>
  Want to record **user or session IDs**? See the [Track users and
  sessions](/monitoring/sessions-and-users) guide.
</Note>

## Trace-level metadata

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

```python theme={null}
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.

```python theme={null}
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
```