OpenTelemetry 是一個可觀測性架構和工具組，旨在建立和管理遙測資料，例如追蹤、度量和記錄。如需 OpenTelemetry 功能的說明，請造訪 什麼是 OpenTelemetry？。

Connector/Python 僅支援追蹤，因此本指南不包含有關度量和記錄訊號的資訊。

在系統上安裝 OpenTelemetry API、SDK 和 OTLP 匯出器套件以及 Connector/Python。選擇性地使用 [telemetry] 快捷方式安裝 mysql-connector-python pip 套件，以提取連線器定義的特定 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()

如需更深入了解並開始使用 Python 的 OpenTelemetry 追蹤，請參閱官方 OpenTelemetry Python 檢測指南。

Connector/Python 包含 MySQL 檢測器，用來檢測 MySQL 連線。此檢測器提供類似於 OpenTelemetry 自己的 MySQL 套件（名為 opentelemetry-instrumentation-mysql）的 API 和用法。

如果系統在嘗試使用檢測器時不支援 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 檢測器產生的追蹤包含一個連線跨度，以及零個或多個查詢跨度，如本節其餘部分所述。

連線跨度

查詢跨度

內容傳播

依預設，進行中跨度的追蹤內容（如果有的話）會傳播至 MySQL 伺服器。

當 MySQL 伺服器停用或不支援 OpenTelemetry 時，傳播沒有作用（追蹤內容會被伺服器忽略），但是，當連線至已啟用且設定 OpenTelemetry 的伺服器時，伺服器會處理已傳播的追蹤，並在來自連線器的跨度與來自伺服器的跨度之間建立父子關係。換句話說，這可提供追蹤連續性。

名為 otel_context_propagation 的布林連線屬性預設為 True。將其設定為 False 會停用內容傳播。

由於 otel_context_propagation 是連線建立後可以變更的連線屬性（會建立連線物件），因此將此屬性設定為 False 對於在連線階段產生的跨度沒有影響。換句話說，連線階段產生的跨度一律會傳播，因為 otel_context_propagation 預設為 True。

此實作與透過 MySQL 用戶端程式庫（或相關的 telemetry_client 用戶端外掛程式）提供的實作不同。