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
Metadata is key-value information that is attached to an entire trace, as opposed to individual spans.
JavaScript/TypeScript
Python
Use the Laminar.setTraceMetadata inside a span context to add metadata to the trace:import { Laminar, observe } from '@lmnr-ai/lmnr';
await observe(
{
name: 'processRequest',
},
async () => {
Laminar.setTraceMetadata({
environment: 'production',
featureFlag: 'new-algorithm-v2',
region: 'us-west'
});
// ...rest of your code here
},
);
observe function:import { observe } from '@lmnr-ai/lmnr';
await observe({
name: 'processRequest',
metadata: {
environment: 'production',
featureFlag: 'new-algorithm-v2'
}
}, async () => {
// Your code here
});
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.
// This won't work because it's outside any span context
Laminar.setTraceMetadata({ environment: 'production' });
await observe({ name: 'myFunction' }, async () => {
// The metadata set above won't be applied here
});
await observe({ name: 'myFunction' }, async () => {
// Set metadata inside the span context
Laminar.setTraceMetadata({ environment: 'production' });
// Your code here
});
In Python, there are two recommended ways to add metadata, but both must be done within a span context:Using set_trace_metadata within a span context
from lmnr import Laminar, observe
@observe()
def my_function():
# IMPORTANT: set_metadata must be called within an active span context
# Here, the @observe decorator creates that context
Laminar.set_trace_metadata({
'environment': 'production',
'feature_flag': 'new-algorithm-v2',
'region': 'us-west'
})
# your code here
Laminar.set_trace_metadata() must be called within an active span context (such as within a function decorated with @observe() or inside a Laminar.start_as_current_span block). If called outside of any span context, it will have no effect.
Passing directly to observe
from lmnr import Laminar
# Note that this is static, i.e. you can't change this at runtime.
@observe(metadata={
'environment': 'production',
'feature_flag': 'new-algorithm-v2'
})
def process_request():
# Your code here
pass
# This won't work because it's outside any span context
Laminar.set_trace_metadata({'environment': 'production'})
@observe()
def my_function():
# The metadata set above won't be applied here
pass
@observe()
def my_function():
# Set metadata inside the span context
Laminar.set_trace_metadata({'environment': 'production'})
# Your code here
Any new call to set metadata will overwrite the previous metadata.
JavaScript/TypeScript
Python
❌ Incorrect usage:await observe({ name: 'myFunction' }, async () => {
Laminar.setTraceMetadata({ environment: 'production' });
// This will overwrite the previous metadata including the environment
Laminar.setTraceMetadata({ region: 'us-west' });
});
await observe({ name: 'myFunction' }, async () => {
Laminar.setTraceMetadata({
environment: 'production',
region: 'us-west'
});
});
❌ Incorrect usage:@observe()
def my_function():
Laminar.set_trace_metadata({'environment': 'production'})
# This will overwrite the previous metadata including the environment
Laminar.set_trace_metadata({'region': 'us-west'})
@observe()
def my_function():
Laminar.set_trace_metadata({
'environment': 'production',
'region': 'us-west'
})
JavaScript/TypeScript
Python
Laminar.setTraceMetadata({
environment: 'production', // or 'staging', 'development', etc.
region: 'us-west',
deploymentId: 'deploy-123'
});
@observe()
def my_function():
Laminar.set_trace_metadata({
'environment': 'production', # or 'staging', 'development', etc.
'region': 'us-west',
'deployment_id': 'deploy-123'
})
# Your code here
JavaScript/TypeScript
Python
Laminar.setTraceMetadata({
batchSize: 128,
optimizerVersion: 'v2',
modelVariant: 'high-performance'
});
@observe()
def my_function():
Laminar.set_trace_metadata({
'batch_size': 128,
'optimizer_version': 'v2',
'model_variant': 'high-performance'
})
# Your code here
A/B Testing
JavaScript/TypeScript
Python
Laminar.setTraceMetadata({
experimentId: 'exp-456',
variant: 'treatment-B',
cohort: 'new-users'
});
@observe()
def experiment_handler():
Laminar.set_trace_metadata({
'experiment_id': 'exp-456',
'variant': 'treatment-B',
'cohort': 'new-users'
})
# Your experiment code here
{
"metadata": {
"userId": "123",
"region": "us-west"
}
}
userId=123 or region=us-west.
- Go to the Traces/Spans page
- Add a metadata filter and fill in the key and value
In the example below, we filter by userId key of the metadata:
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
