Solucionar problemas de Hubs de Eventos do Azure

Este artigo aborda como resolver falhas nos Hubs de Eventos do Azure, incluindo erros comuns para tipos de credenciais na biblioteca dos Event Hubs e passos de mitigação para os resolver. 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 comuns nos Centros de Eventos

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. Este comportamento não é um problema porque os clientes restabelecem uma ligação quando é solicitada uma operação de serviço. Para obter mais informações, consulte erros AMQP no Azure Service Bus.

Resolver questões de permissões nos Centros de Eventos

Um AmqpException com uma AmqpErrorCondition de amqp:unauthorized-access significa que as credenciais fornecidas não permitem realizar a ação (receber ou enviar) com os 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.

Resolver problemas de conectividade dos Centros de Eventos

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 utiliza um proxy de interceção. Para verificar, teste no seu ambiente de alojamento com o proxy desativado.

Erros de exaustão do soquete

Trate os clientes do Event Hubs como uma instância única. Crie e use 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 crias um novo cliente Event Hubs, crias uma nova ligação AMQP, que usa um socket. 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 ligação ao AMQP ao criar múltiplos clientes, use o sinalizador EventHubClientBuilder.shareConnection(), mantenha uma referência a esse EventHubClientBuilder e crie novos clientes a partir dessa mesma instância do criador.

Conectar-se usando uma string 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 Event Hubs permitiam adicionar componentes à cadeia de ligaçã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 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 mais informações sobre a Azure.Identity biblioteca, consulte o artigo do blogue Autenticação e SDK do Azure.

Ativar e configurar registos para Centros de Eventos

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 registos que produzes captam o fluxo de uma aplicação antes de atingires 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 Log4J 2

Use as seguintes etapas para configurar o Log4J 2:

  1. Adicione as dependências no seu pom.xml, utilizando as do pom.xml de exemplo de registo, na secção "Dependencies required for 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 orientações de resolução de problemas neste artigo não ajudarem a resolver os problemas ao utilizar as bibliotecas de cliente do SDK do Azure para Java, submeta um problema no repositório do GitHub do SDK do Azure para Java.

  • Last updated on