tencent cloud

腾讯云可观测平台

动态与公告
产品动态
产品简介
产品概述
产品优势
基本功能
基本概念
应用场景
使用限制
购买指南
云产品监控
应用性能监控
终端性能监控
前端性能监控
云拨测
Prometheus 监控服务
Grafana 服务
事件总线
云压测
快速入门
监控概览
实例分组
云产品监控
应用性能监控
云拨测
云压测
Prometheus 监控服务
Grafana 服务
创建 Dashboard
事件总线
告警服务
云产品监控
云产品监控指标
控制台操作指南
云服务器监控组件
云产品监控对接 Grafana
故障处理
实践教程
应用性能监控
应用性能监控简介
接入指南
控制台操作指南
实践教程
参考信息
常见问题
终端性能监控
终端性能监控概述
控制台操作指南
接入指南
实践教程
前端性能监控
前端性能监控简介
控制台操作指南
接入指南
常见问题
云拨测
产品简介
控制台操作指南
常见问题
云压测
云压测概述
控制台操作指南
实践教程
JavaScript API 列表
常见问题
Prometheus 监控
Prometheus 监控简介
接入指南
控制台操作指南
实践教程
Terraform
常见问题
Grafana 服务
产品简介
控制台操作指南
Grafana 平台常用功能指引
常见问题
Dashboard
什么是 Dashboard
控制台操作指南
告警管理
控制台操作指南
故障处理
常见问题
事件总线
事件总线简介
控制台操作指南
实践教程
常见问题
报表管理
常见问题
腾讯云可观测平台常见问题
告警服务相关
一般性问题
监控图表相关
云服务器监控组件相关
动态阈值告警相关
云监控对接 Grafana 相关
文档阅读指南
相关协议
应用性能监控服务等级协议
APM 隐私协议
APM 数据处理和安全协议
前端性能监控服务等级协议
终端性能监控服务等级协议
云拨测服务等级协议
Prometheus 监控服务服务等级协议
Grafana 服务服务等级协议
云压测服务等级协议
云压测使用限制
Cloud Monitor Service Level Agreement
词汇表
文档腾讯云可观测平台应用性能监控接入指南接入 Python 应用通过 OpenTelemetry-Python 接入 Python 应用(推荐)

通过 OpenTelemetry-Python 接入 Python 应用(推荐)

PDF
聚焦模式
字号
最后更新时间: 2025-10-13 19:10:49
说明:
OpenTelemetry 是工具、API 和 SDK 的集合,用来检测、生成、收集和导出遥测数据(指标、日志和跟踪),帮助用户分析软件的性能和行为。关于 OpenTelemetry 的更多信息请参考 OpenTelemetry 官方网站
OpenTelemetry 社区活跃,技术更迭迅速,广泛兼容主流编程语言、组件与框架,为云原生微服务以及容器架构的链路追踪能力广受欢迎。
本文将通过相关操作介绍如何通过社区的 OpenTelemetry-Python 方案接入 Python 应用。
OpenTelemetry-Python 方案对于 Python 系的常用依赖库和框架,包括 Flask、Django、FastAPI、MySQL Connector 等,提供了自动埋点,在不需要修改代码的情况下就能实现链路信息的上报。其他支持自动埋点的依赖库和框架请参考 OpenTelemetry 社区提供的 完整列表

前提条件

此方案支持 Python 3.6及以上版本。

Django 应用注意事项

如果您的应用使用 Django 框架,通过 OpenTelemetry-Python 方案接入前需要注意如下事项:
推荐使用 uWSGI 方式部署服务,部署方式请参考 通过 uWSGI 托管 Django 应用,直接通过 Python 命令启动可能会造成上报失败。
OpenTelemetry-Python 的引入,可能会导致 Django 应用不再使用默认的配置文件,需要通过环境变量重新指定配置文件。
export DJANGO_SETTINGS_MODULE=mysite.settings

gevent 应用注意事项

如果项目中将 gevent 作为协程库与 Python 自动埋点探针结合使用,可能会出现一系列问题,包括启动报错、Span 异常断链等问题。以下是几种可能的解决方案:
gevent.monkey.patch_all() 需要尽早执行:gevent 通过 monkey patching 修改 Python 标准库中的阻塞式 I/O 操作,使其变为非阻塞式,以适应协程的并发模型。OpenTelemetry 的自动埋点探针也可能依赖或修改标准库的行为。如果 monkey patching 的顺序不当,或者 OpenTelemetry 探针在 gevent 完成 patching 之前加载了某些模块,就可能造成启动报错 RecursionError
from gevent import monkey
monkey.patch_all() # 尽可能早地执行

# 之后再导入其他模块和 OpenTelemetry 相关库
from flask import Flask
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
# ... 其他 OpenTelemetry 配置和应用代码
如果您在使用 Gunicorn 作为 Python 程序的 HTTP 服务器,我们更推荐用 uvicorn 或 gthread 替换 gevent 作为 worker class,以避免潜在的问题。

uWSGI 应用注意事项

uWSGI 使用 master-worker 多进程模型,以下情况可能导致 OpenTelemetry 埋点失败:
插桩代码在 master 进程中初始化,但实际请求在 worker 进程中处理。
worker 进程 fork 后,某些插桩组件可能没有正确继承。
为了保证埋点的成功,可以启用 --lazy-apps 参数,其作用是让每个 worker 独立加载应用,示例如下:
[uwsgi]
module = your_app:application
master = true
processes = 4
lazy-apps = true # 重要:延迟应用加载
enable-threads = true

示例 Demo

所需依赖如下。
pip install flask
pip install mysql-connector-python
pip install redis
pip install requests
示例代码 app.py 通过 Flask 框架提供3个 HTTP 接口,对应的 MySQL 和 Redis 服务请自行搭建,或直接购买云产品。
from flask import Flask
import requests
import time
import mysql.connector
import redis

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

app = Flask(__name__)

# 访问外部站点
@app.route('/')
def index():
start = time.time()
r = requests.get(backend_addr)
return r.text

# 访问数据库
@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

# 访问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)

获取接入点和 Token

1. 登录 腾讯云可观测平台 控制台。
2. 在左侧菜单栏中选择应用性能监控 > 应用列表,单击接入应用
3. 在右侧弹出的接入应用抽屉框中,单击 Python 语言。
4. 接入 Python 应用页面,选择您所要接入的地域以及业务系统
5. 选择接入协议类型OpenTelemetry
6. 上报方式选择您所想要的上报方式,获取您的接入点Token
说明:
内网上报:使用此上报方式,您的服务需运行在腾讯云 VPC。通过 VPC 直接联通,在避免外网通信的安全风险同时,可以节省上报流量开销。
外网上报:当您的服务部署在本地或非腾讯云 VPC 内,可以通过此方式上报数据。请注意外网通信存在安全风险,同时也会造成一定上报流量费用。

接入 Python 应用

步骤1:安装所需的依赖包

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

opentelemetry-bootstrap -a install

步骤2:添加运行参数

通过如下命令启动 Python 应用。
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
对应的字段说明如下:
<serviceName> :应用名,多个使用相同 serviceName 接入的应用进程,在 APM 中会表现为相同应用下的多个实例。应用名最长63个字符,只能包含小写字母、数字及分隔符“ - ”,且必须以小写字母开头,数字或小写字母结尾。
<token> :前置步骤中拿到业务系统 Token。
<hostName>:该实例的主机名,是应用实例的唯一标识,通常情况下可以设置为应用实例的 IP 地址。
<endpoint> :前置步骤中拿到的接入点。
下述内容以应用名为 myService,业务系统 Token 为 myToken,主机名为 192.168.0.10,接入点以 https://pl-demo.ap-guangzhou.apm.tencentcs.com:4317 为例,完整的启动命令为如下。
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

接入验证

启动 Python 应用后,通过8080端口访问对应的接口,例如 https://localhost:8080/。在有正常流量的情况下,应用性能监控 > 应用列表 中将展示接入的应用,单击应用名称/ID 进入应用详情页。再选择实例分析,即可看到接入的应用实例。由于可观测数据的处理存在一定延时,如果接入后在控制台没有查询到应用或实例,请等待30秒左右。

自定义埋点(可选)

当自动埋点不满足您的场景或者需要增加业务层埋点时,您可参照下述内容,使用 OpenTelemetry API 添加自定义埋点。本文仅展示最基本的自定义埋点方式,OpenTelemetry 社区提供了更多灵活的自定义埋点方式,具体使用方法可参考 OpenTelemetry 社区提供的 Python 自定义埋点文档
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) # 对于requests.get()发起的外部请求,OpenTelemetry-Python会自动埋点
slow() # 调用一个自定义函数
return r.text

def slow():
tracer = trace.get_tracer(__name__)
# 自定义函数不在OpenTelemetry-Python自动埋点范围内,因此增加一个自定义埋点
with tracer.start_as_current_span("child_span")
time.sleep(5)
return

问题排查

如果发现自动埋点无法上报数据到 APM,可以通过设置 --traces_exporter=console,otlp_proto_grpc 将链路数据打印到控制台,如果发现控制台中有 span 和 trace 等输出,但是 APM 中没有数据,则排查是否是 endpoint 和 token 有误;如果发现控制台中没有相关的输出,可以检查应用程序所使用的框架或组件是否在 OpenTelemetry 支持的 完整列表 中。如果无法确认具体问题,可以向我们 提交工单

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈