Learn how to enrich your traces and spans with custom metadata and attributes using the LangWatch Python SDK.
Metadata and attributes are key-value pairs that allow you to add custom contextual information to your traces and spans. This enrichment is invaluable for debugging, analysis, filtering, and gaining deeper insights into your LLM application’s behavior.
LangWatch distinguishes between two main types of custom data:
This tutorial will guide you through capturing both types using the Python SDK.
Trace metadata provides context for the entire trace. It’s ideal for information that remains constant throughout the execution of a traced operation, such as:
user_id
)session_id
, thread_id
)app_version
)env: "production"
)You can set trace metadata when a trace is initiated or update it at any point while the trace is active.
The easiest way to add metadata to a trace is by passing a metadata
dictionary to the langwatch.trace()
decorator or context manager.
In this example, user_id
and session_id
are attached to the “UserQueryHandler” trace from the start. Later, query_language
is added.
Refer to the langwatch.trace()
API reference for more details on its parameters.
If you need to add or modify trace metadata after the trace has started (e.g., based on some intermediate result), you can use the update()
method on the LangWatchTrace
object.
You can get the current trace object using langwatch.get_current_trace()
or from the langwatch.trace()
context manager.
Span attributes (often referred to simply as “attributes”) provide context for a specific operation or unit of work within a trace. They are useful for details that are relevant only to that particular step. Examples include:
model_name
, prompt_template_version
, temperature
tool_name
, api_endpoint
, specific input parametersretrieved_document_ids
, chunk_count
You can set attributes on a span when it’s created using the attributes
parameter (less common for dynamic values) or, more typically, by calling the update()
method on the LangWatchSpan
object.
The update()
method is flexible and allows you to pass attributes as keyword arguments.
In the first example, source
, query_complexity
, and items_retrieved
are added to the “FetchResearchData” span. Similarly, model
, prompt_length
, output_length
, and tokens_used
contextualize the “GenerateText” LLM span.
The LangWatchSpan
object also has a set_attributes()
method which takes a dictionary, similar to OpenTelemetry’s underlying span API.
For more details on span parameters and methods, see the langwatch.span()
API reference and the LangWatchSpan
object methods.
Feature | Trace Metadata | Span Attributes |
---|---|---|
Scope | Entire trace (e.g., a whole user request) | Specific span (e.g., one LLM call, one tool use) |
Granularity | Coarse-grained, applies to the overall operation | Fine-grained, applies to a specific part of the operation |
Purpose | General context for the entire operation | Specific details about a particular step or action |
Examples | user_id , session_id , app_version | model_name , tool_parameters , retrieved_chunk_id |
SDK Access | langwatch.trace(metadata={...}) trace.update(metadata={...}) | langwatch.span(attributes={...}) span.update(key=value, ...) span.set_attributes({...}) |
When to use which:
All captured trace metadata and span attributes will be visible in the LangWatch UI.
This rich contextual data allows you to:
user_id
s or model_name
s).Effectively using trace metadata and span attributes is crucial for maximizing the observability of your LLM applications. By enriching your traces with relevant contextual information, you empower yourself to better understand, debug, and optimize your systems with LangWatch.
Remember to instrument your code thoughtfully, adding data that provides meaningful insights without being overly verbose.