Sometimes you have some context prior to running a function and you want to label it at creation time. For example, you may want to tag a span with the model provider endpoint that you use, or the test dataset that you used to run the request.

Note that labels are not the same as metadata. Metadata is additional information about a trace in a form of key-value pairs. Labels are used to categorize and filter spans, and they must be created in the Laminar UI in advance. See metadata for a more detailed comparison.

1. Create a label class

First, you need to create a label class. This is required to define the label name and possible values. Label classes are created in the Laminar UI.

If you do not create a label class, the labels sent from code will not be saved.

2. Label spans from code

This functionality is available from v0.4.35.

Example 1. Labeling a span created with automatic instrumentation

from lmnr import Laminar

with Laminar.with_labels({"my_label": "my_value", "another_label": "value"}):
    openai_client.chat.completions.create(...)

Note that any spans created within the with_labels block will inherit the labels, including auto-instrumented spans or any calls to observed functions.

Example 2. Labeling a span created manually

with Laminar.start_as_current_span(name="foo", labels={"my_label": "value"}):
    # your code here
    pass

Note that only the span created by this Laminar.start_as_current_span call will have the labels.

Every label must have a string key and a string value. They must exactly match the name and possible values of the label class.

3. Viewing labels

The labels will be visible in the Laminar UI, in the “Labels” view of the span.

The only difference for these labels is that they will have CODE as their source.

Filter spans by labels

You can filter spans by labels in the Laminar UI. Go to the traces page and select the spans tab. Add a filter by label, and enter the name and value in the format label_name=label_value.