Acceldata
AIO

Last updated: Nov 17, 2026 16:54 UTC

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.init before it starts recording spans. aio.init sets 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.

  1. Call aio.set_tags with one or more key:value strings. Call it inside aio.root_span or before it, so the whole unit of work gets the tags.
  2. To change the tags later, call aio.set_tags again with the full new set. Each call replaces the tags already set. It doesn't add to them.
  3. 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 async function:

```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._tags logger 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.

Next steps