A Java-hoz készült Azure SDK hibaelhárítási áttekintése

Cikk
10/23/2023

Ez a cikk számos, a Java-hoz készült Azure SDK használatakor elérhető hibaelhárítási eszközt mutat be, és további részleteket tartalmazó cikkekre mutató hivatkozásokat tartalmaz.

A Java-hoz készült Azure SDK számos ügyfélkódtárból áll – egy vagy több minden létező Azure-szolgáltatáshoz. Biztosítjuk, hogy az összes ügyfélkódtár egységes, magas színvonalú legyen, a konfiguráció, a naplózás, a kivételkezelés és a hibaelhárítás gyakori mintáival. További információ: Az Azure SDK használata Java-hoz.

Mivel a hibaelhárítás ilyen széles területre terjedhet ki, a következő hibaelhárítási útmutatókat fejlesztettük ki, amelyeket érdemes lehet áttekinteni:

Az Azure Identity-hitelesítési problémák hibaelhárítása kiterjed a hitelesítési hibák vizsgálati technikáira, az Azure Identity Java ügyfélkódtár hitelesítő adatainak típusaival kapcsolatos gyakori hibákra, valamint a hibák elhárításának lépéseire.
A függőségi verzióütközések hibaelhárítása a függőségi ütközések diagnosztizálásával, enyhítésével és minimalizálásával kapcsolatos témákra terjed ki. Ezek az ütközések akkor fordulhatnak elő, ha az Azure SDK for Java-ügyfélkódtárakat olyan rendszerekben használja, amelyek olyan eszközökkel készültek, mint a Maven és a Gradle.
A hálózatkezelési problémák elhárítása az ügyfélkódtáron kívüli HTTP-hibakereséssel kapcsolatos témakörökre terjed ki, például a Fiddler és a Wireshark használatával.

Az általános hibaelhárítási útmutatók mellett könyvtárspecifikus hibaelhárítási útmutatókat is biztosítunk. Jelenleg az alábbi útmutatók érhetők el:

A dokumentumokon túl az alábbi tartalom útmutatást nyújt a naplózás és a kivételkezelés legjobb kihasználásához, mivel az a Java-hoz készült Azure SDK-hoz kapcsolódik.

Naplózás használata a Java Azure SDK-ban

A következő szakaszok a különböző naplózási módok engedélyezését ismertetik.

Ügyfélnaplózás engedélyezése

A problémák elhárításához fontos, hogy először engedélyezze a naplózást az alkalmazás viselkedésének figyeléséhez. A naplókban szereplő hibák és figyelmeztetések általában hasznos betekintést nyújtanak a hibákba, és időnként korrekciós műveleteket is tartalmaznak a problémák megoldásához. Az Azure SDK for Java átfogó naplózási támogatással rendelkezik. További információ: Naplózás konfigurálása a Java Azure SDK-ban.

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

A problémák elhárításakor érdemes áttekinteni a HTTP-kéréseket, amikor azOkat az Azure-szolgáltatások között küldik és fogadják. A HTTP-kérések és válaszok hasznos adatainak naplózásának engedélyezéséhez szinte minden Java-beli Azure SDK-ügyfélkódtárat konfigurálhat az ügyfélszerkesztőkben az alábbi példában látható módon. Különös figyelmet kell fordítani az httpLogOptions ügyfélszerkesztő metódusára és a számértékekre HttpLogDetailLevel.

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

Ez a kód egyetlen ügyfélpéldány HTTP-kérés-/válasznaplózását módosítja. Másik lehetőségként konfigurálhatja a naplózási HTTP-kéréseket és -válaszokat a teljes alkalmazáshoz úgy, hogy a környezeti változót AZURE_HTTP_LOG_DETAIL_LEVEL az alábbi táblázatban szereplő értékek egyikére állítja. Fontos megjegyezni, hogy ez a módosítás minden olyan Azure-ügyfél naplózását teszi lehetővé, amely támogatja a HTTP-kérések/válaszok naplózását.

Érték	Naplózási szint
`none`	A HTTP-kérések/válaszok naplózása le van tiltva.
`basic`	Csak URL-címeket, HTTP-metódusokat és a kérés befejezéséhez szükséges időt naplózza.
`headers`	Mindent naplóz a BASIC-ben, valamint az összes kérés- és válaszfejlécet.
`body`	Mindent naplóz a BASIC-ben, valamint az összes kérés- és választörzset.
`body_and_headers`	Mindent naplóz a FEJLÉCEKBEN és a TÖRZSben.

Megjegyzés:

Amikor naplózza a kérelem- és választestületeket, győződjön meg arról, hogy nem tartalmaznak bizalmas információkat. Amikor naplózza a lekérdezési paramétereket és a fejléceket, az ügyféltár alapértelmezett lekérdezési paraméterekkel és fejlécekkel rendelkezik, amelyek biztonságosnak tekinthetők a naplózáshoz. Az alábbi példában látható módon további, biztonságosan naplózható lekérdezési paramétereket és fejléceket is hozzáadhat:

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

Kivételkezelés a Java Azure SDK-ban

A Java-hoz készült Azure SDK legtöbb ügyfélszolgáltatás-metódusa httpResponseException vagy egy pontosabb alosztályt ad a hibához. A HttpResponseException típus tartalmaz egy részletes válaszhiba-objektumot, amely konkrét hasznos betekintést nyújt a hiba elhárításához, és korrekciós műveleteket tartalmaz a gyakori problémák megoldásához. Ez a hibainformáció az objektum üzenettulajdonságán HttpResponseException belül található. Mivel ezek a kivételek futásidejű kivételek, a JavaDoc referenciadokumentációja nem hívja fel őket explicit módon.

Az alábbi példa bemutatja, hogyan lehet elkapni ezt a kivételt egy szinkron ügyféllel:

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
}

Az aszinkron ügyfelekkel a hibavisszahívások kivételeit észlelheti és kezelheti, ahogyan az alábbi példában is látható:

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."));

Nyomkövetés használata a Javához készült Azure SDK-ban

Az Azure SDK for Java átfogó nyomkövetési támogatást nyújt, amely lehetővé teszi a végrehajtás folyamatának megtekintését az alkalmazáskódon és a használt ügyfélkódtárakon keresztül. A nyomkövetést az Azure-ügyfélkódtárakban az OpenTelemetry SDK használatával és konfigurálásával, vagy egy OpenTelemetry-kompatibilis ügynök használatával engedélyezheti. Az OpenTelemetria egy népszerű nyílt forráskódú megfigyelhetőségi keretrendszer, amely a natív felhőbeli szoftverek telemetriai adatainak létrehozására, rögzítésére és gyűjtésére használható.

További információ a nyomkövetés engedélyezéséről a Java Azure SDK-ban: Nyomkövetés konfigurálása a Java-hoz készült Azure SDK-ban.

További lépések

Ha a cikkben szereplő hibaelhárítási útmutató nem segít megoldani az Azure SDK for Java ügyfélkódtárak használatakor jelentkező problémákat, javasoljuk, hogy küldjön egy hibát a Java-hoz készült Azure SDK GitHub-adattárban.

Megosztás a következőn keresztül: