Set key:value tags from your Python application so the spans it records carry labels you can filter by in AIO.
Prerequisites
- Your application sends traces with the Python SDK. If it doesn't yet, see Instrument your code.
- Your application calls
aio.initbefore it starts recording spans.aio.initsets up the tagging, so spans started before it runs don't get tags.
The SDK package is acceldata_aio_tracer, and the examples on this page import it as aio. For what tags are and where they come from, see Tags overview.
Set the tags for a unit of work
Use aio.set_tags to set the tags for everything your code does from that point on in the current context.
- Call
aio.set_tagswith one or morekey:valuestrings. Call it insideaio.root_spanor before it, so the whole unit of work gets the tags. - To change the tags later, call
aio.set_tagsagain with the full new set. Each call replaces the tags already set. It doesn't add to them. - To clear the tags, call
aio.set_tags()with no arguments.
import acceldata_aio_tracer as aio
aio.set_tags("region:eu", "tier:gold")
print(aio.current_tags()) # region:eu and tier:gold
aio.set_tags("region:us")
print(aio.current_tags()) # only region:us: the earlier tags are replaced
aio.set_tags()
print(aio.current_tags()) # empty: no tags are set
Add tags for a block of code
Use aio.using_tags to add tags for one block of code. It adds them to any tags already set, and when the block ends, the earlier tags come back. Nested blocks combine their tags, and tags from an inner block don't leak out of it.
- Use it as a context manager:
```python
import acceldata_aio_tracer as aio
aio.set_tags("region:eu")
with aio.using_tags("workflow:nightly"):
print(aio.current_tags()) # region:eu and workflow:nightly
with aio.using_tags("step:summarize"):
print(aio.current_tags()) # region:eu, workflow:nightly, and step:summarize
print(aio.current_tags()) # back to region:eu
```
- Use it as a decorator on a regular function or an
asyncfunction:
```python
import asyncio
import acceldata_aio_tracer as aio
@aio.using_tags("workflow:nightly")
async def run_nightly():
print(aio.current_tags()) # workflow:nightly
@aio.using_tags("workflow:report")
def build_report():
print(aio.current_tags()) # workflow:report
asyncio.run(run_nightly())
build_report()
```
aio.using_tags needs at least one tag, and it can't decorate a generator. For both errors, see Troubleshooting.
Check which tags are set
Call aio.current_tags() to get the tuple of tags that a span started now would get. When no tags are set, it returns an empty tuple, ().
Which spans and log records carry the tags
- Spans: Every span that starts while tags are set gets them. The SDK adds the tags when the span starts, so changing the tags afterward doesn't change a span that's already running.
- Log records: Every log record your application emits while tags are set gets the same tags.
- No tags set: When no tags are set, the SDK adds nothing.
The tags belong to the current context, not to the whole process. Tags apply only where you set them, and there's no default set of tags for the process. asyncio copies the current context into each task it starts, so tags you set before an await reach every span that the unit of work creates.
In AIO, the tags your code sets combine with any tags the project makes from span attributes, and duplicates are removed. For those tags, see Turn span attributes into tags.
Tag format and validation
Each tag is a single string in the form key:value, for example region:eu. The SDK checks each tag when you call aio.set_tags and when an aio.using_tags block opens.
A bad tag never raises an error. The SDK drops it and logs a warning on the acceldata_aio_tracer._tags logger. Your code keeps running, and the valid tags still apply.
The following table lists what the SDK drops and the warning each case logs.
| Tag | What happens | Warning |
|---|---|---|
Not a string, for example 42 |
Dropped | aio: tag 42 is not a string, dropped |
No colon, an empty key (colon first), or an empty value (colon last), for example region |
Dropped | aio: tag 'region' must be 'key:value' with both sides nonblank, dropped |
| Longer than 200 characters | Dropped, not shortened | aio: tag '<your tag>' exceeds 200 characters, dropped |
| An exact duplicate of another tag | Dropped | None |
| More than 32 tags left after the other checks, for example 40 | The first 32 are kept | aio: 40 tags given, only the first 32 are kept (the server's own limit) |
Tip: If tags you set don't show in AIO, turn on warnings for the
acceldata_aio_tracer._tagslogger to see which tags were dropped and why.
Troubleshooting
using_tags() requires at least one tag
aio.using_tags() raises TypeError("using_tags() requires at least one tag") when you call it with no tags. Pass at least one key:value string. To clear the tags instead, call aio.set_tags() with no arguments.
@using_tags cannot cover a generator
Decorating a generator or an async generator with @aio.using_tags raises TypeError("@using_tags cannot cover a generator; usewith aio.using_tags(...):inside it"). Remove the decorator and put a with aio.using_tags(...): block inside the generator instead.

Have a suggestion?