在 Azure SDK for Java 中設定記錄

發行項
05/01/2024

本文提供如何在使用 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 ，所有查詢參數值都會被修訂。個別客戶端連結庫可能會將已知安全的其他查詢參數新增至allowlist。

例如，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 記錄，並將響應標頭和label查詢參數新增Accept-Ranges至對應的 allowlist。這項變更之後，這些值應該會出現在產生的記錄中。

如需組態選項的完整清單，請參閱 HttpLogOptions 檔。

預設記錄器（用於暫時偵錯）

如前所述，所有 Azure 用戶端連結庫都會使用 SLF4J 進行記錄，但有後援的默認記錄器內建於適用於 Java 的 Azure 用戶端連結庫。這個預設記錄器適用於部署應用程式且需要記錄的情況，但無法使用包含 SLF4J 記錄器重新部署應用程式的情況。若要啟用此記錄器，您必須先確定沒有任何 SLF4J 記錄器存在（因為它優先），然後設定 AZURE_LOG_LEVEL 環境變數。下表顯示此環境變數允許的值：

記錄層級	允許的環境變數值
VERBOSE	`verbose`, `debug`
資訊	`info`、、 `informationinformational`
警告	`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 用戶端連結庫的指引：

共用方式為