Manually install an ARMS agent for Python - Application Real-Time Monitoring Service

After you install an Application Real-Time Monitoring Service (ARMS) agent for a Python application, ARMS starts to monitor the application. Then, you can view the monitoring data of the application, such as the topology, traces, and SQL analysis. This topic describes how to manually install an ARMS agent for a Python application.

Note

For applications deployed in Container Service for Kubernetes (ACK) clusters, we recommend that you install the ack-onepilot component rather than manually install an ARMS agent. For more information, see Install the Python agent for Container Service for Kubernetes (ACK) and Container Compute Service (ACS) using the ack-onepilot component.
If you have any questions when you use an ARMS agent for Python, first refer to our documentation. If your questions are not resolved, join the DingTalk group chat (ID: 159215000379) to obtain technical support.
To ensure you can use the agent's latest features, the aliyun-bootstrap component installs the latest agent version by default. To specify an agent version, see the "Install a specific agent version or from a specific region" section in FAQs about the agent for Python.

Before you begin

Make sure the environment where the application resides is connected to Alibaba Cloud over the Internet or an internal network, and the security group of the environment allows outbound traffic for TCP ports 80 and 443.
Check the versions of Python and frameworks. For more information, see Python libraries supported by Application Monitoring.

Notes

If your application starts with uvicorn, choose one of the following configuration methods.
- Method 1: Add the following statement to the first line of the uvicorn entry file to import the Python agent.
```
from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize
```
- Method 2: Replace uvicorn with gunicorn and add the aliyun-instrument prefix to the gunicorn command.
  Example:
```
uvicorn app:app --workers 4 --port=9090 --host 0.0.0.0
```
  Change the command to:
```
aliyun-instrument gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 app:app
```
  Note
  The aliyun-instrument instruction handles the initialization and non-intrusive instrumentation of the ARMS Python agent.
If your application starts with uWSGI, see Install the Python agent for a Django or Flask project that starts with uWSGI.
If you use gevent coroutines, you must set the GEVENT_ENABLE=true environment variable.
For example, if your program contains the following code:
```
from gevent import monkey
monkey.patch_all()
```
You must set the environment variable as follows:
```
GEVENT_ENABLE=true
```

Step 1: Download aliyun-bootstrap

Download the agent installer, aliyun-bootstrap, from the Python Package Index (PyPI) repository.

pip3 install aliyun-bootstrap

Step 2: Configure environment variables

Manually add the following environment variables to the Python application:

For all processes in the shell

export ARMS_APP_NAME=xxx   # The name of the application.
export ARMS_REGION_ID=xxx   # The region ID.
export ARMS_LICENSE_KEY=xxx   # The license key.

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 API operation. For more information, see DescribeTraceLicenseKey.

(Optional) Sample Dockerfile

For the Docker environment, you can refer to the following sample Dockerfile to install an ARMS agent.

# Add environment variables.
ENV ARMS_APP_NAME={AppName}
ENV ARMS_REGION_ID={regionId}
ENV ARMS_LICENSE_KEY={licenseKey}

## Original environment

Step 3: Use aliyun-bootstrap to install the ARMS agent

Run the following command to configure the image repository. This step is recommended to facilitate the installation.

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

Install the ARMS agent for Python.
```
aliyun-bootstrap -a install
```
Note
To install a specific version of the Python agent, run the following command:
```
# Replace ${version} with the actual version number.
aliyun-bootstrap -a install -v ${version}
```
For information about released Python agent versions, see Python agent version guide.

Step 4: Start the application

To start the application by using the ARMS agent for Python, run the following command:

aliyun-instrument python app.py

Verify the result

After about one minute, log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Application List. If the application is displayed on the Application List page, the application is being monitored.

2024-09-23_17-45-22