Instrument your code

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.

Copy your project ID

1. Go to the Connection info page for your project. The same panel also appears once, right after you save a new project.
2. Next to Project ID, select Copy.

The Connection info page doesn't show access keys or secret keys.

Install the SDK

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

pip install acceldata-aio-tracer

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

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

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.

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.

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

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.

If your application already sets up OpenTelemetry itself, call aio.init() first. 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.

Next steps

• Track users and sessions
• Explore traces
• Redaction overview
• Python SDK reference