MySQL Connector/Python 发行说明
MySQL 服务器在 MySQL 企业版 8.1.0 中添加了 OpenTelemetry 支持，这是一个 商业产品。Connector/Python 8.1.0 中添加了 OpenTelemetry 跟踪支持。
OpenTelemetry 是一个可观测性框架和工具包，旨在创建和管理遥测数据，例如跟踪、指标和日志。访问 什么是 OpenTelemetry？ 以获取有关 OpenTelemetry 功能的说明。
Connector/Python 仅支持跟踪，因此本指南不包含有关指标和日志信号的信息。
在系统上安装 OpenTelemetry API、SDK 和 OTLP Exporter 包以及 Connector/Python。或者，在安装 mysql-connector-python pip 包时使用 [telemetry] 快捷方式来引入连接器定义的特定 OpenTelemetry 版本。
手动安装
pip install opentelemetry-api
pip install opentelemetry-sdk
pip install opentelemetry-exporter-otlp-proto-http
pip install mysql-connector-python或者在安装 Connector/Python 时传入 [telemetry] 以执行相同的操作，但它会安装特定且经过测试的 OpenTelemetry 版本，对于 Connector/Python 9.0.0 而言，该版本为 OpenTelemetry v1.18.0
pip install mysql-connector-python[telemetry]Connector/Python 8.1.0 到 8.4.0 包含一个 [opentelemetry] 选项，用于安装 OpenTelemetry SDK/API 库的捆绑版本。不建议在这些版本中这样做。
为了对应用程序进行仪表化，Connector/Python 利用官方的 OpenTelemetry SDK 来初始化 OpenTelemetry，并利用官方的 OpenTelemetry API 来对应用程序的代码进行仪表化。这将从应用程序和包含仪表化的已利用库中发出遥测数据。
可以按照此通用示例演示对应用程序进行仪表化
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.trace.export import ConsoleSpanExporter
provider = TracerProvider()
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("app"):
my_app()要更好地理解和开始使用 OpenTelemetry 跟踪 Python，请参阅官方 OpenTelemetry Python 仪表化 指南。
Connector/Python 包含一个 MySQL 仪表器，用于对 MySQL 连接进行仪表化。此仪表器的 API 和用法类似于 OpenTelemetry 自己的名为 opentelemetry-instrumentation-mysql 的 MySQL 包。
如果系统在尝试使用仪表器时不支持 OpenTelemetry，则会引发异常。
一个使用系统的 OpenTelemetry SDK/API 并使用 MySQL Connector/Python 实现跟踪的示例
import os
import mysql.connector
# An instrumentor that comes with mysql-connector-python
from mysql.connector.opentelemetry.instrumentation import (
MySQLInstrumentor as OracleMySQLInstrumentor,
)
# Loading SDK from the system
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.trace.export import ConsoleSpanExporter
provider = TracerProvider()
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
tracer = trace.get_tracer(__name__)
config = {
"host": "127.0.0.1",
"user": "root",
"password": os.environ.get("password"),
"use_pure": True,
"port": 3306,
"database": "test",
}
# Global instrumentation: all connection objects returned by
# mysql.connector.connect will be instrumented.
OracleMySQLInstrumentor().instrument()
with tracer.start_as_current_span("client_app"):
with mysql.connector.connect(**config) as cnx:
with cnx.cursor() as cur:
cur.execute("SELECT @@version")
_ = cur.fetchall()Connector/Python 仪表器生成的跟踪包含一个连接跨度和零个或多个查询跨度，如本节其余部分所述。
连接跨度
从连接初始化到连接结束的时间。该跨度名为
connection。如果应用程序未提供跨度，则生成的连接跨度是 ROOT 跨度，起源于连接器。
如果应用程序确实提供了跨度，则生成的查询跨度是 CHILD 跨度，起源于连接器。
查询跨度
从请求 SQL 语句（在连接器端）到连接器完成处理服务器对该语句的回复的时间。
为发送到服务器的每个查询请求创建一个查询跨度。如果应用程序未提供跨度，则生成的查询跨度是 ROOT 跨度，起源于连接器。
如果应用程序确实提供了跨度，则生成的查询跨度是 CHILD 跨度，起源于连接器。
查询跨度链接到执行查询的连接的现有连接跨度。
从 MySQL 企业版 8.3.0 开始支持使用预处理语句的查询属性。
从 Connector/Python 8.3.0 开始支持连接对象的查询跨度，其中包括 commit()、rollback() 和 cmd_change_user() 等方法。
上下文传播
默认情况下，正在进行的跨度（如果有）的跟踪上下文将传播到 MySQL 服务器。
当 MySQL 服务器禁用或不支持 OpenTelemetry 时，传播不起作用（跟踪上下文被服务器忽略），但是，当连接到启用了 OpenTelemetry 并配置的服务器时，服务器会处理传播的跟踪并在来自连接器的跨度和来自服务器的跨度之间创建父子关系。换句话说，这提供了跟踪连续性。
注意
从 MySQL 企业版 8.3.0 开始支持使用预处理语句的上下文传播。
-
跟踪上下文是针对在 MySQL 客户端/服务器协议中定义了查询属性的语句传播的，例如 COM_QUERY。
跟踪上下文不针对在 MySQL 客户端/服务器协议中未定义查询属性的语句传播，例如 COM_PING。
-
跟踪上下文传播是通过查询属性完成的，其中定义了一个名为“traceparent”的新属性。其值基于当前跨度上下文。有关如何计算此值的详细信息，请阅读 traceparent 标头 W3C 规范。
如果为查询手动设置了“traceparent”查询属性，则连接器不会覆盖它；假设它提供了要转发到服务器的 OTel 上下文。