MySQL Connector/J 開發人員指南 / 使用 Connector/J 與 OpenTelemetry

第 13 章使用 Connector/J 與 OpenTelemetry

OpenTelemetry 是一組 API、程式庫、代理程式和工具，可為應用程式及其彼此之間的互動提供可觀察性。它使開發人員能夠檢測他們的程式碼，以便他們可以匯出可觀察性資料，包括追蹤、指標和記錄，從而提高分析、偵錯和測試的精細度。

OpenTelemetry 專案為 JDBC 程式庫提供了自動檢測。然而，在分散式追蹤方面，自動檢測無法將內容傳播到資料庫層，導致追蹤鏈中斷。此外，自動檢測僅適用於 JDBC 檢測的 visible 層，將任何值得追蹤的內部操作排除在外。

MySQL Enterprise Server 8.4.0 具有以 OpenTelemetry 格式收集伺服器操作可觀察性資料的功能（詳情請參閱遙測）。component_telemetry 支援此功能。MySQL Connector/J 8.4.0 引入了用戶端對應功能，能夠將內容傳播到它連接的 MySQL 伺服器，並允許應用程式堆疊更完整的可觀察性。

希望啟用 OpenTelemetry 追蹤的 Connector/J 應用程式需要以下第三方程式庫

opentelemetry-api 程式庫。
opentelemetry-context 程式庫
如果您選擇手動檢測，則使用 opentelemetry-sdk 程式庫；如果您偏好自動檢測，則使用 opentelemetry-javaagent。

Connector/J 連線屬性 openTelemetry 控制每個連線如何處理可觀察性資料的產生。此選項接受以下值

REQUIRED：OpenTelemetry 程式庫必須在執行階段可用，否則與 MySQL 伺服器的連線將會失敗。請注意，單獨的 opentelemtry-api 程式庫不會產生任何輸出追蹤。
PREFERRED：如果 OpenTelemetry 程式庫在執行階段可用，則啟用產生 OpenTelemetry 檢測；如果程式庫不可用，則會發出警告。
DISABLED：關閉由 Connector/J 產生 OpenTelemetry 檢測。但是，這並不會阻止外部檢測方式，例如 OpenTelemetry Java 代理程式提供的自動檢測。

未設定屬性的值相當於將其設定為 PREFERRED，只是在執行階段沒有可用的 OpenTelemetry 程式庫時不會發出警告。

請注意，MySQL Connector/J 不提供任何用於設定其自有 OpenTelemetry 匯出器的方法，它完全依賴於呼叫應用程式進行匯出器設定。

以下是如何使用 OpenTelemetry 的示範。它假設用戶端應用程式、MySQL 伺服器和可觀察性後端都在同一部機器上執行。它還假設 component_telemetry 已啟用並在 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 命令等操作就屬於這種情況。儘管如此，伺服器仍然會為對應的操作產生跨度，只是它看起來與原始追蹤沒有連結。

第 13 章 使用 Connector/J 與 OpenTelemetry

第 13 章使用 Connector/J 與 OpenTelemetry