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

[アーティクル]
11/10/2023

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

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

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

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

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

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

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

前述のように、すべての 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 ログ記録フレームワークの一部を構成する方法に関するガイダンスを提供します。