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

  • Cikk

Ez a cikk áttekintést nyújt a Java Azure SDK-t használó alkalmazások naplózásának engedélyezéséről. A Java-hoz készült Azure-ügyfélkódtárak két naplózási lehetőséggel rendelkeznek:

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

Javasoljuk, hogy használja az SLF4J-t, mert jól ismert a Java-ökoszisztémában, és jól dokumentált. További információ: Az SLF4J felhasználói útmutatója.

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 is használ, ugyanaz a naplókimenet mindkét esetben elérhető, mivel a Java-hoz készült Azure-ügyfélkódtárakban található összes naplózási kimenet egy Azure-magos ClientLogger absztrakción keresztül lesz irányí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/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óval globálisan engedélyezheti a AZURE_HTTP_LOG_DETAIL_LEVEL HTTP-naplókat. Ez a változó a következő értékeket támogatja:

  • NONE: A HTTP-naplók le vannak tiltva. Ez az érték az alapértelmezett érték.
  • BASIC: A HTTP-naplók kérelemmetódust, 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 tartalmazzák.
  • 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.

Feljegyzés

A kérelem URL-címe megtisztítva van, vagyis az összes lekérdezési paraméter értéke újra ki van léptetve az api-version érték kivételével. Az egyes ügyfélkódtárak más lekérdezési paramétereket is hozzáadhatnak, amelyekről ismert, hogy biztonságosak az engedélyezési listához.

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

Figyelmeztetés

A naplózási kérések és választestek nem ajánlottak az éles környezetben, mert bizalmas információkat tartalmazhatnak, jelentősen befolyásolhatják a teljesítményt, módosíthatják a tartalom pufferelését, és egyéb mellékhatásokat is eredményezhetnek.

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 adja át a HttpLogOptions egy példányát a httpLogOptions megfelelő ügyfélszerkesztő 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 ezeknek az értékeknek meg kell jelennie 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 van megadva, amikor egy alkalmazás üzembe van helyezve, és naplózásra van szükség, de nem lehet újra üzembe helyezni az alkalmazást egy SLF4J-naplózóval. A naplózó engedélyezéséhez először biztosnak kell lennie abban, hogy nem létezik 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:

Naplószint Környezeti változók megengedett értékei
RÉSZLETES verbose, debug
TÁJÉKOZTATÓ info, , informationinformational
FIGYELMEZTETÉS warn, warning
Hiba err, error

A környezeti változó beállítása után indítsa újra az alkalmazást, hogy a környezeti változó érvénybe léphessen. 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 ismételt kikapcsolásához egyszerűen 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 a naplózást SLF4J által támogatott naplózási keretrendszerrel kell konfigurálnia. 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. Javasoljuk, hogy legalább az alábbi mezőket is bevezhesse az Azure-ügyfélkó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. Láthat például olyan JSON-formátumú naplókat, amelyek az.sdk.message más gyökértulajdonságokként írt környezettel 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)

Feljegyzés

Az Azure-ügyfélkódtár naplói alkalmi hibakeresésre szolgálnak. Nem javasoljuk, hogy az alkalmazás riasztásához vagy figyeléséhez használja a naplóformátumot. Az Azure-ügyfélkódtárak nem garantálják a naplóüzenetek és a környezeti kulcsok stabilitását. Ilyen célokra javasoljuk az elosztott nyomkövetés használatát. Az alkalmazás Elemzések Java-ügynök stabilitási garanciákat biztosít a kérelem- és függőségi telemetria számára. További információ: Nyomkövetés konfigurálása a Java Azure SDK-ban.

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: