Application Real-Time Monitoring Service:Python agent FAQ

Agent installation fails when using aliyun-bootstrap -a install

If the agent fails to install when you use the aliyun-bootstrap -a install command, the following error message appears:

Installation aborted due to download failure.

This failure usually occurs for one of the following two reasons:

1. A network connectivity issue exists with the agent's OSS endpoint. You can check your network connection to the agent's OSS endpoint.

2. The Python interpreter was installed without the ssl module. To verify this, you can run the following command:

python3 -m ssl

If this command returns an error, the ssl module is missing. The aliyun-bootstrap tool requires the ssl module to download dependencies. To resolve this issue, install the ssl module in your Python environment.

Installation succeeds but the application fails to start with a "No module named 'aliyun'" error

This error indicates that the agent was installed in a location that the application's Python interpreter cannot find at runtime. To resolve this, ensure that the Python agent dependencies are in a path that is discoverable by your application's Python interpreter.

You can run the following command in the application's runtime environment to verify that the agent package is installed in the correct location:

python3 -m site

This command prints the search paths that the Python interpreter uses to locate packages. If the Python agent dependencies, such as the ones shown in the following image, are not in any of these paths, it means that aliyun-bootstrap installed the packages to the wrong location.

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

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

Replace ${TARGET_PATH} with the correct package path. For example, based on the preceding image, ${TARGET_PATH} is /root/demo/venv/lib/python3.12/site-packages.

No data from Flask application

Flask applications in debug mode cannot be integrated using `aliyun-instrument`. Instead, you can add the following statement to the Flask entry file to manually import the Python agent. Then, start the application without the `aliyun-instrument` prefix.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

A Django application fails to start after instrumentation

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

export DJANGO_SETTINGS_MODULE=instrumentation_example.settings

No data is reported for a Django application

The auto-reloading feature in Django is enabled by default when you start an application with a command such as python manage.py runserver 0.0.0.0:8080. You can add the --noreload option to disable this feature:

python manage.py runserver 0.0.0.0:8080 --noreload

No data is reported for an application that uses a Uvicorn server

If you enable hot reloading with the --reload parameter or start multiple workers with the --workers parameter on a Uvicorn server, the agent cannot report data. To fix this, you can add the following statement to the application's entry file to manually import the Python agent. When you start the application, you do not need to add the aliyun-instrument prefix.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Uninstall the agent

To uninstall the Python agent, you can run the following command:

aliyun-bootstrap -a uninstall

How to install a probe for a specific region and version

For the best experience, you may need to install a specific version of the agent from the nearest region. The procedure is as follows:

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

export ARMS_REGION_ID=cn-beijing

For a list of all supported regions, see Available regions.

2. Run the following command to install a specific version of the Python agent. If you have another version installed, you must uninstall it first.

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

If you install the Python agent using the non-intrusive method described in Install the Python agent using the ack-onepilot component in Container Service for Kubernetes (ACK) and Container Compute Service (ACS), you can refer to Manually control the agent version to add the aliyun.com/agent-version tag to specify the agent version number.

For a list of all published Python agent versions, see the Python Agent Version Guide.

Specify the log directory for the Python agent

For Python agent V1.6.0 or later, you can set the APSARA_APM_AGENT_WORKSPACE_DIR environment variable to specify a custom log directory. The Python agent stores its log files in the ${APSARA_APM_AGENT_WORKSPACE_DIR}/.apsara-apm/python/logs directory.

By default, the probe selects the log directory based on the following priority:

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

2. ~/.apsara-apm/python/logs (the user's home directory)

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

Specify the network mode for the Python agent

For agent version 1.6.0 or later, you can set the PROFILER_NETWORK_STRATEGY environment variable to specify the network mode for data reporting:

1. internal: Forces the agent to report data over the internal network.

2. public: Forces the agent to report data over the public network.

3. auto: Automatically detects the network mode. This is the default behavior.