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

Cet article explique comment résoudre les défaillances Azure Event Hubs, y compris les erreurs courantes pour les types d’informations d’identification dans la bibliothèque Event Hubs et les étapes d’atténuation pour les résoudre. 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 d’Event Hubs

Toutes les exceptions Event Hubs sont encapsulées dans un 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 retenables (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 pour publier des événements vers des partitions spécifiques. Si l’erreur n’est pas récurrable, il existe un problème de configuration qui doit être résolu.

La manière recommandée de résoudre l’exception spécifique représentée par l’exception AMQP consiste à suivre les consignes exceptions de messagerie d’Event Hubs.

Rechercher des informations pertinentes dans les messages d’exception

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

  • getErrorCondition: erreur AMQP sous-jacente. Pour une description des erreurs, consultez la documentation l’énumération AmqpErrorCondition 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 Event Hubs 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 comportement 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.

Résoudre les problèmes d’autorisation Event Hubs

Un AmqpException avec une AmqpErrorCondition de amqp:unauthorized-access signifie que les informations d’identification fournies ne permettent pas d’effectuer l’action (la réception ou l’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.

Résoudre les problèmes de connectivité Event Hubs

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

Pour résoudre les problèmes de délai d’expiration, procédez comme suit :

Échecs de négociation TLS/SSL

Cette erreur peut se produire lorsque vous utilisez un proxy d’interception. Pour vérifier, testez dans votre environnement d’hébergement avec le proxy désactivé.

Erreurs d’épuisement du socket

Considérez les clients d’Event Hubs comme un singleton. Créez et utilisez une instance unique pendant la durée de vie de votre application. Cette recommandation est importante, car chaque type de client gère sa connexion. Lorsque vous créez un client Event Hubs, vous créez une connexion AMQP, qui utilise un socket. En outre, il est essentiel que les clients héritent de java.io.Closeable, donc votre application doit appeler close() lorsqu'elle a fini d'utiliser un client.

Pour utiliser la même connexion AMQP lors de la création de plusieurs clients, utilisez l’indicateur EventHubClientBuilder.shareConnection() , maintenez une référence à celle-ci EventHubClientBuilderet créez de nouveaux clients à partir de cette même instance de générateur.

Se connecter à l’aide d’une chaîne de connexion IoT

Étant donné que la traduction d’une 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 IoTConnectionString.java décrit comment interroger IoT Hub pour traduire une chaîne de connexion IoT en une chaîne de connexion IoT qui peut être utilisée avec Event Hubs.

Pour plus d’informations, consultez les articles suivants :

Impossible d’ajouter des composants à la chaîne de connexion

Les clients Event Hubs hérités permettaient d’ajouter des composants à la chaîne de connexion récupérée depuis le portail Azure. Les clients hérités se trouvent dans des packages com.microsoft.azure :azure-eventhubs et com.microsoft.azure :azure-eventhubs-eph. La génération actuelle prend en charge les chaînes de connexion uniquement dans le formulaire publié par le portail Azure.

Ajouter « TransportType=AmqpWebSockets »

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

Ajouter « Authentification=Identité Gérée »

Pour vous authentifier avec l’identité managée, consultez l’exemple PublishEventsWithAzureIdentity.java.

Pour plus d’informations sur la Azure.Identity bibliothèque, consultez l’authentification et le billet de blog Kit de développement logiciel (SDK) Azure.

Activer et configurer la journalisation pour Event Hubs

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 que vous produisez retracent le déroulement d’une application avant qu’elle n’atteigne son état final, afin de vous aider à localiser la cause première du problème. Pour obtenir des conseils sur la journalisation, consultez Configurer la journalisation dans le Kit de développement logiciel (SDK) Azure pour Java et Vue d’ensemble de la résolution des problèmes.

Outre l’activation de la journalisation, la définition du niveau de journalisation sur VERBOSE 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 logback

Pour configurer logback, procédez comme suit :

  1. Ajoutez les dépendances dans votre pom.xml en utilisant celles du pom.xml d’exemple de journalisation, dans la section « Dependencies required for logback »
  2. Ajoutez logback.xml à votre dossier src/main/resources.

Activer le journal de transport AMQP

Si l'activation du journal client n'est pas suffisante pour diagnostiquer vos problèmes, vous pouvez activer la journalisation vers 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 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.

Fichier d’exemple « 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 le journal

Une façon de réduire la journalisation est de modifier le niveau de détail. Une autre méthode consiste à ajouter des filtres qui excluent les journaux provenant de packages de noms de journaux tels que com.azure.messaging.eventhubs ou com.azure.core.amqp. Pour obtenir des exemples, consultez les fichiers XML dans les sections Configurer Log4J 2 et Configurer logback.

Lorsque vous soumettez un rapport de bug, les messages de logs provenant de classes dans les paquets suivants sont intéressants :

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

Étapes suivantes

Si les conseils de dépannage de cet article ne permettent pas de résoudre les problèmes lorsque vous utilisez le Kit de développement logiciel (SDK) Azure pour Java bibliothèques clientes, placez un problème dans le Kit de développement logiciel (SDK) Azure pour Java GitHub référentiel.

  • Last updated on