本文提供如何設定 Azure SDK for Java 以整合追蹤功能的概觀。
你可以透過使用 OpenTelemetry SDK 或使用相容的 OpenTelemetry 代理程式，在 Azure 用戶端函式庫中啟用追蹤功能。 OpenTelemetry 是熱門的開放原始碼可觀察性架構，可用於產生、擷取及收集雲端原生軟體的遙測數據。
與追蹤相關的兩個關鍵概念是 span 和 trace。 一個跨度代表追蹤中的單一操作。 範圍可以代表 HTTP 要求、遠端過程調用 （RPC）、資料庫查詢，甚至是程式代碼採用的路徑。 追蹤記錄是由範圍組成的樹狀結構，用來顯示系統中工作流程的路徑。 一個獨特的 16 位元組序列稱為 TraceID 用來區分追蹤。 如需了解這些概念及其與 OpenTelemetry 的關聯，請參閱 OpenTelemetry 文件。
使用 Azure 監視器 Java 代理程式進行 Azure SDK 追蹤
藉由使用 Azure 監視器 Java 行程代理程式，您可以啟用應用程式監視，而不需要變更任何程式代碼。 如需詳細資訊，請參閱 Azure 監視器 基於 OpenTelemetry 的 Java 應用程式自動偵測。 從代理程式 3.2 版開始，預設會啟用 Azure SDK 支援。
使用 OpenTelemetry 代理程式進行 Azure SDK 追蹤
如果你使用 OpenTelemetry Java agent，Azure SDK 儀器化從 1.12.0 版開始便已啟用。
如需更詳細的資訊以設定匯出器、新增手動儀器化或增強遙測，請參閱 Java 用的 OpenTelemetry 儀器化。
注意
OpenTelemetry 代理程式構件是穩定的，但不保證傳輸中遙測資料的穩定性。 此情況可能會導致 Azure SDK 產生的 Span 名稱和屬性名稱在您更新代理程式後隨時間而改變。 如需詳細資訊，請參閱相容性需求。
使用 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 隱含傳播為新 span 的父代。 在異步呼叫中，隱含內容傳播會中斷。 OpenTelemetry 代理程式藉由協助傳播上下文來解決此問題，但 OpenTelemetry SDK 沒有這類功能。
明確傳遞追蹤上下文
Azure SDK 允許在com.azure.core.util.Context 鍵下透過 trace-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 驗證，以了解如何建立安全的應用程式。