次の方法で共有

.NET 用 Azure SDK によるログ記録

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

重要

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

ログ情報

SDK は、各 HTTP 要求と応答をログに記録し、パラメーター クエリとヘッダー値をサニタイズして個人データを削除します。

HTTP 要求ログ エントリ:

  • ユニーク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 のクライアント ライブラリは、.NET の一般的な System.Diagnostics.Tracing.EventSource クラスを介してイベント トレーシング for Windows (ETW) にイベントを記録します。 イベント ソースを使用すると、パフォーマンスのオーバーヘッドを最小限に抑えながら、アプリで構造化ログを使用できます。 イベント ログにアクセスするには、イベント リスナーを登録する必要があります。

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 (string.Equals(e.EventSource.Name, "Azure-Core", StringComparison.Ordinal))
        {
            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 クライアント ライブラリからのログのキャプチャがサポートされています。 .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 シークレット ライブラリの 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.LogAlwaysをAzureEventSourceListener.CreateConsoleLoggerまたはAzureEventSourceListener.CreateTraceLogger
    カスタム ログの構成 AzureEventSourceListener クラスの level コンストラクター パラメーターを EventLevel.Verbose またはEventLevel.LogAlways
    ASP.NET Core ログへのマップ appsettings.json に"Azure.Core": "Debug"を追加する

次のステップ