Metadata

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
});

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
});

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

❌ Incorrect usage (will not work):

# 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

✅ Correct usage:

@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.

❌ 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'
  });
});

❌ 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'
  });
});

❌ 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'})

✅ Correct usage:

@observe()
def my_function():
    Laminar.set_trace_metadata({
        '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'
});

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

Performance Tracking

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

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

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

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

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.

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:

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

To learn more about tags, see 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

Overview

Tracing

Evaluations

Datasets

Labeling Queues

Playground

SQL Editor

What is Trace Metadata?

Adding Metadata to Traces

Using set_trace_metadata within a span context

Passing directly to `observe`

Common Metadata Use Cases

Environment Information

Performance Tracking

A/B Testing

Filtering Traces by Metadata

Metadata vs Tags

Best Practices

Overview

Tracing

Evaluations

Datasets

Labeling Queues

Playground

SQL Editor

​What is Trace Metadata?

​Adding Metadata to Traces

​Using set_trace_metadata within a span context

​Passing directly to observe

​Common Metadata Use Cases

​Environment Information

​Performance Tracking

​A/B Testing

​Filtering Traces by Metadata

​Metadata vs Tags

​Best Practices

What is Trace Metadata?

Adding Metadata to Traces

Using set_trace_metadata within a span context

Passing directly to `observe`

Common Metadata Use Cases

Environment Information

Performance Tracking

A/B Testing

Filtering Traces by Metadata

Metadata vs Tags

Best Practices