Azure SDK for Java のトラブルシューティングの概要

[アーティクル]
09/08/2023

この記事では、Azure SDK for Java を使用するときに使用できる多くのトラブルシューティングツールと、詳細を含む他の記事へのリンクについて説明します。

Azure SDK for Java は、多数のクライアントライブラリ (存在する Azure サービスごとに 1 つ以上) で構成されています。すべてのクライアントライブラリが、構成、ログ記録、例外処理、およびトラブルシューティングの共通パターンを使用して、一貫性のある高い標準で構築されていることを確認します。詳細については、「Azure SDK for Java を使用する」を参照してください。

トラブルシューティングは幅広い対象領域に及ぶ可能性があるため、次のトラブルシューティングガイドを作成しました。このガイドを確認することをお勧めします。

「Azure Identity authentication の問題のトラブルシューティング」では、認証エラー調査手法、Azure Identity Java クライアントライブラリの資格情報の種類に関する一般的なエラー、これらエラーを解決するための移行手順について説明されています。
「依存関係バージョンの競合に対するトラブルシューティング」では、依存関係の競合の診断、軽減、最小化について説明されています。これらの競合は、Maven や Gradle などのツールを使用して構築されたシステムで Azure SDK for Java クライアントライブラリを使用する場合に発生する可能性があります。
「ネットワークの問題のトラブルシューティング」では、Fiddler や Wireshark などのツールを使用して、クライアントライブラリの外部で HTTP デバッグに関連する問題について説明されています。

これらの一般的なトラブルシューティングガイドと共に、ライブラリ固有のトラブルシューティングガイドも記載されています。現時点で、次のガイドを利用できます。

これらのドキュメント以外にも、次のコンテンツでは、Azure SDK for Java に関連するログ記録と例外処理を最大限に活用するためのガイダンスを提供します。

Azure SDK for Java でログを使用する

次のセクションでは、さまざまな種類のログ記録を有効にする方法について説明します。

クライアントのログ記録を有効にする

問題のトラブルシューティングを行うには、まずログ記録を有効にしてアプリケーションの動作を監視することが重要です。ログ内のエラーと警告には、一般的にに、問題の原因に関する有用な分析情報を提供し、問題を修正するための是正措置が含まれる場合があります。 Azure SDK for Java には、包括的なログ記録のサポートがあります。詳細については、「Azure SDK for Java でログを構成する」をご覧ください。

HTTP 要求/応答ログを有効にする

問題のトラブルシューティングを行うときは、Azure サービス間で送受信される HTTP 要求を確認すると便利です。 HTTP 要求と応答ペイロードのログ記録を有効にするには、次の例に示すように、クライアントビルダーでほぼすべての Azure SDK for Java クライアントライブラリを構成できます。特に、クライアントビルダーの httpLogOptions メソッドと、HttpLogDetailLevel で使用できる列挙値に特に注意してください。

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

このコードは、1 つのクライアントインスタンスの HTTP 要求/応答ログを変更します。または、AZURE_HTTP_LOG_DETAIL_LEVEL 環境変数を次の表のいずれかの値に設定して、アプリケーション全体の HTTP 要求と応答のログ記録を構成することもできます。この変更により、HTTP 要求/応答のログ記録をサポートするすべての Azure クライアントのログ記録が有効になることに注意します。

値	ログ記録レベル
`none`	HTTP 要求/応答ログが無効になっています。
`basic`	URL、HTTP メソッド、および要求の完了までの時間のみをログに記録します。
`headers`	BASIC 内のすべてと、すべての要求および応答ヘッダーをログに記録します。
`body`	BASIC 内のすべてと、すべての要求および応答本文をログに記録します。
`body_and_headers`	ヘッダーと本文内のすべてをログに記録します。

Note

要求と応答の本文をログに記録するときは、機密情報が含まれていないことを確認します。クエリパラメーターとヘッダーをログに記録すると、クライアントライブラリには、ログに記録しても安全と見なされるデフォルトのクエリパラメーターとヘッダーのセットがあります。次の例に示すように、ログに記録しても安全なクエリパラメーターとヘッダーを追加できます。

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

Azure SDK for Java での例外処理

ほとんどの Azure SDK for Java クライアントサービスメソッドは、HttpResponseException またはより具体的なサブクラスエラーがスローされます。この HttpResponseException 型には、問題の発生に関する特定の有用な分析情報を提供する詳細な応答エラーオブジェクトが含まれており、一般的な問題を修正するための是正措置が含まれています。このエラー情報は、HttpResponseException オブジェクトのメッセージプロパティ内にあります。これらの例外はランタイム例外であるため、JavaDoc リファレンスドキュメントでは明示的に呼び出されません。

次の例は、同期クライアントでこの例外をキャッチする方法を示しています。

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
}

非同期クライアントでは、次の例に示すように、エラーコールバックで例外をキャッチして処理できます。

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

Azure SDK for Java でトレースを使用する

Azure SDK for Java には包括的なトレースサポートが用意されており、アプリケーションコードと使用しているクライアントライブラリを通じて実行のフローを確認できます。 Azureクライアントライブラリでトレースを有効にするには、OpenTelemetry SDK または OpenTelemetry互換エージェントを使用して構成します。 OpenTelemetry は、クラウドネイティブソフトウェアのテレメトリデータを生成、キャプチャ、収集するためによく使用されるオープンソースの監視フレームワークです。

Azure SDK for Java でトレースを有効にする方法の詳細については、「Azure SDK for Java でトレースを構成する」を参照してください。

次のステップ

この記事のトラブルシューティングガイダンスが、Azure SDK for Java クライアントライブラリを使用するときの問題の解決に役立たない場合は、Azure SDK for Java GitHub リポジトリに問題を提出することをお勧めします。

次の方法で共有