英語で読む

次の方法で共有


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 つの静的メソッド (CreateConsoleLoggerCreateTraceLogger) が含まれています。 これらの各メソッドには、ログ レベルを指定する省略可能なパラメーターを指定できます。 パラメーターを指定しない場合は、既定のログ レベル 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 ライブラリを例として使用して、次の手順を実行します。

  1. Microsoft.Extensions.Azure NuGet パッケージをインストールします。

    dotnet add package Microsoft.Extensions.Azure
    
  2. 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 クライアント
    • 登録されているすべてのクライアントで使用する既定のトークン資格情報を設定します。
  3. 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 コンテナーに登録することが不可能または不要であるシナリオがあります。

これらのシナリオでは、次の手順を実行します。

  1. Microsoft.Extensions.Azure NuGet パッケージをインストールします。

    dotnet add package Microsoft.Extensions.Azure
    
  2. 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());
    
  3. 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();
    
  4. 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 ライブラリを例として使用して、次の手順を実行します。

  1. Azure.Monitor.OpenTelemetry.AspNetCore NuGet パッケージをインストールします。

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
    
  2. ライブラリのクライアントを作成または登録します。 ディストリビューションでは両方のケースがサポートされています。

    await using var client = new ServiceBusClient("<connection_string>");
    
  3. 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 要求と応答の本文をログに記録する

注意

この機能は、HTTP を使って Azure サービスと通信するライブラリにのみ適用されます。 AMQP などの代替プロトコルに基づくライブラリでは、コンテンツ ログはサポートされていません。 サポートされていない例には、Event Hubs、Service Bus、Web PubSub などの Azure サービスのライブラリが含まれます。

クライアント ライブラリの予期しない動作をトラブルシューティングする場合は、次の項目を調べると便利です。

  • 基になる Azure サービスの REST API に送信された HTTP 要求本文。
  • Azure サービスの REST API から受信した HTTP 応答本文。

既定では、前述のコンテンツのログ記録は無効になっています。 HTTP 要求と応答の本文のログ記録を有効にするには、次の手順を実行します。

  1. クライアント オプション オブジェクトの 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);
    
  2. 詳細/デバッグ以上のイベント/ログ レベルで、お好みのログ記録方法を使用します。 具体的な手順については、次の表で自分の方法を確認してください。

    アプローチ 手順
    組み込みメソッドを使用してログを有効にする EventLevel.Verbose または EventLevel.LogAlwaysAzureEventSourceListener.CreateConsoleLogger または AzureEventSourceListener.CreateTraceLogger に渡す
    カスタム ログを構成する AzureEventSourceListener クラスの level コンストラクター パラメーターを EventLevel.Verbose または EventLevel.LogAlways に設定する
    ASP.NET Core のログ記録にマップする "Azure.Core": "Debug"appsettings.json に追加する

次のステップ