Acceldata
 AIO
Search documentation… ⌘K

Last updated: Oct 06, 2026 15:09 UTC

CLI

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.

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, %s is replaced by the command or the error.

Situation

Message

The command isn't on PATH

"Command not found: %s. Attempting direct execution as fallback." The CLI then tries to run the command directly.

The command can't be run

"Failed to execute command %s: %s", followed by "Acceldata AIO instrumentation failed, but this should not break your application"

Any other failure

"Acceldata AIO CLI failed: %s", 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