次の方法で共有

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

  • [アーティクル]

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

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

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

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

これらのドキュメント以外にも、次のコンテンツでは、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 リポジトリに問題を提出することをお勧めします。