Partager via

Résoudre les problèmes liés à Azure Event Hubs

  • Article

Cet article traite des techniques d’investigation des défaillances, des erreurs courantes pour les types d’informations d’identification dans la bibliothèque Event Hubs et des étapes d’atténuation pour résoudre ces erreurs. Outre les techniques de dépannage générales et les conseils qui s’appliquent indépendamment du cas d’usage d’Event Hubs, les articles suivants couvrent des fonctionnalités spécifiques de la bibliothèque Event Hubs :

Le reste de cet article traite des techniques de dépannage générales et des conseils qui s’appliquent à tous les utilisateurs de la bibliothèque Event Hubs.

Gérer les exceptions Event Hubs

Toutes les exceptions Event Hubs sont encapsulées dans une amqpException. Ces exceptions ont souvent un code d’erreur AMQP sous-jacent qui spécifie si une erreur doit être retentée. Pour les erreurs retentables (autrement dit, amqp:connection:forced ou amqp:link:detach-forced), les bibliothèques clientes tentent de récupérer à partir de ces erreurs en fonction des options de nouvelle tentative spécifiées lors de l’instanciation du client. Pour configurer les options de nouvelle tentative, suivez l’exemple d’événements de publication sur une partition spécifique. Si l’erreur n’est pas récurrable, il existe un problème de configuration qui doit être résolu.

La méthode recommandée pour résoudre l’exception spécifique que représente l’exception AMQP consiste à suivre les instructions relatives aux exceptions de messagerie Event Hubs.

Rechercher des informations pertinentes dans les messages d’exception

Une exception AmqpException contient les trois champs suivants, qui décrivent l’erreur :

  • getErrorCondition : erreur AMQP sous-jacente. Pour obtenir une description des erreurs, consultez la documentation amqpErrorCondition enum ou la spécification OASIS AMQP 1.0.
  • isTransient : valeur qui indique si la tentative d’exécution de la même opération est possible. Les clients du Kit de développement logiciel (SDK) appliquent la stratégie de nouvelle tentative lorsque l’erreur est temporaire.
  • getErrorContext : contient les informations suivantes sur l’origine de l’erreur AMQP :

Exceptions couramment rencontrées

amqp :connection :forced et amqp :link :detach-forced

Lorsque la connexion à Event Hubs est inactive, le service déconnecte le client après un certain temps. Ce problème n’est pas un problème, car les clients rétablissent une connexion lorsqu’une opération de service est demandée. Pour plus d’informations, consultez les erreurs AMQP dans Azure Service Bus.

Problèmes d’autorisation

Avec AmqpException amqpErrorCondition, amqp:unauthorized-access cela signifie que les informations d’identification fournies ne permettent pas d’effectuer l’action (réception ou envoi) avec Event Hubs. Pour résoudre ce problème, essayez les tâches suivantes :

Pour obtenir d’autres solutions possibles, consultez Résoudre les problèmes d’authentification et d’autorisation avec Event Hubs.

Problèmes de connectivité

Délai d’expiration lors de la connexion au service

Pour résoudre les problèmes de délai d’expiration, essayez les tâches suivantes :

Échecs d’établissement de liaison TLS/SSL

Cette erreur peut se produire lorsqu’un proxy d’interception est utilisé. Pour vérifier, nous vous recommandons de tester dans votre environnement d’hébergement avec le proxy désactivé.

Erreurs d’épuisement du socket

Les applications doivent préférer traiter les clients Event Hubs en tant que singleton, en créant et en utilisant une seule instance tout au long de la durée de vie de leur application. Cette recommandation est importante, car chaque type de client gère sa connexion. Lorsque vous créez un client Event Hubs, il génère une nouvelle connexion AMQP, qui utilise un socket. En outre, il est essentiel que les clients héritent de java.io.Closeable, de sorte que votre application est chargée d’appeler close() lorsqu’elle est terminée à l’aide d’un client.

Pour utiliser la même connexion AMQP lors de la création de plusieurs clients, vous pouvez utiliser l’indicateur EventHubClientBuilder.shareConnection() , contenir une référence à cette EventHubClientBuilderconnexion et créer de nouveaux clients à partir de cette même instance de générateur.

Connecter à l’aide d’un chaîne de connexion IoT

Étant donné que la traduction d’un chaîne de connexion nécessite l’interrogation du service IoT Hub, la bibliothèque cliente Event Hubs ne peut pas l’utiliser directement. L’exemple IoT Connecter ionString.java décrit comment interroger IoT Hub pour traduire un chaîne de connexion IoT en un qui peut être utilisé avec Event Hubs.

Pour plus d’informations, consultez les articles suivants :

Impossible d’ajouter des composants au chaîne de connexion

Les clients Event Hubs hérités ont autorisé les clients à ajouter des composants au chaîne de connexion récupérés à partir du Portail Azure. Les clients hérités se trouvent dans les packages com.microsoft.azure :azure-eventhubs et com.microsoft.azure :azure-eventhubs-eph. La génération actuelle prend en charge les chaîne de connexion uniquement dans le formulaire publié par le Portail Azure.

Ajouter « TransportType=AmqpWebSockets »

Pour utiliser des sockets web, consultez l’exemple PublishEventsWithSocketsAndProxy.java .

Ajouter « Authentication=Managed Identity »

Pour vous authentifier avec Managed Identity, consultez l’exemple PublishEventsWithAzureIdentity.java.

Pour plus d’informations sur la Azure.Identity bibliothèque, case activée notre billet de blog Sur l’authentification et le kit de développement logiciel (SDK) Azure.

Activer et configurer la journalisation

Le Kit de développement logiciel (SDK) Azure pour Java offre un article de journalisation cohérent pour vous aider à résoudre les erreurs d’application et à accélérer leur résolution. Les journaux produits capturent le flux d’une application avant d’atteindre l’état terminal pour faciliter la localisation du problème racine. Pour obtenir des conseils sur la journalisation, consultez La vue d’ensemble de la configuration de la journalisation dans le Kit de développement logiciel (SDK) Azure pour Java et résolution des problèmes.

Outre l’activation de la journalisation, la définition du niveau VERBOSE de journalisation ou DEBUG fournit des insights sur l’état de la bibliothèque. Les sections suivantes montrent des exemples de configurations log4j2 et logback pour réduire les messages excessifs lorsque la journalisation détaillée est activée.

Configurer Log4J 2

Procédez comme suit pour configurer Log4J 2 :

  1. Ajoutez les dépendances dans votre pom.xml en utilisant celles de l’exemple de journalisation pom.xml, dans la section « Dépendances requises pour Log4j2 ».
  2. Ajoutez log4j2.xml à votre dossier src/main/resources .

Configurer la restauration des journaux

Pour configurer la restauration automatique, procédez comme suit :

  1. Ajoutez les dépendances dans votre pom.xml à l’aide des dépendances de l’exemple de journalisation pom.xml, dans la section « Dépendances requises pour logback ».
  2. Ajoutez logback.xml à votre dossier src/main/resources .

Activer la journalisation des transports AMQP

Si l’activation de la journalisation des clients n’est pas suffisante pour diagnostiquer vos problèmes, vous pouvez activer la journalisation dans un fichier dans la bibliothèque AMQP sous-jacente, Qpid Proton-J. Qpid Proton-J utilise java.util.logging. Vous pouvez activer la journalisation en créant un fichier de configuration avec le contenu indiqué dans la section suivante. Vous pouvez également définir proton.trace.level=ALL et quelles sont les options de configuration souhaitées pour l’implémentation java.util.logging.Handler . Pour connaître les classes d’implémentation et leurs options, consultez Package java.util.logging dans la documentation du Kit de développement logiciel (SDK) Java 8.

Pour tracer les trames de transport AMQP, définissez la variable d’environnement PN_TRACE_FRM=1 .

Exemple de fichier « logging.properties »

Le fichier de configuration suivant enregistre la sortie du niveau TRACE de Proton-J au fichier 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

Réduire la journalisation

Une façon de réduire la journalisation consiste à modifier la détail. Une autre façon consiste à ajouter des filtres qui excluent les journaux des packages de noms d’enregistreurs d’événements comme com.azure.messaging.eventhubs ou com.azure.core.amqp. Pour obtenir des exemples, consultez les fichiers XML dans les sections Configuration de Log4J 2 et Configurer logback .

Lorsque vous envoyez un bogue, les messages de journal provenant de classes dans les packages suivants sont intéressants :

  • com.azure.core.amqp.implementation
  • com.azure.core.amqp.implementation.handler
    • L’exception est que vous pouvez ignorer le onDelivery message dans ReceiveLinkHandler.
  • com.azure.messaging.eventhubs.implementation

Étapes suivantes

Si les conseils de dépannage de cet article n’aident pas à résoudre les problèmes lorsque vous utilisez le Kit de développement logiciel (SDK) Azure pour les bibliothèques clientes Java, nous vous recommandons de déposer un problème dans le référentiel Azure SDK pour Java GitHub.