适用于 Java 的 Azure SDK 故障排除概述

项目
10/23/2023

本文介绍了使用适用于 Java 的 Azure SDK 时可用的许多故障排除工具，并提供了指向其他文章的链接以及更多详细信息。

用于 Java 的 Azure SDK 包含许多客户端库 - 每个存在的 Azure 服务都有一个或多个。我们确保所有客户端库都构建为一致、高标准，并采用用于配置、日志记录、异常处理和故障排除的常见模式。有关详细信息，请参阅使用适用于 Java 的 Azure SDK。

由于故障排除可以跨越如此广泛的主题区域，因此我们开发了以下可能需要查看的故障排除指南：

排查 Azure 标识身份验证问题包括身份验证失败调查技术、Azure 标识 Java 客户端库中凭据类型的常见错误，以及解决这些错误的缓解步骤。
对依赖项版本冲突进行故障排除涵盖与诊断、缓解和最小化依赖项冲突相关的主题。在使用 Maven 和 Gradle 等工具生成的系统中使用 Azure SDK for Java 客户端库时，可能会出现这些冲突。
排查网络问题包括使用 Fiddler 和 Wireshark 等工具在客户端库外部进行 HTTP 调试相关的主题。

除了这些常规故障排除指南，我们还提供了特定于库的故障排除指南。现在提供了以下指南：

除了这些文档之外，以下内容还提供了有关如何充分利用日志记录和异常处理的指导，因为它与适用于 Java 的 Azure SDK 相关。

在 Azure SDK for Java 中使用日志记录

以下部分介绍如何启用不同类型的日志记录。

启用客户端日志记录

若要排查问题，请务必首先启用日志记录来监视应用程序的行为。日志中的错误和警告通常提供有关出错情况的有用见解，有时包括修复问题的纠正措施。适用于 Java 的 Azure SDK 提供全面的日志记录支持。有关详细信息，请参阅在 Azure SDK for Java 中配置日志记录。

启用 HTTP 请求/响应日志记录

排查问题时，查看在 Azure 服务之间发送和接收的 HTTP 请求非常有用。若要启用 HTTP 请求和响应有效负载日志记录，可以在客户端生成器中配置几乎所有用于 Java 客户端库的 Azure SDK，如以下示例所示。具体而言，请 httpLogOptions 特别注意客户端生成器上的方法以及可用的 HttpLogDetailLevel枚举值。

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .connectionString(connectionString)
        .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
        .buildClient();

此代码更改单个客户端实例的 HTTP 请求/响应日志记录。或者，可以通过将环境变量设置为 AZURE_HTTP_LOG_DETAIL_LEVEL 下表中的值之一来配置整个应用程序的日志记录 HTTP 请求和响应。请务必注意，此更改为支持记录 HTTP 请求/响应的每个 Azure 客户端启用日志记录。

值	日志记录级别
`none`	HTTP 请求/响应日志记录已禁用。
`basic`	仅记录 URL、HTTP 方法和完成请求的时间。
`headers`	记录 BASIC 中的所有内容，以及所有请求和响应标头。
`body`	记录 BASIC 中的所有内容，以及所有请求和响应正文。
`body_and_headers`	记录 HEADERS 和 BODY 中的所有内容。

注意

记录请求和响应正文时，请确保它们不包含机密信息。记录查询参数和标头时，客户端库具有一组默认的查询参数和标头，这些参数和标头被视为可以安全记录。可以添加可安全记录的其他查询参数和标头，如以下示例所示：

clientBuilder.httpLogOptions(new HttpLogOptions()
    .addAllowedHeaderName("safe-to-log-header-name")
    .addAllowedQueryParamName("safe-to-log-query-parameter-name"))

Azure SDK for Java 中的异常处理

大多数用于 Java 的 Azure SDK 客户端服务方法在失败时引发 HttpResponseException 或更具体的子类。该 HttpResponseException 类型包括详细的响应错误对象，该对象提供对出错情况的特定有用见解，并包括修复常见问题的纠正措施。可以在对象的消息属性 HttpResponseException 中找到此错误信息。由于这些异常是运行时异常，因此 JavaDoc 参考文档不会显式调用它们。

以下示例演示如何使用同步客户端捕获此异常：

try {
    ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
    client.getConfigurationSetting(setting);
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
    // Do something with the exception
}

使用异步客户端，可以在错误回调中捕获和处理异常，如以下示例所示：

ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
asyncClient.getConfigurationSetting(setting)
    .doOnSuccess(ignored -> System.out.println("Success!"))
    .doOnError(
        error -> error instanceof ResourceNotFoundException,
        error -> System.out.println("Exception: 'getConfigurationSetting' could not be performed."));

在 Azure SDK for Java 中使用跟踪

Azure SDK for Java 提供全面的跟踪支持，使你能够查看通过应用程序代码和正在使用的客户端库的执行流。可以通过使用和配置 OpenTelemetry SDK 或使用与 OpenTelemetry 兼容的代理在 Azure 客户端库中启用跟踪。 OpenTelemetry 是一种常用的开源可观测性框架，用于为云原生软件生成、捕获和收集遥测数据。

有关如何在 Azure SDK for Java 中启用跟踪的详细信息，请参阅在 Azure SDK for Java 中配置跟踪。

后续步骤

如果本文中的故障排除指南在使用 Azure SDK for Java 客户端库时无法解决问题，建议在 Azure SDK for Java GitHub 存储库中提出问题。

通过