> ## Documentation Index
> Fetch the complete documentation index at: https://tracevell.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tags

## Overview

Tags are string identifiers that you can attach to **spans**. They’re useful for categorization and filtering:

* Filter traces/spans in the UI (for example, "show all traces tagged `beta-feature`")
* Group traces for aggregate analysis
* Mark traces for review (for example, `needs-review`, `regression`)

You can add tags to a span when it’s created, from inside its span context, or post-hoc after a trace finishes.

Tags are different from metadata: tags are strings on spans; metadata is key-value context on the trace. See [Metadata](https://tracevell.com/docs/tracing/structure/metadata.md) for a detailed comparison.

In the Tracevell UI, you pick from the tags your project already has, or create a new one while tagging a span.

## 1. Adding tags to a span when it is created

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

### Example: Tagging a manual span

This is a dynamic way to tag a span: decide which tags to apply at runtime when you create it.

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Tracevell } from '@lmnr-ai/lmnr';
>
> const span = Laminar.startSpan({
>   name: 'foo',
>   tags: ['my_tag', 'another_tag'],
> });
>
> try {
>   await Laminar.withSpan(span, async () => {
>     // your code here
>   });
> } finally {
>   span.end();
> }
> ```
>
> See also: [`Laminar.startSpan`](https://tracevell.com/docs/sdk/manual-spans#ts-tracevell-start-span) and [`Laminar.withSpan`](https://tracevell.com/docs/sdk/manual-spans#ts-tracevell-with-span).

> [tab] Python
>
> ```python theme={null}
> from lmnr import Tracevell, use_span
>
> span = Laminar.start_span(
>     name="foo",
>     tags=["my_tag", "another_tag"],
> )
> try:
>     with use_span(span):
>         # your code here
>         pass
> finally:
>     span.end()
> ```
>
> See also: [`Laminar.start_span`](https://tracevell.com/docs/sdk/manual-spans#py-tracevell-start-span) and [`use_span()`](https://tracevell.com/docs/sdk/manual-spans#py-tracevell-with-span).

Note that only the span created by this `startSpan` / `start_span` call will have the tags—child spans don’t inherit tags automatically.

### Example: Tagging an observed function

This is a static way to tag a span: the observed function will always have the same set of tags.

> [tab] TypeScript
>
> ```typescript theme={null}
> import { observe } from '@lmnr-ai/lmnr';
>
> await observe(
>   {
>     name: 'foo',
>     tags: ['my_tag', 'another_tag'],
>   },
>   async (message: string) => {
>     // your code here
>   },
>   'Hello, world!'
> );
> ```
>
> See also: [`observe(options, fn, ...args)`](https://tracevell.com/docs/sdk/observe#ts-observe).

> [tab] Python
>
> ```python theme={null}
> from lmnr import observe
>
> @observe(name="foo", tags=["my_tag", "another_tag"])
> def foo(message: str):
>     # your code here
>     pass
>
> foo("Hello, world!")
> ```
>
> See also: [`@observe()`](https://tracevell.com/docs/sdk/observe#py-observe).

### Example: Tagging any span from within its context

For adding span tags to work, you must call it inside a span context (for example, inside `observe()` / an `@observe`d function).

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Tracevell, observe } from '@lmnr-ai/lmnr';
>
> async function foo(message: string) {
>   if (message.length > 100) {
>     // ✅ Correct usage. We are inside a span context.
>     Laminar.setSpanTags(['long_input']);
>   }
> }
>
> // ❌ Incorrect usage. We are not inside any span context. This will not work.
> // Laminar.setSpanTags(['my_tag', 'another_tag']);
>
> await observe({ name: 'foo' }, foo, 'a'.repeat(200));
> ```
>
> See also: [`Laminar.setSpanTags`](https://tracevell.com/docs/sdk/span-methods#ts-tracevell-set-span-tags) and [`observe(options, fn, ...args)`](https://tracevell.com/docs/sdk/observe#ts-observe).

> [tab] Python
>
> ```python theme={null}
> from lmnr import Tracevell, observe
>
> @observe(name="foo")
> def foo(message: str):
>     if len(message) > 100:
>         # ✅ Correct usage. We are inside a span context.
>         Laminar.add_span_tags(["long_input"])
>
> # ❌ Incorrect usage. We are not inside any span context. This will not work.
> # Laminar.add_span_tags(["my_tag", "another_tag"])
>
> foo("a" * 200)
> ```
>
> See also: [`Laminar.add_span_tags`](https://tracevell.com/docs/sdk/span-methods#py-tracevell-add-span-tags) and [`@observe()`](https://tracevell.com/docs/sdk/observe#py-observe).

## 2. Adding tags to a span once it is created

This is useful for incorporating user feedback into a trace for further analysis.

### 2.1. Tagging in the Tracevell UI

Once you’ve created and sent a trace to Tracevell, you can add tags to spans in the Tracevell UI.

* Open a trace (in **Traces**) or a span (in **Spans**).
* Select the span you want to tag.
* Click **Tags**, then select existing tags (or type a new name to create one).

![Adding tags to a span in the Tracevell UI](https://mintcdn.com/laminarai/pKM35iraOOzRKwfP/images/add-tag.png?fit=max\&auto=format\&n=pKM35iraOOzRKwfP\&q=85\&s=efcd89144d70c11925b6c77407f3d576)

Tagging in the Tracevell UI

### 2.2. Tagging in the Tracevell SDK

You can also add tags to a completed trace in the Tracevell SDK using `LaminarClient.tags.tag`. This adds tags to the top-level (root) span of the trace.

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Tracevell, LaminarClient, observe } from '@lmnr-ai/lmnr';
>
> const laminarClient = new LaminarClient();
>
> // Take note of the traceId.
> const { traceId } = await observe({ name: 'chat_completion' }, async () => {
>   return {
>     // ✅ Correct usage. We are inside a span context,
>     // so `getTraceId` returns a string UUID.
>     traceId: Laminar.getTraceId(),
>   };
> });
>
> await Laminar.flush();
>
> // Call this later, when you get user feedback.
> const userFeedbackHandler = (traceId: string, userFeedback: 'good' | 'bad') =>
>   laminarClient.tags.tag(traceId, userFeedback);
> ```
>
> See also: [`client.tags.tag(traceId, tags)`](https://tracevell.com/docs/sdk/client#ts-client-tags-tag).

> [tab] Python
>
> ```python theme={null}
> from lmnr import Tracevell, LaminarClient, observe
>
> laminar_client = LaminarClient()
>
> # Take note of the trace_id.
> @observe(name="chat_completion")
> def chat_completion():
>     return Laminar.get_trace_id()
>
> trace_id = chat_completion()
> Laminar.flush()
>
> # Call this later, when you get user feedback.
> def user_feedback_handler(trace_id: str, user_feedback: str):
>     laminar_client.tags.tag(trace_id, user_feedback)
> ```
>
> See also: [`client.tags.tag(trace_id, tags)`](https://tracevell.com/docs/sdk/client#py-client-tags-tag).

Make sure to call `Laminar.getTraceId()` / `Laminar.get_trace_id()` inside a span context. Outside, it returns `null` / `None`.

## Viewing tags

The tags will be visible in the Tracevell UI, shown on each span as shields.

![Span tags displayed as shields in the Tracevell UI](https://mintcdn.com/laminarai/RPYdoMdfsv6y-QUL/images/traces/tags-example.png?fit=max\&auto=format\&n=RPYdoMdfsv6y-QUL\&q=85\&s=4577ec587eb8a8e8dab4e83bf86c5f56)

Tags in the Tracevell UI

## Filtering by span tags

In the **Traces** view and the **Spans** view, you can filter by span tags.

Simply add a “Tags” filter and type the name of the tag you want to include.

![Adding a tag filter](https://mintcdn.com/laminarai/RPYdoMdfsv6y-QUL/images/traces/tags-add-filter.png?fit=max\&auto=format\&n=RPYdoMdfsv6y-QUL\&q=85\&s=e86bc6712870e68aad9fd2d289371c98)

![Filtered traces](https://mintcdn.com/laminarai/RPYdoMdfsv6y-QUL/images/traces/tags-filtered.png?fit=max\&auto=format\&n=RPYdoMdfsv6y-QUL\&q=85\&s=310fb5896b6041225d8f11d0821cbfe1)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.