Acceldata
AIO

Last updated: Oct 06, 2026 15:41 UTC

Install the AIO Python SDK, point it at your project, and send your first trace to the AIO UI.

Prerequisites

  • Python 3.10 or later.
  • A project in AIO. To create one, see Create a project.
  • Your tenant ID. The SDK doesn't send anything without one. The Connection Info page for your project shows it.

Copy your connection values

  1. Go to the Connection Info page for your project. The same panel also appears right after you create a new project.

The Connection Info page, showing the Endpoint, Project ID, and Tenant ID values, each with a copy button, and the Generate API key button.

  1. Select Generate API key. The Access key and Secret key fields appear. Copy the secret key now, because the page doesn't show it again on a later visit. To learn more about keys, see Create an API key.
  2. Select Copy all. It's available only after you generate a key.
  3. Paste the copied lines into your application's .env file.

Copy all copies five lines in this order:

AIO_TENANT_ID=your-tenant-id
AIO_PROJECT_ID=00000000-0000-0000-0000-000000000000
AIO_ACCESS_KEY=YOUR_ACCESS_KEY
AIO_SECRET_KEY=YOUR_SECRET_KEY
AIO_ENDPOINT=https://aio.example.com/aio

To copy a single value, select the button next to it, such as Copy project ID or Copy tenant ID.

Install the SDK

  • In your application's environment, install the acceldata-aio-tracer package:
bash
  pip install acceldata-aio-tracer

To also instrument FastAPI and httpx, install the http extra instead:

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

To instrument database drivers that the SDK doesn't cover on its own, install the db extra. It adds instrumentation for DB-API, psycopg2, PyMySQL, MySQL Connector, asyncpg, aiopg, mysqlclient, and pymssql. You don't need it for psycopg (version 3), which the SDK covers already.

pip install "acceldata-aio-tracer[db]"

If a library isn't installed in your environment, the SDK skips its instrumentation.

Configure credentials

The SDK needs a tenant, exactly one project, and a collector endpoint. Pass them to aio.init() as arguments, or set them as environment variables. Explicit arguments take precedence over the environment.

Setting aio.init() argument Environment variable Notes
Tenant tenant_id AIO_TENANT_ID, or aio.tenant_id in OTEL_RESOURCE_ATTRIBUTES Required. Can't be blank.
Project project_id or project_name AIO_PROJECT_ID, or aio.project_id in OTEL_RESOURCE_ATTRIBUTES Set exactly one. project_id is the UUID you copied.
Collector endpoint aio_collector_endpoint AIO_COLLECTOR_ENDPOINT, then OTEL_EXPORTER_OTLP_ENDPOINT If neither is set, the SDK uses endpoint. Set it when the collector is on a different host or port.
AIO endpoint endpoint AIO_ENDPOINT The AIO server. Required when you use project_name.
Access key and secret key access_key and secret_key AIO_ACCESS_KEY and AIO_SECRET_KEY The SDK sends them only when you set both.
Service name service OTEL_SERVICE_NAME Defaults to unknown_service.
Environment environment AIO_ENVIRONMENT, or deployment.environment in OTEL_RESOURCE_ATTRIBUTES Defaults to default.

The SDK uses a project_id exactly as you give it and doesn't check that it's correct. Double-check that you pasted the right value.

If your process already has the variables from Copy all in its environment, call aio.init() without credential arguments, for example aio.init(service="support-bot").

Select a project by name

If you pass project_name instead of project_id, the SDK looks up the project in AIO when it starts:

  • If one project has exactly that name, the SDK uses it.
  • If no project has that name, the SDK creates one, with the description "Auto created by SDK".
  • If two or more projects have exactly that name, setup fails with the message duplicate exact project name.

For data retention settings, see Data retention.

Send a first trace

  1. Call aio.init() once when your application starts, before you create any HTTP or model clients. Clients you create earlier aren't traced.
  2. Wrap each unit of work in with aio.root_span(...), such as a chat turn, a workflow run, or a scheduled job.
  3. Run your application.

The following example sends one trace. In it, replace the tenant ID, project ID, endpoint, and keys with your own values.

import logging

import acceldata_aio_tracer as aio

logging.basicConfig(level=logging.INFO)


def answer(question: str) -> str:
    # Call your model client here.
    return f"You asked: {question}"


def main() -> None:
    started = aio.init(
        service="support-bot",
        tenant_id="your-tenant-id",
        project_id="00000000-0000-0000-0000-000000000000",
        aio_collector_endpoint="https://aio.example.com/your-collector-endpoint",
        access_key="YOUR_ACCESS_KEY",
        secret_key="YOUR_SECRET_KEY",
    )
    print("Telemetry running:", started)

    question = "How do I reset my password?"
    with aio.root_span("conversation-123", input_preview=question):
        print(answer(question))


if __name__ == "__main__":
    main()

When setup succeeds, aio.init() returns True and logs a line that starts with aio: telemetry enabled for support-bot. It also lists the tenant and project. Calling aio.init() a second time returns True and does nothing.

The first argument to aio.root_span() is the conversation ID that groups traces into a session. To learn more, see Track users and sessions.

Note: The SDK captures prompt and completion content. To withhold sensitive content before it leaves your application, see Redaction.

Check that the trace arrived

Spans reach AIO within a few seconds.

  1. Go to the Traces tab of your project.
  2. For Time, keep Last 24 hours, or choose a shorter range.
  3. Select Refresh.

Your trace appears at the top of the list. To read it, see Explore traces.

Instrument without code changes

The aio-instrument command runs your application with the SDK attached, so you don't have to edit your code. It reads the tenant, project, and endpoint from environment variables.

export OTEL_RESOURCE_ATTRIBUTES="aio.tenant_id=your-tenant-id,aio.project_id=00000000-0000-0000-0000-000000000000"
export AIO_COLLECTOR_ENDPOINT="https://aio.example.com/your-collector-endpoint"
export AIO_ACCESS_KEY="YOUR_ACCESS_KEY"
export AIO_SECRET_KEY="YOUR_SECRET_KEY"
export OTEL_SERVICE_NAME="support-bot"

aio-instrument python app.py

If telemetry doesn't start, you'll see this warning: "Acceldata AIO auto-instrumentation: telemetry not started. Set OTEL_RESOURCE_ATTRIBUTES with aio.tenant_id and aio.project_id." Errors from aio-instrument are logged and never stop your application. For every option, see CLI.

Troubleshooting

If setup fails, aio.init() doesn't raise an error. It returns False, logs a message, and your application keeps running without telemetry. The one exception is a redaction policy that can't be enforced, which raises RedactionUnavailable. For more, see Redaction.

Log message What to do
"aio: nonblank tenant_id is required; telemetry is disabled" Set tenant_id or AIO_TENANT_ID.
"aio: exactly one nonblank project_id or project_name is required; telemetry is disabled" Set either project_id or project_name, not both.
"aio: project resolution failed (duplicate exact project name); continuing without telemetry" The text in parentheses gives the reason. In this example, two projects have the same name. Rename one, or use project_id instead.
"aio: project resolution failed (endpoint is required when project_name is used); continuing without telemetry" Set endpoint or AIO_ENDPOINT.
"aio: telemetry setup failed; continuing without it" Check the rest of your log for the cause.

If your application already sets up OpenTelemetry itself, call aio.init() first. Otherwise the SDK logs a warning that an OpenTelemetry tracer provider was already configured, and your telemetry lands under the default tenant. To fix it, call aio.init() before you configure OpenTelemetry, or add the AIO tenant and project attributes to that provider's resource. For more on that setup, see OpenTelemetry.

If the Traces list shows "No traces in this window", choose a wider time range and clear any filters. Then check that your application ran with the SDK attached and that aio.init() returned True. Hide infra traces is on by default and hides traces that start with an HTTP or MCP call. To see those traces, clear Hide infra traces.

Next steps