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

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:

• Az Azure Event Hubs hibaelhárítása
• Az Azure Service Bus hibaelhárítása

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át szinte minden Java-hoz készült Azure SDK ügyfélkönyvtár esetében engedélyezheti, ha az alábbi példában bemutatott módon konfigurálja az ügyfélépítőket. Különös figyelmet kell fordítani az httpLogOptions ügyfélalkotó metódusára és az enumerációs é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 a kérési és válaszüzeneteket naplózza, 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él API metódusa HttpResponseException-t vagy egy pontosabb alosztályt dob hibaként. 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.

Következő lépések

Ha a cikkben található hibaelhárítási útmutató nem segít megoldani az Azure SDK for Java ügyfélkönyvtárak használatakor felmerülő problémákat, javasoljuk, hogy hibajegyet nyújtson be a Java-hoz készült Azure SDK GitHub-adattárban.