在 Azure SDK for Java 中配置日志记录

项目
10/23/2023

本文概述如何在使用 Azure SDK for Java 的应用程序中启用日志记录。适用于 Java 的 Azure 客户端库具有两个日志记录选项：

用于临时调试的内置记录框架。
支持使用 SLF4J 接口进行日志记录。

我们推荐你使用 SLF4J，因为它在 Java 生态系统中众所周知，且文档也很完善。有关详细信息，请参阅 SLF4J 用户手册。

本文链接到介绍许多常用 Java 记录框架的其他文章。这些文章提供了配置示例，并介绍了 Azure 客户端库如何使用记录框架。

无论使用哪种日志记录配置，在任何一种情况下都可以使用相同的日志输出，因为适用于 Java 的 Azure 客户端库中的所有日志记录输出都是通过 azure-core ClientLogger 抽象路由的。

本文的其余部分详细介绍了所有可用的日志记录选项的配置。

默认记录器（用于临时调试）

如前所述，所有 Azure 客户端库都使用 SLF4J 进行日志记录，但是适用于 Java 的 Azure 客户端库中内置了备用的默认记录器。此默认记录器适用于以下情况：已部署应用程序且需要进行日志记录，但无法使用随附的 SLF4J 记录器重新部署应用程序。若要启用此记录器，必须先确定不存在 SLF4J 记录器（因为它优先），然后设置 AZURE_LOG_LEVEL 环境变量。下表显示了此环境变量允许的值：

日志级别	允许的环境变量值
详细	`verbose`, `debug`
信息	`info`, `information`, `informational`
WARNING	`warn`, `warning`
ERROR	`err`, `error`

设置环境变量后，请重启应用程序以使环境变量生效。此记录器将日志记录到控制台，不提供 SLF4J 实现的高级自定义功能，例如滚动更新和日志记录到文件。若要再次关闭日志记录，只需删除该环境变量并重启应用程序。

SLF4J 日志记录

默认情况下，应使用 SLF4J 支持的记录框架配置日志记录。首先，添加相关的 SLF4J 日志记录实现，作为项目的依赖项。有关详细信息，请参阅 SLF4J 用户手册中的 Declaring project dependencies for logging（声明用于日志记录的项目依赖项）。接下来，将记录器配置为在环境中根据需要工作，例如设置日志级别、配置哪些类执行和不记录等。本文中的链接提供了一些示例，但有关详细信息，请参阅所选日志记录框架的文档。

日志格式

日志记录框架支持自定义日志消息格式和布局。建议至少包括以下字段，以便对 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 Monitor 时，可以使用 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 中的配置跟踪。

后续步骤

现在，你已了解日志记录在 Azure SDK for Java 中的工作原理，请考虑查看以下文章。这些文章提供了有关如何配置一些更常用 Java 日志记录框架以使用 SLF4J 和 Java 客户端库的指导：