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

Este artigo apresenta muitas ferramentas de resolução de problemas disponíveis quando utiliza o SDK do Azure para Java, e liga a outros artigos com mais detalhes.

O SDK do Azure para Java consiste em muitas bibliotecas clientes – uma ou mais para cada serviço Azure existente. A Microsoft garante que todas as bibliotecas clientes são construídas segundo um padrão consistente e elevado, com padrões comuns para configuração, registo, tratamento de exceções e resolução de problemas. Para obter mais informações, consulte Usar o SDK do Azure para Java.

Como a resolução de problemas pode abranger uma área de estudo tão ampla, a Microsoft desenvolveu os seguintes guias de resolução que poderá querer consultar:

• Solucionar problemas de autenticação do Azure Identity abrange técnicas de investigação de falhas de autenticação, erros comuns para os tipos de credenciais na biblioteca de cliente Java do Azure Identity e etapas de mitigação para resolver esses erros.
• Resolver conflitos de versão de dependência abrange assuntos relacionados ao 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 cliente Java em sistemas criados com ferramentas como Maven e Gradle.
• A solução de problemas de rede abrange assuntos relacionados à depuração HTTP fora da biblioteca do cliente, usando ferramentas como Fiddler e Wireshark.

Para além destes guias gerais de resolução de problemas, a Microsoft também disponibiliza guias específicos de resolução de problemas para bibliotecas. Atualmente, estão disponíveis os seguintes guias:

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

Além desses documentos, o conteúdo a seguir fornece orientação sobre como fazer o melhor uso do registro em log e do tratamento de exceções em relação ao SDK do Azure para Java.

Usar o log no SDK do Azure para Java

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

Habilitar o log do cliente

Para resolver problemas, primeiro ative o registo para monitorizar o comportamento da sua aplicação. Os erros e avisos nos logs geralmente fornecem informações ú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 ao log. Para obter mais informações, consulte Configurar o log no SDK do Azure para Java.

Habilitar o log de solicitação/resposta HTTP

Ao resolver problemas, analise os pedidos HTTP à medida que são enviados e recebidos entre os serviços Azure. Para permitir o registo do conteúdo do pedido e da resposta HTTP, configure quase todas as bibliotecas de cliente do SDK do Azure para Java nos respetivos construtores de cliente, conforme mostrado no exemplo seguinte. Em particular, preste especial atenção ao httpLogOptions método no construtor de clientes e aos valores de enum disponíveis em HttpLogDetailLevel.

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

Este código altera o registo de pedidos HTTP e respostas para uma única instância cliente. Em alternativa, pode configurar o registo dos pedidos e respostas HTTP para toda a sua aplicação, definindo a AZURE_HTTP_LOG_DETAIL_LEVEL variável de ambiente para um dos valores da tabela seguinte. Esta alteração permite o registo para todos os clientes do Azure que suportam o registo de pedidos HTTP e respostas.

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 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 informações úteis específicas 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 message do objeto HttpResponseException. Como estas exceções são exceções em 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 retornos de chamada 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 rastreamento no SDK do Azure para Java

O SDK do Azure para Java oferece suporte abrangente ao rastreamento, permitindo que você veja o fluxo de execução por meio do código do aplicativo e das bibliotecas de cliente que está usando. Você pode habilitar o rastreamento em bibliotecas de cliente do Azure usando e configurando o SDK do OpenTelemetry ou usando um agente compatível com OpenTelemetry. OpenTelemetry é uma estrutura de observabilidade de código aberto popular para gerar, capturar e coletar dados de telemetria para software nativo da 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óximos passos

Se as orientações de resolução de problemas neste artigo não ajudarem a resolver os problemas ao utilizar as bibliotecas de cliente do SDK do Azure para Java, submeta um problema no repositório do GitHub do SDK do Azure para Java.