Azure SDK for Java でログを構成する

[アーティクル]
05/07/2024

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

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

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

この記事は、広く使用されている Java ログ記録フレームワークの多くを対象とする他の記事にリンクしています。それらの他の記事では、構成の例を紹介し、Azure クライアントライブラリでのログ記録フレームワークの使用方法について説明しています。

どのようなログ構成を使用しても、Java 用 Azure クライアントライブラリのすべてのログ出力は azure-core ClientLogger 抽象化を使用してルーティングされるため、いずれにしても同じログ出力を利用できます。

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

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

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

OpenTelemetry を使用する場合は、HTTP リクエストのログの代わりに分散トレースの使用を検討してください。詳細については、「Azure SDK for Java でトレースを構成する」をご覧ください。

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

AZURE_HTTP_LOG_DETAIL_LEVEL 環境変数を使用して、HTTP ログをグローバルに有効にすることができます。この変数は次の値をサポートします。

NONE: HTTP ログが無効になります。この値は既定値です。
BASIC: HTTP ログには、リクエストメソッド、サニタイズされたリクエスト URL、試行回数、応答コード、リクエスト本文と応答本文のコンテンツ長が含まれます。
HEADERS: HTTP ログには、基本的な詳細がすべて含まれており、ログ記録の目的で安全であることが知られているヘッダーも含まれています。つまり、HTTP ログには機密情報や機密情報は含まれていません。ヘッダー名の完全なリストは、 HttpLogOptions クラスで入手できます。
BODY_AND_HEADERS: HTTP ログには、 HEADERS レベルで提供されるすべての詳細が含まれます。また、16 KB 未満で印刷可能である限り、要求および応答の本文も含まれます。

Note

リクエスト 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`
ERROR	`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)

Note

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

次のステップ

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

次の方法で共有