Visão geral da 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 do Azure existente. Garantimos que todas as bibliotecas de cliente sejam criadas de acordo com um padrão consistente e de alto padrão, 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, desenvolvemos os seguintes guias de solução de problemas que você pode querer revisar:

• 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 credenciais na biblioteca de cliente Java de Identidade do Azure e etapas de mitigação para resolver esses erros.
• Solucionar problemas de conflitos de versão de dependência abrange assuntos relacionados ao diagnóstico, atenuaçã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 o Fiddler e o Wireshark.

Juntamente com esses guias gerais de solução de problemas, também fornecemos guias de solução de problemas específicos da biblioteca. No momento, 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 orientação sobre como fazer o melhor uso do 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 log.

Habilitar o log do cliente

Para solucionar problemas, é importante primeiro habilitar o log para monitorar o comportamento do seu aplicativo. 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 para log. Para obter mais informações, confira Configurar o registro em log no SDK do Azure para Java.

Habilitar o log de solicitação/resposta HTTP

Ao solucionar problemas, é útil revisar as solicitações HTTP à medida que são enviadas e recebidas entre os serviços do Azure. Para habilitar o log da carga de solicitação e resposta HTTP, você pode configurar quase todas as bibliotecas de cliente do SDK do Azure para Java em seus construtores de clientes, conforme mostrado no exemplo a seguir. Em particular, preste atenção especial ao httpLogOptions método no construtor do cliente e aos valores de enum disponíveis no HttpLogDetailLevel.

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

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

Valor	Nível de log
none	O log de solicitação/resposta HTTP está desabilitado.
basic	Registra somente URLs, métodos HTTP e tempo para concluir a solicitação.
headers	Registra tudo no BASIC, além de todos os cabeçalhos de solicitação e resposta.
body	Registra tudo no BASIC, além de todo o corpo de solicitação e resposta.
body_and_headers	Registra tudo em CABEÇALHOS e CORPO.

Observação

Ao registrar os órgãos de solicitação e resposta, verifique se eles não contêm informações confidenciais. Quando você registra parâmetros de consulta e cabeçalhos, a biblioteca cliente tem um conjunto padrão de parâmetros de consulta e cabeçalhos que são considerados seguros para log. É possível adicionar parâmetros de consulta adicionais e cabeçalhos que são seguros para registrar, conforme mostrado no exemplo a seguir:

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 de cliente do SDK do Azure para Java lança um HttpResponseException ou uma subclasse mais específica na 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 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 chama 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 o 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 nas bibliotecas de cliente 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 a orientação de solução de problemas neste artigo não ajudar a resolver problemas ao usar o SDK do Azure para bibliotecas de cliente Java, recomendamos que você registre um problema no repositório do Azure SDK para Java GitHub.