本文概述如何在使用 Azure SDK for Java 的應用程式中啟用日誌記錄。 適用於 Java 的 Azure 用戶端連結庫有兩個記錄選項：
- 用於暫時偵錯的內建記錄架構。
- 支援使用 SLF4J 介面進行記錄。
我們建議您使用 SLF4J，因為它在 Java 生態系統中很有名，而且記錄得很好。 如需詳細資訊，請參閱 SLF4J 使用者手動。
本文連結至涵蓋許多熱門 Java 記錄架構的其他文章。 這些其他文章提供組態範例，並描述 Azure 用戶端連結庫如何使用記錄架構。
無論您使用何種記錄組態，在任一情況下都可以使用相同的記錄輸出，因為適用於 Java 的 Azure 用戶端連結庫中的所有記錄輸出都會透過 azure 核心 ClientLogger 抽象概念路由傳送。
本文的其餘部分詳述所有可用記錄選項的設定。
啟用 HTTP 要求/回應記錄
HTTP 要求和回應記錄預設為關閉。 您可以設定透過 HTTP 與 Azure 服務通訊的用戶端，針對他們收到的每個要求和回應（或例外狀況）寫入記錄檔記錄。
如果您使用 OpenTelemetry，請考慮使用分散式追蹤，而不是記錄 HTTP 要求。 如需詳細資訊，請參閱 在 Azure SDK for Java 中設定追蹤。
使用環境變數設定 HTTP 記錄
您可以使用 AZURE_HTTP_LOG_DETAIL_LEVEL 環境變數全域啟用 HTTP 記錄。 此變數支援下列值：
-
NONE：HTTP 記錄已停用。 此值為預設值。 -
BASIC：HTTP 記錄包含要求方法、清理要求URL、嘗試計數、回應碼，以及要求和響應主體的內容長度。 -
HEADERS：HTTP 記錄包含所有基本詳細數據，也包含已知安全用於記錄用途的標頭，亦即，它們不包含秘密或敏感性資訊。 HttpLogOptions 類別中提供標頭名稱的完整清單。 -
BODY_AND_HEADERS：HTTP 記錄包含HEADERS層級所提供的所有詳細資訊，並且包含要求和回應內容，只要它們小於 16 KB 且能列印。
備註
要求 URL 已淨化 - 也就是說，除了 api-version 的值之外，所有查詢參數值都會被遮蔽。 個別客戶端函式庫可能會將已知安全的其他查詢參數新增至允許清單。
例如，Azure Blob 記憶體共用存取簽章 （SAS） URL 會以下列格式記錄： https://myaccount.blob.core.windows.net/pictures/profile.jpg?sv=REDACTED&st=REDACTED&se=REDACTED&sr=REDACTED&sp=REDACTED&rscd=REDACTED&rsct=REDACTED&sig=REDACTED
警告
不建議在生產環境中使用記錄要求和響應主體，因為它們可能包含敏感性資訊、大幅影響效能、變更內容的緩衝方式，以及產生其他副作用。
在程式代碼中設定 HTTP 記錄
實作 HttpTrait<T> 介面的 Azure 用戶端產生器支援以程式代碼為基礎的 HTTP 記錄組態。 程式代碼型組態適用於個別客戶端實例，相較於環境變數組態，提供更多選項和自定義。
若要設定記錄，請將 HttpLogOptions 的實例傳遞至 httpLogOptions 對應客戶端產生器上的方法。 下列程式代碼顯示應用程式組態服務的範例：
HttpLogOptions httpLogOptions = new HttpLogOptions()
.setLogLevel(HttpLogDetailLevel.HEADERS)
.addAllowedHeaderName("Accept-Ranges")
.addAllowedQueryParamName("label");
ConfigurationClient configurationClient = new ConfigurationClientBuilder()
.httpLogOptions(httpLogOptions)
...
.buildClient();
此程式代碼會啟用具有標頭的 HTTP 記錄，並將Accept-Ranges響應標頭和label查詢參數添加至對應的允許清單。 這項變更之後，這些值應該會出現在產生的記錄中。
如需組態選項的完整清單，請參閱 HttpLogOptions 檔。
預設記錄器（用於暫時偵錯）
如前所述，所有 Azure 用戶端連結庫都會使用 SLF4J 進行記錄，但有後援的默認記錄器內建於適用於 Java 的 Azure 用戶端連結庫。 這個預設記錄器適用於部署應用程式且需要記錄的情況，但無法使用包含 SLF4J 記錄器重新部署應用程式的情況。 若要啟用此記錄器，您必須先確定沒有任何 SLF4J 記錄器存在（因為它優先），然後設定 AZURE_LOG_LEVEL 環境變數。 下表顯示此環境變數允許的值：
| 日誌等級 | 允許的環境變數值 |
|---|---|
| 詳細 |
verbose、debug |
| 資訊 |
info、information、informational |
| 警告 |
warn、warning |
| 錯誤 |
err、error |
設定環境變數之後，請重新啟動應用程式，讓環境變數生效。 此記錄器會記錄至主控台，而且不提供 SLF4J 實作的進階自定義功能，例如變換和記錄至檔案。 若要再次關閉記錄，只要移除環境變數並重新啟動應用程式即可。
SLF4J 記錄
根據預設，您應該使用 SLF4J 支援的記錄架構來設定記錄。 首先，將相關的 SLF4J 紀錄實作添加為您專案的相依性。 如需詳細資訊，請參閱在 SLF4J 使用者手冊中 宣告專案相依性以進行記錄 。 接下來，將您的記錄器設定為在您的環境中必要時運作，例如設定記錄層級、配置哪些類別進行和不進行記錄等等。 本文中的連結提供一些範例，但如需詳細資訊，請參閱所選記錄架構的檔。
記錄格式
記錄架構支援自定義記錄訊息格式設定和版面配置。 建議您至少包含下列欄位，以便針對 Azure 用戶端連結庫進行疑難解答：
- 具有毫秒精確度的日期和時間
- 記錄嚴重性
- 記錄器名稱
- 執行緒名稱
- 訊息
如需範例，請參閱您所使用之記錄架構的文件。
結構化記錄
除了記錄先前所述的一般屬性之外，Azure 用戶端連結庫也會在適用時標註具有額外內容的記錄訊息。 例如，您可能會看到 JSON 格式的記錄，其中包含以 az.sdk.message 其他根屬性撰寫的內容，如下列範例所示：
16:58:51.038 INFO c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP request","method":"GET","url":"<>","tryCount":"1","contentLength":0}
16:58:51.141 INFO c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP response","contentLength":"558","statusCode":200,"url":"<>","durationMs":102}
當您將記錄傳送至 Azure 監視器時，您可以使用 Kusto 查詢語言 來剖析記錄。 下列查詢提供範例：
traces
| where message startswith "{\"az.sdk.message"
| project timestamp, logger=customDimensions["LoggerName"], level=customDimensions["LoggingLevel"], thread=customDimensions["ThreadName"], azSdkContext=parse_json(message)
| evaluate bag_unpack(azSdkContext)
備註
Azure 客戶端函式庫記錄是用於臨時偵錯。 我們不建議依賴記錄格式來警示或監視您的應用程式。 Azure 用戶端連結庫不保證記錄訊息或內容密鑰的穩定性。 為了達到此目的，我們建議使用分散式追蹤。 Application Insights Java 代理程式提供請求和依賴性遙測的穩定保證。 如需詳細資訊，請參閱 在 Azure SDK for Java 中設定追蹤。
後續步驟
現在您已知道記錄如何在適用於 Java 的 Azure SDK 中運作，請考慮檢閱下列文章。 這些文章提供如何設定一些較常用 Java 記錄架構以使用 SLF4J 和 Java 用戶端連結庫的指引：