Python agent FAQ

Installation fails when using aliyun-bootstrap -a install

Installing the agent with the aliyun-bootstrap -a install command may cause the following error:

Installation aborted due to download failure.

This failure typically has one of two causes:

1. A network problem is preventing the agent from reaching its OSS endpoint. Verify the network connection.

Starting Aliyun Python Agent installation...
agent download url: https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz
Checking network connectivity...
Downloading agent from https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz...
Downloading: 100%|████████████████████████████████████████████████████████████| 1.00M/1.00M [00:00<00:00, 6.21MB/s]
Extracting wheels from archive...
Extracting files: 100%|███████████████████████████████████████████████████████| 27/27 [00:00<00:00, 2151.05file/s]
Found 27 wheel files
Installing 27 packages...
Installing packages:   0%|                                                   | 0/27 [00:00<?, ?pkg/s]
Installing packages:   0%|                                                   | 0/27 [00:00<?, ?pkg/s]

2. Your Python interpreter is missing the SSL module.

python3 -m ssl

An error from this command indicates that the SSL module is missing from your python interpreter. The aliyun-bootstrap script requires this module to download dependencies, so you must install it in your Python environment.

Startup error: No module named 'aliyun'

This error indicates the agent was installed in a location that your application cannot find at runtime. You must ensure that the python interpreter in your application's environment can find the Python agent dependencies.

Run the following command in your application's environment to verify that aliyun-bootstrap installed the agent package to a searchable path:

python3 -m site

This command prints the search paths that the python interpreter uses to find packages. If the Python agent dependencies, as shown in the example directory structure below, are not found in any of these paths, the installation location is incorrect.

.venv
  bin
  lib
    python3.12
      site-packages  library root
        _distutils_hack
        aliyun
          instrumentation
          opentelemetry
          sdk
          semconv
            __init__.py
        aliyun_instrumentation_dashscope-1.0.0.dist-info
        aliyun_instrumentation_dify-1.1.0.dist-info
        aliyun_instrumentation_langchain-1.1.0.dist-info
        aliyun_instrumentation_llama_index-1.0.3.dev0.dist-info
        aliyun_instrumentation_openai-1.0.1.dist-info
        aliyun_instrumentation_vllm-0.1.0.dist-info
        aliyun_opentelemetry_exporter_otlp_proto_common-1.25.0.dist-info
        aliyun_opentelemetry_exporter_otlp_proto_grpc-1.25.0.dist-info
        aliyun_opentelemetry_exporter_otlp_proto_http-1.25.0.dist-info
        aliyun_opentelemetry_instrumentation-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_aiohttp_client-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_asgi-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_django-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_fastapi-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_flask-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_httpx-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_logging-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_redis-0.46b0.dev0.dist-info

You can use the following command to specify the installation location for the aliyun-bootstrap package:

aliyun-bootstrap -a install -t ${TARGET_PATH}

Replace ${TARGET_PATH} with the correct path for your environment. For example, the path might be /root/demo/venv/lib/python3.12/site-packages.

No data reported from Flask applications

You cannot use the aliyun-instrument method to integrate a Flask application when debug mode is enabled. Instead, you must add the following statements to the entry file of the Flask application to manually import the Python agent. This allows you to start the application without adding the aliyun-instrument prefix.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Django application fails to start

If your Django application fails to start and shows an error similar to AttributeError: module 'django.conf global_settings' has no attribute 'ROOT_URLCONF', set the DJANGO_SETTINGS_MODULE environment variable to your project's settings module.

export DJANGO_SETTINGS_MODULE=instrumentation_example.settings

No data reported from Django applications

Django's hot reloading feature, enabled by default with commands like python manage.py runserver 0.0.0.0:8080, can prevent the agent from reporting data. To fix this, add the --noreload option to disable hot reloading:

python manage.py runserver 0.0.0.0:8080 --noreload

No data reported from Uvicorn applications

Using a Uvicorn server with hot reloading (the --reload parameter) or multiple workers (the --workers parameter) can prevent the agent from reporting data. To resolve this, you must manually import the Python agent by adding the following line to your application's entry file. Do not use the aliyun-instrument prefix when starting the application.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Uninstall the agent

To uninstall the Python agent, run the following command:

aliyun-bootstrap -a uninstall

Install a specific region and version

For optimal performance, you may need to install a specific version of the agent from the nearest region. Follow these steps:

1. Set the ARMS_REGION_ID environment variable to specify the region from which to pull the agent.

export ARMS_REGION_ID=cn-beijing

For a list of supported regions, see Available regions.

2. Install a specific version of the Python agent with the following command. If another version of the agent is installed, we recommend uninstalling it first.

# Replace ${version} with the target version number
aliyun-bootstrap -a install -v ${version}

If you installed the Python agent using the non-intrusive method described in Install the Python agent with the ack-onepilot component in Container Service for Kubernetes (ACK) and Container Compute Service (ACS), you can specify the agent version by adding the aliyun.com/agent-version label. For more information, see Control agent versions independently.

For a list of all published Python agent versions, see the Python agent release notes.

Specify the log directory

Ensure your Python agent version is 1.6.0 or later. You can then set the APSARA_APM_AGENT_WORKSPACE_DIR environment variable. The agent stores its log files in the ${APSARA_APM_AGENT_WORKSPACE_DIR}/.apsara-apm/python/logs directory.

By default, the agent determines the log directory in the following order of priority:

1. /home/admin/.opt/.apsara-apm/python/logs (The volume directory for the ack-onepilot component)

2. ~/.apsara-apm/python/logs (The user home directory)

3. ./.apsara-apm/python/logs (The same directory as the main Python entry file)

Specify the network reporting mode

If your agent version is 1.6.0 or later, you can set the PROFILER_NETWORK_STRATEGY environment variable to specify the network reporting mode:

1. internal: Forces internal network reporting.

2. public: Forces public network reporting.

3. auto: Automatically detects the network mode (default behavior).

Invisible token usage in OpenAI streaming

For more information, see Streaming output. By default, the OpenAI protocol does not return token usage in streaming calls. To receive this information, set stream_options={"include_usage": true} to include the token usage details in the final data chunk.

Prevent agent injection into child processes

To prevent the agent from injecting into any child process created by the target application, set the APSARA_APM_INSTRUMENTATION_CHILD_PROCESS environment variable to false.