All Products
Search
Document Center

Cloud Monitor:Report Python application data using OpenTelemetry

Last Updated:Dec 04, 2025

After you instrument a Python application with OpenTelemetry and report its trace data to Cloud Monitor 2.0, Cloud Monitor 2.0 starts monitoring the application. You can then view monitoring data, such as application topology, call traces, abnormal transactions, slow transactions, and SQL analysis. This topic describes how to use the OpenTelemetry Python Agent or software development kit (SDK) for automatic or manual instrumentation and data reporting.

Important

Use the Alibaba Cloud proprietary Python Agent for the best results.

Compared to open source implementations, the Alibaba Cloud Python agent provides observability for common large model frameworks, such as llama-index, dify, langchain, openai, and Qwen. It also offers richer metrics, traces, and continuous profiling data. For more information, see Manually install the Python agent.

Prerequisites

Python 3.7 or later.

Background information

OpenTelemetry provides several automatic instrumentation plugins that support automatic Span creation for common frameworks. The following table lists the supported frameworks. For a complete list, see the official OpenTelemetry documentation.

Note

Version ~= V.N indicates ≥ V.N and == V.*. For example, aiohttp ~= 3.0 means that the required aiohttp version is aiohttp ≥ 3.0 and aiohttp == 3.*.

Expand to view supported Python frameworks

OpenTelemetry plugin

Supported packages and versions

opentelemetry-instrumentation-aio-pika

aio_pika - [7.2.0, 10.0.0)

opentelemetry-instrumentation-aiohttp-client

aiohttp ~= 3.0

opentelemetry-instrumentation-aiohttp-server

aiohttp ~= 3.0

opentelemetry-instrumentation-aiopg

aiopg - [0.13.0, 2.0.0)

opentelemetry-instrumentation-asgi

asgiref ~= 3.0

opentelemetry-instrumentation-asyncpg

asyncpg ≥ 0.12.0

opentelemetry-instrumentation-aws-lambda

aws_lambda

opentelemetry-instrumentation-boto

boto ~= 2.0

opentelemetry-instrumentation-boto3sqs

boto3 ~= 1.0

opentelemetry-instrumentation-botocore

botocore ~= 1.0

opentelemetry-instrumentation-cassandra

  • cassandra-driver ~= 3.25

  • scylla-driver ~= 3.25

opentelemetry-instrumentation-celery

celery - [4.0, 6.0)

opentelemetry-instrumentation-confluent-kafka

confluent-kafka - [1.8.2, 2.2.0]

opentelemetry-instrumentation-dbapi

dbapi

opentelemetry-instrumentation-django

django ≥ 1.10

opentelemetry-instrumentation-elasticsearch

elasticsearch ≥ 2.0

opentelemetry-instrumentation-falcon

falcon - [1.4.1, 4.0.0)

opentelemetry-instrumentation-fastapi

fastapi ~= 0.58

opentelemetry-instrumentation-flask

flask - [1.0, 3.0)

opentelemetry-instrumentation-grpc

grpcio ~= 1.27

opentelemetry-instrumentation-httpx

httpx ≥ 0.18.0

opentelemetry-instrumentation-jinja2

jinja2 - [2.7, 4.0)

opentelemetry-instrumentation-kafka-python

kafka-python ≥ 2.0

opentelemetry-instrumentation-logging

logging

opentelemetry-instrumentation-mysql

mysql-connector-python ~= 8.0

opentelemetry-instrumentation-mysqlclient

mysqlclient < 3

opentelemetry-instrumentation-pika

pika≥ 0.12.0

opentelemetry-instrumentation-psycopg2

psycopg2 ≥ 2.7.3.1

opentelemetry-instrumentation-pymemcache

pymemcache - [1.3.5, 5)

opentelemetry-instrumentation-pymongo

pymongo - [3.1, 5.0)

opentelemetry-instrumentation-pymysql

PyMySQL < 2

opentelemetry-instrumentation-pyramid

pyramid ≥ 1.7

opentelemetry-instrumentation-redis

redis ≥ 2.6

opentelemetry-instrumentation-remoulade

remoulade ≥ 0.50

opentelemetry-instrumentation-requests

requests ~= 2.0

opentelemetry-instrumentation-sqlalchemy

sqlalchemy

opentelemetry-instrumentation-sqlite3

sqlite3

opentelemetry-instrumentation-starlette

starlette ~= 0.13.0

opentelemetry-instrumentation-system-metrics

psutil ≥ 5

opentelemetry-instrumentation-tornado

tornado ≥ 5.1.1

opentelemetry-instrumentation-tortoiseorm

tortoise-orm ≥ 0.17.0

opentelemetry-instrumentation-urllib

urllib

opentelemetry-instrumentation-urllib3

urllib3 - [1.0.0, 3.0.0)

opentelemetry-instrumentation-wsgi

wsgi

Step 1: Get endpoint information

  1. Log on to the Cloud Monitor 2.0 console, and select a workspace. In the left navigation pane, click Integration Center.

  2. In the Server Applications section, click the Python card, and set Protocol Type to OpenTelemetry.

  3. In the Parameter Settings section, click Get on the right of LicenseKey. Then, set Instrumentation Method, Connection Method, and Reporting Method as needed. Enter Application Name, Version, and Environment.

    The corresponding integration code is generated at the bottom of the page based on your configurations. The code contains endpoint information, such as the Endpoint and LicenseKey.

    image

Step 2: Set dependency libraries

Automatic instrumentation (Recommended)

  1. Download and install the required packages.

    pip install opentelemetry-distro opentelemetry-exporter-otlp
    
    opentelemetry-bootstrap -a install
    Note

    The opentelemetry-bootstrap -a install command scans the site-packages folder of the current Python environment. If a framework that OpenTelemetry supports for automatic instrumentation is found, the command automatically downloads the corresponding OpenTelemetry plugin for that framework. For example, if Django is already installed, the command automatically downloads the opentelemetry-instrumentation-django package.

  2. Configure the following environment variables and then start your application.

    export OTEL_SERVICE_NAME=<service name>
    export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=<traces.endpoint>
    export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=<metrics.endpoint>
    export OTEL_EXPORTER_OTLP_HEADERS="x-arms-license-key=<license-key>,x-arms-project=<arms-project>,x-cms-workspace=<workspace>"
    export OTEL_RESOURCE_ATTRIBUTES=service.name=<service name>,acs.cms.workspace=<workspace>,service.version=<service version>,deployment.environment=<environment>
    opentelemetry-instrument <your_run_command>

    Replace the placeholders in the preceding code with the endpoint information that you obtained in Step 1. Replace <your_run_command> with the startup command for your Python application. Examples of <your_run_command> include the following:

    • Normal application: python app.py

    • Flask application: flask run -p 8000

    • Django application: python manage.py runserver --noreload

    • uWSGI application: uwsgi --http :8000 --module app.wsgi

    • Gunicorn application: gunicorn app:app --bind=127.0.0.1:8000 or gunicorn app:app --workers 2 --worker-class uvicorn.workers.UvicornWorker --bind 127.0.0.1:8000 (multi-worker mode)

    • Uvicorn application: uvicorn app:app --host localhost --port 8000

    Note

    When you use automatic instrumentation, do not enable hot reloading configurations, such as --reload or reload=True. Otherwise, OpenTelemetry automatic instrumentation will fail. Hot reloading is enabled by default in Django development environments. To use OpenTelemetry automatic instrumentation, you must explicitly specify the --noreload parameter. OpenTelemetry automatic instrumentation does not currently support the multi-worker mode for Uvicorn applications.

Manual instrumentation

  1. Download the required packages.

    pip install opentelemetry-api
    pip install opentelemetry-sdk
    pip install opentelemetry-exporter-otlp
  2. Create a Python demo application.

    Create a main.py file and add the following content:

    from opentelemetry import trace, baggage
    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter as OTLPSpanHttpExporter
    from opentelemetry.sdk.resources import DEPLOYMENT_ENVIRONMENT, HOST_NAME, Resource, SERVICE_NAME, SERVICE_VERSION
    from opentelemetry.sdk.trace import TracerProvider
    from opentelemetry.sdk.trace.export import BatchSpanProcessor
    
    def inner_method():
        tracer = trace.get_tracer(__name__)
        with tracer.start_as_current_span("child_span") as child_span:
            print("hello world")
    
    def outer_method():
        tracer = trace.get_tracer(__name__)
        with tracer.start_as_current_span("parent_span") as parent_span:
            inner_method()
    
    # Initialize OpenTelemetry
    def init_opentelemetry():
        # Set the service name and hostname.
        resource = Resource(attributes={
            SERVICE_NAME: "<service name>",  # Application name.
            SERVICE_VERSION: "<service version>",  # Version number.
            DEPLOYMENT_ENVIRONMENT: "<environment>", # Deployment environment.
            HOST_NAME: "${hostName}", # Replace ${hostName} with the hostname.
            "acs.cms.workspace": "<workspace>"  # Replace <workspace> with your workspace name.
        })
        
        headers = {
            "x-arms-license-key": "<license-key>",  # Replace <license-key> with the endpoint information obtained in Step 1.
            "x-arms-project": "<arms-project>",  # Replace <arms-project> with the endpoint information obtained in Step 1.
            "x-cms-workspace": "<workspace>"  # Replace <workspace> with your workspace name.
        }
        
        # Report data over HTTP.
        span_processor = BatchSpanProcessor(OTLPSpanHttpExporter(
            endpoint="<endpoint>",  # Replace <endpoint> with the endpoint information obtained in Step 1.
            headers=headers
        ))
        
        trace_provider = TracerProvider(resource=resource, active_span_processor=span_processor)
        trace.set_tracer_provider(trace_provider)
    
    if __name__ == '__main__':
        init_opentelemetry()
        outer_method()
  3. Start the application.

    python main.py

View monitoring data

  1. Log on to the Cloud Monitor 2.0 console, and select a workspace. In the left navigation pane, choose Application Center > Application Observability > Application Insights.

  2. On the Application List page, click the name of the target application to view its monitoring details. For more information, see Application Monitoring.