events
Azure SDK for .NET を使用したログ記録
Azure SDK for .NET のクライアント ライブラリには、クライアント ライブラリの操作をログに記録する機能が含まれています。 このログ記録により、クライアント ライブラリが Azure サービスに対して行う I/O 要求と応答を監視できます。 通常、このログは、通信の問題をデバッグまたは診断するために使用されます。 この記事では、Azure SDK for .NET を使用してログ記録を有効にする以下の方法について説明します。
重要
この記事は、最新バージョンの Azure SDK for .NET を使用するクライアント ライブラリに適用されます。 ライブラリがサポートされているかどうかを確認するには、Azure SDK の最新リリースの一覧を参照してください。 アプリで以前のバージョンの Azure SDK クライアント ライブラリを使っている場合は、該当するサービス ドキュメントの具体的な手順を参照してください。
SDK により、各 HTTP 要求および応答がログに記録されます。パラメーター クエリとヘッダー値はサニタイズされ、個人データが削除されます。
HTTP 要求ログ エントリ:
- Unique ID
- HTTP メソッド
- URI
- 送信要求ヘッダー
HTTP 応答ログ エントリ:
- I/O 操作の実行時間 (時間経過)
- 要求 ID
- HTTP 状態コード
- HTTP 理由語句
- 応答ヘッダー
- エラー情報 (該当する場合)
HTTP 要求と応答のコンテンツ:
Content-Type
ヘッダーに応じて、コンテンツ ストリームはテキストまたはバイトになります。注意
コンテンツ ログは既定で無効になっています。 有効にするには、「HTTP 要求と応答の本文をログに記録する」を参照してください。 この機能は、HTTP を使って Azure サービスと通信するライブラリにのみ適用されます。 AMQP などの代替プロトコルに基づくライブラリでは、コンテンツ ログはサポートされていません。 サポートされていない例には、Event Hubs、Service Bus、Web PubSub などの Azure サービスのライブラリが含まれます。
イベント ログは通常、次の 3 つのレベルのいずれかで出力されます。
- 要求と応答イベントの情報
- エラーの警告
- 詳細なメッセージとコンテンツ ログの詳細
Azure SDK for .NET のクライアント ライブラリでは、System.Diagnostics.Tracing.EventSource クラスを使用して Windows イベント トレーシング (ETW) にイベントを記録します。これは、.NET では一般的です。 イベント ソースを使用すると、パフォーマンスのオーバーヘッドを最小限に抑えながら、アプリで構造化されたログを使用できます。 イベント ログにアクセスするには、イベント リスナーを登録する必要があります。
SDK には Azure.Core.Diagnostics.AzureEventSourceListener クラスが含まれています。これには、.NET アプリの包括的なログ記録を簡略化する 2 つの静的メソッド (CreateConsoleLogger
と CreateTraceLogger
) が含まれています。 これらの各メソッドには、ログ レベルを指定する省略可能なパラメーターを指定できます。 パラメーターを指定しない場合は、既定のログ レベル Informational
が使用されます。
Azure SDK for .NET クライアント ライブラリの主な原則は、包括的なログをリアルタイムで簡単に表示できるようにすることです。 CreateConsoleLogger
メソッドを使用すると、1 行のコードでログをコンソール ウィンドウに送信できます。
using AzureEventSourceListener listener =
AzureEventSourceListener.CreateConsoleLogger();
トレース リスナーを実装する場合は、CreateTraceLogger
メソッドを使用して、標準の .NET イベント トレース機構 (System.Diagnostics.Tracing) にログを記録できます。 .NET でのイベント トレースの詳細については、「トレース リスナー」を参照してください。
この例では、詳細レベルのログ記録を指定します。
using AzureEventSourceListener listener =
AzureEventSourceListener.CreateTraceLogger(EventLevel.Verbose);
前述のように、Azure SDK for .NET からログ メッセージを受信するには、イベント リスナーを登録する必要があります。 包括的なログを実装する際に上記の簡略化されたメソッドのいずれも使用しない場合は、AzureEventSourceListener
クラスのインスタンスを作成できます。 そのインスタンスに、作成したコールバック メソッドを渡します。 このメソッドでは、必要に応じて好きに処理できるログ メッセージを受信します。 また、インスタンスを構築するときに、含めるログ レベルを指定することもできます。
次の例では、カスタム メッセージを使用してコンソールにログを記録するイベント リスナーを作成します。 ログは、詳細レベルの Azure Core クライアント ライブラリから生成されたイベントにフィルター処理されます。 Azure Core ライブラリでは、Azure-Core
というイベント ソースの名前が使用されます。
using Azure.Core.Diagnostics;
using System.Diagnostics.Tracing;
// code omitted for brevity
using var listener = new AzureEventSourceListener((e, message) =>
{
// Only log messages from "Azure-Core" event source
if (e.EventSource.Name == "Azure-Core")
{
Console.WriteLine($"{DateTime.Now} {message}");
}
},
level: EventLevel.Verbose);
AzureEventSourceLogForwarder サービスにより、標準の ASP.NET Core のログ構成をログ記録に使用できます。 このサービスは、ログ メッセージを Azure SDK イベント ソースから ILoggerFactory に転送します。
次の表は、Azure SDK for .NET の EventLevel
を ASP.NET Core の LogLevel
にマップする方法を示しています。
Azure SDK EventLevel |
ASP.NET Core LogLevel |
---|---|
Critical |
Critical |
Error |
Error |
Informational |
Information |
Warning |
Warning |
Verbose |
Debug |
LogAlways |
Information |
Azure Service Bus ライブラリを例として使用して、次の手順を実行します。
Microsoft.Extensions.Azure NuGet パッケージをインストールします。
dotnet add package Microsoft.Extensions.Azure
Program.cs で、次のように AddAzureClients 拡張メソッドの呼び出しを介して、Azure SDK ライブラリのクライアントを登録します:
using Azure.Identity; using Microsoft.Extensions.Azure; // code omitted for brevity builder.Services.AddAzureClients(azureBuilder => { azureBuilder.AddServiceBusClient( builder.Configuration.GetConnectionString("ServiceBus")); azureBuilder.UseCredential(new DefaultAzureCredential()); });
上記のサンプルでは、
AddAzureClients
メソッドは:- 依存関係の挿入 (DI) コンテナーに次のオブジェクトを登録します。
- ログ フォワーダー サービス
- Azure Service Bus クライアント
- 登録されているすべてのクライアントで使用する既定のトークン資格情報を設定します。
- 依存関係の挿入 (DI) コンテナーに次のオブジェクトを登録します。
appsettings.json で、Service Bus ライブラリの既定のログ レベルを変更します。 たとえば、これを
Debug
に切り替えるには、Logging:LogLevel:Azure.Messaging.ServiceBus
キーを次のように設定します。{ "ConnectionStrings": { "ServiceBus": "<connection_string>" }, "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning", "Azure.Messaging.ServiceBus": "Debug" } }, "AllowedHosts": "*" }
Logging:LogLevel:Azure.Messaging.ServiceBus
キーがDebug
に設定されているため、EventLevel.Verbose
までの Service Bus クライアント イベントがログに記録されます。
Azure SDK ライブラリのクライアントを DI コンテナーに登録することが不可能または不要であるシナリオがあります。
- Azure SDK ライブラリに、DI コンテナーにクライアントを登録するための
IServiceCollection
拡張メソッドが含まれていない。 - 他の Azure SDK ライブラリに依存する Azure 拡張ライブラリをアプリで使用する。 そのような Azure 拡張ライブラリの例としては、次のようなものがあります。
これらのシナリオでは、次の手順を実行します。
Microsoft.Extensions.Azure NuGet パッケージをインストールします。
dotnet add package Microsoft.Extensions.Azure
Program.cs でログ フォワーダー サービスを DI コンテナーにシングルトンとして登録します:
using Azure.Identity; using Microsoft.AspNetCore.DataProtection; using Microsoft.Extensions.Azure; using Microsoft.Extensions.DependencyInjection.Extensions; var builder = WebApplication.CreateBuilder(args); builder.Services.AddRazorPages(); builder.Services.TryAddSingleton<AzureEventSourceLogForwarder>(); builder.Services.AddDataProtection() .PersistKeysToAzureBlobStorage("<connection_string>", "<container_name>", "keys.xml") .ProtectKeysWithAzureKeyVault(new Uri("<uri>"), new DefaultAzureCredential());
DI コンテナーからログ フォワーダー サービスをフェッチし、その Start メソッドを呼び出します。 たとえば、ASP.NET Core Razor Pages ページ モデル クラスでコンストラクターの挿入を使用する場合:
using Microsoft.AspNetCore.Mvc.RazorPages; using Microsoft.Extensions.Azure; public class IndexModel : PageModel { public IndexModel(AzureEventSourceLogForwarder logForwarder) => logForwarder.Start();
appsettings.json で、Azure Core ライブラリの既定のログ レベルを変更します。 たとえば、これを
Debug
に切り替えるには、Logging:LogLevel:Azure.Core
キーを次のように設定します。{ "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning", "Azure.Core": "Debug" } }, "AllowedHosts": "*" }
Logging:LogLevel:Azure.Core
キーがDebug
に設定されているため、EventLevel.Verbose
までの Azure Core ライブラリ イベントがログに記録されます。
詳細については、「.NET Core と ASP.NET Core でのログ記録」を参照してください。
バージョン 1.2.0
以降の Azure Monitor OpenTelemetry ディストリビューションは、Azure クライアント ライブラリからのログの取り込みをサポートしています。 「.NET Core および ASP.NET Core でのログ記録」で説明されている構成オプションのいずれかを使って、ログを制御できます。
Azure Service Bus ライブラリを例として使用して、次の手順を実行します。
Azure.Monitor.OpenTelemetry.AspNetCore NuGet パッケージをインストールします。
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
ライブラリのクライアントを作成または登録します。 ディストリビューションでは両方のケースがサポートされています。
await using var client = new ServiceBusClient("<connection_string>");
appsettings.json で、Service Bus ライブラリの既定のログ レベルを変更します。 たとえば、これを
Debug
に切り替えるには、Logging:LogLevel:Azure.Messaging.ServiceBus
キーを次のように設定します。{ "ConnectionStrings": { "ServiceBus": "<connection_string>" }, "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning", "Azure.Messaging.ServiceBus": "Debug" } }, "AllowedHosts": "*" }
Logging:LogLevel:Azure.Messaging.ServiceBus
キーがDebug
に設定されているため、EventLevel.Verbose
までの Service Bus クライアント イベントがログに記録されます。
注意
この機能は、HTTP を使って Azure サービスと通信するライブラリにのみ適用されます。 AMQP などの代替プロトコルに基づくライブラリでは、コンテンツ ログはサポートされていません。 サポートされていない例には、Event Hubs、Service Bus、Web PubSub などの Azure サービスのライブラリが含まれます。
クライアント ライブラリの予期しない動作をトラブルシューティングする場合は、次の項目を調べると便利です。
- 基になる Azure サービスの REST API に送信された HTTP 要求本文。
- Azure サービスの REST API から受信した HTTP 応答本文。
既定では、前述のコンテンツのログ記録は無効になっています。 HTTP 要求と応答の本文のログ記録を有効にするには、次の手順を実行します。
クライアント オプション オブジェクトの IsLoggingContentEnabled プロパティを
true
に設定し、オプション オブジェクトをクライアントのコンストラクターに渡します。 たとえば、Azure Key Vault Secrets ライブラリの HTTP 要求と応答をログするには、次のようにします。var clientOptions = new SecretClientOptions { Diagnostics = { IsLoggingContentEnabled = true, } }; var client = new SecretClient( new Uri("https://<keyvaultname>.vault.azure.net/"), new DefaultAzureCredential(), clientOptions);
詳細/デバッグ以上のイベント/ログ レベルで、お好みのログ記録方法を使用します。 具体的な手順については、次の表で自分の方法を確認してください。
アプローチ 手順 組み込みメソッドを使用してログを有効にする EventLevel.Verbose
またはEventLevel.LogAlways
をAzureEventSourceListener.CreateConsoleLogger
またはAzureEventSourceListener.CreateTraceLogger
に渡すカスタム ログを構成する AzureEventSourceListener
クラスのlevel
コンストラクター パラメーターをEventLevel.Verbose
またはEventLevel.LogAlways
に設定するASP.NET Core のログ記録にマップする "Azure.Core": "Debug"
を appsettings.json に追加する
- Azure App Service のアプリの診断ログの有効化
- Azure のセキュリティ ログと監査のオプションを確認する
- Azure プラットフォーム ログを操作する方法を確認する
- .NET のログ記録とトレースの詳細を確認する
.NET に関するフィードバック
.NET はオープンソース プロジェクトです。 フィードバックを提供するにはリンクを選択します。
その他のリソース
トレーニング
モジュール
App Service 診断ログを使用して Web アプリケーション ログをキャプチャする - Training
Azure Web アプリからトレース出力をキャプチャする方法について説明します。 ライブ ログ ストリームを表示し、オフライン分析用にログ ファイルをダウンロードします。