Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

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.

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.

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 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.0.0.dev5

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.0.0.dev5
File Size Uploaded Provenance Actions
acceldata_aio_tracer-1.0.0.dev5.tar.gz 508.5 kB Without provenance Details for acceldata_aio_tracer-1.0.0.dev5.tar.gz

Built distribution (wheel)

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

Total release size: 1.2 MB

Release files / acceldata_aio_tracer-1.0.0.dev5.tar.gz

Download URL acceldata_aio_tracer-1.0.0.dev5.tar.gz
Size 508.5 kB
Tags Source
SHA-256 checksum
How to use checksums
5ce2d05334feaf834055b7b13e5a5ddd45c9937e9d092555e58bbf817597ea61
BLAKE2b-256 checksum
How to use checksums
7d08d3cd07e778c6601287960ae05ca9c23dc92037cdcb2386cfd1472d305432
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.4.1 CPython/3.14.5 Darwin/25.5.0

Release files / acceldata_aio_tracer-1.0.0.dev5-py3-none-any.whl

Download URL acceldata_aio_tracer-1.0.0.dev5-py3-none-any.whl
Size 696.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cd6f22c3dc5c7d69df056c6d2a4cd0da4201ca22c8fa71444928862390b67aec
BLAKE2b-256 checksum
How to use checksums
3a3cf1e7bbcd17296b3e22ee399306a1da8ec159b80a632ac9787070f2033038
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.4.1 CPython/3.14.5 Darwin/25.5.0

Security for acceldata-aio-tracer 1.0.0.dev5

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