What is Trace Metadata?
Metadata provides additional context to your traces beyond the basic trace information. It helps you:- Filter and search for specific traces
- Add business context to technical traces
- Group related traces together
- Categorize traces by environment, feature, or user segment
Adding Metadata to Traces
- JavaScript/TypeScript
- Python
Use the Alternatively, you can add metadata directly in the ❌ Incorrect usage (will not work):✅ Correct usage:
Laminar.setTraceMetadata
inside a span context to add metadata to the trace:observe
function:Laminar.setTraceMetadata()
must be called within an active span context (such as within an observe
function call). If called outside of any span context, it will have no effect.Any new call to set metadata will overwrite the previous metadata.
- JavaScript/TypeScript
- Python
❌ Incorrect usage:✅ Correct usage:
Common Metadata Use Cases
Environment Information
- JavaScript/TypeScript
- Python
Performance Tracking
- JavaScript/TypeScript
- Python
A/B Testing
- JavaScript/TypeScript
- Python
Filtering Traces by Metadata
You can filter traces by metadata in the Laminar UI. Currently, we only support exact key-value matches, e.g. a trace withuserId=123
or region=us-west
.
- Go to the Traces/Spans page
- Add a metadata filter and fill in the key and value
userId
key of the metadata:

Metadata vs Tags
Adding metadata to a trace is different from adding tags to a span:Metadata | Tags | |
---|---|---|
Scope | Applies to entire trace | Applies to individual spans |
Purpose | General trace context | Specific span classification |
Validation | Any string key-value pairs | Any string |
UI Location | Shown in trace overview | Shown in individual span details |
Common Uses | Environment info, user context | Data categories, tags |
Best Practices
- Consistent Keys: Use consistent key names across your application
- Avoid Sensitive Data: Don’t include PII or sensitive data in metadata
- Keep It Lightweight: Only include metadata that adds meaningful context
- Standardize Values: Use consistent formats and enumerations for values