Partilhar via

Solucionar problemas de Hubs de Eventos do Azure

  • Artigo

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

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

Manipular exceções de Hubs de Eventos

Todas as exceções dos Hubs de Eventos 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 que podem ser repetidos (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 as opções de repetição, siga o exemplo publicar eventos em partições específicas. Se o erro não puder ser repetido, 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 a orientação Exceções de Mensagens dos Hubs de Eventos.

Encontre 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 do Enum AmqpErrorCondition ou então a especificação OASIS AMQP 1.0 .
  • isTransient: Um valor que indica se é possível tentar realizar a mesma operação novamente. Os clientes 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:

Exceções comumente encontradas

amqp:connection:forced e amqp:link:detach-forced

Quando a conexão com Hubs de Eventos está ociosa, o serviço desconecta o cliente depois de 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 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 Hubs de Eventos. Para resolver esse problema, tente as seguintes tarefas:

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

Problemas de conectividade

Tempo limite ao estabelecer ligação com o serviço

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

Falhas de aperto de mão TLS/SSL

Este erro pode ocorrer quando um proxy de intercetação é usado. Para verificar, recomendamos testar em seu ambiente de hospedagem com o proxy desativado.

Erros de exaustão do soquete

As aplicações devem preferir tratar os clientes do Event Hubs como um singleton, criando e usando uma única instância ao longo da vida útil da sua aplicação. Essa recomendação é importante porque cada tipo de cliente gerencia sua conexão. Quando você cria um novo cliente de Hubs de Eventos, isso resulta em uma nova conexão AMQP, que usa um soquete. Além disso, é essencial que os clientes herdem de java.io.Closeable, para que a 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, pode-se usar o sinalizador EventHubClientBuilder.shareConnection(), manter uma referência a esse EventHubClientBuildere criar novos clientes a partir dessa mesma instância do builder.

Conectar-se usando uma cadeia de conexão IoT

Como a tradução de uma cadeia de conexão requer consultar o serviço Hub IoT, a biblioteca cliente 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 possa 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 antigos dos Hubs de Eventos permitiam que utilizadores adicionassem componentes à string de conexão obtida 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 formato publicado pelo portal do Azure.

Adicionar "TransportType=AmqpWebSockets"

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

Adicionar "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, consulte a nossa autenticação em e a publicação no blog do SDK do Azure.

Habilitar e configurar os logs

O SDK do Azure para Java oferece uma história de registro consistente para ajudar na solução de erros de aplicativos e ajudar a agilizar sua resolução. Os logs produzidos capturam o fluxo de um aplicativo antes de atingir o estado terminal para ajudar a localizar o problema raiz. Para obter orientação sobre o registo, consulte Configurar o registo 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 como VERBOSE ou DEBUG fornece informações sobre o estado da biblioteca. As secções seguintes mostram exemplos de configurações de log4j2 e de logback para reduzir o excesso de mensagens quando o registo detalhado está habilitado.

Configurar o Log4J 2

Use as seguintes etapas para configurar o Log4J 2:

  1. Adicione as dependências no seu pom.xml usando as do exemplo de registo de pom.xml, 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 no seu pom.xml usando as do exemplo de registo pom.xml, na secção "Dependências necessárias para logback".
  2. Adicione logback.xml à sua pasta src/main/resources .

Habilitar o log de transporte AMQP

Se ativar o registo do cliente não for suficiente para diagnosticar os seus problemas, pode ativar o registo num ficheiro 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 java.util.logging.Handler. Para obter as classes de implementação e suas opções, consulte Package java.util.logging na documentação do Java 8 SDK.

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

Exemplo de arquivo "logging.properties"

O seguinte arquivo de configuração registra a saída de nível TRACE 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 o registo de atividades

Uma maneira de reduzir o registo de logs é alterar a verbosidade. Outra maneira é 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 Configurar Log4J 2 e Configurar 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 exceção é que você pode ignorar a mensagem onDelivery no ReceiveLinkHandler.
  • com.azure.messaging.eventhubs.implementation

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ê arquive um problema no repositório SDK do Azure para Java GitHub.