Visão geral de solução de problemas do SDK do Azure para Java

Este artigo apresenta muitas ferramentas de solução de problemas disponíveis quando você usa o SDK do Azure para Java e links para outros artigos com mais detalhes.

O SDK do Azure para Java consiste em muitas bibliotecas de cliente – uma ou mais para cada serviço Azure existente. Microsoft garante que todas as bibliotecas de clientes sejam criadas para um padrão consistente e alto, com padrões comuns para configuração, registro em log, tratamento de exceções e solução de problemas. Para obter mais informações, consulte Usar o SDK do Azure para Java.

Como a solução de problemas pode abranger uma área de assunto tão ampla, Microsoft desenvolveu os seguintes guias de solução de problemas que talvez você queira examinar:

• Solucionar problemas de autenticação de Identidade do Azure abrange técnicas de investigação de falha de autenticação, erros comuns para os tipos de credencial na biblioteca de clientes Java de Identidade do Azure e etapas de mitigação para resolver esses erros.
• Solução de problemas de conflitos de versão de dependência aborda assuntos relacionados a diagnóstico, mitigação e minimização de conflitos de dependência. Esses conflitos podem surgir quando você usa o SDK do Azure para bibliotecas de clientes Java em sistemas criados com ferramentas como Maven e Gradle.
• A solução de problemas de rede aborda assuntos relacionados à depuração HTTP fora da biblioteca de clientes, usando ferramentas como Fiddler e Wireshark.

Juntamente com esses guias gerais de solução de problemas, Microsoft também fornece guias de solução de problemas específicos da biblioteca. Atualmente, os seguintes guias estão disponíveis:

• Solucionar problemas dos Hubs de Eventos do Azure
• Solucionar problemas do Barramento de Serviço do Azure

Além desses documentos, o conteúdo a seguir fornece diretrizes sobre como fazer o melhor uso do registro em log e tratamento de exceções, conforme se relaciona com o SDK do Azure para Java.

Uso de registro no SDK do Azure para Java

As seções a seguir descrevem como habilitar diferentes tipos de registro em log.

Habilitar o log do cliente

Para solucionar problemas, primeiro habilite o registro em log para monitorar o comportamento do aplicativo. Os erros e avisos nos logs geralmente fornecem insights úteis sobre o que deu errado e, às vezes, incluem ações corretivas para corrigir problemas. O SDK do Azure para Java tem suporte abrangente para registro em log. Para obter mais informações, consulte Configurar o log no SDK do Azure para Java.

Habilitar registro em log de solicitação/resposta HTTP

Ao solucionar problemas, examine as solicitações HTTP conforme elas são enviadas e recebidas entre Azure serviços. Para habilitar o registro em log do conteúdo de solicitação e resposta HTTP, configure quase todos os SDK do Azure para bibliotecas de cliente Java em seus construtores de clientes, conforme mostrado no exemplo a seguir. Particularmente, preste atenção especial ao método httpLogOptions no construtor do cliente e aos valores de enumeração disponíveis em HttpLogDetailLevel.

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

Esse código altera a solicitação HTTP e o log de resposta para uma única instância do cliente. Como alternativa, você pode configurar o registro em log de solicitações HTTP e respostas para todo o aplicativo definindo a AZURE_HTTP_LOG_DETAIL_LEVEL variável de ambiente como um dos valores na tabela a seguir. Essa alteração permite o registro em log para cada cliente Azure que dá suporte ao registro em log de solicitação e resposta HTTP.

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

Tratamento de exceções no SDK do Azure para Java

A maioria dos métodos de serviço do cliente do SDK do Azure para Java lança uma HttpResponseException ou uma subclasse mais específica em caso de falha. O HttpResponseException tipo inclui um objeto de erro de resposta detalhado que fornece insights úteis específicos sobre o que deu errado e inclui ações corretivas para corrigir problemas comuns. Você pode encontrar essas informações de erro dentro da propriedade de mensagem do HttpResponseException objeto. Como essas exceções são exceções de tempo de execução, a documentação de referência do JavaDoc não as menciona explicitamente.

O exemplo a seguir mostra como capturar essa exceção com um cliente síncrono:

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
}

Com clientes assíncronos, você pode capturar e manipular exceções nos callbacks de erro, conforme mostrado no exemplo a seguir:

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."));

Usar o rastreamento no SDK do Azure para Java

O SDK do Azure para Java oferece suporte abrangente de rastreamento, permitindo que você veja o fluxo de execução por meio do código do aplicativo e das bibliotecas de cliente que você está usando. Você pode habilitar o rastreamento em bibliotecas de clientes do Azure usando e configurando o SDK do OpenTelemetry ou usando um agente compatível com OpenTelemetry. O OpenTelemetry é uma estrutura popular de observabilidade de software livre para gerar, capturar e coletar dados de telemetria para programas de software nativos de nuvem.

Para obter mais informações sobre como habilitar o rastreamento no SDK do Azure para Java, consulte Configurar o rastreamento no SDK do Azure para Java.

Próximas etapas

Se as diretrizes de solução de problemas neste artigo não ajudarem a resolver problemas ao usar o SDK do Azure para bibliotecas de cliente Java, registre um problema no SDK do Azure para Java GitHub repositório.