Azure SDK for .NET を使用したログ記録

[アーティクル]
04/15/2024

Azure SDK for .NET のクライアントライブラリには、クライアントライブラリの操作をログに記録する機能が含まれています。このログ記録により、クライアントライブラリが Azure サービスに対して行う I/O 要求と応答を監視できます。通常、このログは、通信の問題をデバッグまたは診断するために使用されます。この記事では、Azure SDK for .NET を使用してログ記録を有効にする以下の方法について説明します。

組み込みメソッドを使用してログを有効にする
カスタムログを構成する
ASP.NET Core のログ記録にマップする

重要

この記事は、最新バージョンの Azure SDK for .NET を使用するクライアントライブラリに適用されます。ライブラリがサポートされているかどうかを確認するには、Azure SDK の最新リリースの一覧を参照してください。アプリで以前のバージョンの Azure SDK クライアントライブラリを使っている場合は、該当するサービスドキュメントの具体的な手順を参照してください。

ログ情報

SDK により、各 HTTP 要求および応答がログに記録されます。パラメータークエリとヘッダー値はサニタイズされ、個人データが削除されます。

HTTP 要求ログエントリ:

Unique ID
HTTP メソッド
URI
送信要求ヘッダー

HTTP 応答ログエントリ:

I/O 操作の実行時間 (時間経過)
要求 ID
HTTP 状態コード
HTTP 理由語句
応答ヘッダー
エラー情報 (該当する場合)

HTTP 要求と応答のコンテンツ:

Content-Type ヘッダーに応じて、コンテンツストリームはテキストまたはバイトになります。

Note

コンテンツログは既定で無効になっています。有効にするには、「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);

ASP.NET Core のログ記録にマップする

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 クライアント
- 登録されているすべてのクライアントで使用する既定のトークン資格情報を設定します。
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 でのログ記録」を参照してください。

Azure.Monitor.OpenTelemetry.AspNetCore を使ったログ

バージョン 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 要求と応答の本文をログに記録する

Note

この機能は、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 SDK for .NET を使用したログ記録

ログ情報

組み込みメソッドを使用してログ記録を有効にする

コンソールウィンドウにログを記録する

診断トレースにログを記録する

カスタムログ記録を構成する

ASP.NET Core のログ記録にマップする

クライアント登録を使用したログ記録

クライアント登録なしのログ記録

Azure.Monitor.OpenTelemetry.AspNetCore を使ったログ

HTTP 要求と応答の本文をログに記録する

次のステップ

その他のリソース

次の方法で共有

Azure SDK for .NET を使用したログ記録

ログ情報

組み込みメソッドを使用してログ記録を有効にする

コンソール ウィンドウにログを記録する

診断トレースにログを記録する

カスタム ログ記録を構成する

ASP.NET Core のログ記録にマップする

クライアント登録を使用したログ記録

クライアント登録なしのログ記録

Azure.Monitor.OpenTelemetry.AspNetCore を使ったログ

HTTP 要求と応答の本文をログに記録する

次のステップ

その他のリソース

コンソールウィンドウにログを記録する

カスタムログ記録を構成する