Skip to main content

acceldata-aio-tracer

The Acceldata AIO instrumentation SDK. OpenTelemetry-native: it does not replace your instrumentation, it completes it.

Installation

pip install acceldata-aio-tracer

Requires Python 3.10 or newer. FastAPI and httpx instrumentation ship as an optional extra:

pip install 'acceldata-aio-tracer[http]'

Quickstart

import acceldata_aio_tracer as aio

aio.init(
    service="my-app",
    tenant_id="...",
    project_id="...",
    endpoint="https://aio.example.com",
    access_key="...",
    secret_key="...",
)

with aio.root_span(conversation_id=conversation_id, input_preview=user_message):
    ...   # model calls, tools, MCP, outbound HTTP

That is the whole integration. init() runs once at startup, before you build any client; root_span() wraps each unit of work.

tenant_id must be nonblank. It is a claim rather than proof: the Collector checks it against the identity its gateway authenticated, and overwrites it from there.

Endpoints

endpoint is the AIO server. Telemetry goes to that same host unless you say otherwise, so a second endpoint is only needed when the Collector lives somewhere else:

aio.init(
    ...,
    endpoint="https://aio.example.com",
    aio_collector_endpoint="https://collector.example.com",
)

Both fall back to the environment when the argument is omitted — AIO_ENDPOINT and AIO_COLLECTOR_ENDPOINT — and the standard OTEL_EXPORTER_OTLP_ENDPOINT is honoured for the Collector as well.

Selecting a project

Pass exactly one selector. When the UUID is known, project_id is used unchanged and the SDK makes no request to the server.

Otherwise pass the name and let the SDK resolve it:

aio.init(
    service="my-app",
    tenant_id="...",
    project_name="customer-facing-agent",
    endpoint="https://aio.example.com",
    access_key="...",
    secret_key="...",
)

The name is matched exactly, and a project that does not exist is created as Acceldata-hosted, with 60-day retention and the description "Auto created by SDK". Two processes racing to create the same name is safe: the loser adopts the winner's project. Whether a project is one you may write to — its status, its type — is the server's decision, so the SDK does not second-guess it.

When a name cannot be resolved, whether from a failed lookup, a refused create, or a malformed or ambiguous response, init() returns False and the application runs without telemetry.

What it does

Gives a turn a root. Chat transports like socket.io have no server span, so without a root the model call, each tool call, each MCP handshake and every outbound HTTP request start their own disconnected trace. root_span() opens one span they all nest under, so a user's question is one trace.

Puts the conversation id on every span. Instrumentation libraries tag the spans they own and leave the rest bare. Measured on one application, 2 of 8 instrumentation scopes carried the id, and the untagged spans held over a million tokens — so per-conversation totals were wrong by 15%. This SDK holds the id for the duration of the turn and stamps it on every span started inside, whichever library produced it. An id a library set for itself does not survive that: the open conversation is the one that reaches ingest.

Carries the user's message even when the turn fails. The preview is set when the turn opens, not when it completes, so a request that dies before the first model call still shows what was asked.

What to wrap

root_span() marks a unit of work the application knows the boundaries of and instrumentation cannot infer. A chat turn is one. So is a workflow run:

with aio.root_span(conversation_id=f"{instance_id}:{session_id}", name="workflow_run"):
    ...

Call it once per unit of work, not once per span — it is not a replacement for tracer.start_as_current_span(). name becomes a low-cardinality column, so keep it a fixed label and never interpolate an id into it.

Pass user_id when a turn belongs to a particular person. It rides every span in the unit of work alongside the conversation id, so usage and cost can be attributed per user.

Tags

A tag is a "key:value" label the application already knows when the turn starts — "escalated:yes", "region:eu". It uses the same context-variable mechanism as the conversation id: set it for a unit of work and it is stamped on every span started inside, whichever library produced the span. There is no process-wide default. A tag belongs to the work, not to the process.

using_tags is the usual call. It adds to whatever an enclosing scope already set, and restores that outer set on exit — as a context manager or as a decorator on a sync or async function:

with aio.root_span(conversation_id=conversation_id):
    with aio.using_tags("region:eu"):
        ...
@aio.using_tags("workflow:nightly")
def run_nightly():
    ...

set_tags replaces the set rather than adding to it. set_tags() with no arguments clears. Use it when this turn's tags should not inherit.

Tags apply to spans started after they are set; they do not rewrite a span that is already open. A generator function cannot take @using_tags — use with inside it, the same restriction as redaction.

A tag must be "key:value" with both sides nonblank, and at most 200 characters. Duplicates are collapsed; at most 32 tags are kept. Anything that fails those rules is logged at warning and dropped, not raised, so a bad tag cannot break the application. Empty using_tags() is the exception: that is API misuse and raises TypeError. current_tags() returns what would be stamped on a span started now.

Instrumentation

Instrumentation for models, agents and MCP ships inside the package: init() activates whichever of those libraries is installed in your environment and skips the rest. The FastAPI and httpx layers are the one optional extra (see Installation), and the SDK works with none of them — you still get the root span and identity on whatever your application emits itself.

Call init() as early as possible in your process. Coverage for a client built beforehand depends on how that library's instrumentation attaches: most patch a shared class method and pick up existing instances on their next call, while a few — the FastAPI middleware in the [http] extra among them — attach at construction and only see clients built afterward. Calling init() first is always safe and never the wrong choice.

If your application already configures OpenTelemetry, the SDK adds itself to the existing provider rather than replacing it, and warns if that provider's resource carries no tenant.

Stability

Telemetry never breaks the application: every failure path is swallowed, and init() returns False rather than raising when it cannot start.

service, tenant_id, project_id and endpoint will not be renamed. project_name and aio_collector_endpoint are keyword-only, as are the other optional parameters; always pass them by name. set_tags, using_tags and current_tags are the public names for tags.

Upgrading to 1.0.0.dev2. endpoint used to mean the OTLP Collector and now means the AIO server. Where the two differ, move the old value to aio_collector_endpoint; otherwise project resolution is pointed at the Collector.

Troubleshooting

init() returned False and nothing is showing up. It needs a nonblank tenant_id and exactly one of project_id or project_name — passing both, or neither, is refused. The reason is logged at warning level rather than emitting telemetry under the wrong tenant.

Spans are missing tags. Tags are set on the unit of work, not by init(). Set them before the span starts; they do not rewrite a span that is already open.

Spans are missing tokens, tool calls, or model attributes. The client was possibly constructed before init() ran — see Instrumentation for which integrations that affects. Calling init() before constructing any client sidesteps the question entirely.

Calling init() from more than one place. It is idempotent — the second and later calls are no-ops that return True immediately — so it is safe to call from more than one entry point (a test fixture and the application, for example) without re-registering instrumentation.

License

Apache-2.0. The instrumentation layer is vendored from OpenLIT; UPSTREAM.md, included in the package, records exactly what was changed and why, per the license's attribution requirements.

Metadata

Release files for acceldata-aio-tracer 1.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for acceldata-aio-tracer 1.1.1
File Size Uploaded Provenance Actions
acceldata_aio_tracer-1.1.1.tar.gz 521.0 kB Without provenance Details for acceldata_aio_tracer-1.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for acceldata-aio-tracer 1.1.1
File Interpreter ABI Platform Actions
acceldata_aio_tracer-1.1.1-py3-none-any.whl Python 3 none any Details for acceldata_aio_tracer-1.1.1-py3-none-any.whl

Total release size: 1.2 MB

Release files / acceldata_aio_tracer-1.1.1.tar.gz

Download URL acceldata_aio_tracer-1.1.1.tar.gz
Size 521.0 kB
Tags Source
SHA-256 checksum
How to use checksums
4f3a099ce9c3f66e837f663eaf1750070544afef325b33667dc1fbe139bff0f8
BLAKE2b-256 checksum
How to use checksums
2e8cffd824595599be1485418909fe8be978f43a18f681f2a8e100328876360c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.4.1 CPython/3.14.2 Darwin/25.5.0

Release files / acceldata_aio_tracer-1.1.1-py3-none-any.whl

Download URL acceldata_aio_tracer-1.1.1-py3-none-any.whl
Size 711.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2793367214502a84c2b9bd030c9ca701cdd2aaef00e61156a76839f176936b4b
BLAKE2b-256 checksum
How to use checksums
6b252a301af2ccdf254abc2ff16e19f0d4f28346c4eb7a37804f8172d11b6f20
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.4.1 CPython/3.14.2 Darwin/25.5.0

Security for acceldata-aio-tracer 1.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page