Install the ARMS agent for Python with uWSGI for Django or Flask applications - Application Real-Time Monitoring Service

When Django or Flask applications run on uWSGI, you need to import the Application Real-Time Monitoring Service (ARMS) Python agent directly in the application entry file and enable lazy-apps mode.

Important

Do not use the aliyun-instrument command prefix with uWSGI. Import the agent directly in your application code instead.

Prerequisites

Before you begin, make sure that you have:

The ARMS agent for Python installed

Import the agent in the entry file

Add the following import to the first line of the uWSGI entry file (wsgi.py for Django or app.py for Flask):

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

This import initializes the ARMS agent before the application framework loads, enabling automatic instrumentation of supported libraries.

Start uWSGI with lazy-apps

Add --lazy-apps to the uWSGI startup command, or set lazy-apps = true in the configuration file.

CLI example:

uwsgi --http :8000 --wsgi-file app.py --callable application --master --enable-threads --threads 2 --processes 4 --lazy-apps

Configuration file example (INI format):

[uwsgi]
http = :8000
wsgi-file = <your-wsgi-file-path>
callable = application
socket = <your-socket-file-path>
chmod-socket = 660

# Process settings
master = true
processes = 4
threads = 4

# ARMS agent: required settings
enable-threads = true
lazy-apps = true

Replace the following placeholders with your actual values:

Placeholder	Description	Example
`<your-wsgi-file-path>`	Path to the WSGI entry file	`/myproject/myproject/wsgi.py`
`<your-socket-file-path>`	Path to the Unix socket file	`/myproject/wsgi.sock`

Why lazy-apps is required

lazy-apps is a configuration option in uWSGI that controls how application modules are loaded. By default, uWSGI loads the application when the master process starts and then forks worker processes. With lazy-apps = true, uWSGI loads the application after each worker process starts.

Effects of enabling lazy-apps

Memory isolation -- each worker process loads the application in its own context, preventing states across different processes from interfering with each other.
Dynamic reloading -- in development mode, hot updates of code become more convenient because each worker process reloads the application at startup without needing to restart the entire master process.
Avoidance of global state issues -- each worker process has its own state when lazy-apps is enabled, reducing issues caused by shared state.

Effects of not enabling lazy-apps

Global state sharing -- if global variables are used in the application, these variables are shared across all worker processes, which may lead to unpredictable behavior.
Startup speed -- since all worker processes load the application when the master process starts, the overall startup speed might be relatively faster, especially when starting a large number of worker processes.
Code change handling -- without lazy-apps, if code changes are made, the entire uWSGI process must be restarted for the changes to take effect, rather than just restarting a single worker process.

Verify trace data

After you start the application with the configuration above, open the ARMS console and confirm that trace data appears. If data does not appear, check the following:

The import statement is on the first line of the entry file.
lazy-apps is enabled in the uWSGI configuration.