Глава 13 Использование Connector/J с OpenTelemetry

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

Проект OpenTelemetry предоставляет автоматическую инструментировку для библиотек JDBC. Однако, когда речь заходит о распределенной трассировке, автоматическая инструментировка не способна распространять контекст на уровень базы данных, что приводит к разрыву цепочки трассировки. Кроме того, автоматическая инструментировка применяется только к видимой части инструментировки JDBC, исключая любые внутренние операции, которые также заслуживают трассировки.

MySQL Enterprise Server 8.4.0 имеет возможность сбора данных наблюдаемости для операций сервера в формате OpenTelemetry (см. для получения подробностей). Данная функция поддерживается . MySQL Connector/J 8.4.0 представляет собой соответствующую функцию на стороне клиента, с возможностью распространения контекста на MySQL-сервер, к которому он подключается, и обеспечивает более полную наблюдаемость для стека приложения.

Приложения, использующие Connector/J, которые хотят включить трассировку OpenTelemetry, нуждаются в следующих сторонних библиотеках:

Свойство подключения Connector/J openTelemetry контролирует обработку производства данных наблюдаемости для каждого подключения. Этот параметр принимает следующие значения:

Отсутствие значения для свойства эквивалентно установке его как PREFERRED, за исключением того, что не выводится предупреждение, когда библиотека OpenTelemetry недоступна во время выполнения.

Обратите внимание, что MySQL Connector/J не предоставляет средств для настройки собственных экспортеров OpenTelemetry — он полностью полагается на вызывающее приложение для настройки экспортера.

Следующее демонстрирует использование OpenTelemetry. Предполагается, что клиентское приложение, MySQL-сервер и бэкенд наблюдаемости работают на одной машине. Также предполагается, что функция включена и правильно настроена на MySQL-сервере. Агент Java используется для простоты. Также используется библиотека opentelemetry-instrumentation-annotations, поэтому нет необходимости писать код OpenTelemetry в демонстрационном классе.

Эта простая демонстрация содержит класс OTelDemo, который создаёт подключение к базе данных Sakila и выполняет SQL-запрос SELECT, возвращающий пять строк из таблицы film. Цель демонстрации — просто сгенерировать последовательность трассировок, а не получить что-либо практически полезное. Вот содержимое исходного файла src/demo/OTelDemo.java.

package demo;
import java.sql.*;
import io.opentelemetry.instrumentation.annotations.WithSpan;
public class OTelDemo {
    public static void main(String[] args) throws Exception {
        listFiveFilms();
    }
    @WithSpan
    private static void listFiveFilms() throws Exception {
        try (Connection conn = DriverManager.getConnection("jdbc:mysql://johndoe:s3cr3t@localhost:3306/sakila")) {
            Statement stmt = conn.createStatement();
            ResultSet rs = stmt.executeQuery("SELECT * FROM film LIMIT 5");
            while (rs.next()) {
                System.out.println(rs.getString(2));
            }
        }
    }
}

Основная трассировка наблюдается в коде приложения с помощью аннотации @WithSpan. Эта трассировка становится текущим контекстом (родительским) для любых последующих отрезков, созданных внутри драйвера JDBC. Впоследствии, посредством распространения контекста с выполненными командами, трассировка, созданная драйвером, становится родителем отрезков, созданных на MySQL-сервере.

Код можно скомпилировать, используя команду:

$ javac -classpath "lib/*" -d bin src/demo/OTelDemo.java

Перед запуском демонстрации настройте бэкенд наблюдаемости, например, с помощью Jaeger. Затем можно выполнить код с помощью команды:

$ java -javaagent:agent/opentelemetry-javaagent.jar \
  -Dotel.traces.exporter=jaeger \
  -Dotel.metrics.exporter=none \
  -Dotel.service.name=OTelDemo \
  -Dotel.instrumentation.common.default-enabled=false \
  -Dotel.instrumentation.opentelemetry-api.enabled=true \
  -Dotel.instrumentation.opentelemetry-instrumentation-annotations.enabled=true \
  -classpath "bin:lib/*" \
  demo.OTelDemo
 [otel.javaagent 2024-04-12 16:10:32:140 +0100]
 [main] INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: 1.32.0
 ACADEMY DINOSAUR
 ACE GOLDFINGER
 ADAPTATION HOLES
 AFFAIR PREJUDICE
 AFRICAN EGG 

Теперь можно открыть бэкенд Jaeger в браузере и найти трассировки службы OTelDemo.

Распределённая трассировка в MySQL ограничена выполнением запросов. Это ограничение обусловлено тем, что распространение контекста реализовано через атрибуты запросов и поддерживается только для выполнения запросов. Во время выполнения сервер генерирует отрезки и для других операций. Эти отрезки также могут быть видны в бэкенде наблюдаемости, но они не связаны с какой-либо из трассировок, начатых клиентским приложением или библиотекой. Аналогично, отрезки, созданные Connector/J, которые не генерируют команды сервера или генерируют команды, не поддерживающие атрибуты запросов, изображаются как терминальные узлы в графиках трассировки. Это демонстрируется командой PING. Тем не менее, сервер по-прежнему генерирует отрезок для соответствующей операции, просто он выглядит не связанным с исходной трассировкой.