This page explains what tags are, where they come from, which ones you can change, and where you see and filter them in AIO.
A tag is a label in the form key:value, for example region:eu, that you attach to traces, sessions, and spans. Tags let you group and find your data by what matters to you, such as a region, a workflow, or a reviewer. Then you can narrow the Traces, Sessions, and Spans lists to the rows that carry a tag, or leave them out.
Where tags come from
Tags come from three sources. All three work the same way when you filter, but only tags added by hand can be changed in the UI.
| Source | How it's set | Change it in the UI |
|---|---|---|
| Set in code | Your application calls aio.set_tags or aio.using_tags from the Python SDK. Every span started while the tags are set carries them. |
No |
| Derived from span attributes | A project's Attribute Tags settings turn chosen span attribute keys into tags. Each new span with that attribute gets the tag <attribute key>:<attribute value>, for example deployment:prod. |
No. Turning a key off stops new spans from getting the tag, but tags already stored stay. |
| Added by hand | A user who can change the project adds a tag on a trace, session, or span page. | Yes. You can add and remove these tags. |
Tags set in code and tags derived from span attributes are written when AIO receives the span, so they're read-only. Attribute tags apply only to spans that arrive after the key is turned on. Spans recorded earlier don't get them.
A tag added by hand belongs to the one trace, session, or span you add it to. A tag added to a span doesn't appear on its trace or session, and a tag added to a trace or session doesn't appear on its spans.
How it works

- Your code tags spans. When your application sets tags with the Python SDK, the SDK adds them to every span it starts while the tags are set. For details, see Tag traces in code.
- AIO adds attribute tags. When a span arrives with an attribute key that the project has turned on, AIO adds a tag made from that attribute's key and value. For details, see Turn span attributes into tags.
- People add tags by hand. On a trace, session, or span page, a user who can change the project selects Add tag to add tags, and removes them from the same place. For details, see Add tags by hand.
- Tags show as chips. The trace page, the session page, and the span pane show a row of tag chips:
- The trace page shows the tags from all of the trace's spans, plus the tags added by hand to the trace.
- The session page shows the tags from all of the session's spans, plus the tags added by hand to the session.
- The span pane shows only that span's own tags.
Chips for tags added by hand come first, followed by chips for tags from code and span attributes.

- You filter lists by tag. The Tags control in the filter bar of the Traces, Sessions, and Spans lists lets you show only rows that have any of the tags you choose, or exclude rows that have them. For details, see Filter by tags.
Anyone who can view a project can see its tags and filter by them. Adding and removing tags by hand, and turning attribute keys on or off, need permission to change the project. For details, see Project permissions.

Have a suggestion?