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

项目
05/01/2024

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

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

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

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

无论使用哪种日志记录配置，在任何一种情况下都可以使用相同的日志输出，因为适用于 Java 的 Azure 客户端库中的所有日志记录输出都是通过 azure-core 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();

此代码启用包含标头的 Accept-Ranges HTTP 日志，并将响应标头和 label 查询参数添加到相应的允许列表。此更改后，这些值应显示在生成的日志中。

有关配置选项的完整列表，请参阅 HttpLogOptions 文档。

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

如前所述，所有 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 客户端库进行故障排除：

具有毫秒精度的日期和时间
日志严重性
记录器名称
线程名
Message

有关示例，请参阅所用日志记录框架的文档。

结构化日志记录

除了记录前面提及的常见属性之外，Azure 客户端库还注释了具有额外上下文的日志消息（如果适用）。例如，你可能会看到包含 az.sdk.message 以其他根属性形式写入的上下文的 JSON 格式日志，如以下示例所示：

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 客户端库的指导：