The ARMS Python agent supports specific Python versions, third-party components, and frameworks.
Supported Python versions
Supported Protobuf versions
The Python agent uses Protobuf to encode data for reporting. This can create conflicts with the Protobuf version in your application. The Python agent is compatible with the following Protobuf version range:
"protobuf>=3.20.0, < 7.0"Integrating the agent can change the versions of your dependencies, such as Protobuf. To prevent potential errors, use one of the following methods:
If a dependency such as Protobuf is already installed, you can prioritize its version by using the following commands:
# Find the package installation path. Third-party dependency paths typically end with site-packages.
python3 -m site
# Set the PYTHONPATH environment variable.
export PYTHONPATH=/from/to/site-packagesIf the first method does not work, follow the instructions in Manual Installation of Python Agent. After integrating the agent, run the following command to force a specific dependency version:
pip3 install xx==${your_original_dependency_version} --force-reinstall
Supported OpenTelemetry API versions
The Python agent follows the OpenTelemetry API specification. Because different API versions can vary, the agent supports the following version range:
"opentelemetry-api <= 1.39.0"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 sitecustomizeApproach 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:appThe 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=trueSupported plugin versions
LLM (large language model) applications
Component | PyPI/GitHub repository | Minimum version | Maximum version |
AgentScope | v1.0 | v1.0.10 | |
CrewAI | v0.1.0 | v1.7.2 | |
Dashscope | v1.0.0 | v1.2.1 | |
Dify | v0.12.8 | v1.11.2 | |
Dify plugin | Any | No limit | |
Dify React | v0.1.0 | v0.1.0 | |
Google ADK | v1.2.1 | v1.21.0 | |
LangChain | v0.1.0 | v1.2.0 | |
LangGraph | Any | v1.0.5 | |
LiteLLM | v1.0.0 | v1.79.0 | |
Llama-index | v0.10.5 | v0.10.43 | |
MCP | v1.3.0 | v1.12.4 | |
OpenAI | v1.0.0 | v2.14.0 | |
OpenAI agent | v0.3.3 | v0.6.6 | |
RagFlow | v0.14.0 | v0.21.1 |
LLM (large language model) services
Component | PyPI/GitHub repository | Minimum version | Maximum version |
SGLang | v0.4.6 | v0.4.9.post6 | |
vLLM v0 | v0.5.0 | v0.8.4 | |
vLLM v1 | v0.8.2 | v0.16.0 |
HTTP/RPC frameworks
Component | PyPI/GitHub repository | Minimum version | Maximum version |
aiohttp | v3.0 | No limit | |
asgiref | v3.0 | No limit | |
BlackSheep | v1.2.0 | No limit | |
Click | v8.1.3 | < 9.0.0 | |
Django | v1.10 | No limit | |
FastAPI | v0.92 | No limit | |
Flask | v1.0 | No limit | |
gRPC | v1.42.0 | No limit | |
Jinja2 | v2.7 | < 4.0 | |
Requests | v2.0 | No limit | |
Tornado | v5.1.1 | No limit | |
WSGI | None | Any | No limit |
Vector databases
Component | PyPI/GitHub repository | Minimum version | Maximum version |
Milvus | v2.4.1 | No limit |
Memory frameworks
Component | PyPI/GitHub repository | Minimum version | Maximum version |
Mem0 | v1.0.0 | v1.0.2 |
Database frameworks
Component | PyPI/GitHub repository | Minimum version | Maximum version |
aiopg | v0.13.0 | < 2.0.0 | |
AsyncPG | v0.12.0 | No limit | |
DBAPI | None | Any | No limit |
MySQL | v8.0 | < 10.0 | |
MySQLClient | Any | < 3 | |
psycopg | v3.1.0 | No limit | |
psycopg2 | v2.7.3.1 | No limit | |
Pydantic | v1.10.2 | No limit | |
PyMongo | v3.1 | < 5.0 | |
PyMSSQL | v2.1.5 | < 3 | |
PyMySQL | Any | < 2 | |
SQLAlchemy | v1.0.0 | < 2.1.0 | |
SQLite3 | None | Any | No limit |
TortoiseORM | v0.17.0 | No limit |
Caching plugins
Component | PyPI/GitHub repository | Minimum version | Maximum version |
Cassandra | v3.25 | No limit | |
Elasticsearch | v6.0 | No limit | |
PyMemcache | v1.3.5 | < 5 | |
Redis | v2.6 | No limit | |
Scylla | v3.25 | No limit |
Message queue plugins
Component | PyPI/GitHub repository | Minimum version | Maximum version |
aio-pika | Any | No limit | |
aiokafka | Any | No limit | |
Celery | v4.0 | < 6.0 | |
Confluent Kafka | v1.8.2 | v2.7.0 | |
Kafka-Python | Any | No limit | |
Pika | Any | No limit | |
Remoulade | v0.50 | No limit |
Other plugins
Component | PyPI/GitHub repository | Minimum version | Maximum version |
asyncio | None | Any | No limit |
Logging | None | Any | No limit |
Loguru | v0.5.0 | v1.0 | |
Threading | None | Any | No limit |