Panoramica della risoluzione dei problemi per Azure SDK per Java

Questo articolo presenta molti strumenti per la risoluzione dei problemi disponibili quando si usa Azure SDK per Java e collegamenti ad altri articoli con altri dettagli.

Azure SDK per Java è costituito da molte librerie client, una o più per ogni servizio di Azure esistente. Si garantisce che tutte le librerie client siano compilate in base a uno standard coerente e elevato, con modelli comuni per la configurazione, la registrazione, la gestione delle eccezioni e la risoluzione dei problemi. Per altre informazioni, vedere Usare Azure SDK per Java.

Poiché la risoluzione dei problemi può estendersi su un'area di interesse di questo tipo, sono state sviluppate le guide alla risoluzione dei problemi seguenti che è possibile esaminare:

• Risolvere i problemi di autenticazione di Identità di Azure illustra le tecniche di analisi degli errori di autenticazione, gli errori comuni per i tipi di credenziali nella libreria client Java di Azure Identity e i passaggi di mitigazione per risolvere questi errori.
• Risolvere i conflitti di versione delle dipendenze riguarda gli argomenti relativi alla diagnosi, alla mitigazione e alla riduzione dei conflitti di dipendenza. Questi conflitti possono verificarsi quando si usano le librerie client di Azure SDK per Java nei sistemi creati con strumenti come Maven e Gradle.
• Risolvere i problemi di rete riguarda gli argomenti relativi al debug HTTP all'esterno della libreria client, usando strumenti come Fiddler e Wireshark.

Oltre a queste guide generali alla risoluzione dei problemi, vengono fornite anche guide alla risoluzione dei problemi specifiche della libreria. Al momento sono disponibili le guide seguenti:

• Risolvere i problemi di Hub eventi di Azure
• Risolvere i problemi di bus di servizio di Azure

Oltre a questi documenti, il contenuto seguente fornisce indicazioni su come usare al meglio la registrazione e la gestione delle eccezioni in relazione ad Azure SDK per Java.

Usare la registrazione in Azure SDK per Java

Le sezioni seguenti descrivono come abilitare diversi tipi di registrazione.

Abilitare la registrazione client

Per risolvere i problemi, è importante prima abilitare la registrazione per monitorare il comportamento dell'applicazione. Gli errori e gli avvisi nei log forniscono in genere informazioni dettagliate utili su ciò che si è verificato e talvolta includono azioni correttive per risolvere i problemi. Azure SDK per Java offre supporto completo per la registrazione. Per altre informazioni, vedere Configurare la registrazione in Azure SDK per Java.

Abilitare la registrazione di richieste/risposte HTTP

Durante la risoluzione dei problemi, è utile esaminare le richieste HTTP man mano che vengono inviate e ricevute tra i servizi di Azure. Per abilitare la registrazione del payload di richiesta e risposta HTTP, è possibile configurare quasi tutte le librerie client di Azure SDK per Java nei generatori di client, come illustrato nell'esempio seguente. In particolare, prestare particolare attenzione al metodo sul httpLogOptions generatore client e i valori di enumerazione disponibili in HttpLogDetailLevel.

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .connectionString(connectionString)
        .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
        .buildClient();

Questo codice modifica la registrazione della richiesta/risposta HTTP per una singola istanza client. In alternativa, è possibile configurare la registrazione di richieste e risposte HTTP per l'intera applicazione impostando la AZURE_HTTP_LOG_DETAIL_LEVEL variabile di ambiente su uno dei valori nella tabella seguente. È importante notare che questa modifica abilita la registrazione per ogni client di Azure che supporta la registrazione di richieste/risposta HTTP.

Valore	Livello di registrazione
none	La registrazione di richieste/risposte HTTP è disabilitata.
basic	Registra solo GLI URL, i metodi HTTP e il tempo necessario per completare la richiesta.
headers	Registra tutti gli elementi in BASIC, oltre a tutte le intestazioni di richiesta e risposta.
body	Registra tutti gli elementi in BASIC, oltre a tutto il corpo della richiesta e della risposta.
body_and_headers	Registra tutti gli elementi in HEADERS e BODY.

Nota

Quando si registrano corpi di richiesta e risposta, assicurarsi che non contengano informazioni riservate. Quando si registrano parametri e intestazioni di query, la libreria client ha un set predefinito di parametri di query e intestazioni considerati sicuri per la registrazione. È possibile aggiungere altri parametri di query e intestazioni sicuri per la registrazione, come illustrato nell'esempio seguente:

clientBuilder.httpLogOptions(new HttpLogOptions()
    .addAllowedHeaderName("safe-to-log-header-name")
    .addAllowedQueryParamName("safe-to-log-query-parameter-name"))

Gestione delle eccezioni in Azure SDK per Java

La maggior parte dei metodi del servizio client Azure SDK per Java genera un'eccezione HttpResponseException o una sottoclasse più specifica in caso di errore. Il HttpResponseException tipo include un oggetto errore di risposta dettagliato che fornisce informazioni utili specifiche su ciò che è andato storto e include azioni correttive per risolvere i problemi comuni. È possibile trovare queste informazioni sull'errore all'interno della proprietà message dell'oggetto HttpResponseException . Poiché queste eccezioni sono eccezioni di runtime, la documentazione di riferimento JavaDoc non li chiama in modo esplicito.

L'esempio seguente illustra come intercettare questa eccezione con un client sincrono:

try {
    ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
    client.getConfigurationSetting(setting);
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
    // Do something with the exception
}

Con i client asincroni è possibile intercettare e gestire le eccezioni nei callback degli errori, come illustrato nell'esempio seguente:

ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
asyncClient.getConfigurationSetting(setting)
    .doOnSuccess(ignored -> System.out.println("Success!"))
    .doOnError(
        error -> error instanceof ResourceNotFoundException,
        error -> System.out.println("Exception: 'getConfigurationSetting' could not be performed."));

Usare la traccia in Azure SDK per Java

Azure SDK per Java offre supporto completo per la traccia, consentendo di visualizzare il flusso di esecuzione tramite il codice dell'applicazione e le librerie client in uso. È possibile abilitare la traccia nelle librerie client di Azure usando e configurando OpenTelemetry SDK o usando un agente compatibile con OpenTelemetry. OpenTelemetry è un diffuso framework di osservabilità open source per la generazione, l'acquisizione e la raccolta di dati di telemetria per il software nativo del cloud.

Per altre informazioni su come abilitare la traccia in Azure SDK per Java, vedere Configurare la traccia in Azure SDK per Java.

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 di Azure SDK per Java.