Enable ARMS Monitoring via Python Agent on Function Compute Custom Runtime - ARMS

When you run Python applications on Function Compute (FC), you need visibility into traces and performance metrics to diagnose latency, errors, and bottlenecks. Application Real-Time Monitoring Service (ARMS) provides a Python agent that collects this data automatically. The agent wraps your startup command to inject monitoring -- no code changes required.

How it works

The integration follows three steps:

Build an agent layer -- Download the ARMS Python agent package, install its dependencies, and upload the result as an FC layer.
Configure the function -- Attach the layer to your function, set environment variables for ARMS authentication, and modify the startup command.
Verify -- Run the function and confirm that monitoring data appears in the ARMS console.

Prerequisites

Before you begin, make sure that you have:

An FC function that uses a custom runtime
A local Python version that matches the custom runtime version (for example, Python 3.10)
An ARMS LicenseKey -- call the DescribeTraceLicenseKey API to retrieve it
The region ID of the region where your function is deployed

Step 1: Build the agent layer

Download the agent package

Run wget to download the ARMS Python agent package. Choose the URL based on your network:

Over a VPC network (internal endpoint):

# Download a specific version
wget http://arms-apm-<region-id>.oss-<region-id>-internal.aliyuncs.com/aliyun-python-agent/<version>/aliyun-python-agent.tar.gz

# Download the latest version
wget http://arms-apm-<region-id>.oss-<region-id>-internal.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz

Over the internet (public endpoint):

# Download a specific version
wget http://arms-apm-<region-id>.oss-<region-id>.aliyuncs.com/aliyun-python-agent/<version>/aliyun-python-agent.tar.gz

# Download the latest version
wget http://arms-apm-<region-id>.oss-<region-id>.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz

Replace the following placeholders:

Placeholder	Description	Example
`<region-id>`	The region where your function is deployed. See Supported regions.	`cn-hangzhou`
`<version>`	The agent version. See Python agent release notes.	`1.5.0`

For example, to download version 1.5.0 from the cn-hangzhou region over the internet:

wget http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/1.5.0/aliyun-python-agent.tar.gz

Install the agent dependencies

Extract the package and install the Python wheels into a folder named aliyun-instrument:

# Extract the package
tar -zxvf aliyun-python-agent.tar.gz

# Install dependencies into the aliyun-instrument folder
pip3 install target/*.whl -t aliyun-instrument

After installation, update the shebang line in ./aliyun-instrument/bin/aliyun-instrument. Replace the first line:

#!/usr/bin/python3

with the Python path used by your FC custom runtime:

#!/var/fc/lang/python3.10/bin/python3

Adjust the Python path if your custom runtime uses a different Python version.

Upload the layer to Function Compute

Log on to the Function Compute console. In the left-side navigation pane, choose Advanced Features > Layers.
In the top navigation bar, select the region where your function is deployed. On the Layer Management page, click Create Layer.
On the Create Layer page, select Upload Layer By Folder and upload the aliyun-instrument folder.

Create a layer by uploading the aliyun-instrument folder

Important

The aliyun-instrument folder must be the top-level folder in the upload. Do not nest it inside another folder with the same name. An incorrect folder structure causes environment variable resolution to fail.

Step 2: Configure the function

Attach the layer

Log on to the Function Compute console. In the left-side navigation pane, click Functions.
In the top navigation bar, select the region. On the Functions page, click the name of your function.
On the function details page, click the Configuration tab. Click Edit next to Advanced Configuration.
In the Advanced Configuration panel, click +Add Layer and then select Add Custom Layer. Select the layer you created in Step 1 and choose the Layer Version. Click Deploy.

Set environment variables

On the Configuration tab, add the following environment variables:

Variable	Value	Description
`ARMS_APP_NAME`	`FC:<your-function-name>`	The application name displayed in ARMS. Replace `<your-function-name>` with the actual function name.
`ARMS_LICENSE_KEY`	`<your-license-key>`	The ARMS LicenseKey. See Prerequisites.
`ARMS_REGION_ID`	`<region-id>`	The region ID, such as `cn-hangzhou`.
`LD_LIBRARY_PATH`	`/code:/code/lib:/usr/local/lib:/opt/lib:/opt/php8.1/lib:/opt/php8.0/lib:/opt/php7.2/lib`	Library search paths required by the runtime.
`PATH`	`/code/python/bin:/var/fc/lang/python3.10/bin:/usr/local/bin/apache-maven/bin:/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/ruby/bin:/opt/bin:/code:/code/bin`	Executable search paths. Includes the Python binary and the `aliyun-instrument` command from the layer.
`PYTHONPATH`	`/opt:/opt/python:/code`	Python module search paths. `/opt` points to the layer contents.
`PYTHONUSERBASE`	`/code/python`	Base directory for Python user-level packages.

Modify the startup command

The aliyun-instrument command wraps your application startup to inject ARMS monitoring automatically, without changes to your application code.

On the function details page, click the Configuration tab and then click Edit next to Basic Configuration. Prepend aliyun-instrument to your existing Startup Command:

aliyun-instrument python3 app.py

uvicorn applications

If your application starts with uvicorn, switch to gunicorn with the UvicornWorker class and prepend aliyun-instrument. For example, change:

uvicorn -w 4 -b 0.0.0.0:8000 app:app

to:

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

gevent applications

If your application uses gevent coroutines, for example:

from gevent import monkey
monkey.patch_all()

add the following environment variable:

Variable	Value
`GEVENT_ENABLE`	`true`

This tells the agent to apply gevent-compatible instrumentation hooks.

Verify the integration

Invoke your function to generate traffic.
Wait about one minute for the agent to report data.
Log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Application List.
Confirm that your application appears in the list and is reporting data.

Verify that the application appears in the ARMS Application List

Troubleshooting

If the application does not appear after a few minutes, check the following:

Issue	What to check
Authentication failure	The `ARMS_LICENSE_KEY` value is correct.
Wrong region	The `ARMS_REGION_ID` matches the region where the function is deployed.
Layer structure error	The `aliyun-instrument` folder is the top-level folder in the layer, not nested inside another folder.
Agent not loaded	The `PYTHONPATH` includes `/opt` so that the function can locate the agent dependencies in the layer.
Startup command incorrect	The startup command is prefixed with `aliyun-instrument` (for example, `aliyun-instrument python3 app.py`).

Application Real-Time Monitoring Service:Integrate a Python agent with a Function Compute application