Label your traces, sessions, and spans with key:value tags, then use those tags to find runs in the lists.
A tag is a key:value label, such as team:support. Tags come from three sources:
| Source | Where you set it | What carries the tag | Can you change it in the UI? |
|---|---|---|---|
| Code | The Python SDK, with set_tags or using_tags |
Spans started while the tags are open | No |
| Attribute | A project's Attribute Tags settings | Spans ingested after you turn on the attribute key | No |
| Manual | The trace page, the session page, or the span pane | Only the trace, session, or span you added it to | Yes |
The UI calls tags from code and from attributes ingest tags. Tags you add by hand are manual tags.
Prerequisites
- Your application sends traces to a project through the SDK. For setup, see Instrument your code.
- To turn attribute keys on or off, or to add and remove manual tags, you need permission to modify the project. For details, see Project permissions.
Tag traces in code
The SDK stamps the open tags on every span and log record started in the current context. There's no process-wide default, so open the tags where the work runs.
using_tags(*tags)adds tags to the ones already open and restores the outer tags when it exits. Use it as a context manager, or as a decorator on a sync or async function.set_tags(*tags)replaces the tags for the current context.current_tags()returns the tags that are open right now.
The following example tags each request with the feature it handles, and adds a customer tier inside the unit of work. It reads the connection values from the AIO_* environment variables.
import acceldata_aio_tracer as aio
aio.init(service="support-bot")
@aio.using_tags("feature:refunds")
def handle_message(conversation_id: str, question: str) -> str:
with aio.root_span(conversation_id, input_preview=question):
with aio.using_tags("customer_tier:gold"):
print(aio.current_tags())
return "Your refund is on its way."
if __name__ == "__main__":
handle_message("conv-1234", "Where is my refund?")
Follow these rules for tags you set in code:
- Write each tag as
"key:value", with text on both sides of the colon. - Keep each tag to 200 characters or fewer.
- Open no more than 32 tags at once. AIO also keeps at most 32 tags from code on each span.
- Duplicate tags are removed.
The SDK drops a tag that breaks these rules and logs a warning, for example:
aio: tag 42 is not a string, droppedaio: tag 'refunds' must be 'key:value' with both sides nonblank, droppedaio: tag 'note:…' exceeds 200 characters, droppedaio: 40 tags given, only the first 32 are kept (the server's own limit)
using_tags raises a TypeError in two cases:
- You call it with no tags:
using_tags() requires at least one tag. - You put it as a decorator on a generator. Inside the generator, use
with aio.using_tags(...):instead.
Once a span is stored, you can filter by its tags right away.
For the full function signatures, see Python SDK.
Turn a span attribute into a tag
Turn on an attribute key for a project, and every span ingested after that gets a {key}:{value} tag for that attribute. For example, turning on customer.tier tags a span that has customer.tier set to gold with customer.tier:gold.
- Go to the project's Attribute Tags settings page at
/projects/<your-project>/settings/attribute-tags. - In Search attributes, enter part of the attribute key. The search ignores case.
- In the key's row, under Enable, select the switch to turn it on.
The list reloads, and the count line shows how many keys are on, for example "3 of 20 enabled". To stop tagging new spans with an attribute, select its switch again to turn it off.
The table lists the keys that are on first. After them come up to 50 attribute keys seen on the project's spans in the last 24 hours, with the most frequent first. Spans, last 24h shows how many spans carried each key. It shows "—" for a key that's on but wasn't seen in that time.
Keep these points in mind:
- Only new spans change. Turning a key on or off affects only spans ingested from then on. Tags already stored stay.
- A project can have up to 20 keys on. At the limit, the switches for keys that are off are unavailable, with the tooltip "Limit of 20 reached. Turn one off to enable this."
- Long values are skipped. A value longer than 200 characters is dropped, not cut short.
You can't turn on these keys:
- Keys that start with
aio., because AIO already shows them in their own columns. - Large text attributes:
gen_ai.workflow.input,gen_ai.workflow.output,gen_ai.tool.call.arguments,gen_ai.tool.call.result,mcp.request.payload,mcp.response.payload,gen_ai.retrieval.documents,gen_ai.retrieval.query.text,gen_ai.system_instructions, andgen_ai.tool.definitions. - Keys that contain
,or|. - Keys that had 1,000 or more distinct values in the last 24 hours, since a tag with that many values isn't useful for filtering.
Keys rejected for their name don't appear in the list at all.
If you can view the project but can't modify it, the page shows only the keys that are on, with no search box and no switches. If no keys are on, it shows "None enabled."
Add a tag by hand
Add manual tags on a trace, a session, or a single span.
- Open the trace or session. To tag a span, select it in the waterfall to open the span pane. For how to find and open them, see Explore traces.
- Next to the tags, select Add tag. The Add tag dialog opens with one row that has a Key name and a Value.
- For Key name, choose an existing key, or enter a new key and select Add “team”.
- For Value, choose one or more values, or enter a new value and select Add “escalated”.
- To add another key, select Add row. To drop a row, select Remove row.
- Select Add. The button reads Add tag or Add 2 tags to match how many tags you're adding.
The chips reload with the new tags. A manual tag applies only to the item you added it to. A tag added to a span doesn't appear on its trace or session.
Each row needs a key and at least one value. A key can't contain :, and a value can be at most 200 characters. AIO trims spaces from both. If a tag fails, it stays in its row with the error, so selecting Add again sends only the tags that are left.
Remove a manual tag
- On the manual value's chip, select ✕. Its label reads, for example, "Remove team:escalated".
You can't remove tags that came from code or from an attribute key in the UI.
If you can't modify the project, the add and remove controls don't appear. An item with no tags shows "No tags".
See tags on a trace, session, or span
Tag chips appear on the trace page, the session page, and the span pane. Each chip shows one key with its values, such as "team: support, billing", followed by "+3" when more values exist.
- Manual chips come first and look different from ingest chips.
- A key with both manual and ingest values shows as two chips.
- Chips that don't fit on the first line collapse behind "+4 more". Select Show less to collapse them again.
On a trace or session, ingest chips show the tags on any of its spans. On a span, they show only that span's own tags.
Filter the lists by tags
The Traces, Sessions, and Spans lists each have a Tags filter. Choose a project first. The filter is hidden while the Rules filter is on.
- On the Traces, Sessions, or Spans tab, select Tags.
- In Search tags, enter part of a tag.
- Select the checkbox for each tag you want.
- To drop rows that have the chosen tags instead, select Exclude these. To switch back, select Match any of these.
The filter shows "All" when nothing is chosen, the tag when one is chosen, or a count such as "2 selected" or "excluding 2". To clear the filter, select Clear in the panel, or ✕ on the filter.
With no search, the panel suggests the 50 most recently seen tags. A search returns up to 20 tags that contain your text. Suggestions include tags from all three sources.
How the filter matches:
- A row matches if it has any of the chosen tags. No mode requires every chosen tag.
- Matching ignores case.
- Exclude mode drops every row that has any of the chosen tags.
What counts as a match depends on the list:
| List | A row matches when |
|---|---|
| Traces | Any span in the trace has the tag from code or an attribute, or the trace has the tag as a manual tag |
| Sessions | Any span in the session has the tag, or the session has the tag as a manual tag |
| Spans | The span itself has the tag. A tag on the parent trace doesn't match its spans |
The URL keeps the tag filter, for example ?tags=team:support,feature:refunds&tagMode=exclude, so a link you share opens the same view.

Have a suggestion?