Compartilhar via

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 clientes – uma ou mais para cada Serviço do Azure existente. Garantimos 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, desenvolvemos os seguintes guias de solução de problemas que talvez você queira examinar:

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:

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, é importante primeiro habilitar 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, é útil examinar solicitações HTTP conforme elas são enviadas e recebidas entre os serviços do Azure. Para habilitar o registro em log da solicitação HTTP e do conteúdo de resposta, você pode configurar quase todas as bibliotecas de clientes do SDK do Azure para 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 o log de solicitação/resposta HTTP para uma única instância do cliente. Como alternativa, você pode configurar o registro de solicitações e respostas HTTP para todo o aplicativo definindo a variável de ambiente AZURE_HTTP_LOG_DETAIL_LEVEL como um dos valores na tabela a 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 registros em 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 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 da solicitação e da resposta.
body_and_headers Registra tudo em CABEÇALHOS e CORPO.

Observação

Quando você registrar os corpos de solicitação e resposta, verifique se eles não contêm informações confidenciais. Quando você registra parâmetros e cabeçalhos de consulta, a biblioteca de clientes tem um conjunto padrão de parâmetros de consulta e cabeçalhos considerados seguros para registrar. É possível adicionar parâmetros de consulta e cabeçalhos adicionais que são seguros para registrar em log, 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 cliente do SDK do Azure para Java lança um HttpResponseException ou uma subclasse mais específica sobre 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 quando você usa o SDK do Azure para bibliotecas de clientes Java, recomendamos que você registre um problema no repositório GitHub do Azure SDK para Java.

  • Last updated on