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 os eventos de publicação de exemplo para uma partição específica. 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 as diretrizes de Exceções de Mensagens de 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 AmqpErrorCondition Enum ou a especificação OASIS AMQP 1.0.
  • isTransient: Um valor que indica se é possível tentar executar a mesma operação. Os clientes SDK aplicam a política de repetição quando o erro é transitório.
  • getErrorContext: Contém as seguintes informações sobre onde o erro AMQP se originou:

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 Barramento de Serviço do Azure.

Problemas de permissão

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

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

Problemas de conectividade

Tempo limite ao conectar-se ao serviço

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

  • Verifique se a cadeia de conexão ou o nome de domínio totalmente qualificado especificado ao criar o cliente está correto. Para obter mais informações, consulte Obter uma cadeia de conexão de Hubs de Eventos.
  • Verifique as permissões de firewall e porta em seu ambiente de hospedagem e verifique se as portas AMQP 5671 e 5762 estão abertas.
    • Certifique-se de que o ponto de extremidade é permitido através do firewall.
  • Tente usar WebSockets, que se conecta na porta 443. Para obter mais informações, consulte o exemplo PublishEventsWithWebSocketsAndProxy.java .
  • Veja se a sua rede está a bloquear endereços IP específicos. Para obter mais informações, consulte Que endereços IP preciso permitir?
  • Se aplicável, verifique a configuração do proxy. Para obter mais informações, consulte o exemplo PublishEventsWithWebSocketsAndProxy.java .
  • Para obter mais informações sobre como solucionar problemas de conectividade de rede, consulte Solucionar problemas de conectividade - Hubs de Eventos do Azure.

Falhas de handshake 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

Os aplicativos devem preferir tratar os clientes dos Hubs de Eventos como um singleton, criando e usando uma única instância durante o tempo de vida de seu aplicativo. 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 do java.io.Closeable, para que seu aplicativo 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 EventHubClientBuilder.shareConnection() sinalizador, manter uma referência a isso EventHubClientBuildere criar novos clientes a partir dessa mesma instância do construtor.

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 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 que podem estar em inglês:

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

Os clientes de Hubs de Eventos herdados permitiram que os clientes adicionassem componentes à cadeia de conexão recuperada do portal do Azure. Os clientes herdados estão nos 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 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, confira nossa Autenticação e a Azure.Identity postagem do blog do SDK do Azure.

Habilitar e configurar o registro em log

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 registro em log, consulte Configurar o 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 informações sobre o estado da biblioteca. As seções a seguir mostram exemplos de log4j2 e configurações de logback para reduzir o excesso de mensagens quando o log detalhado está habilitado.

Configurar o Log4J 2

Use as seguintes etapas para configurar o Log4J 2:

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

Habilitar o log de transporte AMQP

Se habilitar o log do cliente não for suficiente para diagnosticar seus problemas, você poderá habilitar o registro em 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 java.util.logging.Handler implementação. 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 PN_TRACE_FRM=1 variável de ambiente.

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

Uma maneira de diminuir o registro em log é 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 Configurando o 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 onDelivery mensagem 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ê registre um problema no repositório do SDK do Azure para Java GitHub.