Manually install the Python agent-Application Real-Time Monitoring Service(ARMS)-阿里云帮助中心

This topic describes how to manually install the Python agent. Once installed, ARMS monitors your application, allowing you to view its topology, traces, SQL analysis, and other monitoring data.

Note

For applications deployed in a Kubernetes environment, manual agent installation is not recommended. Instead, integrate with ARMS by installing a component. For instructions, see Install the Python agent on Container Service for Kubernetes (ACK) and Container Compute Service (ACS) by using the ack-onepilot component.
If you encounter any issues while using the Python agent, see the Python agent FAQ. If the documentation does not answer your questions, contact us in the DingTalk support group (Group ID: 159215000379).
The aliyun-bootstrap component installs the latest agent version by default, providing access to the latest features. To install a specific version, see the How to install an agent for a specific region and version section in the Python agent FAQ.

Prerequisites

Ensure your build environment is connected to the public internet or the Alibaba Cloud internal network. The security group for the environment must allow outbound TCP traffic on ports 80 and 443.
Check your Python and framework versions. For requirements, see Supported Python components and frameworks for ARMS Application Monitoring.

Python framework compatibility

Review these framework-specific requirements before you proceed.

uvicorn

If your application starts with uvicorn, choose one of the following approaches:

Approach A: Import the agent in code. Add this import statement to the first line of your uvicorn entry file:

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Approach B: Switch to gunicorn with the aliyun-instrument prefix. Replace your uvicorn command:

# Before
uvicorn app:app --workers 4 --port=9090 --host 0.0.0.0

# After
aliyun-instrument gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 app:app

Note

The aliyun-instrument prefix handles initialization and non-intrusive instrumentation of the ARMS Python agent.

uWSGI

If your application starts with uWSGI, see Install the Python agent for a Django or Flask project that starts with uWSGI.

gevent

If you use gevent coroutines, set the GEVENT_ENABLE environment variable to true.

For example, if your code contains:

from gevent import monkey
monkey.patch_all()

Set the following environment variable in your deployment:

GEVENT_ENABLE=true

Step 1: Download the aliyun-bootstrap installer

Download the agent installer from the Python Package Index (PyPI).

pip3 install aliyun-bootstrap

Step 2: Configure environment variables

Manually add the following environment variables for the Python application:

# Method 1: Add environment variables for all processes in the current shell
export ARMS_APP_NAME=xxx   # The name of your application.
export ARMS_REGION_ID=xxx   # The region ID for your Alibaba Cloud account.
export ARMS_LICENSE_KEY=xxx   # Your license key.

# Method 2: Add environment variables for a single process
ARMS_APP_NAME=xxx ARMS_REGION_ID=xxx ARMS_LICENSE_KEY=xxx aliyun-instrument xxx.py

You can obtain the license key by calling an OpenAPI operation. For more information, see List license keys.

(Optional) Docker installation example

For Docker environments, update your Dockerfile based on the following sample.

# Add environment variables
ENV ARMS_APP_NAME={YourAppName}
ENV ARMS_REGION_ID={YourRegionId}
ENV ARMS_LICENSE_KEY={YourLicenseKey}
## Original environment

Step 3: Install the Python agent

To speed up the installation, we recommend first configuring the image repository by running the following command:

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ && pip config set install.trusted-host mirrors.aliyun.com

Install the agent.
```
aliyun-bootstrap -a install
```
Note
To install a specific version of the Python agent, run the following command:
```
# Replace ${version} with the target version number.
aliyun-bootstrap -a install -v ${version}
```
For a list of all released Python agent versions, see Release notes for the Python agent.

Step 4: Start the application

Start with the ARMS Python agent

aliyun-instrument python app.py

Verify the results

The integration is successful if, after about one minute, your Python application appears on the Application Monitoring > Application List page in the ARMS console and reports data.