Condividi tramite

Risolvere i problemi relativi a Hub eventi di Azure

  • Articolo

Questo articolo illustra le tecniche di analisi degli errori, gli errori comuni per i tipi di credenziali nella libreria di Hub eventi e i passaggi di mitigazione per risolvere questi errori. Oltre alle tecniche e alle linee guida generali per la risoluzione dei problemi applicabili indipendentemente dal caso d'uso di Hub eventi, gli articoli seguenti illustrano funzionalità specifiche della libreria di Hub eventi:

Nella parte restante di questo articolo vengono illustrate le tecniche di risoluzione dei problemi generali e le linee guida applicabili a tutti gli utenti della libreria di Hub eventi.

Gestire le eccezioni di Event Hubs

Tutte le eccezioni di Event Hubs sono avvolte in un AmqpException. Queste eccezioni hanno spesso un codice di errore AMQP sottostante che specifica se è necessario ritentare un errore. Per gli errori riprovabili (ovvero, amqp:connection:forced o amqp:link:detach-forced), le librerie client tentano di eseguire il ripristino da questi errori in base alle opzioni di ripetizione dei tentativi specificate durante l'istanziazione del client. Per configurare le opzioni di ripetizione dei tentativi, seguire l'esempio per pubblicare eventi in una partizione specifica. Se l'errore non è irreversibile, è necessario risolvere alcuni problemi di configurazione.

Il modo consigliato per risolvere l'eccezione specifica rappresentata dall'eccezione AMQP consiste nel seguire le indicazioni sulle eccezioni di messaggistica di Event Hubs .

Trovare informazioni rilevanti nei messaggi di eccezione

Un AmqpException contiene i tre campi seguenti, che descrivono l'errore:

  • getErrorCondition: errore AMQP sottostante. Per una descrizione degli errori, vedere la documentazione di AmqpErrorCondition Enum o la specifica OASIS AMQP 1.0.
  • isTransient: valore che indica se è possibile provare a eseguire la stessa operazione. I client SDK applicano i criteri di ripetizione dei tentativi quando l'errore è temporaneo.
  • getErrorContext: contiene le informazioni seguenti sulla provenienza dell'errore AMQP:

Eccezioni comunemente rilevate

amqp:connection:forced e amqp:link:detach-forced

Quando la connessione a Hub eventi è inattiva, il servizio disconnette il client dopo qualche tempo. Questo problema non è un problema perché i client stabiliscono nuovamente una connessione quando viene richiesta un'operazione del servizio. Per ulteriori informazioni, vedere errori AMQP nel Bus di Servizio di Azure.

Problemi di autorizzazione

Un AmqpException con un AmqpErrorCondition di amqp:unauthorized-access significa che le credenziali fornite non consentono di effettuare l'azione (ricezione o invio) con Event Hubs. Per risolvere questo problema, provare le attività seguenti:

Per altre possibili soluzioni, vedere Risolvere i problemi di autenticazione e autorizzazione con Event Hubs.

Problemi di connettività

Timeout durante la connessione al servizio

Per risolvere i problemi di timeout, provare le attività seguenti:

Errori di handshake TLS/SSL

Questo errore può verificarsi quando si utilizza un proxy di intercettazione. Per verificare, è consigliabile eseguire il test nell'ambiente di hosting con il proxy disabilitato.

Errori di esaurimento dei socket

Le applicazioni dovrebbero preferire trattare i client di Event Hubs come singleton, creando e utilizzando un'unica istanza per tutta la durata dell'applicazione. Questa raccomandazione è importante perché ogni tipo di client gestisce la connessione. Quando si crea un nuovo client di Hub eventi, viene generata una nuova connessione AMQP, che usa un socket. Inoltre, è essenziale che i client ereditino da java.io.Closeable, in modo che l'applicazione sia responsabile della chiamata close() quando ha finito di utilizzare un client.

Per utilizzare la stessa connessione AMQP durante la creazione di più client, puoi usare il flag EventHubClientBuilder.shareConnection(), mantenere un riferimento a quella EventHubClientBuildere creare nuovi client dalla stessa istanza del builder.

Connettersi usando una stringa di connessione IoT

Poiché la traduzione di una stringa di connessione richiede di eseguire query sul servizio IoT Hub, la libreria client di Event Hubs non può usarla direttamente. L'esempio di IoTConnectionString.java descrive come eseguire query sull'hub IoT per tradurre una stringa di connessione IoT in una stringa utilizzabile con Hub eventi.

Per altre informazioni, vedere gli articoli seguenti:

Non è possibile aggiungere componenti alla stringa di connessione

I client legacy di Event Hubs permettevano ai clienti di aggiungere componenti alla stringa di connessione recuperata dal portale di Azure. I client legacy si trovano nei pacchetti com.microsoft.azure:azure-eventhubs e com.microsoft.azure:azure-eventhubs-eph. La generazione corrente supporta le stringhe di connessione solo nel formato pubblicato dal portale di Azure.

Aggiungere "TransportType=AmqpWebSockets"

Per usare web socket, vedere l'esempio di PublishEventsWithSocketsAndProxy.java.

Aggiungere "Authentication=Managed Identity"

Per eseguire l'autenticazione con l'identità gestita, vedere l'esempio PublishEventsWithAzureIdentity.java.

Per altre informazioni sulla libreria di Azure.Identity, vedere il post di blog Authentication and the Azure SDK (Autenticazione di e Azure SDK).

Abilitare e configurare la registrazione

Azure SDK per Java offre una storia di registrazione coerente che consente di risolvere gli errori delle applicazioni e di accelerare la risoluzione. I log prodotti acquisiscono il flusso di un'applicazione prima di raggiungere lo stato terminale per rilevare il problema alla radice. Per indicazioni sulla registrazione, vedere Configurare la registrazione in Azure SDK per Java e Panoramica della risoluzione dei problemi.

Oltre ad abilitare la registrazione, impostare il livello di log su VERBOSE o DEBUG fornisce informazioni dettagliate sullo stato della libreria. Le sezioni seguenti illustrano configurazioni di esempio per log4j2 e logback, per ridurre i messaggi eccessivi quando è abilitato il logging verboso.

Configurare Log4J 2

Per configurare Log4J 2, seguire questa procedura:

  1. Aggiungere le dipendenze nel pom.xml usando quelle dell'esempio di registrazione pom.xml, nella sezione "Dipendenze necessarie per Log4j2".
  2. Aggiungere log4j2.xml alla cartella src/main/resources.

Configurare il logback

Per configurare il logback, seguire questa procedura:

  1. Aggiungere le dipendenze nel pom.xml usando quelle dell'esempio di registrazione pom.xml, nella sezione "Dipendenze necessarie per il logback".
  2. Aggiungere logback.xml alla cartella src/main/resources .

Abilitare la registrazione del trasporto AMQP

Se l'abilitazione della registrazione client non è sufficiente per diagnosticare i problemi, è possibile abilitare la registrazione in un file nella libreria AMQP sottostante, Qpid Proton-J. Qpid Proton-J usa java.util.logging. È possibile abilitare la registrazione creando un file di configurazione con il contenuto illustrato nella sezione successiva. In alternativa, impostare proton.trace.level=ALL e le opzioni di configurazione desiderate per l'implementazione java.util.logging.Handler. Per le classi di implementazione e le relative opzioni, vedere Package java.util.logging nella documentazione di Java 8 SDK.

Per tracciare i frame di trasporto AMQP, impostare la variabile di ambiente PN_TRACE_FRM=1.

File "logging.properties" di esempio

Il file di configurazione seguente registra l'output del livello TRACE da Proton-J al file di 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

Ridurre i log

Un modo per ridurre il logging consiste nel modificare la verbosità. Un altro modo consiste nell'aggiungere filtri che escludono i log dai pacchetti di nomi di logger, ad esempio com.azure.messaging.eventhubs o com.azure.core.amqp. Per esempi, vedere i file XML nelle sezioni Configurazione di Log4J 2 e Configurazione di logback.

Quando si invia un bug, i messaggi di log delle classi nei pacchetti seguenti sono interessanti:

  • com.azure.core.amqp.implementation
  • com.azure.core.amqp.implementation.handler
    • L'eccezione è che è possibile ignorare il messaggio di onDelivery in ReceiveLinkHandler.
  • com.azure.messaging.eventhubs.implementation

Passaggi successivi

Se le linee guida per la risoluzione dei problemi in questo articolo non consentono di risolvere i problemi quando si usano le librerie client di Azure SDK per Java, è consigliabile segnalare un problema nel repository GitHub Azure SDK per Java.