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

Artigo
10/23/2023

Este artigo apresenta muitas ferramentas de solução de problemas disponíveis para você 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 clientes sejam construídas de acordo com um padrão alto e consistente, com padrões comuns para configuração, registro, 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 temática tão ampla, desenvolvemos os seguintes guias de solução de problemas que você pode querer revisar:

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.
A solução de problemas de 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.

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

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 solucionar problemas, é importante primeiro habilitar o registro em 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 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 solucionar problemas, é útil revisar as solicitações HTTP à medida que são enviadas e recebidas entre os serviços do Azure. Para habilitar o registro em log da carga útil 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 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();

Esse código altera o log de solicitação/resposta HTTP para uma única instância de cliente. Como alternativa, você pode configurar o registro de solicitações e respostas HTTP para todo o seu 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 registro em log para cada cliente do Azure que dá suporte ao registro em log de solicitação/resposta HTTP.

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

Nota

Ao registrar corpos de solicitação e resposta, certifique-se de que eles não contenham informações confidenciais. Quando você registra parâmetros de consulta e cabeçalhos, a biblioteca do cliente tem um conjunto padrão de parâmetros de consulta e cabeçalhos que são considerados seguros para registro. É 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 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 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 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 diretrizes de solução de problemas neste artigo não ajudarem a resolver problemas quando você usa o SDK do Azure para bibliotecas de cliente Java, recomendamos que você registre um problema no repositório do SDK do Azure para Java GitHub.

Share via