tencent cloud

Connecting Python Applications Using OpenTelemetry-Python (Recommended)
Download PDF
Last updated: 2025-10-13 19:10:49
Connecting Python Applications Using OpenTelemetry-Python (Recommended)
Last updated: 2025-10-13 19:10:49
Download PDF
Note:
OpenTelemetry is a collection of tools, APIs, and SDKs for monitoring, generating, collecting, and exporting telemetry data (metrics, logs, and traces) to help users analyze the performance and behavior of the software. For more information about OpenTelemetry, see the OpenTelemetry official website.
The OpenTelemetry community is active, with rapid technological changes, and widely compatible with mainstream programming languages, components, and frameworks, making its link-tracing capability highly popular for cloud-native microservices and container architectures.
This document will introduce how to connect Python applications using the OpenTelemetry-Python scheme provided by the community.
The OpenTelemetry-Python scheme provides automatic Event Tracking for commonly used dependency libraries and frameworks in the Python ecosystem, including Flask, Django, FastAPI, MySQL Connector, etc., enabling link information reporting without needing to modify the code. For other dependency libraries and frameworks that support automatic Event Tracking, see the complete list provided by the OpenTelemetry community.

Prerequisites

This scheme supports Python 3.6 and above.

Django Application Precautions

If your application uses the Django framework, pay attention to the following matters before access through the OpenTelemetry-Python solution:
Deploy the service using uWSGI. For deployment methods, see through uWSGI hosting Django application. Starting directly through Python command may cause reporting failure.
Introducing OpenTelemetry-Python may lead to Django application no longer using the default configuration file. Re-specify the configuration file through environment variables.
export DJANGO_SETTINGS_MODULE=mysite.settings

Gevent Application Notes

If the project uses gevent as the coroutine library in conjunction with the Python automatic event tracking probe, a series of issues may occur, including startup error and Span chain break. The following are several possible solutions:
gevent.monkey.patch_all() must be executed as soon as possible: gevent modifies blocking I/O operations in Python standard library through monkey patching to make them non-blocking, adapting to the concurrency model of coroutines. OpenTelemetry's automatic event tracking probe may also depend on or modify standard library behavior. If the order of monkey patching is improper, or if the OpenTelemetry probe loads specific modules before gevent completes patching, it may cause startup error RecursionError.
from gevent import monkey
monkey.patch_all() # Execute as early as possible

# then import other modules and OpenTelemetry-related libraries
from flask import Flask
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
# ... other OpenTelemetry configurations and application code
If you are using Gunicorn as the HTTP server for your Python program, we recommend replacing gevent with uvicorn or gthread as the worker class to avoid potential issues.

UWSGI Application Notes

uWSGI uses a master-worker multiprocessing model. The following scenarios may cause OpenTelemetry instrumentation to fail:
Instrumentation code is initialized in the master process, but actual requests are processed in worker processes.
Worker processes may not correctly inherit specific instrumentation components after a fork.
To ensure successful instrumentation, enable the --lazy-apps parameter. It enables each worker to independently load the application, as shown below:
[uwsgi]
module = your_app:application
master = true
processes = 4
lazy-apps = true  # Important: delay application loading
enable-threads = true

Demo

Required dependencies are as follows:
pip install flask
pip install mysql-connector-python
pip install redis
pip install requests
The demo code app.py provides 3 HTTP APIs through the Flask framework. Set up the corresponding MySQL and Redis services yourself or directly purchase Cloud Services.
from flask import Flask
import requests
import time
import mysql.connector
import redis

backend_addr = 'https://example.com/' 

app = Flask(__name__)

# Accessing External Site
@app.route('/')
def index():
    start = time.time()
    r = requests.get(backend_addr)
    return r.text

# Accessing Database
@app.route('/mysql')
def func_rdb():
    cnx = mysql.connector.connect(host='127.0.0.1', database="<DB-NAME>", user='<DB-USER>', password='<DB-PASSWORD>', auth_plugin='mysql_native_password')
    cursor = cnx.cursor()
    val = "null"
    cursor.execute("select value from table_demo where id=1;")
    val = cursor.fetchone()[0]
    cursor.close()
    cnx.close()
    return "rdb res:" + val

# Accessing Redis
@app.route("/redis")
def func_kvop():
    client = redis.StrictRedis(host="localhost", port=6379)
    val = "null"
    val = client.get('foo').decode("utf8")
    return "kv res:" + val

app.run(host='0.0.0.0', port=8080)

Get the connect point and Token.

1. Log in to the TCOP console.
2. In the left menu column, select Application Performance Management > Application list, and click Access application.
3. In the Access application drawer frame that pops up on the right, click the Python language.
4. On the Access Python application page, select the Region and Business System you want to connect.
5. Select Access protocol type as OpenTelemetry.
6. Reporting method Choose your desired reporting method, and obtain your Access Point and Token.
Note:
Private network reporting: Using this reporting method, your service needs to run in the Tencent Cloud VPC. Through VPC connecting directly, you can avoid the security risks of public network communication and save on reporting traffic overhead.
Public network reporting: If your service is deployed locally or in non-Tencent Cloud VPC, you can report data in this method. However, it involves security risks in public network communication and incurs reporting traffic fees.

Connecting Python Applications

Step 1: Install the required dependency packets.

pip install opentelemetry-instrumentation-redis
pip install opentelemetry-instrumentation-mysql
pip install opentelemetry-distro opentelemetry-exporter-otlp

opentelemetry-bootstrap -a install

Step 2: Add runtime parameters.

Start the Python application with the following command.
opentelemetry-instrument \\
--traces_exporter otlp_proto_grpc \\
--metrics_exporter none \\
--logs_exporter none \\
--service_name <serviceName> \\
--resource_attributes token=<token>,host.name=<hostName> \\
--exporter_otlp_endpoint <endpoint> \\
python3 app.py
The corresponding field descriptions are as follows:
<serviceName>: Application name. Multiple application processes connecting with the same serviceName are displayed as multiple instances under the same application in APM. The application name can be up to 63 characters and can only contain lowercase letters, digits, and the separator (-), and it must start with a lowercase letter and end with a digit or lowercase letter.
<token>: The business system Token obtained in the preliminary steps.
<hostName>: The hostname of this instance, which is the unique identifier of the application instance. It can usually be set to the IP address of the application instance.
<endpoint>: The connect point obtained in the preliminary steps.
The content below uses myService as the application name, myToken as the Business System Token, 192.168.0.10 as the hostname, and https://pl-demo.ap-guangzhou.apm.tencentcs.com:4317 as the connect point example, the complete startup command is:
opentelemetry-instrument \\
--traces_exporter otlp_proto_grpc \\
--metrics_exporter none \\
--logs_exporter none \\
--service_name myService \\
--resource_attributes token=myToken,host.name=192.168.0.10 \\
--exporter_otlp_endpoint https://pl-demo.ap-guangzhou.apm.tencentcs.com:4317/ \\
python3 app.py

Connection Verification

After the Python application starts, access the corresponding API through port 8080, for example, https://localhost:8080/. In normal traffic cases, the connected application will be displayed in APM > Application List. Click Application name/ID to enter the application details page, then select Instance Analysis to view the connected application instance. Since there is a certain delay in the processing of observable data, if the application or instance is not found on the console after connection, wait for about 30 seconds.

Custom Event Tracking (Optional)

When automatic Event Tracking does not meet your scenario, or you need to add business layer Event Tracking, you can see the content below and use the OpenTelemetry API to add custom Event Tracking. This document only shows the most basic custom Event Tracking method. The OpenTelemetry community offers more flexible custom Event Tracking. For specific methods of use, you can see the Python Custom Event Tracking Documentation provided by the OpenTelemetry community.
from opentelemetry import trace
import requests
from flask import Flask
import time

backend_addr = 'https://example.com/' 
app = Flask(__name__)
 
@app.route('/')
def index():
   r = requests.get(backend_addr) # For external requests initiated by requests.get(), OpenTelemetry-Python will perform automatic Event Tracking.
    slow() # Call a custom function
    return r.text

def slow():
    tracer = trace.get_tracer(__name__)
    # Custom functions are not within the automatic Event Tracking range of OpenTelemetry-Python; therefore, add a custom Event Tracking.
    with tracer.start_as_current_span("child_span")  
        time.sleep(5)
        return

Issue Troubleshooting

If automatic event tracking fails to report data to APM, you can set --traces_exporter=console,otlp_proto_grpc to print link data to the console. If spans and traces are output in the console but no data appears in APM, check whether the endpoint and token are correct. If there is no output in the console, verify whether the framework or component used by the application is in the complete list supported by OpenTelemetry. If the specific issue cannot be identified, you may submit a ticket to us.

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback