在 Azure SDK for Java 中設定追蹤

本文提供如何設定 Azure SDK for Java 以整合追蹤功能的概觀。

您可以使用 和 設定 OpenTelemetry SDK 或使用與 OpenTelemetry 相容的代理程式，在 Azure 用戶端連結庫中啟用追蹤。 OpenTelemetry 是熱門的開放原始碼可觀察性架構，可用於產生、擷取及收集雲端原生軟體的遙測數據。

追蹤有兩個重要概念： 範圍 和 追蹤。 範圍代表追蹤中的單一作業。 範圍可以代表 HTTP 要求、遠端過程調用 （RPC）、資料庫查詢，甚至是程式代碼採用的路徑。 追蹤是範圍樹狀結構，其中顯示透過系統的工作路徑。 您可以透過稱為 TraceID 的唯一 16 位元組序列來區別追蹤。 如需這些概念及其與 OpenTelemetry 關聯的詳細資訊，請參閱 OpenTelemetry 檔。

使用 Azure 監視器 Java 代理程式進行 Azure SDK 追蹤

藉由使用 Azure 監視器 Java 行程代理程式，您可以啟用應用程式監視，而不需要變更任何程式代碼。 如需詳細資訊，請參閱 適用於 Java 應用程式的 Azure 監視器 OpenTelemetry 型自動檢測。 從代理程式 3.2 版開始，預設會啟用 Azure SDK 支援。

使用 OpenTelemetry 代理程序追蹤 Azure SDK 呼叫

如果您使用 OpenTelemetry Java 代理程式，從 1.12.0 版開始，即會啟用現用的 Azure SDK 檢測。

如需如何設定導出工具、新增手動檢測或擴充遙測的詳細資訊，請參閱 適用於 Java 的 OpenTelemetry Instrumentation。

注意

OpenTelemetry 代理程式成品穩定，但未提供無線遙測穩定性保證，這可能會導致 Azure SDK 所產生的跨範圍名稱和屬性名稱，如果您更新代理程式，可能會隨著時間而變更。 如需詳細資訊，請參閱 相容性需求。

使用 OpenTelemetry SDK 手動偵測應用程式 （預覽）

如果您直接使用 OpenTelemetry SDK，請務必為您選擇的後端設定 SDK 和導出工具。 如需詳細資訊，請參閱 OpenTelemetry 檔。

若要啟用 Azure SDK 追蹤，請將最新的 com.azure:azure-core-tracing-opentelemetry 套件新增至您的應用程式。 例如，在 Maven 中，將下列專案新增至 您的 pom.xml 檔案：

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-tracing-opentelemetry</artifactId>
</dependency>

如果您現在執行應用程式，您應該會在後端取得 Azure SDK 範圍。 不過，使用異步呼叫時，Azure SDK 與應用程式範圍的相互關聯可能會中斷。

根據預設，Azure SDK 會使用 io.opentelemetry.context.Context.current()由 OpenTelemetry 隱含傳播為新範圍的父代。 在異步呼叫中，隱含內容傳播會中斷。 OpenTelemetry 代理程式藉由協助內容傳播來解決此問題，但 OpenTelemetry SDK 沒有這類功能。

明確傳遞追蹤內容

Azure SDK 允許在金鑰下trace-context明確com.azure.core.util.Context傳遞追蹤內容。 當您提供明確的追蹤內容時，Azure SDK 會使用它，而不是隱含追蹤內容，以啟用應用程式和 Azure SDK 範圍之間的相互關聯。

在下列範例中，以手動方式追蹤連入 Web 要求時，會在此要求的範圍內以異步方式呼叫應用程式組態用戶端連結庫。

Span span = TRACER.spanBuilder("incoming request").startSpan();
io.opentelemetry.context.Context traceContext = io.opentelemetry.context.Context.root().with(span);

// Put the incoming-request span (wrapped into the OpenTelemetry Context) into the Azure SDK Context
// and pass it over to the Application Configuration call.
appConfigClient.setConfigurationSettingWithResponse(settings, true, new com.azure.core.util.Context("trace-context", traceContext));

// You could also pass the context using the reactor `contextWrite` method under the same `trace-context` key.
appConfigAsyncClient.setConfigurationSettingWithResponse(settings)
   .contextWrite(reactor.util.context.Context.of("trace-context", traceContext))

//...

Azure SDK 追蹤慣例

若要瞭解 SDK 發出的範圍和屬性，請參閱 Azure SDK 語意慣例規格。 Azure SDK （和 OpenTelemetry） 語意慣例不穩定，未來可能會變更。

下一步

現在您已熟悉適用於 Java 的 Azure SDK 中的核心跨領域功能，請參閱 使用 Java 和 Azure 身分識別 進行 Azure 驗證，以瞭解如何建立安全的應用程式。