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 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 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

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.

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, procédez comme suit :

Échecs de négociation 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, 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, vous pouvez utiliser l’indicateur EventHubClientBuilder.shareConnection(), contenir une référence à ce EventHubClientBuilderet créer 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 ont autorisé les clients à ajouter des composants à la chaîne de connexion récupérée à partir du 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 bibliothèque de Azure.Identity, consultez 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 générés capturent le flux d’une application avant d’atteindre l’état du terminal pour aider à localiser le problème racine. 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 liés à l'utilisation des bibliothèques clientes Azure SDK for Java, nous vous recommandons de déposer un problème dans le référentiel GitHub Azure SDK for Java.