Azure SDK for Java でのログ記録の構成

この記事では、JavaのAzure SDKを使用するアプリケーションでログ記録を有効にする方法の概要について説明します。 Java用の Azure クライアント ライブラリには、次の 2 つのログ オプションが用意されています。

  • 一時的なデバッグを目的とした組み込みのログ 記録フレームワーク。
  • SLF4J インターフェイスを使用したログ記録のサポート。

SLF4J は、Java エコシステムでよく知られており、十分に文書化されているため、使用します。 詳細については、SLF4J のユーザー マニュアルを参照してください。

この記事は、一般的な Java ログ フレームワークの多くをカバーする他の記事にリンクしています。 これらの他の記事では、構成例を示し、Azure クライアント ライブラリでログ 記録フレームワークを使用する方法について説明します。

どのようなログ構成を使用する場合でも、Java用の Azure クライアント ライブラリのすべてのログ出力が、azure コアのClientLogger抽象化を介してルーティングされるため、同じログ出力が得られます。

この記事の残りの部分では、使用可能なすべてのログ オプションの構成について詳しく説明します。

HTTP 要求と応答のログ記録を有効にする

HTTP 要求と応答のログは、既定ではオフになっています。 HTTP 経由で Azure サービスと通信するクライアントを構成して、受信した要求と応答 (または例外) ごとにログ レコードを書き込むことができます。

OpenTelemetry を使用する場合は、HTTP 要求のログではなく分散トレースを使用することを検討してください。 詳細については、「 Azure SDK for Java でトレースを構成する」を参照してください。

環境変数を使用して HTTP ログを構成する

AZURE_HTTP_LOG_DETAIL_LEVEL環境変数を使用して、すべてのクライアントの HTTP ログを有効にします。 この変数を次のいずれかの値に設定します。

  • NONE: HTTP ログはオフです。 この値が既定値です。
  • BASIC: HTTP ログには、要求メソッド、サニタイズされた要求 URL、try count、応答コード、要求本文と応答本文のコンテンツ長が含まれます。
  • HEADERS: HTTP ログには、すべての基本的な詳細が含まれます。また、ログ記録の目的で安全であることが知られているヘッダーも含まれます。つまり、シークレットや機密情報は含まれません。 ヘッダー名の完全な一覧は、 HttpLogOptions クラスで使用できます。
  • BODY_AND_HEADERS: HTTP ログは、HEADERS レベルで提供されるすべての詳細に加えて、16 KB 未満で印刷可能な場合にはリクエストとレスポンスの本文も含みます。

注

要求 URL はサニタイズされます。つまり、 api-version 値を除くすべてのクエリ パラメーター値が編集されます。 個々のクライアント ライブラリは、許可リストに安全であることが知られている他のクエリ パラメーターを追加する場合があります。

たとえば、Azure Blob Storage Shared Access Signature (SAS) URL は次の形式でログに記録されます。 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

警告

要求と応答の本文は、機密情報が含まれている可能性があり、パフォーマンスに大きな影響を与え、コンテンツのバッファリング方法を変更し、その他の副作用があるため、運用環境ではログに記録しないでください。

コードで HTTP ログを構成する

HttpTrait<T> インターフェイスを実装する Azure クライアント ビルダーは、コード ベースの HTTP ログ構成をサポートします。 コード ベースの構成は個々のクライアント インスタンスに適用され、環境変数の構成と比較してより多くのオプションとカスタマイズが提供されます。

ログを構成するには、 HttpLogOptions のインスタンスを、対応するクライアント ビルダーの httpLogOptions メソッドに渡します。 次のコードは、App Configuration サービスの例を示しています。

HttpLogOptions httpLogOptions = new HttpLogOptions()
        .setLogLevel(HttpLogDetailLevel.HEADERS)
        .addAllowedHeaderName("Accept-Ranges")
        .addAllowedQueryParamName("label");

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .httpLogOptions(httpLogOptions)
        ...
        .buildClient();

このコードは、ヘッダーを含む HTTP ログを有効にし、 Accept-Ranges 応答ヘッダーと label クエリ パラメーターを対応する許可リストに追加します。 この変更後、これらの値は生成されたログに表示されます。

構成オプションの完全な一覧については、 HttpLogOptions のドキュメントを参照してください。

既定のロガー (一時的なデバッグ用)

前に説明したように、すべての Azure クライアント ライブラリはログ記録に SLF4J を使用しますが、Java 用の Azure クライアント ライブラリに組み込まれているフォールバックの既定のロガーがあります。 この既定のロガーは、アプリケーションをデプロイし、ログを必要とするが、SLF4J ロガーが含まれているアプリケーションを再デプロイできない場合に使用します。 このロガーを有効にするには、まず SLF4J ロガーが存在しないことを確認してから (優先されるため)、 AZURE_LOG_LEVEL 環境変数を設定します。 次の表に、この環境変数に使用できる値を示します。

ログ レベル 使用できる環境変数の値
詳細 verbose、debug
情報 info、 information、 informational
警告: warn、warning
エラー err、error

環境変数を設定した後、アプリケーションを再起動して環境変数を有効にします。 このロガーはコンソールにログを記録し、ロールオーバーやファイルへのログ記録など、SLF4J 実装の高度なカスタマイズ機能を提供しません。 ログ記録をオフにするには、環境変数を削除してアプリケーションを再起動します。

SLF4J のログ記録

既定では、SLF4J でサポートされているログ 記録フレームワークを使用してログ記録を構成します。 まず、プロジェクトからの依存関係として、関連する SLF4J ログの実装を含めます。 詳細については、SLF4J ユーザー・マニュアルでの ログ記録のためのプロジェクト依存関係の宣言 を参照してください。 次に、ログ レベルの設定、ログの実行と記録しないクラスの構成など、環境で必要に応じて機能するようにロガーを構成します。 いくつかの例は、この記事のリンクから提供されていますが、詳細については、選択したログ 記録フレームワークのドキュメントを参照してください。

ログの形式

ログ 記録フレームワークでは、カスタム ログ メッセージの書式設定とレイアウトがサポートされます。 Azure クライアント ライブラリのトラブルシューティングを行えるようにするため、少なくとも次のフィールドを含めてください:

  • ミリ秒精度の日付と時刻
  • ログの重大度
  • ロガー名
  • スレッド名
  • メッセージ

例については、使用するログ 記録フレームワークのドキュメントを参照してください。

構造化ログ

Azure クライアント ライブラリは、前述の一般的なプロパティをログに記録するだけでなく、必要に応じて追加のコンテキストでログ メッセージに注釈を付けます。 たとえば、次の例に示すように、コンテキストが他のルート プロパティとして書き込まれた az.sdk.message を含む JSON 形式のログが表示される場合があります。

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}

Azure Monitor にログを送信するときに、 Kusto クエリ言語 を使用してそれらを解析できます。 次のクエリは例を示しています。

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)

注

Azure クライアント ライブラリ ログは、アドホック デバッグを目的としています。 アプリケーションを警告または監視するためにログ形式に依存しないでください。 Azureクライアント ライブラリでは、ログ メッセージやコンテキスト キーの安定性は保証されません。 このような目的で、分散トレースを使用します。 Application Insights Java エージェントは、要求と依存関係のテレメトリの安定性を保証します。 詳細については、「 Azure SDK for Java でトレースを構成する」を参照してください。

次のステップ

Azure SDK for Java でのログ記録のしくみを確認したら、次の記事を確認することを検討してください。 これらの記事では、SLF4J および Java クライアント ライブラリで動作するように、より一般的な Java ログ フレームワークの一部を構成する方法に関するガイダンスを提供します。

  • Last updated on