Compartilhar via

Solucionar problemas dos Hubs de Eventos do Azure

  • Artigo

Este artigo aborda técnicas de investigação de falhas, erros comuns para os tipos de credencial na biblioteca de Hubs de Eventos e etapas de mitigação para resolver esses erros. Além das técnicas gerais de solução de problemas e diretrizes que se aplicam independentemente do caso de uso dos Hubs de Eventos, os seguintes artigos abordam recursos específicos da biblioteca de Hubs de Eventos:

O restante deste artigo aborda técnicas gerais de solução de problemas e diretrizes que se aplicam a todos os usuários da biblioteca de Hubs de Eventos.

Gerenciar exceções dos Hubs de Eventos

Todas as exceções dos Event Hubs são encapsuladas em um AmqpException. Essas exceções geralmente têm um código de erro AMQP subjacente que especifica se um erro deve ser repetido. Para erros retíveis (ou seja, amqp:connection:forced ou amqp:link:detach-forced), as bibliotecas de cliente tentam se recuperar desses erros com base nas opções de repetição especificadas ao instanciar o cliente. Para configurar opções de repetição, siga o exemplo de eventos de publicação de para a partição específica. Se o erro não for recuperável, há algum problema de configuração que precisa ser resolvido.

A maneira recomendada de resolver a exceção específica que a exceção AMQP representa é seguir as orientações de Exceções de Mensagens dos Hubs de Eventos.

Localizar informações relevantes em mensagens de exceção

Um AmqpException contém os três campos a seguir, que descrevem o erro:

  • getErrorCondition: o erro AMQP subjacente. Para obter uma descrição dos erros, consulte a documentação AmqpErrorCondition Enum do OASIS AMQP 1.0 spec.
  • isTransient: um valor que indica se é possível tentar executar a mesma operação. Os clientes do SDK aplicam a política de repetição quando o erro é transitório.
  • getErrorContext: contém as seguintes informações sobre a origem do erro AMQP:
    • LinkErrorContext: erros que ocorrem no link de envio ou de recebimento.
    • SessionErrorContext: erros que ocorrem na sessão.
    • AmqpErrorContext: erros que ocorrem na conexão ou um erro AMQP geral.

Exceções comumente encontradas

amqp:connection:forced and amqp:link:detach-forced

Quando a conexão com os Hubs de Eventos está ociosa, o serviço desconecta o cliente após algum tempo. Esse problema não é um problema porque os clientes restabelecem uma conexão quando uma operação de serviço é solicitada. Para obter mais informações, consulte erros de AMQP no Azure Service Bus.

Problemas de permissão

Um AmqpException com um AmqpErrorCondition de amqp:unauthorized-access significa que as credenciais fornecidas não permitem executar a ação (receber ou enviar) com os Hubs de Eventos. Para resolver esse problema, experimente as seguintes tarefas:

Para outras soluções possíveis, consulte Solucionar problemas de autenticação e autorização com os Hubs de Eventos.

Problemas de conectividade

Tempo limite ao se conectar ao serviço

Para resolver problemas de tempo limite, experimente as seguintes tarefas:

Falhas de handshake de TLS/SSL

Esse erro pode ocorrer quando um proxy de interceptação é usado. Para verificar, recomendamos testar em seu ambiente de hospedagem com o proxy desabilitado.

Erros de esgotamento do soquete

Os aplicativos devem preferir tratar os clientes dos Hubs de Eventos como um singleton, criando e usando uma única instância durante todo o ciclo de vida do aplicativo. Essa recomendação é importante porque cada tipo de cliente gerencia sua conexão. Quando você cria um novo cliente dos Hubs de Eventos, ele resulta em uma nova conexão AMQP, que usa um soquete. Além disso, é fundamental que os clientes herdem de java.io.Closeable, para que sua aplicação seja responsável por chamar close() quando terminar de usar um cliente.

Para usar a mesma conexão AMQP ao criar vários clientes, você pode usar o sinalizador EventHubClientBuilder.shareConnection(), manter uma referência a esse EventHubClientBuilder e criar novos clientes a partir dessa mesma instância do construtor.

Conectar usando uma cadeia de conexão de IoT

Como a tradução de uma cadeia de conexão exige uma consulta ao serviço do Hub de IoT, a biblioteca de clientes dos Hubs de Eventos não pode usá-la diretamente. O exemplo de IoTConnectionString.java descreve como consultar o Hub IoT para converter uma cadeia de conexão IoT em uma que pode ser usada com Hubs de Eventos.

Para obter mais informações, consulte os seguintes artigos:

Não é possível adicionar componentes à cadeia de conexão

Os clientes legados dos Hubs de Eventos permitiram aos usuários adicionar componentes à cadeia de conexão recuperada do portal do Azure. Os clientes herdados estão em pacotes com.microsoft.azure:azure-eventhubs e com.microsoft.azure:azure-eventhubs-eph. A geração atual dá suporte a cadeias de conexão somente no formulário publicado pelo portal do Azure.

Adicionar "TransportType=AmqpWebSockets"

Para usar soquetes da Web, consulte o exemplo de PublishEventsWithSocketsAndProxy.java.

Adicione "Authentication=Managed Identity"

Para autenticar com a Identidade Gerenciada, consulte o exemplo PublishEventsWithAzureIdentity.java.

Para obter mais informações sobre a biblioteca de Azure.Identity, confira nossa Autenticação e SDK do Azure.

Habilitar e configurar o registro em log

O SDK do Azure para Java oferece uma história de log consistente para ajudar na solução de problemas de erros do aplicativo e para ajudar a agilizar sua resolução. Os logs produzidos capturam o fluxo de um aplicativo antes de atingir o estado do terminal para ajudar a localizar o problema raiz. Para obter diretrizes sobre o registro em log, consulte Configurar o registro em log no SDK do Azure para Java e Visão geral da solução de problemas.

Além de habilitar o registro em log, definir o nível de log para VERBOSE ou DEBUG fornece insights sobre o estado da biblioteca. As seções a seguir mostram configurações de log4j2 e logback de exemplo para reduzir o excesso de mensagens quando o log detalhado está habilitado.

Configurar Log4J 2

Use as seguintes etapas para configurar o Log4J 2:

  1. Adicione as dependências em seu pom.xml usando as do pom.xml de exemplo de log, na seção "Dependências necessárias para Log4j2".
  2. Adicione log4j2.xml à sua pasta src/main/resources.

Configurar o logback

Use as seguintes etapas para configurar o logback:

  1. Adicione as dependências em seu pom.xml usando as do pom.xml de exemplo de log, na seção "Dependências necessárias para logback".
  2. Adicione logback.xml à sua pasta src/main/resources.

Habilitar o log de transporte do AMQP

Se a habilitação do log do cliente não for suficiente para diagnosticar seus problemas, será possível habilitar o log em um arquivo na biblioteca AMQP subjacente, Qpid Proton-J. Qpid Proton-J usa java.util.logging. Você pode habilitar o registro em log criando um arquivo de configuração com o conteúdo mostrado na próxima seção. Ou defina proton.trace.level=ALL e as opções de configuração desejadas para a implementação do java.util.logging.Handler. Para obter as classes de implementação e suas opções, consulte pacote java.util.logging na documentação do SDK do Java 8.

Para rastrear os quadros de transporte AMQP, defina a variável de ambiente PN_TRACE_FRM=1.

Exemplo de arquivo "logging.properties"

O arquivo de configuração a seguir registra a saída de nível de rastreamento do Proton-J para o arquivo proton-trace.log:

handlers=java.util.logging.FileHandler
.level=OFF
proton.trace.level=ALL
java.util.logging.FileHandler.level=ALL
java.util.logging.FileHandler.pattern=proton-trace.log
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format=[%1$tF %1$tr] %3$s %4$s: %5$s %n

Reduzir registros de log

Uma maneira de diminuir o registro é alterar o detalhamento. Outra opção é adicionar filtros que excluem logs de pacotes de nomes de logger como com.azure.messaging.eventhubs ou com.azure.core.amqp. Para obter exemplos, consulte os arquivos XML nas seções Configurando o Log4J 2 e Configurando o logback.

Quando você envia um bug, as mensagens de log das classes nos seguintes pacotes são interessantes:

  • com.azure.core.amqp.implementation
  • com.azure.core.amqp.implementation.handler
    • A única exceção é que você pode ignorar a mensagem de onDelivery em ReceiveLinkHandler.
  • com.azure.messaging.eventhubs.implementation

Próximas etapas

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