OpenTelemetry — это фреймворк и набор инструментов для наблюдаемости, предназначенные для создания и управления данными телеметрии, такими как трассировки, метрики и журналы. Посетите Что такое OpenTelemetry?, чтобы узнать о возможностях OpenTelemetry.

Connector/Python поддерживает только трассировку, поэтому в этом руководстве отсутствует информация о сигналах метрик и журналов.

Установите пакеты OpenTelemetry API, SDK и OTLP Exporter на систему вместе с 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

Или передайте [telemetry] при установке Connector/Python, чтобы выполнить те же действия, но установить конкретную и проверенную версию 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], которая устанавливала свёрнутую версию библиотек SDK/API OpenTelemetry. В этих версиях это не рекомендовалось.

Для инструментирования приложения Connector/Python использует официальный SDK OpenTelemetry для инициализации OpenTelemetry и официальный API OpenTelemetry для инструментирования кода приложения. Это генерирует телеметрию из приложения и используемых библиотек, которые включают инструментирование.

Приложение можно инструментировать, как показано в этом общем примере:

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.

Если система не поддерживает OpenTelemetry, при попытке использовать инструментировщик возникает исключение.

Пример, который использует SDK/API OpenTelemetry системы и реализует отслеживание с 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, содержит один span подключения и ноль или более spans запросов, как описано в остальной части этого раздела.

Span подключения

Span запроса

Распространение контекста

По умолчанию контекст трассировки текущего span (если он есть) распространяется на MySQL-сервер.

Распространение не имеет эффекта, когда MySQL-сервер отключил или не поддерживает OpenTelemetry (контекст трассировки игнорируется сервером), однако, при подключении к серверу с включенным и настроенным OpenTelemetry, сервер обрабатывает распространённые трассировки и создаёт родительско-дочерние связи между spans от подключение и теми, которые исходят от сервера. Другими словами, это обеспечивает непрерывность трассировки.

Логическая свойство подключения с именем otel_context_propagation по умолчанию True. Установка его в False отключает распространение контекста.

Поскольку otel_context_propagation — это свойство подключения, которое можно изменить после установления подключения (объект подключения создан), установка такого свойства в False не влияет на spans, сгенерированные во время фазы подключения. Другими словами, spans, сгенерированные во время фазы подключения, всегда распространяются, поскольку otel_context_propagation по умолчанию True.

Эта реализация отличается от реализации, предоставленной через MySQL-библиотеку клиента (или связанный telemetry_client плагин клиентской стороны).