Capturing Metadata and Attributes
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:
- Trace Metadata: Information that applies to the entire lifecycle of a request or a complete operation.
- Span Attributes: Information specific to a particular unit of work or step within a trace.
This tutorial will guide you through capturing both types using the Python SDK.
Trace Metadata
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 identifiers (
user_id
) - Session or conversation identifiers (
session_id
,thread_id
) - Application version (
app_version
) - Environment (
env: "production"
) - A/B testing flags or variant names
You can set trace metadata when a trace is initiated or update it at any point while the trace is active.
Setting Trace Metadata at Initialization
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.
Updating Trace Metadata Dynamically
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
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:
- For an LLM call span:
model_name
,prompt_template_version
,temperature
- For a tool call span:
tool_name
,api_endpoint
, specific input parameters - For a RAG span:
retrieved_document_ids
,chunk_count
- Custom business logic flags or intermediate results specific to that span.
Setting Span Attributes
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.
Key Differences: Trace Metadata vs. Span Attributes
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:
- Use Trace Metadata for information that you’d want to associate with every single span within that trace, or that defines the overarching context of the request (e.g., who initiated it, what version of the service is running).
- Use Span Attributes for details specific to the execution of that particular span. This helps in understanding the parameters, behavior, and outcome of individual components within your trace.
Viewing in LangWatch
All captured trace metadata and span attributes will be visible in the LangWatch UI.
- Trace Metadata is typically displayed in the trace details view, providing an overview of the entire operation.
- Span Attributes are shown when you inspect individual spans within a trace.
This rich contextual data allows you to:
- Filter and search for traces and spans based on specific metadata or attribute values.
- Analyze performance by correlating metrics with different metadata/attributes (e.g., comparing latencies for different
user_id
s ormodel_name
s). - Debug issues by quickly understanding the context and parameters of a failed or slow operation.
Conclusion
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.