在 Azure SDK for Java 中設定記錄

發行項
12/13/2023

本文提供如何在使用 Azure SDK for Java 的應用程式中啟用記錄的概觀。適用於 Java 的 Azure 用戶端連結庫有兩個記錄選項：

用於暫時偵錯的內建記錄架構。
支援使用 SLF4J 介面進行記錄。

我們建議您使用 SLF4J，因為它在 Java 生態系統中很有名，而且記錄得很好。如需詳細資訊，請參閱 SLF4J 使用者手冊。

本文連結至涵蓋許多熱門 Java 記錄架構的其他文章。這些其他文章提供組態範例，並描述 Azure 用戶端連結庫如何使用記錄架構。

無論您使用何種記錄組態，在任一情況下都可以使用相同的記錄輸出，因為適用於 Java 的 Azure 用戶端連結庫中的所有記錄輸出都會透過 azure 核心 ClientLogger 抽象概念路由傳送。

本文的其餘部分詳述所有可用記錄選項的設定。

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

如前所述，所有 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 用戶端連結庫的指引：