​
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
Metadata is key-value information that is attached to an entire trace, as opposed to individual spans.

​
Adding Metadata to Traces

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
  },
);
Alternatively, you can add metadata directly in the 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.
❌ Incorrect usage (will not work):
// 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
});
✅ Correct usage:
await observe({ name: 'myFunction' }, async () => {
  // Set metadata inside the span context
  Laminar.setTraceMetadata({ environment: 'production' });
  // Your code here
});
Any new call to set metadata will overwrite the previous metadata.
❌ 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' });
});
✅ Correct usage:
await observe({ name: 'myFunction' }, async () => {
  Laminar.setTraceMetadata({
    environment: 'production',
    region: 'us-west'
  });
});

​
Common Metadata Use Cases

​
Environment Information

Laminar.setTraceMetadata({
    environment: 'production', // or 'staging', 'development', etc.
    region: 'us-west',
    deploymentId: 'deploy-123'
});

​
Performance Tracking

Laminar.setTraceMetadata({
    batchSize: 128,
    optimizerVersion: 'v2',
    modelVariant: 'high-performance'
});

​
A/B Testing

Laminar.setTraceMetadata({
    experimentId: 'exp-456',
    variant: 'treatment-B',
    cohort: 'new-users'
});

​
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 with 
{
    "metadata": {
        "userId": "123",
        "region": "us-west"
    }
}
can be matched by searching for userId=123 or region=us-west.
  1. Go to the Traces/Spans page
  2. Add a metadata filter and fill in the key and value
In the example below, we filter by userId key of the metadata: Filter by metadata

​
Metadata vs Tags

Adding metadata to a trace is different from adding tags to a span:
MetadataTags
ScopeApplies to entire traceApplies to individual spans
PurposeGeneral trace contextSpecific span classification
ValidationAny string key-value pairsAny string
UI LocationShown in trace overviewShown in individual span details
Common UsesEnvironment info, user contextData categories, tags
To learn more about tags, see tags.

​
Best Practices

  1. Consistent Keys: Use consistent key names across your application
  2. Avoid Sensitive Data: Don’t include PII or sensitive data in metadata
  3. Keep It Lightweight: Only include metadata that adds meaningful context
  4. Standardize Values: Use consistent formats and enumerations for values