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

2025-04-16

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

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

SLF4J は Java エコシステムでよく知られており、十分に文書化されているため、SLF4J を使用することをお勧めします。詳細については、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、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 ログフレームワークの一部を構成する方法に関するガイダンスを提供します。