Acceldata
AIO

Last updated: Oct 07, 2026 16:32 UTC

This page lists every option of aio-instrument. The command starts an existing Python program with AIO instrumentation, so you don't have to change the program's code.

aio-instrument comes with the acceldata-aio-tracer package. For installation steps, see Instrument your code.

Usage

aio-instrument [options] command [command_args...]

Put the aio-instrument options first. Then add the command that starts your program and that command's own arguments.

The command-line interface (CLI) has no options for the tenant, project, or keys. Set them as environment variables before you run the command:

  • OTEL_RESOURCE_ATTRIBUTES must include aio.tenant_id and aio.project_id. Without them, telemetry doesn't start.
  • AIO_ACCESS_KEY and AIO_SECRET_KEY set the gateway credential pair. They're sent only when you set both.

For every environment variable the SDK reads, see Python SDK.

Example

The following example starts app.py with instrumentation. Replace the tenant id, project id, and endpoint with your own values.

export OTEL_RESOURCE_ATTRIBUTES="aio.tenant_id=example-tenant,aio.project_id=01900000-0000-7000-8000-000000000000"
aio-instrument --service_name support-bot --otlp_endpoint https://collector.example.com python app.py

Options

Option names use underscores, for example --service_name. Boolean options are plain flags that take no value. Each option has an equivalent environment variable, which the help text for that option also shows.

Option Equivalent environment variable What it sets Default
--environment OTEL_DEPLOYMENT_ENVIRONMENT The deployment environment default
--application_name OTEL_SERVICE_NAME The application name for tracing. Deprecated: use --service_name instead. None
--service_name OTEL_SERVICE_NAME The service name for tracing None
--otlp_endpoint OTEL_EXPORTER_OTLP_ENDPOINT The OpenTelemetry Protocol (OTLP) endpoint for the exporter None
--otlp_headers OTEL_EXPORTER_OTLP_HEADERS OTLP headers, given as a JSON string None
--disable_batch AIO_DISABLE_BATCH Turns off batch span processing Off
--capture_message_content OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT Turns on capture of message content True
--disabled_instrumentors AIO_DISABLED_INSTRUMENTORS A comma-separated list of instrumentors to turn off None
--controller_mode AIO_CONTROLLER_MODE A controller-managed instrumentation profile None
--disable_metrics AIO_DISABLE_METRICS Turns off metrics collection Off
--disable_events AIO_DISABLE_EVENTS Turns off event emission through the OpenTelemetry logger Off
--pricing_json AIO_PRICING_JSON A file path or URL to a pricing JSON file None
--collect_gpu_stats AIO_COLLECT_GPU_STATS Turns on graphics processing unit (GPU) statistics collection Off
--collect_system_metrics AIO_COLLECT_SYSTEM_METRICS Turns on system metrics for CPU, memory, disk, and network, plus GPU when one is detected Off
--capture_db_parameters AIO_CAPTURE_DB_PARAMETERS Captures database query parameters as OpenTelemetry attributes, one per key Off
--max_content_length AIO_MAX_CONTENT_LENGTH The maximum number of characters kept from captured content None (no limit)
--custom_span_attributes AIO_CUSTOM_SPAN_ATTRIBUTES Custom span attributes, given as a JSON string such as '{"team": "ml"}' None
--custom_metrics_attributes AIO_CUSTOM_METRICS_ATTRIBUTES Custom metrics attributes, given as a JSON string such as '{"team": "ml"}' None
--version None Prints aio-instrument 1.0.0 Not applicable

Caution: --capture_db_parameters can expose sensitive data from your database queries in your traces.

How options and environment variables combine

Environment variables take precedence over options. The CLI writes an option's value to its environment variable only when that variable isn't already set. If you've set OTEL_SERVICE_NAME, for example, --service_name has no effect.

When you set a boolean option through its environment variable, use true, 1, or yes to turn it on.

Content capture is on by default. To turn it off, set OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false before you run the command.

What happens when you run the command

  1. aio-instrument adds its bootstrap directory and the current directory to PYTHONPATH.
  2. It replaces itself with your command.
  3. When your program starts, the bootstrap removes itself from PYTHONPATH. Subprocesses that your program starts aren't instrumented.
  4. The bootstrap starts telemetry with no arguments, so every setting comes from the environment.

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

Messages and exit codes

The following table lists the messages that aio-instrument logs. In each example, the command is python and the error is a sample error.

Situation Message
The command isn't on PATH "Command not found: python. Attempting direct execution as fallback." The CLI then tries to run the command directly.
The command can't be run "Failed to execute command python: [Errno 13] Permission denied", followed by "Acceldata AIO instrumentation failed, but this should not break your application"
Any other failure "Acceldata AIO CLI failed: [Errno 13] Permission denied", followed by "This should not prevent your application from running. Consider running without aio-instrument."

If you stop the CLI with Ctrl+C, it exits with code 130.

Next steps