Naplózás konfigurálása a Java-hoz készült Azure SDK-ban

Ez a cikk áttekintést nyújt a Java Azure SDK használó alkalmazások naplózásának engedélyezéséről. A Java Azure ügyfélkódtárai két naplózási lehetőséget kínálnak:

• Beépített naplózási keretrendszer ideiglenes hibakeresési célokra.
• A naplózás támogatása az SLF4J felülettel.

Használja az SLF4J-t, mert jól ismert az Java ökoszisztémában, és jól dokumentált. További információ: SLF4J felhasználói kézikönyv.

Ez a cikk más cikkekre hivatkozik, amelyek számos népszerű Java-naplózási keretrendszert érintenek. Ezek a további cikkek konfigurációs példákat nyújtanak, és ismertetik, hogyan használhatják az Azure ügyfélkódtárak a naplózási keretrendszereket.

Bármilyen naplózási konfigurációt használ is, ugyanazt a naplókimenetet kapja, mert a Java-hoz készült Azure-ügyfélkönyvtárakban minden naplózási kimenet egy azure-core ClientLogger absztrakción keresztül van továbbítva.

A cikk további része az összes elérhető naplózási beállítás konfigurációját ismerteti.

HTTP-kérések és válaszok naplózásának engedélyezése

A HTTP-kérések és a válaszok naplózása alapértelmezés szerint ki van kapcsolva. Konfigurálhatja az Azure-szolgáltatásokkal HTTP-n keresztül kommunikáló ügyfeleket, hogy minden kapott kéréshez és válaszhoz (vagy kivételhez) naplórekordot írjanak.

OpenTelemetria használata esetén fontolja meg az elosztott nyomkövetés használatát a HTTP-kérések naplózása helyett. További információ: Nyomkövetés konfigurálása a Java Azure SDK-ban.

HTTP-naplózás konfigurálása környezeti változóval

A környezeti változó használatával kapcsolja be a AZURE_HTTP_LOG_DETAIL_LEVEL HTTP-naplókat az összes ügyfélhez. Állítsa be ezt a változót az alábbi értékek egyikére:

• NONE: A HTTP-naplók ki vannak kapcsolva. Ez az alapértelmezett érték.
• BASIC: A HTTP-naplók tartalmazzák a kérelem metódusát, a megtisztított kérelem URL-címét, a próbálkozások számát, a válaszkódot, valamint a kérelem- és választörzsek tartalomhosszát.
• HEADERS: A HTTP-naplók tartalmazzák az összes alapvető részletet, és olyan fejléceket is tartalmaznak, amelyekről ismert, hogy biztonságosak naplózási célokra – vagyis nem tartalmaznak titkos kulcsokat vagy bizalmas információkat. A fejlécnevek teljes listája elérhető a HttpLogOptions osztályban.
• BODY_AND_HEADERS: A HTTP-naplók tartalmazzák a szint által megadott összes részletet, valamint tartalmazzák a HEADERS kérelem- és választörzseket is, amennyiben 16 KB-nál kisebbek és nyomtathatók.

Az Azure Blob Storage megosztott hozzáférésű jogosultságkódjának (SAS) URL-címe például a következő formátumban van naplózva: 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

HTTP-naplózás konfigurálása kódban

A HttpTrait<T> interfészt implementáló Azure-ügyfélkészítők támogatják a kódalapú HTTP-naplózási konfigurációt. A kódalapú konfiguráció az egyes ügyfélpéldányokra vonatkozik, és több lehetőséget és testreszabást biztosít, mint a környezeti változók konfigurációja.

A naplók konfigurálásához továbbítson egy HttpLogOptions példányt a httpLogOptions megfelelő ügyfél-építő metódusának. Az alábbi kód egy példát mutat be az App Configuration service-hez:

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

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

Ez a kód lehetővé teszi a HTTP-naplók fejlécekkel való használatát, és hozzáadja a Accept-Ranges válaszfejlécet és a label lekérdezési paramétert a megfelelő engedélyezési listákhoz. A módosítás után ezek az értékek megjelennek a létrehozott naplókban.

A konfigurációs beállítások teljes listáját a HttpLogOptions dokumentációjában találja.

Alapértelmezett naplózó (ideiglenes hibakereséshez)

Mint említettük, minden Azure-ügyfélkódtár SLF4J-t használ a naplózáshoz, de van egy tartalék, alapértelmezett naplózó, amely a Java-hoz készült Azure-ügyfélkódtárakba van beépítve. Ez az alapértelmezett naplózó olyan esetekben használható, amikor egy alkalmazást helyez üzembe, és naplózásra van szüksége, de nem tudja újra üzembe helyezni az alkalmazást egy SLF4J-naplózóval együtt. A naplózó engedélyezéséhez először győződjön meg arról, hogy nincs SLF4J-naplózó (mert elsőbbséget élvez), majd állítsa be a környezeti változót AZURE_LOG_LEVEL . Az alábbi táblázat a környezeti változóhoz engedélyezett értékeket mutatja be:

A környezeti változó beállítása után indítsa újra az alkalmazást a környezeti változó engedélyezéséhez. Ez a naplózó naplózza a konzolt, és nem biztosítja az SLF4J implementáció speciális testreszabási funkcióit, például az átállást és a fájlba való naplózást. A naplózás kikapcsolásához távolítsa el a környezeti változót, és indítsa újra az alkalmazást.

SLF4J-naplózás

Alapértelmezés szerint konfigurálja a naplózást egy SLF4J által támogatott naplózási keretrendszer használatával. Először is adjon meg egy releváns SLF4J-naplózási implementációt a projekt függőségeként. További információ: Projektfüggőségek deklarálása naplózáshoz az SLF4J felhasználói kézikönyvében. Ezután konfigurálja a naplózót úgy, hogy szükség szerint működjön a környezetben, például állítsa be a naplószinteket, konfigurálja, hogy mely osztályok végeznek és mit nem naplóznak, és így tovább. Néhány példát a cikkben található hivatkozásokon keresztül talál, de további információkért tekintse meg a kiválasztott naplózási keretrendszer dokumentációját.

Naplóformátum

A naplózási keretrendszerek támogatják az egyéni naplóüzenetek formázását és elrendezését. Adja meg legalább az alábbi mezőket az Azure ügyféloldali kódtárak hibaelhárításához:

• Dátum és idő ezredmásodperc pontossággal
• Napló súlyossága
• Naplózó neve
• Szál neve
• Üzenet

Példákért tekintse meg a használt naplózási keretrendszer dokumentációját.

Strukturált naplózás

A korábban említett gyakori tulajdonságok naplózása mellett az Azure-ügyfélkódtárak a naplóüzeneteket külön kontextusba helyezik, ha vannak ilyenek. Például láthat JSON-formátumú naplókat, amelyek az.sdk.message más gyökértulajdonságok formájában írt kontextussal rendelkeznek, ahogyan az alábbi példában látható.

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}

Amikor naplókat küld az Azure Monitornak, a Kusto lekérdezési nyelvével elemezheti őket. A következő lekérdezés egy példát mutat be:

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)

Következő lépések

Most, hogy már tudja, hogyan működik a naplózás a Javához készült Azure SDK-ban, tekintse át az alábbi cikkeket. Ezek a cikkek útmutatást nyújtanak a népszerűbb Java-naplózási keretrendszerek SLF4J és Java-ügyfélkódtárak használatához való konfigurálásához:

• java.util.logging
• Logback
• Log4J
• nyomkövetés