Skip to main content
Trace metadata applies to the entire trace. Use it for information that’s constant across spans:
  • Environment — production, staging, development
  • Region — us-west, eu-central
  • Deployment — version numbers, feature flags, A/B test variants
  • Request context — correlation IDs, upstream service info
Set metadata early—ideally where the trace begins—so all spans share the same context.

​
Adding Metadata

Set metadata inside an active span context (for example, inside observe() or an @observed function). If you call it outside any span context, it won’t attach to anything. 
import { Laminar, observe } from '@lmnr-ai/lmnr';

await observe({ name: 'processRequest' }, async () => {
  Laminar.setTraceMetadata({
    environment: 'production',
    featureFlag: 'new-algorithm-v2',
    region: 'us-west',
  });
});
See also: Laminar.setTraceMetadata and observe(..., { metadata })

​
Notes

  • Trace metadata is merged as spans arrive. If multiple spans set the same key, the last span processed wins (order is not guaranteed), so values can change while a trace is still ingesting.
  • Set each metadata key in one place per trace (ideally the root span) and avoid duplicate keys in nested observe(...) calls or AI SDK telemetry.
  • Keep metadata JSON-serializable and avoid sensitive data.

​
Filtering by Metadata

In the Laminar UI, metadata filters currently match exact key-value pairs (for example, region=us-west).
If a trace seems to appear in results while it’s running and then disappears after it finishes, check whether the same metadata key is being set by multiple spans. Because metadata is merged on ingestion, the final value can change as more spans arrive, which can flip whether a trace matches a filter.

​
Metadata vs Tags

MetadataTags
ScopeEntire traceIndividual spans
FormatKey-value pairsString labels
Best forEnvironment, cohort, request contextCategorization, review labels

​
Best Practices

  • Use consistent keys (environment, region, feature_flag).
  • Use environment for prod/staging/dev; add a low-cardinality key like developer or source to separate dev traces in a shared project.
  • Keep it lightweight and JSON-serializable.
  • Avoid sensitive data (no PII).