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 credenciais na biblioteca de Hubs de Eventos e etapas de atenuação para resolver esses erros. Além das técnicas e orientações 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 repetí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 os exemplos de eventos de publicação em 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 a orientação 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 do AmqpErrorCondition Enum ou a especificação do 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:forçado e amqp:link:detach-forced

Quando a conexão com 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 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 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 se conectar ao serviço

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

Falhas de handshake 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 exaustão do soquete

Os aplicativos devem preferir tratar os clientes de 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, ele 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 conversão de uma cadeia de conexão requer a consulta do serviço do 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 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 de Hubs de Eventos herdados permitiam 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 oferece 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 Azure.Identity biblioteca, confira nossa postagem de blog 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 de aplicativos e para ajudar a agilizar sua resolução. Os logs produzidos capturam o fluxo de um aplicativo antes de acessarem o estado do terminal para ajudar a localizar o problema raiz. Para obter orientação sobre 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 log, definir o nível de log como VERBOSE ou DEBUG fornecer insights sobre o estado da biblioteca. As seções a seguir mostram exemplos de configurações de log4j2 e 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 logback

Use as seguintes etapas para configurar o logback:

  1. Adicione as dependências em seu pom.xml usando as do pom de exemplo de log.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 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 arquivo de configuração a seguir 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 registro em log

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 de 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óximas etapas

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