Konfigurera loggning i Azure SDK för Java

Artikel
05/01/2024

Den här artikeln innehåller en översikt över hur du aktiverar loggning i program som använder Azure SDK för Java. Azure-klientbiblioteken för Java har två loggningsalternativ:

Ett inbyggt loggningsramverk för tillfällig felsökning.
Stöd för loggning med SLF4J-gränssnittet.

Vi rekommenderar att du använder SLF4J eftersom det är välkänt i Java-ekosystemet och det är väl dokumenterat. Mer information finns i användarhandboken till SLF4J.

Den här artikeln länkar till andra artiklar som täcker många av de populära Java-loggningsramverken. De här andra artiklarna innehåller konfigurationsexempel och beskriver hur Azure-klientbiblioteken kan använda loggningsramverken.

Oavsett vilken loggkonfiguration du använder är samma loggutdata tillgängliga i båda fallen eftersom alla loggningsutdata i Azure-klientbiblioteken för Java dirigeras via en azure-core-abstraktion ClientLogger .

Resten av den här artikeln beskriver konfigurationen av alla tillgängliga loggningsalternativ.

Aktivera HTTP-begäran/svarsloggning

HTTP-begäran och svarsloggning är inaktiverade som standard. Du kan konfigurera klienter som kommunicerar med Azure-tjänster via HTTP för att skriva en loggpost för varje begäran och svar (eller undantag) som de får.

Om du använder OpenTelemetry kan du överväga att använda distribuerad spårning i stället för att logga för HTTP-begäranden. Mer information finns i Konfigurera spårning i Azure SDK för Java.

Konfigurera HTTP-loggning med en miljövariabel

Du kan använda AZURE_HTTP_LOG_DETAIL_LEVEL miljövariabeln för att aktivera HTTP-loggar globalt. Den här variabeln stöder följande värden:

NONE: HTTP-loggar är inaktiverade. Det här är standardvärdet.
BASIC: HTTP-loggar innehåller begärandemetoden, den sanerade begärande-URL:en, antalet försök, svarskoden och innehållslängden för begärande- och svarsorgan.
HEADERS: HTTP-loggar innehåller all grundläggande information och innehåller även rubriker som är kända för att vara säkra i loggningssyfte , det vill sa att de inte innehåller hemligheter eller känslig information. Den fullständiga listan med rubriknamn är tillgänglig i klassen HttpLogOptions .
BODY_AND_HEADERS: HTTP-loggar innehåller all information som tillhandahålls av HEADERS nivån och innehåller även begärande- och svarsorgan så länge de är mindre än 16 kB och kan skrivas ut.

Kommentar

Begärande-URL:en är sanerad, dvs. alla frågeparametervärden redigeras förutom api-version värdet. Enskilda klientbibliotek kan lägga till andra frågeparametrar som är kända för att vara säkra i listan över tillåtna.

Till exempel loggas URL:en för Signatur för delad åtkomst i Azure Blob Storage (SAS) i följande format: 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

Varning

Loggningsförfrågan och svarsorgan rekommenderas inte i produktion eftersom de kan innehålla känslig information, avsevärt påverka prestanda, ändra hur innehållet buffrats och få andra biverkningar.

Konfigurera HTTP-loggning i kod

Azure-klientbyggare som implementerar HttpTrait<T-gränssnittet> stöder kodbaserad HTTP-loggningskonfiguration. Kodbaserad konfiguration gäller för enskilda klientinstanser och innehåller fler alternativ och anpassningar jämfört med miljövariabelkonfiguration.

För att konfigurera loggar skickar du en instans av HttpLogOptions till httpLogOptions metoden på motsvarande klientbyggare. Följande kod visar ett exempel för appkonfigurationstjänsten:

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

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

Den här koden aktiverar HTTP-loggar med huvuden och lägger till Accept-Ranges svarshuvudet och label frågeparametern i motsvarande allowlists. Efter den här ändringen bör dessa värden visas i de genererade loggarna.

En fullständig lista över konfigurationsalternativ finns i dokumentationen om HttpLogOptions .

Standardloggare (för tillfällig felsökning)

Som nämnts använder alla Azure-klientbibliotek SLF4J för loggning, men det finns en reserv, standardloggare inbyggd i Azure-klientbibliotek för Java. Den här standardloggaren tillhandahålls för fall där ett program distribueras och loggning krävs, men det går inte att distribuera om programmet med en SLF4J-loggare. Om du vill aktivera den här loggaren måste du först vara säker på att det inte finns någon SLF4J-loggning (eftersom den har företräde) och sedan ange AZURE_LOG_LEVEL miljövariabeln. I följande tabell visas de värden som tillåts för den här miljövariabeln:

Loggningsnivå	Tillåtna värden för miljövariabel
VERBOSE	`verbose`, `debug`
INFORMATIONAL	`info`, , `informationinformational`
WARNING	`warn`, `warning`
ERROR	`err`, `error`

När miljövariabeln har angetts startar du om programmet så att miljövariabeln börjar gälla. Den här loggaren loggar till konsolen och tillhandahåller inte de avancerade anpassningsfunktionerna i en SLF4J-implementering, till exempel rollover och loggning till filen. Om du vill inaktivera loggningen igen tar du bara bort miljövariabeln och startar om programmet.

SLF4J-loggning

Som standard bör du konfigurera loggning med hjälp av ett SLF4J-stödt loggningsramverk. Inkludera först en relevant SLF4J-loggningsimplementering som ett beroende från projektet. Mer information finns i Deklarera projektberoenden för loggning i användarhandboken för SLF4J. Konfigurera sedan loggaren så att den fungerar efter behov i din miljö, till exempel att ställa in loggnivåer, konfigurera vilka klasser som gör och inte loggar och så vidare. Några exempel tillhandahålls via länkarna i den här artikeln, men mer information finns i dokumentationen för ditt valda loggningsramverk.

Loggformat

Loggningsramverk stöder anpassad loggmeddelandeformatering och layouter. Vi rekommenderar att du inkluderar minst följande fält för att göra det möjligt att felsöka Azure-klientbibliotek:

Datum och tid med millisekunders precision
Loggens allvarlighetsgrad
Loggningsnamn
Trådnamn
Meddelande

Exempel finns i dokumentationen för det loggningsramverk som du använder.

Strukturerad loggning

Förutom att logga de vanliga egenskaper som nämnts tidigare kommenterar Azure-klientbibliotek loggmeddelanden med extra kontext när det är tillämpligt. Du kan till exempel se JSON-formaterade loggar som innehåller az.sdk.message kontext som skrivits som andra rotegenskaper, som du ser i följande exempel:

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}

När du skickar loggar till Azure Monitor kan du använda Kusto-frågespråket för att parsa dem. Följande fråga innehåller ett exempel:

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)

Kommentar

Azure-klientbiblioteksloggar är avsedda för ad hoc-felsökning. Vi rekommenderar inte att du förlitar dig på loggformatet för att avisera eller övervaka ditt program. Azure-klientbibliotek garanterar inte stabiliteten för loggmeddelanden eller kontextnycklar. I sådana syften rekommenderar vi att du använder distribuerad spårning. Application Insights Java-agenten ger stabilitetsgarantier för telemetri för begäran och beroende. Mer information finns i Konfigurera spårning i Azure SDK för Java.

Nästa steg

Nu när du vet hur loggning fungerar i Azure SDK för Java kan du läsa följande artiklar. De här artiklarna ger vägledning om hur du konfigurerar några av de mer populära Java-loggningsramverken så att de fungerar med SLF4J och Java-klientbiblioteken:

Dela via