Condividi tramite

Configurare la registrazione in Azure SDK per Java

  • Articolo

Questo articolo offre una panoramica di come abilitare la registrazione nelle applicazioni che usano Azure SDK per Java. Le librerie client di Azure per Java hanno due opzioni di registrazione:

  • Framework di registrazione predefinito per scopi temporanei di debug.
  • Supporto per la registrazione tramite l'interfaccia SLF4J .

È consigliabile usare SLF4J perché è noto nell'ecosistema Java ed è ben documentato. Per altre informazioni, vedere il manuale dell'utente di SLF4J.

Questo articolo è collegato ad altri articoli che illustrano molti dei framework di registrazione Java più diffusi. Questi altri articoli forniscono esempi di configurazione e descrivono come le librerie client di Azure possono usare i framework di registrazione.

Indipendentemente dalla configurazione di registrazione usata, lo stesso output del log è disponibile in entrambi i casi perché tutti gli output di registrazione nelle librerie client di Azure per Java vengono instradati tramite un'astrazione azure-core ClientLogger .

Il resto di questo articolo illustra in dettaglio la configurazione di tutte le opzioni di registrazione disponibili.

Abilitare la registrazione di richieste/risposte HTTP

La registrazione di richieste e risposte HTTP è disattivata per impostazione predefinita. È possibile configurare i client che comunicano con i servizi di Azure tramite HTTP per scrivere un record di log per ogni richiesta e risposta (o eccezione) ricevuti.

Se si usa OpenTelemetry, è consigliabile usare la traccia distribuita anziché la registrazione per le richieste HTTP. Per altre informazioni, vedere Configurare la traccia in Azure SDK per Java.

Configurare la registrazione HTTP con una variabile di ambiente

È possibile usare la AZURE_HTTP_LOG_DETAIL_LEVEL variabile di ambiente per abilitare i log HTTP a livello globale. Questa variabile supporta i valori seguenti:

  • NONE: i log HTTP sono disabilitati. Si tratta del valore predefinito.
  • BASIC: i log HTTP contengono il metodo di richiesta, l'URL della richiesta sanificata, il numero di tentativi, il codice di risposta e la lunghezza del contenuto per i corpi di richiesta e risposta.
  • HEADERS: i log HTTP includono tutti i dettagli di base e includono anche intestazioni note per la registrazione, ovvero non contengono segreti o informazioni riservate. L'elenco completo dei nomi di intestazione è disponibile nella classe HttpLogOptions .
  • BODY_AND_HEADERS: i log HTTP includono tutti i dettagli forniti dal HEADERS livello e includono anche corpi di richiesta e risposta, purché siano inferiori a 16 KB e stampabili.

Nota

L'URL della richiesta viene sanificato, ovvero tutti i valori dei parametri di query vengono elaborati, ad eccezione del api-version valore . Le singole librerie client possono aggiungere altri parametri di query noti per essere sicuri per l'elenco elementi consentiti.

Ad esempio, l'URL della firma di accesso condiviso (SAS) Archiviazione BLOB di Azure viene registrato nel formato seguente:https://myaccount.blob.core.windows.net/pictures/profile.jpg?sv=REDACTED&st=REDACTED&se=REDACTED&sr=REDACTED&sp=REDACTED&rscd=REDACTED&rsct=REDACTED&sig=REDACTED

Avviso

I corpi di richiesta e risposta di registrazione non sono consigliati nell'ambiente di produzione perché potrebbero contenere informazioni riservate, influire in modo significativo sulle prestazioni, modificare il modo in cui il contenuto viene memorizzato nel buffer e avere altri effetti collaterali.

Configurare la registrazione HTTP nel codice

I generatori di client di Azure che implementano l'interfaccia HttpTrait<T> supportano la configurazione della registrazione HTTP basata su codice. La configurazione basata su codice si applica alle singole istanze client e offre più opzioni e personalizzazioni rispetto alla configurazione delle variabili di ambiente.

Per configurare i log, passare un'istanza di HttpLogOptions al metodo nel httpLogOptions generatore client corrispondente. Il codice seguente illustra un esempio per il servizio Configurazione app:

HttpLogOptions httpLogOptions = new HttpLogOptions()
        .setLogLevel(HttpLogDetailLevel.HEADERS)
        .addAllowedHeaderName("Accept-Ranges")
        .addAllowedQueryParamName("label");

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .httpLogOptions(httpLogOptions)
        ...
        .buildClient();

Questo codice abilita i log HTTP con intestazioni e aggiunge l'intestazione Accept-Ranges della risposta e il label parametro di query agli elenchi consentiti corrispondenti. Dopo questa modifica, questi valori dovrebbero essere visualizzati nei log prodotti.

Per l'elenco completo delle opzioni di configurazione, vedere la documentazione di HttpLogOptions .

Logger predefinito (per il debug temporaneo)

Come indicato, tutte le librerie client di Azure usano SLF4J per la registrazione, ma esiste un fallback, il logger predefinito integrato nelle librerie client di Azure per Java. Questo logger predefinito viene fornito per i casi in cui viene distribuita un'applicazione e la registrazione è necessaria, ma non è possibile ridistribuire l'applicazione con un logger SLF4J incluso. Per abilitare questo logger, è prima necessario assicurarsi che non esista alcun logger SLF4J (perché ha la precedenza) e quindi impostare la AZURE_LOG_LEVEL variabile di ambiente. La tabella seguente mostra i valori consentiti per questa variabile di ambiente:

Livello di registrazione Valori consentiti della variabile di ambiente
DETTAGLIATO verbose, debug
INFORMATIVO info, information, informational
AVVISO warn, warning
ERROR err, error

Dopo aver impostato la variabile di ambiente, riavviare l'applicazione per rendere effettiva la variabile di ambiente. Questo logger accede alla console e non fornisce le funzionalità di personalizzazione avanzate di un'implementazione SLF4J, ad esempio il rollover e la registrazione nel file. Per disattivare di nuovo la registrazione, rimuovere la variabile di ambiente e riavviare l'applicazione.

Registrazione SLF4J

Per impostazione predefinita, è necessario configurare la registrazione usando un framework di registrazione supportato da SLF4J. In primo luogo, includere un'implementazione di registrazione SLF4J pertinente come dipendenza dal progetto. Per altre informazioni, vedere Dichiarazione delle dipendenze del progetto per l'accesso nel manuale dell'utente SLF4J. Configurare quindi il logger in modo che funzioni in base alle esigenze nell'ambiente, ad esempio l'impostazione dei livelli di log, la configurazione delle classi che eseguono e non registrano e così via. Alcuni esempi vengono forniti tramite i collegamenti in questo articolo, ma per altre informazioni, vedere la documentazione relativa al framework di registrazione scelto.

Formato del log

I framework di registrazione supportano la formattazione e i layout personalizzati dei messaggi di log. È consigliabile includere almeno i campi seguenti per consentire la risoluzione dei problemi delle librerie client di Azure:

  • Data e ora con precisione in millisecondi
  • Gravità del log
  • Nome logger
  • Nome del thread
  • Message

Per esempi, vedere la documentazione relativa al framework di registrazione usato.

Registrazione strutturata

Oltre a registrare le proprietà comuni indicate in precedenza, le librerie client di Azure annotano i messaggi di log con contesto aggiuntivo, se applicabile. Ad esempio, è possibile che vengano visualizzati log in formato JSON contenenti az.sdk.message contesto scritto come altre proprietà radice, come illustrato nell'esempio seguente:

16:58:51.038 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP request","method":"GET","url":"<>","tryCount":"1","contentLength":0}
16:58:51.141 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP response","contentLength":"558","statusCode":200,"url":"<>","durationMs":102}

Quando si inviano log a Monitoraggio di Azure, è possibile usare il linguaggio di query Kusto per analizzarli. La query seguente fornisce un esempio:

traces
| where message startswith "{\"az.sdk.message"
| project timestamp, logger=customDimensions["LoggerName"], level=customDimensions["LoggingLevel"], thread=customDimensions["ThreadName"], azSdkContext=parse_json(message)
| evaluate bag_unpack(azSdkContext)

Nota

I log della libreria client di Azure sono destinati al debug ad hoc. Non è consigliabile basarsi sul formato di log per avvisare o monitorare l'applicazione. Le librerie client di Azure non garantiscono la stabilità dei messaggi di log o delle chiavi di contesto. A tale scopo, è consigliabile usare la traccia distribuita. L'agente Java di Application Insights offre garanzie di stabilità per i dati di telemetria delle richieste e delle dipendenze. Per altre informazioni, vedere Configurare la traccia in Azure SDK per Java.

Passaggi successivi

Dopo aver appreso il funzionamento della registrazione in Azure SDK per Java, vedere gli articoli seguenti. Questi articoli forniscono indicazioni su come configurare alcuni dei framework di registrazione Java più diffusi per l'uso con SLF4J e le librerie client Java: