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

2025-06-19

本文概述了如何在使用适用于 Java 的 Azure SDK 的应用程序中启用日志记录。适用于 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();

此代码启用包含标头的 Accept-Ranges HTTP 日志，并将响应标头和 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 客户端库还对日志消息进行批注（如果适用）。例如，你可能会看到包含 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 客户端库的指导：

通过