OpenTelemetry

Send traces to AIO from an application that already uses OpenTelemetry, without giving up the tracer provider you already have.

Prerequisites

• An AIO project. To create one, see Create a project.
• An access key and secret key. To get a key pair, see Create an API key.
• The AIO Python SDK installed in your application. For the install steps, see Instrument your code.

Get your project's connection details

1. On the projects list, in the row for your project, select the connection icon (Connection info for followed by the project name).

The Connection info page opens.

2. Next to Project ID, select Copy, and save the value to use in your configuration.
3. Next to Endpoint, select Copy, and save that value too.
4. Select Back to projects.

You also see these details once, right after you create a project.

Add AIO to your OpenTelemetry setup

The AIO SDK works with an OpenTelemetry setup in one of two ways. Pick one based on whether AIO or your own code sets up OpenTelemetry first.

Call aio.init() before your OpenTelemetry setup

When aio.init() runs first, the SDK sets up the tracer provider and exports spans to AIO itself. Use this option if you plan to use redaction, because redaction only works this way.

import acceldata_aio_tracer as aio
# Call init once at startup, before your OpenTelemetry setup code
# and before you create HTTP or model clients.
aio.init(
    service="support-bot",
    tenant_id="your-tenant-id",
    project_id="00000000-0000-0000-0000-000000000000",
)

Replace your-tenant-id with your tenant ID and the zero UUID with the project ID you copied. To set the endpoint and keys, see Instrument your code.

Keep your existing tracer provider

If your application sets up a TracerProvider before it calls aio.init(), AIO keeps that provider. It doesn't replace the provider. It adds its attribution step to it.

AIO doesn't add an exporter to a provider it reuses. Your spans go wherever that provider already exports them.

Add aio.tenant_id and aio.project_id to your provider's resource. If you don't add them, your telemetry lands under the default tenant.

import acceldata_aio_tracer as aio
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
TENANT_ID = "your-tenant-id"
PROJECT_ID = "00000000-0000-0000-0000-000000000000"
# Your existing OpenTelemetry setup. Keep your own span processors
# and exporters on this provider.
provider = TracerProvider(
    resource=Resource.create(
        {
            "service.name": "support-bot",
            "aio.tenant_id": TENANT_ID,
            "aio.project_id": PROJECT_ID,
        }
    )
)
trace.set_tracer_provider(provider)
# AIO adds its attribution step to the provider above.
aio.init(service="support-bot", tenant_id=TENANT_ID, project_id=PROJECT_ID)

If you've already set up a LoggerProvider, AIO reuses it only when no log processors have been added to it yet. Otherwise, aio.init() returns False and telemetry stays off.

Set values with standard OpenTelemetry variables

The SDK reads the standard OpenTelemetry environment variables in the following table. A value passed to aio.init() takes priority over them.

Write OTEL_RESOURCE_ATTRIBUTES as comma-separated key=value pairs:

export OTEL_SERVICE_NAME=support-bot
export OTEL_RESOURCE_ATTRIBUTES="aio.tenant_id=your-tenant-id,aio.project_id=00000000-0000-0000-0000-000000000000,deployment.environment=production"

With these set, call aio.init() without the matching arguments. For every setting and its default, see the Python SDK reference.

Know what AIO reads from your spans

• Conversations: AIO reads gen_ai.conversation.id from spans of any instrumentation, and spans that share the value belong to one conversation. For more about grouping, see Track users and sessions.
• Other instrumentation: AIO fully maps spans from the AIO SDK and from OpenLIT. It stores spans from other OpenTelemetry instrumentation unchanged and doesn't map them onto its own fields, such as span kind, model, and token usage.
• Metrics: AIO accepts metrics, but they don't appear anywhere in the product yet.

Troubleshooting

A warning says the TracerProvider carries no aio.tenant_id

Your application set up its tracer provider before aio.init(), and the provider's resource has no tenant. Add aio.tenant_id and aio.project_id to that provider's resource, or call aio.init() before your OpenTelemetry setup code.

aio.init() raises RedactionUnavailable

You turned on redaction, but your application had already set up a tracer provider. AIO applies redaction when it exports spans, and a reused provider doesn't use AIO's exporter. Call aio.init() before your OpenTelemetry setup code.

The log says "aio: telemetry setup failed; continuing without it"

Check whether your application added log processors to its LoggerProvider before calling aio.init(). AIO can reuse a LoggerProvider only if no processors have been added to it yet.

The Connection info page says "Project not found"

The project in the address isn't one you can see. Check your access in Project permissions.

Next steps

• Instrument your code
• Send traces using OpenLIT
• Explore traces
• Python SDK reference