.NET Core および ASP.NET Core でのログ記録Logging in .NET Core and ASP.NET Core

作成者: Kirk LarkinJuergen GutschRick AndersonBy Kirk Larkin, Juergen Gutsch and Rick Anderson

.NET Core では、組み込みやサード パーティ製のさまざまなログ プロバイダーと連携するログ API がサポートされています。.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. この記事では、組み込みプロバイダーと共にログ API を使用する方法について説明します。This article shows how to use the logging API with built-in providers.

この記事に記載されているほとんどのコード例は、ASP.NET Core アプリのものです。Most of the code examples shown in this article are from ASP.NET Core apps. これらのコード スニペットのログ記録固有の部分は、汎用ホストを使用するすべての .NET Core アプリに適用されます。The logging-specific parts of these code snippets apply to any .NET Core app that uses the Generic Host. ASP.NET Core Web アプリ テンプレートでは、汎用ホストが使用されます。The ASP.NET Core web app templates use the Generic Host.

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

ログ プロバイダーLogging providers

ログを表示する Console プロバイダーを除き、ログ プロバイダーはログを保存します。Logging providers store logs, except for the Console provider which displays logs. たとえば、Azure Application Insights プロバイダーでは、Azure Application Insights にログが保存されます。For example, the Azure Application Insights provider stores logs in Azure Application Insights. 複数のプロバイダーを有効にすることができます。Multiple providers can be enabled.

既定の ASP.NET Core Web アプリ テンプレートでは:The default ASP.NET Core web app templates:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

上記のコードは、ASP.NET Core Web アプリ テンプレートを使用して作成された Program クラスを示しています。The preceding code shows the Program class created with the ASP.NET Core web app templates. 以降のいくつかのセクションでは、汎用ホストを使用する ASP.NET Core Web アプリ テンプレートに基づくサンプルを提供します。The next several sections provide samples based on the ASP.NET Core web app templates, which use the Generic Host. ホスト コンソール以外のアプリについては、このドキュメントで後ほど説明します。Non-host console apps are discussed later in this document.

Host.CreateDefaultBuilder によって追加されたログ プロバイダーの既定のセットをオーバーライドするには、ClearProviders を呼び出し、必要なログ プロバイダーを追加します。To override the default set of logging providers added by Host.CreateDefaultBuilder, call ClearProviders and add the required logging providers. コード例を次に示します。For example, the following code:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

その他のプロバイダーについては、以下を参照してください。For additional providers, see:

ログを作成するCreate logs

ログを作成するには、依存関係の挿入 (DI) から ILogger<TCategoryName> オブジェクトを使用します。To create logs, use an ILogger<TCategoryName> object from dependency injection (DI).

次のような例です。The following example:

  • AboutModel 型の完全修飾名のログ "カテゴリ" を使用する、ロガー ILogger<AboutModel> を作成します。Creates a logger, ILogger<AboutModel>, which uses a log category of the fully qualified name of the type AboutModel. ログのカテゴリは、各ログに関連付けられている文字列です。The log category is a string that is associated with each log.
  • LogInformation を呼び出して、Information レベルでログを記録します。Calls LogInformation to log at the Information level. ログの "レベル" は、ログに記録されるイベントの重大度を示します。The Log level indicates the severity of the logged event.
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }
    public string Message { get; set; }

    public void OnGet()
    {
        Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
        _logger.LogInformation(Message);
    }
}

レベルカテゴリについては、このドキュメントで後ほど詳しく説明します。Levels and categories are explained in more detail later in this document.

Blazor の詳細については、このドキュメントの Blazor および Blazor WebAssembly でのログの作成に関するセクションを参照してください。For information on Blazor, see Create logs in Blazor and Blazor WebAssembly in this document.

Main および Startup でログを作成に関するセクションには、MainStartup でログを作成する方法が示されています。Create logs in Main and Startup shows how to create logs in Main and Startup.

ログの構成Configure logging

一般的に、ログの構成は appsettings.{Environment} .json ファイルの Logging セクションで指定されます。Logging configuration is commonly provided by the Logging section of appsettings.{Environment}.json files. 次のappsettings.Development.json ファイルは、ASP.NET Core Web アプリ テンプレートによって生成されます。The following appsettings.Development.json file is generated by the ASP.NET Core web app templates:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

上記の JSON では、次のように指定されています。In the preceding JSON:

  • "Default""Microsoft"、および "Microsoft.Hosting.Lifetime" の各カテゴリが指定されています。The "Default", "Microsoft", and "Microsoft.Hosting.Lifetime" categories are specified.
  • "Microsoft" カテゴリは、"Microsoft" で始まるすべてのカテゴリに適用されます。The "Microsoft" category applies to all categories that start with "Microsoft". たとえば、この設定は "Microsoft.AspNetCore.Routing.EndpointMiddleware" カテゴリに適用されます。For example, this setting applies to the "Microsoft.AspNetCore.Routing.EndpointMiddleware" category.
  • "Microsoft" カテゴリでは、ログ レベルが Warning 以上のログが記録されます。The "Microsoft" category logs at log level Warning and higher.
  • "Microsoft.Hosting.Lifetime" カテゴリは "Microsoft" カテゴリよりも詳細なので、"Microsoft.Hosting.Lifetime" カテゴリではログ レベルが "情報" 以上のログが記録されます。The "Microsoft.Hosting.Lifetime" category is more specific than the "Microsoft" category, so the "Microsoft.Hosting.Lifetime" category logs at log level "Information" and higher.
  • 特定のログ プロバイダーが指定されていないため、LogLevel は、Windows EventLog を除くすべての有効なログ プロバイダーに適用されます。A specific log provider is not specified, so LogLevel applies to all the enabled logging providers except for the Windows EventLog.

Logging プロパティには LogLevel およびログ プロバイダーのプロパティを含めることができます。The Logging property can have LogLevel and log provider properties. LogLevel により、選択したカテゴリに対するログの最小レベルが指定されます。The LogLevel specifies the minimum level to log for selected categories. 上記の JSON では、InformationWarning のログ レベルが指定されています。In the preceding JSON, Information and Warning log levels are specified. LogLevel はログの重大度を 0 - 6 の範囲で示します。LogLevel indicates the severity of the log and ranges from 0 to 6:

Trace = 0、Debug = 1、Information = 2、Warning = 3、Error = 4、Critical = 5、None = 6。Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5, and None = 6.

LogLevel を指定すると、指定したレベル以上のメッセージに対してログが有効になります。When a LogLevel is specified, logging is enabled for messages at the specified level and higher. 上記の JSON では、Default カテゴリは Information 以上に対してのみログに記録されます。In the preceding JSON, the Default category is logged for Information and higher. たとえば、InformationWarningErrorCritical のメッセージがログに記録されます。For example, Information, Warning, Error, and Critical messages are logged. LogLevel が指定されていない場合、ログは既定で Information レベルになります。If no LogLevel is specified, logging defaults to the Information level. 詳細については、「ログ レベル」を参照してください。For more information, see Log levels.

プロバイダー プロパティで LogLevel プロパティを指定できます。A provider property can specify a LogLevel property. プロバイダーの下の LogLevel によって、そのプロバイダーのログに記録するレベルが指定され、プロバイダー以外のログ設定がオーバーライドされます。LogLevel under a provider specifies levels to log for that provider, and overrides the non-provider log settings. 以下の appsettings.json ファイルについて考えます:Consider the following appsettings.json file:

{
  "Logging": {
    "LogLevel": { // All providers, LogLevel applies to all the enabled providers.
      "Default": "Error", // Default logging, Error and higher.
      "Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information", // Overrides preceding LogLevel:Default setting.
        "Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
      }
    },
    "EventSource": { // EventSource provider
      "LogLevel": {
        "Default": "Warning" // All categories of EventSource provider.
      }
    }
  }
}

Logging.{providername}.LogLevel の設定により Logging.LogLevel の設定がオーバーライドされます。Settings in Logging.{providername}.LogLevel override settings in Logging.LogLevel. 上記の JSON では、Debug プロバイダーの既定のログ レベルは Information に設定されています。In the preceding JSON, the Debug provider's default log level is set to Information:

Logging:Debug:LogLevel:Default:Information

上記の設定により、Microsoft.Hosting 以外のすべての Logging:Debug: カテゴリに Information ログ レベルが指定されます。The preceding setting specifies the Information log level for every Logging:Debug: category except Microsoft.Hosting. 特定のカテゴリが一覧表示されると、特定のカテゴリによって既定のカテゴリがオーバーライドされます。When a specific category is listed, the specific category overrides the default category. 上記の JSON では、Logging:Debug:LogLevel カテゴリ "Microsoft.Hosting""Default" によって、Logging:LogLevel の設定がオーバーライドされます。In the preceding JSON, the Logging:Debug:LogLevel categories "Microsoft.Hosting" and "Default" override the settings in Logging:LogLevel

最小ログ レベルは、次のいずれかに指定できます。The minimum log level can be specified for any of:

  • 特定のプロバイダー: たとえば、Logging:EventSource:LogLevel:Default:InformationSpecific providers: For example, Logging:EventSource:LogLevel:Default:Information
  • 特定のカテゴリ: たとえば、Logging:LogLevel:Microsoft:WarningSpecific categories: For example, Logging:LogLevel:Microsoft:Warning
  • すべてのプロバイダーとすべてのカテゴリ: Logging:LogLevel:Default:WarningAll providers and all categories: Logging:LogLevel:Default:Warning

最小レベルを下回るログは、次のことが "行われません"。Any logs below the minimum level are not:

  • プロバイダーに渡される。Passed to the provider.
  • ログに記録または表示される。Logged or displayed.

すべてのログを抑制するには、LogLevel.None を指定します。To suppress all logs, specify LogLevel.None. LogLevel.None の値は、LogLevel.Critical (5) より大きい 6 です。LogLevel.None has a value of 6, which is higher than LogLevel.Critical (5).

プロバイダーでログのスコープがサポートされている場合、IncludeScopes によってそれを有効にするかどうかが指定されます。If a provider supports log scopes, IncludeScopes indicates whether they're enabled. 詳細については、「ログ スコープ」を参照してください。For more information, see log scopes

次の appsettings.json ファイルには、既定で有効になっているすべてのプロバイダーが含まれています。The following appsettings.json file contains all the providers enabled by default:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "EventSource": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "EventLog": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "AzureAppServicesFile": {
      "IncludeScopes": true,
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "AzureAppServicesBlob": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

上記のサンプルについて:In the preceding sample:

  • カテゴリとレベルは推奨値ではありません。The categories and levels are not suggested values. このサンプルは、すべての既定のプロバイダーを表示するために提供されています。The sample is provided to show all the default providers.
  • Logging.{providername}.LogLevel の設定により Logging.LogLevel の設定がオーバーライドされます。Settings in Logging.{providername}.LogLevel override settings in Logging.LogLevel. たとえば、Debug.LogLevel.Default のレベルにより LogLevel.Default のレベルがオーバーライドされます。For example, the level in Debug.LogLevel.Default overrides the level in LogLevel.Default.
  • 各既定のプロバイダーの "別名" が使用されます。Each default provider alias is used. 各プロバイダーでは "エイリアス" が定義されます。これは構成で完全修飾型名の代わりに使用できます。Each provider defines an alias that can be used in configuration in place of the fully qualified type name. 組み込みプロバイダーの別名には次のものがあります。The built-in providers aliases are:
    • コンソールConsole
    • デバッグDebug
    • EventSourceEventSource
    • EventLogEventLog
    • AzureAppServicesFileAzureAppServicesFile
    • AzureAppServicesBlobAzureAppServicesBlob
    • ApplicationInsightsApplicationInsights

コマンド ライン、環境変数、およびその他の構成でログ レベルを設定するSet log level by command line, environment variables, and other configuration

ログ レベルは、いずれかの構成プロバイダーで設定できます。Log level can be set by any of the configuration providers.

: の区切り記号は、すべてのプラットフォームの環境変数階層キーには対応していません。The : separator doesn't work with environment variable hierarchical keys on all platforms. __(ダブルアンダースコア)は、__, the double underscore, is:

  • すべてのプラットフォームに対応しています。Supported by all platforms. たとえば、Bash: の区切り記号には対応していませんが、__ には対応しています。For example, the : separator is not supported by Bash, but __ is.
  • 自動で : に置換されます。Automatically replaced by a :

次のコマンドは:The following commands:

  • 環境キー Logging:LogLevel:Microsoft を Windows の Information の値に設定します。Set the environment key Logging:LogLevel:Microsoft to a value of Information on Windows.
  • ASP.NET Core Web アプリケーション テンプレートを使用して作成されたアプリを使用する際に、設定をテストします。Test the settings when using an app created with the ASP.NET Core web application templates. dotnet run コマンドは、set を使用した後、プロジェクト ディレクトリで実行する必要があります。The dotnet run command must be run in the project directory after using set.
set Logging__LogLevel__Microsoft=Information
dotnet run

上記の環境設定は:The preceding environment setting:

  • コマンド ウィンドウから起動されたプロセスでのみ設定可能です。Is only set in processes launched from the command window they were set in.
  • Visual Studio で起動されたブラウザーでは読み取れません。Isn't read by browsers launched with Visual Studio.

次の setx コマンドは、Windows 上で環境キーと値も設定します。The following setx command also sets the environment key and value on Windows. set とは異なり、setx 設定は保持されます。Unlike set, setx settings are persisted. /M スイッチにより、システム環境で変数が設定されます。The /M switch sets the variable in the system environment. /M が使用されていない場合には、ユーザー環境変数が設定されます。If /M isn't used, a user environment variable is set.

setx Logging__LogLevel__Microsoft=Information /M

Azure App Service で、 設定 > 構成 ページの新しいアプリケーション設定を選択します。On Azure App Service, select New application setting on the Settings > Configuration page. Azure App Service アプリケーションの設定は:Azure App Service application settings are:

  • 保存時に暗号化され、暗号化されたチャネルで送信されます。Encrypted at rest and transmitted over an encrypted channel.
  • 環境変数として公開されます。Exposed as environment variables.

詳細については、「Azure アプリ: Azure Portal を使用してアプリの構成をオーバーライドする」を参照してください。For more information, see Azure Apps: Override app configuration using the Azure Portal.

環境変数を使用して ASP.NET Core 構成値を設定する方法の詳細については、「環境変数」を参照してください。For more information on setting ASP.NET Core configuration values using environment variables, see environment variables. コマンド ライン、Azure Key Vault、Azure App Configuration、その他のファイル形式など、他の構成ソースの使用の詳細については、「ASP.NET Core の構成」を参照してください。For information on using other configuration sources, including the command line, Azure Key Vault, Azure App Configuration, other file formats, and more, see ASP.NET Core の構成.

フィルター規則を適用する方法How filtering rules are applied

ILogger<TCategoryName> オブジェクトを作成すると、ILoggerFactory オブジェクトによって、そのロガーに適用するプロバイダーごとに 1 つの規則が選択されます。When an ILogger<TCategoryName> object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. ILogger インスタンスによって書き込まれるすべてのメッセージは、選択した規則に基づいてフィルター処理されます。All messages written by an ILogger instance are filtered based on the selected rules. 使用できる規則から、各プロバイダーとカテゴリのペアごとに最も明確な規則が選択されます。The most specific rule for each provider and category pair is selected from the available rules.

特定のカテゴリに ILogger が作成されるときに、各プロバイダーに次のアルゴリズムが使用されます。The following algorithm is used for each provider when an ILogger is created for a given category:

  • プロバイダーとそのエイリアスと一致するすべての規則が選択されます。Select all rules that match the provider or its alias. 一致が見つからない場合は、空のプロバイダーですべての規則が選択されます。If no match is found, select all rules with an empty provider.
  • 前の手順の結果、最も長いカテゴリのプレフィックスが一致する規則が選択されます。From the result of the preceding step, select rules with longest matching category prefix. 一致が見つからない場合は、カテゴリを指定しないすべての規則が選択されます。If no match is found, select all rules that don't specify a category.
  • 複数の規則が選択されている場合は、最後の 1 つが使用されます。If multiple rules are selected, take the last one.
  • 規則が選択されていない場合は、MinimumLevel が使用されます。If no rules are selected, use MinimumLevel.

dotnet run および Visual Studio からのログ出力Logging output from dotnet run and Visual Studio

既定のログ プロバイダーで作成されたログが表示されます。Logs created with the default logging providers are displayed:

  • Visual Studio 内In Visual Studio
    • デバッグ時はデバッグ出力ウィンドウ内。In the Debug output window when debugging.
    • ASP.NET Core Web サーバー ウィンドウ内。In the ASP.NET Core Web Server window.
  • アプリが dotnet run で実行されている場合はコンソール ウィンドウ内。In the console window when the app is run with dotnet run.

"Microsoft" カテゴリから始まるログは、ASP.NET Core のフレームワークのコードからのログです。Logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core とアプリケーション コードでは、同じログ API とログ プロバイダーが使用されます。ASP.NET Core and application code use the same logging API and providers.

ログのカテゴリLog category

ILogger オブジェクトが作成されるときに、"カテゴリ" が指定されます。When an ILogger object is created, a category is specified. このカテゴリは、ILogger のインスタンスによって作成される各ログ メッセージと共に含められます。That category is included with each log message created by that instance of ILogger. カテゴリ文字列は任意ですが、規則ではクラス名を使用します。The category string is arbitrary, but the convention is to use the class name. たとえば、コントローラーでは、名前が "TodoApi.Controllers.TodoController" になる場合があります。For example, in a controller the name might be "TodoApi.Controllers.TodoController". ASP.NET Core Web アプリでは、ILogger<T> を使用して、カテゴリとして T の完全修飾型名を使用する ILogger インスタンスが自動的に取得されます。The ASP.NET Core web apps use ILogger<T> to automatically get an ILogger instance that uses the fully qualified type name of T as the category:

public class PrivacyModel : PageModel
{
    private readonly ILogger<PrivacyModel> _logger;

    public PrivacyModel(ILogger<PrivacyModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.PrivacyModel called.");
    }
}

カテゴリを明示的に指定するには、ILoggerFactory.CreateLogger を呼び出します。To explicitly specify the category, call ILoggerFactory.CreateLogger:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

    public ContactModel(ILoggerFactory logger)
    {
        _logger = logger.CreateLogger("TodoApi.Pages.ContactModel");
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.ContactModel called.");
    }

ILogger<T> は、T の完全修飾型名を使用した CreateLogger の呼び出しと同じです。ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

ログ レベルLog level

次の表に、LogLevel 値、便利な Log{LogLevel} 拡張メソッド、推奨される使用法を示します。The following table lists the LogLevel values, the convenience Log{LogLevel} extension method, and the suggested usage:

LogLevelLogLevel [値]Value MethodMethod 説明Description
トレースTrace 00 LogTrace 最も詳細なメッセージが含まれます。Contain the most detailed messages. これらのメッセージには、機密性の高いアプリ データが含まれる場合があります。These messages may contain sensitive app data. これらのメッセージは既定で無効になっているため、運用環境では有効に "しないでください"。These messages are disabled by default and should not be enabled in production.
デバッグDebug 11 LogDebug デバッグと開発用。For debugging and development. 量が多いため、運用環境では慎重に使用してください。Use with caution in production due to the high volume.
情報Information 22 LogInformation アプリの一般的なフローを追跡します。Tracks the general flow of the app. 長期的な値が含まれている可能性があります。May have long-term value.
警告Warning 33 LogWarning 異常なイベントや予期しないイベント用。For abnormal or unexpected events. 通常、アプリが失敗する原因にならないエラーや条件が含まれます。Typically includes errors or conditions that don't cause the app to fail.
エラーError 44 LogError 処理できないエラーと例外の場合。For errors and exceptions that cannot be handled. これらのメッセージは、アプリ全体のエラーではなく、現在の操作や要求における失敗を示します。These messages indicate a failure in the current operation or request, not an app-wide failure.
重大Critical 55 LogCritical 即時の注意が必要なエラーの場合。For failures that require immediate attention. 例: データ損失のシナリオ、ディスク領域不足。Examples: data loss scenarios, out of disk space.
NoneNone 66 ログのカテゴリにメッセージを記述しないように指定します。Specifies that a logging category should not write any messages.

前の表では、重大度が最も低い方から高い方に LogLevel が一覧表示されています。In the previous table, the LogLevel is listed from lowest to highest severity.

Log メソッドの最初のパラメーター LogLevel は、ログの重大度を示します。The Log method's first parameter, LogLevel, indicates the severity of the log. ほとんどの開発者は、Log(LogLevel, ...) を呼び出すのではなく、Log{LogLevel} 拡張メソッドを呼び出します。Rather than calling Log(LogLevel, ...), most developers call the Log{LogLevel} extension methods. Log{LogLevel} 拡張メソッドによって、Log メソッドが呼び出され、LogLevel が指定されますThe Log{LogLevel} extension methods call the Log method and specify the LogLevel. たとえば、次の 2 つのログ呼び出しは、機能的に同等で、同じログが生成されます。For example, the following two logging calls are functionally equivalent and produce the same log:

[HttpGet]
public IActionResult Test1(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);

    _logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem はイベント ID です。MyLogEvents.TestItem is the event ID. MyLogEvents はサンプル アプリの一部であり、ログ イベント ID セクションに表示されます。MyLogEvents is part of the sample app and is displayed in the Log event ID section.

MyDisplayRouteInfo and ToCtxStringRick.Docs.Samples.RouteInfo NuGet パッケージによって提供されます。MyDisplayRouteInfo and ToCtxString are provided by the Rick.Docs.Samples.RouteInfo NuGet package. このメソッドにより Controller ルート情報が表示されます。The methods display Controller route information.

Information および Warning ログを作成するコードを次に示します。The following code creates Information and Warning logs:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

上記のコードでは、最初の Log{LogLevel} パラメーター MyLogEvents.GetItem は、ログ イベント ID です。In the preceding code, the first Log{LogLevel} parameter,MyLogEvents.GetItem, is the Log event ID. 2 つ目のパラメーターは、他のメソッド パラメーターによって提供される引数値のプレースホルダーを含むメッセージ テンプレートです。The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. メソッド パラメーターについては、このドキュメントで後述するメッセージ テンプレートのセクションで説明します。The method parameters are explained in the message template section later in this document.

適切な Log{LogLevel} メソッドを呼び出して、特定のストレージ メディアに書き込むログ出力量を制御します。Call the appropriate Log{LogLevel} method to control how much log output is written to a particular storage medium. 次に例を示します。For example:

  • 運用環境:In production:
    • Trace または Information のレベルでログを記録すると、詳細なログ メッセージが大量に生成されます。Logging at the Trace or Information levels produces a high-volume of detailed log messages. コストを制御し、データ ストレージの上限を超えないようにするには、Trace および Information のレベルのメッセージを、大容量の低コストのデータ ストアに記録します。To control costs and not exceed data storage limits, log Trace and Information level messages to a high-volume, low-cost data store. TraceInformation を特定のカテゴリに制限することを検討してください。Consider limiting Trace and Information to specific categories.
    • Warning から Critical のレベルでログを記録しても、ログ メッセージはほとんど生成されません。Logging at Warning through Critical levels should produce few log messages.
      • 通常、コストとストレージの制限は考慮されません。Costs and storage limits usually aren't a concern.
      • ログの数が少ないほど、データ ストアをより柔軟に選択できるようになります。Few logs allow more flexibility in data store choices.
  • 開発中:In development:
    • Warning を設定します。Set to Warning.
    • トラブルシューティングの際に Trace または Information のメッセージを追加します。Add Trace or Information messages when troubleshooting. 出力を制限するには、調査中のカテゴリに対してのみ Trace または Information を設定します。To limit output, set Trace or Information only for the categories under investigation.

ASP.NET Core では、フレームワーク イベントのログが書き込まれます。ASP.NET Core writes logs for framework events. たとえば、次のログ出力について考えてみます。For example, consider the log output for:

  • ASP.NET Core テンプレートを使用して作成された Razor Pages アプリA Razor Pages app created with the ASP.NET Core templates.
  • Logging:Console:LogLevel:Microsoft:Information に設定されているログLogging set to Logging:Console:LogLevel:Microsoft:Information
  • プライバシー ページへの移動Navigation to the Privacy page:
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

次の JSON は Logging:Console:LogLevel:Microsoft:Information を設定します。The following JSON sets Logging:Console:LogLevel:Microsoft:Information:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

ログ イベント IDLog event ID

各ログで "イベント ID" を指定できます。Each log can specify an event ID. このサンプル アプリでは、MyLogEvents クラスを使用してイベント ID を定義します。The sample app uses the MyLogEvents class to define event IDs:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

イベント ID によって一連のイベントが関連付けられます。An event ID associates a set of events. たとえば、ページ上に項目の一覧を表示する機能に関連するすべてのログを 1001 に設定します。For example, all logs related to displaying a list of items on a page might be 1001.

ログ プロバイダーでは、ID フィールドやログ メッセージにイベント ID が格納されたり、またはまったく格納されなかったりする場合があります。The logging provider may store the event ID in an ID field, in the logging message, or not at all. Debug プロバイダーでイベント ID が表示されることはありません。The Debug provider doesn't show event IDs. Console プロバイダーでは、カテゴリの後のブラケット内にイベント ID が表示されます。The console provider shows event IDs in brackets after the category:

info: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) NOT FOUND

一部のログ プロバイダーでは、イベント ID がフィールドに格納されます。これにより、ID に対するフィルター処理が可能になります。Some logging providers store the event ID in a field, which allows for filtering on the ID.

ログ メッセージ テンプレートLog message template

各ログ API では、メッセージ テンプレートが使用されます。Each log API uses a message template. メッセージ テンプレートには、指定される引数のためのプレースホルダーを含めることができます。The message template can contain placeholders for which arguments are provided. プレースホルダーには、数値ではなく名前を使用します。Use names for the placeholders, not numbers.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

プレースホルダーの名前ではなく、プレースホルダーの順序によって、値の指定に使用されるパラメーターが決まります。The order of placeholders, not their names, determines which parameters are used to provide their values. 次のコードでは、パラメーター名がメッセージ テンプレート内のシーケンスの外にあります。In the following code, the parameter names are out of sequence in the message template:

string p1 = "param1";
string p2 = "param2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

上記のコードでは、シーケンス内のパラメーター値を含むログ メッセージが作成されます。The preceding code creates a log message with the parameter values in sequence:

Parameter values: param1, param2

この方法により、ログ プロバイダーが セマンティック ログまたは構造化ログを実装できるようになります。This approach allows logging providers to implement semantic or structured logging. 書式設定されたメッセージ テンプレートだけでなく、引数自体がログ システムに渡されます。The arguments themselves are passed to the logging system, not just the formatted message template. これにより、ログ プロバイダーはフィールドとしてパラメーター値を格納することができます。This enables logging providers to store the parameter values as fields. たとえば、次のロガー メソッドについて考えてみます。For example, consider the following logger method:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

たとえば、Azure Table Storage にログを記録する場合:For example, when logging to Azure Table Storage:

  • 各 Azure Table エンティティには、ID プロパティと RequestTime プロパティを含めることができます。Each Azure Table entity can have ID and RequestTime properties.
  • プロパティを持つテーブルによって、ログに記録されたデータに対するクエリが簡略化されます。Tables with properties simplify queries on logged data. たとえば、クエリによって、特定の RequestTime の範囲内のすべてのログを検索できます。テキスト メッセージから時間を解析する必要はありません。For example, a query can find all logs within a particular RequestTime range without having to parse the time out of the text message.

例外をログに記録するLog exceptions

ロガー メソッドには、例外パラメーターを受け取るオーバーロードがあります。The logger methods have overloads that take an exception parameter:

[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    try
    {
        if (id == 3)
        {
            throw new Exception("Test exception");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
        return NotFound();
    }

    return ControllerContext.MyDisplayRouteInfo();
}

MyDisplayRouteInfo and ToCtxStringRick.Docs.Samples.RouteInfo NuGet パッケージによって提供されます。MyDisplayRouteInfo and ToCtxString are provided by the Rick.Docs.Samples.RouteInfo NuGet package. このメソッドにより Controller ルート情報が表示されます。The methods display Controller route information.

例外ログはプロバイダー固有です。Exception logging is provider-specific.

既定のログ レベルDefault log level

既定のログ レベルが設定されていない場合、既定のログ レベル値は Information になります。If the default log level is not set, the default log level value is Information.

たとえば、次の Web アプリについて考えてみます。For example, consider the following web app:

  • ASP.NET Web アプリ テンプレートを使用して作成された。Created with the ASP.NET web app templates.
  • appsettings.jsonappsettings.Development.json が削除または名前が変更された。appsettings.json and appsettings.Development.json deleted or renamed.

上記の設定で、プライバシー ページまたはホーム ページに移動すると、カテゴリ名に Microsoft が含まれる多くのTraceDebugInformation のメッセージが生成されます。With the preceding setup, navigating to the privacy or home page produces many Trace, Debug, and Information messages with Microsoft in the category name.

次のコードは、既定のログ レベルが構成で設定されていない場合に、既定のログ レベルを設定します。The following code sets the default log level when the default log level is not set in configuration:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

一般に、ログ レベルは、コードではなく構成で指定する必要があります。Generally, log levels should be specified in configuration and not code.

フィルター関数Filter function

フィルター関数は、構成またはコードによって規則が割り当てられていないすべてのプロバイダーとカテゴリに対して呼び出されます。A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddFilter((provider, category, logLevel) =>
                {
                    if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Controller")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Microsoft")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else
                    {
                        return false;
                    }
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

上記のコードでは、カテゴリに Controller または Microsoft が含まれ、ログ レベルが Information 以上の場合にコンソール ログが表示されます。The preceding code displays console logs when the category contains Controller or Microsoft and the log level is Information or higher.

一般に、ログ レベルは、コードではなく構成で指定する必要があります。Generally, log levels should be specified in configuration and not code.

ASP.NET Core と EF Core のカテゴリASP.NET Core and EF Core categories

次の表に、ASP.NET Core と Entity Framework Core で使用されるいくつかのカテゴリと、ログに関するメモを示します。The following table contains some categories used by ASP.NET Core and Entity Framework Core, with notes about the logs:

カテゴリCategory メモNotes
Microsoft.AspNetCoreMicrosoft.AspNetCore ASP.NET Core の一般的な診断。General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection どのキーが検討、検索、および使用されたか。Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering 許可されるホスト。Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting HTTP 要求が完了するまでにかかった時間と、それらの開始時刻。How long HTTP requests took to complete and what time they started. どのホスティング スタートアップ アセンブリが読み込まれたか。Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc MVC と Razor の診断。MVC and Razor diagnostics. モデルの構築、フィルター処理の実行、ビューのコンパイル、アクションの選択。Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing 一致する情報をルーティングします。Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server 接続の開始、停止、キープ アライブ応答。Connection start, stop, and keep alive responses. HTTPS 証明書情報。HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles 提供されるファイル。Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore Entity Framework Core の一般的な診断。General Entity Framework Core diagnostics. データベースのアクティビティと構成、変更の検出、移行。Database activity and configuration, change detection, migrations.

コンソール ウィンドウに他のカテゴリを表示するには、appsettings.Development.json を次のように設定します。To view more categories in the console window, set appsettings.Development.json to the following:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Trace",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

ログのスコープLog scopes

"スコープ" では、論理操作のセットをグループ化できます。A scope can group a set of logical operations. このグループ化を使用して、セットの一部として作成される各ログに同じデータをアタッチすることができます。This grouping can be used to attach the same data to each log that's created as part of a set. たとえば、トランザクション処理の一部として作成されるすべてのログに、トランザクション ID を含めることができます。For example, every log created as part of processing a transaction can include the transaction ID.

スコープは:A scope:

次のプロバイダーではスコープがサポートされています。The following providers support scopes:

ロガーの呼び出しを using ブロックでラップすることによって、スコープを使用します。Use a scope by wrapping logger calls in a using block:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;

    using (_logger.BeginScope("using block message"))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

        todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            _logger.LogWarning(MyLogEvents.GetItemNotFound, 
                "Get({Id}) NOT FOUND", id);
            return NotFound();
        }
    }

    return ItemToDTO(todoItem);
}

次の JSON では、Console プロバイダーのスコープを有効にしています。The following JSON enables scopes for the console provider:

{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": true, // Required to use Scopes.
      "LogLevel": {
        "Microsoft": "Warning",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

次のコードでは、Console プロバイダーのスコープを有効にしています。The following code enables scopes for the console provider:

public class Scopes
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging((hostingContext, logging) =>
            {
                logging.ClearProviders();
                logging.AddConsole(options => options.IncludeScopes = true);
                logging.AddDebug();
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

一般に、ログは、コードではなく構成で指定する必要があります。Generally, logging should be specified in configuration and not code.

組み込みのログ プロバイダーBuilt-in logging providers

ASP.NET Core には、次のログ プロバイダーが含まれています。ASP.NET Core includes the following logging providers:

ASP.NET Core モジュールを使用した stdout およびデバッグ ログの詳細については、「Azure App Service および IIS での ASP.NET Core のトラブルシューティング」および「ASP.NET Core モジュール」を参照してください。For information on stdout and debug logging with the ASP.NET Core Module, see Azure App Service および IIS での ASP.NET Core のトラブルシューティング and ASP.NET Core モジュール.

コンソールConsole

Console プロバイダーでは、コンソールへの出力がログに記録されます。The Console provider logs output to the console. 開発中の Console ログを表示する方法の詳細については、「dotnet run および Visual Studio からのログ出力」を参照してください。For more information on viewing Console logs in development, see Logging output from dotnet run and Visual Studio.

デバッグDebug

Debug プロバイダーでは、System.Diagnostics.Debug クラスを使用してログ出力が書き込まれます。The Debug provider writes log output by using the System.Diagnostics.Debug class. Debug プロバイダーに書き込むために System.Diagnostics.Debug.WriteLine が呼び出されます。Calls to System.Diagnostics.Debug.WriteLine write to the Debug provider.

Linux では、Debug プロバイダーのログの場所は配布によって異なり、次のいずれかになります。On Linux, the Debug provider log location is distribution-dependent and may be one of the following:

  • /var/log/message/var/log/message
  • /var/log/syslog/var/log/syslog

イベント ソースEvent Source

EventSource プロバイダーでは、Microsoft-Extensions-Logging という名前のクロスプラットフォーム イベント ソースに書き込まれます。The EventSource provider writes to a cross-platform event source with the name Microsoft-Extensions-Logging. Windows では、プロバイダーによって ETW が使用されます。On Windows, the provider uses ETW.

dotnet trace ツールdotnet trace tooling

dotnet-trace ツールは、実行中のプロセスの .NET Core のトレースのコレクションを有効にする、クロスプラットフォームの CLI グローバル ツールです。The dotnet-trace tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process. このツールでは、LoggingEventSource を使用して Microsoft.Extensions.Logging.EventSource プロバイダー データを収集します。The tool collects Microsoft.Extensions.Logging.EventSource provider data using a LoggingEventSource.

インストール手順については、dotnet-trace に関するページを参照してください。See dotnet-trace for installation instructions.

dotnet trace ツールを使用して、アプリからトレースを収集します。Use the dotnet trace tooling to collect a trace from an app:

  1. dotnet run コマンドを使用してアプリを実行します。Run the app with the dotnet run command.

  2. .NET Core アプリのプロセス識別子 (PID) を決定します。Determine the process identifier (PID) of the .NET Core app:

    アプリのアセンブリと同じ名前を持つプロセスの PID を検索します。Find the PID for the process that has the same name as the app's assembly.

  3. dotnet trace コマンドを実行します。Execute the dotnet trace command.

    一般的なコマンド構文General command syntax:

    dotnet trace collect -p {PID} 
        --providers Microsoft-Extensions-Logging:{Keyword}:{Event Level}
            :FilterSpecs=\"
                {Logger Category 1}:{Event Level 1};
                {Logger Category 2}:{Event Level 2};
                ...
                {Logger Category N}:{Event Level N}\"
    

    PowerShell コマンド シェルを使用する場合は、--providers 値を単一引用符 (') で囲みます。When using a PowerShell command shell, enclose the --providers value in single quotes ('):

    dotnet trace collect -p {PID} 
        --providers 'Microsoft-Extensions-Logging:{Keyword}:{Event Level}
            :FilterSpecs=\"
                {Logger Category 1}:{Event Level 1};
                {Logger Category 2}:{Event Level 2};
                ...
                {Logger Category N}:{Event Level N}\"'
    

    Windows 以外のプラットフォームでは、-f speedscope オプションを追加して、出力トレース ファイルの形式を speedscope に変更します。On non-Windows platforms, add the -f speedscope option to change the format of the output trace file to speedscope.

    キーワードKeyword 説明Description
    11 LoggingEventSource に関するメタ イベントをログに記録します。Log meta events about the LoggingEventSource. ILogger からのイベントは記録されません。Doesn't log events from ILogger).
    22 ILogger.Log() が呼び出されたときに、Message イベントをオンにします。Turns on the Message event when ILogger.Log() is called. プログラムで (書式設定されずに) 情報が提供されます。Provides information in a programmatic (not formatted) way.
    44 ILogger.Log() が呼び出されたときに、FormatMessage イベントをオンにします。Turns on the FormatMessage event when ILogger.Log() is called. 書式設定された文字列バージョンの情報が提供されます。Provides the formatted string version of the information.
    88 ILogger.Log() が呼び出されたときに、MessageJson イベントをオンにします。Turns on the MessageJson event when ILogger.Log() is called. 引数の JSON 表現が提供されます。Provides a JSON representation of the arguments.
    イベント レベルEvent Level 説明Description
    00 LogAlways
    11 Critical
    22 Error
    33 Warning
    44 Informational
    55 Verbose

    {Logger Category}{Event Level}FilterSpecs エントリは、追加のログ フィルター条件を表します。FilterSpecs entries for {Logger Category} and {Event Level} represent additional log filtering conditions. セミコロン (;) で FilterSpecs エントリを区切ります。Separate FilterSpecs entries with a semicolon (;).

    Windows コマンド シェルを使用した例 (--providers 値を囲む単一引用符なし):Example using a Windows command shell (no single quotes around the --providers value):

    dotnet trace collect -p {PID} --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"
    

    上記のコマンドにより次のことがアクティブになります。The preceding command activates:

    • エラー (2) に対して書式設定された文字列 (4) を生成するイベント ソース ロガー。The Event Source logger to produce formatted strings (4) for errors (2).
    • Informational ログ レベル (4) での Microsoft.AspNetCore.Hosting のログ記録。Microsoft.AspNetCore.Hosting logging at the Informational logging level (4).
  4. Enter キーまたは Ctrl + C キーを押すことで、dotnet trace ツールを停止します。Stop the dotnet trace tooling by pressing the Enter key or Ctrl+C.

    トレースは、dotnet trace コマンドが実行されたフォルダーに trace.nettrace という名前で保存されます。The trace is saved with the name trace.nettrace in the folder where the dotnet trace command is executed.

  5. Perfview を使用してトレースを開きます。Open the trace with Perfview. trace.nettrace ファイルを開き、トレース イベントを調べます。Open the trace.nettrace file and explore the trace events.

アプリで CreateDefaultBuilder を使ってホストがビルドされない場合は、イベント ソース プロバイダーをアプリのログ構成に追加します。If the app doesn't build the host with CreateDefaultBuilder, add the Event Source provider to the app's logging configuration.

詳細については次を参照してください:For more information, see:

PerfviewPerfview

ログの収集と表示には、PerfView ユーティリティを使用します。Use the PerfView utility to collect and view logs. ETW ログを表示できる他のツールはありますが、ASP.NET Core から出力される ETW イベントを操作する場合、PerfView は最適なエクスペリエンスを提供します。There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by ASP.NET Core.

このプロバイダーでログに記録されるイベントを収集するように PerfView を構成するには、 [追加プロバイダー] の一覧に文字列 *Microsoft-Extensions-Logging を追加しますTo configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. 文字列の先頭にある * を忘れないでください。Don't miss the * at the start of the string.

Windows EventLogWindows EventLog

EventLog プロバイダーにより、ログ出力が Windows イベント ログに送信されます。The EventLog provider sends log output to the Windows Event Log. 他のプロバイダーとは異なり、EventLog プロバイダーでは既定のプロバイダー以外の設定が継承 "されません"。Unlike the other providers, the EventLog provider does not inherit the default non-provider settings. EventLog ログ設定が指定されていない場合は、既定の LogLevel.Warning になります。If EventLog log settings aren't specified, they default to LogLevel.Warning.

LogLevel.Warning より下のイベントをログに記録するには、ログ レベルを明示的に設定してください。To log events lower than LogLevel.Warning, explicitly set the log level. 次の例では、イベント ログの既定のログ レベルを LogLevel.Information に設定します。The following example sets the Event Log default log level to LogLevel.Information:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

AddEventLog のオーバーロードを使用すると、EventLogSettings を渡すことができます。AddEventLog overloads can pass in EventLogSettings. null または指定しない場合は、次の既定の設定が使用されます。If null or not specified, the following default settings are used:

  • LogName:"Application"LogName: "Application"
  • SourceName: ".NET Runtime"SourceName: ".NET Runtime"
  • MachineName:ローカル コンピューター名が使用されます。MachineName: The local machine name is used.

次のコードでは、SourceName が既定値の ".NET Runtime" から MyLogs に変更されます。The following code changes the SourceName from the default value of ".NET Runtime" to MyLogs:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddEventLog(eventLogSettings =>
                {
                    eventLogSettings.SourceName = "MyLogs"; 
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Azure App ServiceAzure App Service

Microsoft.Extensions.Logging.AzureAppServices プロバイダー パッケージは、Azure App Service アプリのファイル システムのテキスト ファイルと、Azure Storage アカウントの BLOB ストレージにログを書き込みます。The Microsoft.Extensions.Logging.AzureAppServices provider package writes logs to text files in an Azure App Service app's file system and to blob storage in an Azure Storage account.

プロバイダー パッケージは、共有フレームワークに含まれていません。The provider package isn't included in the shared framework. プロバイダーを使用するには、プロバイダー パッケージをプロジェクトに追加します。To use the provider, add the provider package to the project.

プロバイダーの設定を構成するには、次の例のように AzureFileLoggerOptionsAzureBlobLoggerOptions を使用します。To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the following example:

public class Scopes
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
                .ConfigureServices(serviceCollection => serviceCollection
                    .Configure<AzureFileLoggerOptions>(options =>
                    {
                        options.FileName = "azure-diagnostics-";
                        options.FileSizeLimit = 50 * 1024;
                        options.RetainedFileCountLimit = 5;
                    })
                    .Configure<AzureBlobLoggerOptions>(options =>
                    {
                        options.BlobName = "log.txt";
                    }))
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
    }
}

Azure App Service にデプロイされると、Azure portal の [App Service] ページの [App Service ログ] セクションの設定がアプリで使用されます。When deployed to Azure App Service, the app uses the settings in the App Service logs section of the App Service page of the Azure portal. 次の設定が更新されると、アプリの再起動や再デプロイを必要とせずに、変更がすぐに有効になります。When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • [アプリケーション ログ (ファイル システム)]Application Logging (Filesystem)
  • [アプリケーション ログ (BLOB)]Application Logging (Blob)

ログ ファイルの既定の場所は、D:\home\LogFiles\Application です。既定のファイル名は diagnostics-yyyymmdd.txt です。The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. 既定のファイル サイズ制限は 10 MB です。保持されるファイルの既定の最大数は 2 です。The default file size limit is 10 MB, and the default maximum number of files retained is 2. 既定の BLOB 名は {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt です。The default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

このプロバイダーは、プロジェクトが Azure 環境で実行される場合にのみログを記録します。This provider only logs when the project runs in the Azure environment.

Azure ログのストリーミングAzure log streaming

Azure ログのストリーミングでは、以下からのリアル タイムでのログ アクティビティの表示がサポートされています。Azure log streaming supports viewing log activity in real time from:

  • アプリ サーバーThe app server
  • Web サーバーThe web server
  • 失敗した要求のトレースFailed request tracing

Azure ログのストリーミングを構成するにはTo configure Azure log streaming:

  • アプリのポータル ページから [App Service ログ] ページに移動します。Navigate to the App Service logs page from the app's portal page.
  • [アプリケーション ログ (ファイル システム)][オン] に設定します。Set Application Logging (Filesystem) to On.
  • ログ [レベル] を選択します。Choose the log Level. この設定は、Azure ログ ストリーミングにのみ適用されます。This setting only applies to Azure log streaming.

[ログ ストリーム] ページに移動して、ログを表示します。Navigate to the Log Stream page to view logs. ログに記録されたメッセージは、ILogger インターフェイスを使用してログに記録されます。The logged messages are logged with the ILogger interface.

Azure Application InsightsAzure Application Insights

Microsoft.Extensions.Logging.ApplicationInsights プロバイダー パッケージでは、Azure Application Insights にログが書き込まれます。The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Application Insights は、Web アプリを監視するサービスであり、クエリを実行してテレメトリ データを分析するためのツールを提供します。Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. このプロバイダーを使用する場合は、Application Insights ツールを使ってクエリを実行し、ログを分析できます。If you use this provider, you can query and analyze your logs by using the Application Insights tools.

ログ プロバイダーは、Microsoft.ApplicationInsights.AspNetCore の依存関係として組み込まれており、ASP.NET Core で利用可能なすべてのテレメトリを提供するパッケージです。The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the package that provides all available telemetry for ASP.NET Core. このパッケージを使用する場合は、プロバイダー パッケージをインストールする必要はありません。If you use this package, you don't have to install the provider package.

Microsoft.ApplicationInsights.Web パッケージは、ASP.NET Core ではなく、ASP.NET 4.x 用です。The Microsoft.ApplicationInsights.Web package is for ASP.NET 4.x, not ASP.NET Core.

詳細については、次のリソースを参照してください。For more information, see the following resources:

サードパーティ製のログ プロバイダーThird-party logging providers

ASP.NET Core で使用できるサードパーティ製のログ記録フレームワークをいくつか紹介します。Third-party logging frameworks that work with ASP.NET Core:

一部のサードパーティ製フレームワークは、セマンティック ログ記録 (構造化ログ記録とも呼ばれます) を実行できます。Some third-party frameworks can perform semantic logging, also known as structured logging.

サード パーティ製フレームワークを使用することは、組み込みのプロバイダーのいずれかを使用することと似ています。Using a third-party framework is similar to using one of the built-in providers:

  1. プロジェクトに NuGet パッケージを追加します。Add a NuGet package to your project.
  2. ログ記録フレームワークによって提供される ILoggerFactory 拡張メソッドを呼び出します。Call an ILoggerFactory extension method provided by the logging framework.

詳細については、各プロバイダーのドキュメントをご覧ください。For more information, see each provider's documentation. サード パーティ製のログ プロバイダーは、Microsoft ではサポートされていません。Third-party logging providers aren't supported by Microsoft.

ホスト コンソール以外のアプリNon-host console app

非 Web コンソール アプリで汎用ホストを使用する方法の例については、バックグラウンド タスクのサンプル アプリ (ASP.NET Core でホステッド サービスを使用するバックグラウンド タスク) の Program.cs ファイルを参照してください。For an example of how to use the Generic Host in a non-web console app, see the Program.cs file of the Background Tasks sample app (ASP.NET Core でホステッド サービスを使用するバックグラウンド タスク).

汎用ホストを使用しないアプリのログ記録コードは、プロバイダーの追加方法とロガーの作成方法によって異なります。Logging code for apps without Generic Host differs in the way providers are added and loggers are created.

ログ プロバイダーLogging providers

ホスト コンソール以外のアプリでは、LoggerFactory を作成するときにプロバイダーの Add{provider name} 拡張メソッドを呼び出します。In a non-host console app, call the provider's Add{provider name} extension method while creating a LoggerFactory:

class Program
{
    static void Main(string[] args)
    {
        var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

ログを作成するCreate logs

ログを作成するには、ILogger<TCategoryName> オブジェクトを使用します。To create logs, use an ILogger<TCategoryName> object. ILogger を作成するには、LoggerFactory を使用します。Use the LoggerFactory to create an ILogger.

次の例では、カテゴリが LoggingConsoleApp.Program のロガーを作成します。The following example creates a logger with LoggingConsoleApp.Program as the category.

class Program
{
    static void Main(string[] args)
    {
        var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

次の ASP.NET Core の例では、ロガーを使用して、レベルが Information のログを作成します。In the following ASP.NET CORE examples, the logger is used to create logs with Information as the level. ログの "レベル" は、ログに記録されるイベントの重大度を示します。The Log level indicates the severity of the logged event.

class Program
{
    static void Main(string[] args)
    {
        var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

レベルカテゴリについては、このドキュメントで詳しく説明しています。Levels and categories are explained in more detail in this document.

ホストの構築時のログ記録Log during host construction

ホストの構築時のログ記録は、直接サポートされていません。Logging during host construction isn't directly supported. ただし、別のロガーを使用することができます。However, a separate logger can be used. 次の例では、CreateHostBuilder でログを記録するために、Serilog ロガーが使用されています。In the following example, a Serilog logger is used to log in CreateHostBuilder. AddSerilog では、Log.Logger で指定された静的な構成が使用されます。AddSerilog uses the static configuration specified in Log.Logger:

using System;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var builtConfig = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddCommandLine(args)
            .Build();

        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .WriteTo.File(builtConfig["Logging:FilePath"])
            .CreateLogger();

        try
        {
            return Host.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddRazorPages();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {   
                    logging.AddSerilog();
                })
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}

ILogger に依存するサービスを構成するConfigure a service that depends on ILogger

ASP.NET Core の以前のバージョンでは Web ホスト用に別の DI コンテナーが作成されるため、ロガーの Startup へのコンストラクター挿入が機能します。Constructor injection of a logger into Startup works in earlier versions of ASP.NET Core because a separate DI container is created for the Web Host. 汎用ホストに対して 1 つのコンテナーのみが作成される理由については、破壊的変更に関するお知らせに関する記事を参照してください。For information about why only one container is created for the Generic Host, see the breaking change announcement.

ILogger<T> に依存するサービスを構成するには、コンストラクターの挿入を使用するか、ファクトリ メソッドを指定します。To configure a service that depends on ILogger<T>, use constructor injection or provide a factory method. ファクトリ メソッドの方法は、他の選択肢がない場合にのみお勧めします。The factory method approach is recommended only if there is no other option. たとえば、DI によって提供される ILogger<T> インスタンスを必要とするサービスについて考えてみます。For example, consider a service that needs an ILogger<T> instance provided by DI:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddRazorPages();

    services.AddSingleton<IMyService>((container) =>
    {
        var logger = container.GetRequiredService<ILogger<MyService>>();
        return new MyService() { Logger = logger };
    });
}

上記の強調表示されているコードは、DI コンテナーで MyService のインスタンスを初めて構築する必要があるときに実行される Func です。The preceding highlighted code is a Func that runs the first time the DI container needs to construct an instance of MyService. この方法では、任意の登録済みサービスにアクセスできます。You can access any of the registered services in this way.

Main でログを作成するCreate logs in Main

次のコードでは、ホストを構築した後に DI から ILogger インスタンスを取得することによって Main でログを記録します。The following code logs in Main by getting an ILogger instance from DI after building the host:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Host created.");

    host.Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Startup でログを作成するCreate logs in Startup

次のコードは、Startup.Configure にログを書き込みます。The following code writes logs in Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env,
                      ILogger<Startup> logger)
{
    if (env.IsDevelopment())
    {
        logger.LogInformation("In Development.");
        app.UseDeveloperExceptionPage();
    }
    else
    {
        logger.LogInformation("Not Development.");
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapRazorPages();
    });
}

Startup.ConfigureServices メソッドでの DI コンテナーの設定が完了する前にログを書き込むことはサポートされていません。Writing logs before completion of the DI container setup in the Startup.ConfigureServices method is not supported:

  • Startup コンストラクターへのロガーの挿入はサポートされていません。Logger injection into the Startup constructor is not supported.
  • Startup.ConfigureServices メソッド シグネチャへのロガーの挿入はサポートされていませんLogger injection into the Startup.ConfigureServices method signature is not supported

この制限の理由は、ログ記録は DI と構成に依存しており、さらに構成は DI に依存しているためです。The reason for this restriction is that logging depends on DI and on configuration, which in turns depends on DI. DI コンテナーは、ConfigureServices が完了するまで設定されません。The DI container isn't set up until ConfigureServices finishes.

ILogger<T> に依存するサービスの構成、または Startup へのロガーのコンストラクター挿入が以前のバージョンで機能した理由については、ILogger に依存するサービスの構成に関するページを参照してください。For information on configuring a service that depends on ILogger<T> or why constructor injection of a logger into Startup worked in earlier versions, see Configure a service that depends on ILogger

非同期でないロガー メソッドNo asynchronous logger methods

ログ記録は高速に実行され、非同期コードのパフォーマンス コストを下回る必要があります。Logging should be so fast that it isn't worth the performance cost of asynchronous code. ログ データ ストアが低速の場合は、そこへ直接書き込まないでください。If a logging data store is slow, don't write to it directly. まずログ メッセージを高速なストアに書き込んでから、後で低速なストアに移動することを検討してください。Consider writing the log messages to a fast store initially, then moving them to the slow store later. たとえば、SQL Server にログを記録する場合、Log メソッドは同期しているため、Log メソッドで直接それを行わないでください。For example, when logging to SQL Server, don't do so directly in a Log method, since the Log methods are synchronous. 代わりに、ログ メッセージをインメモリ キューに同期的に追加し、バックグラウンド ワーカーにキューからメッセージをプルさせて、SQL Server にデータをプッシュする非同期処理を実行させます。Instead, synchronously add log messages to an in-memory queue and have a background worker pull the messages out of the queue to do the asynchronous work of pushing data to SQL Server. 詳細については、この GitHub の問題を参照してください。For more information, see this GitHub issue.

実行中のアプリのログ レベルを変更するChange log levels in a running app

ログ API には、アプリの実行中にログ レベルを変更するシナリオは含まれていません。The Logging API doesn't include a scenario to change log levels while an app is running. ただし、一部の構成プロバイダーは構成を再読み込みすることができ、ログ構成に直ちに影響します。However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. たとえば、ファイル構成プロバイダーでは、既定でログ構成が再度読み込まれます。For example, the File Configuration Provider, reloads logging configuration by default. アプリの実行中にコードの構成が変更された場合、アプリは IConfigurationRoot.Reload を呼び出して、アプリのログ構成を更新できます。If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

ILogger と ILoggerFactoryILogger and ILoggerFactory

ILogger<TCategoryName>ILoggerFactory のインターフェイスと実装は .NET Core SDK に含まれています。The ILogger<TCategoryName> and ILoggerFactory interfaces and implementations are included in the .NET Core SDK. これらは、次の NuGet パッケージでも入手できます。They are also available in the following NuGet packages:

コードでログ フィルター規則を適用するApply log filter rules in code

ログ フィルター規則を設定するには、構成を使用することをお勧めします。The preferred approach for setting log filter rules is by using Configuration.

コードにフィルター規則を登録する方法を次の例に示します。The following example shows how to register filter rules in code:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
               logging.AddFilter("System", LogLevel.Debug)
                  .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)
                  .AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

logging.AddFilter("System", LogLevel.Debug)System カテゴリとログ レベル Debug を指定します。logging.AddFilter("System", LogLevel.Debug) specifies the System category and log level Debug. 特定のプロバイダーが構成されていないため、フィルターはすべてのプロバイダーに適用されます。The filter is applied to all providers because a specific provider was not configured.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) は以下を指定します。AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) specifies:

  • Debug ログ プロバイダー。The Debug logging provider.
  • ログ レベル Information 以上。Log level Information and higher.
  • "Microsoft" で始まるすべてのカテゴリ。All categories starting with "Microsoft".

カスタム ロガーを作成するCreate a custom logger

カスタム ロガーを追加するには、ILoggerFactory を使用して ILoggerProvider を追加します。To add a custom logger, add an ILoggerProvider with ILoggerFactory:

public void Configure(
    IApplicationBuilder app,
    IWebHostEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory.AddProvider(new CustomLoggerProvider(new CustomLoggerConfiguration()));

ILoggerProvider により、1 つ以上の ILogger インスタンスが作成されます。The ILoggerProvider creates one or more ILogger instances. ILogger インスタンスは、情報をログに記録するためにフレームワークによって使用されます。The ILogger instances are used by the framework to log the information.

カスタム ロガーの構成のサンプルSample custom logger configuration

サンプルでは次のことが行われます。The sample:

  • イベント ID とログ レベルによってログ コンソールの色を設定する非常に基本的なサンプルとして設計されています。Is designed to be a very basic sample that sets the color of the log console by event ID and log level. ロガーは通常、イベント ID によって変更されることはなく、ログ レベルに固有のものではありません。Loggers generally don't change by event ID and are not specific to log level.
  • 次の構成の種類を使用して、ログ レベルとイベント ID ごとに異なるカラー コンソール エントリを作成します。Creates different color console entries per log level and event ID using the following configuration type:
public class ColorConsoleLoggerConfiguration
{
    public LogLevel LogLevel { get; set; } = LogLevel.Warning;
    public int EventId { get; set; } = 0;
    public ConsoleColor Color { get; set; } = ConsoleColor.Yellow;
}

上記のコードでは、既定のレベルを Warning に設定し、色を Yellow に設定しています。The preceding code sets the default level to Warning and the color to Yellow. EventId が 0 に設定されている場合は、すべてのイベントをログに記録します。If the EventId is set to 0, we will log all events.

カスタム ロガーを作成するCreate the custom logger

ILogger 実装カテゴリ名は、通常、ログ ソースです。The ILogger implementation category name is typically the logging source. たとえば、ロガーが作成される型は次のようになります。For example, the type where the logger is created:

public class ColorConsoleLogger : ILogger
{
    private readonly string _name;
    private readonly ColorConsoleLoggerConfiguration _config;

    public ColorConsoleLogger(string name, ColorConsoleLoggerConfiguration config)
    {
        _name = name;
        _config = config;
    }

    public IDisposable BeginScope<TState>(TState state)
    {
        return null;
    }

    public bool IsEnabled(LogLevel logLevel)
    {
        return logLevel == _config.LogLevel;
    }

    public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, 
                        Exception exception, Func<TState, Exception, string> formatter)
    {
        if (!IsEnabled(logLevel))
        {
            return;
        }

        if (_config.EventId == 0 || _config.EventId == eventId.Id)
        {
            var color = Console.ForegroundColor;
            Console.ForegroundColor = _config.Color;
            Console.WriteLine($"{logLevel} - {eventId.Id} " +
                              $"- {_name} - {formatter(state, exception)}");
            Console.ForegroundColor = color;
        }
    }
}

上記のコードでは次の操作が行われます。The preceding code:

  • カテゴリ名ごとにロガー インスタンスを作成します。Creates a logger instance per category name.
  • logLevel に一意のロガーがあるようにするため、IsEnabledlogLevel == _config.LogLevel を確認します。Checks logLevel == _config.LogLevel in IsEnabled, so each logLevel has a unique logger. 一般に、ロガーは、すべての上位ログ レベルに対しても有効にする必要があります。Generally, loggers should also be enabled for all higher log levels:
public bool IsEnabled(LogLevel logLevel)
{
    return logLevel >= _config.LogLevel;
}

カスタム LoggerProvider を作成するCreate the custom LoggerProvider

LoggerProvider は、ロガー インスタンスを作成するクラスです。The LoggerProvider is the class that creates the logger instances. カテゴリごとにロガー インスタンスを作成する必要はないかもしれませんが、これは NLog や log4net などの一部のロガーでは理にかなっています。Maybe it is not needed to create a logger instance per category, but this makes sense for some Loggers, like NLog or log4net. これを行うと、必要に応じて、カテゴリごとに異なるログ出力ターゲットを選択することもできます。Doing this you are also able to choose different logging output targets per category if needed:

public class ColorConsoleLoggerProvider : ILoggerProvider
{
    private readonly ColorConsoleLoggerConfiguration _config;
    private readonly ConcurrentDictionary<string, ColorConsoleLogger> _loggers = new ConcurrentDictionary<string, ColorConsoleLogger>();

    public ColorConsoleLoggerProvider(ColorConsoleLoggerConfiguration config)
    {
        _config = config;
    }

    public ILogger CreateLogger(string categoryName)
    {
        return _loggers.GetOrAdd(categoryName, name => new ColorConsoleLogger(name, _config));
    }

    public void Dispose()
    {
        _loggers.Clear();
    }
}

上記のコードでは、CreateLogger によってカテゴリ名ごとに ColorConsoleLogger のインスタンスが 1 つ作成され、それが ConcurrentDictionary<TKey,TValue> に格納されます。In the preceding code, CreateLogger creates a single instance of the ColorConsoleLogger per category name and stores it in the ConcurrentDictionary<TKey,TValue>;

カスタム ロガーの使用と登録Usage and registration of the custom logger

Startup.Configure にロガーを登録します。Register the logger in the Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, 
                      ILoggerFactory loggerFactory)
{
    // Default registration.
    loggerFactory.AddProvider(new ColorConsoleLoggerProvider(
                              new ColorConsoleLoggerConfiguration
    {
        LogLevel = LogLevel.Error,
        Color = ConsoleColor.Red
    }));

    // Custom registration with default values.
    loggerFactory.AddColorConsoleLogger();

    // Custom registration with a new configuration instance.
    loggerFactory.AddColorConsoleLogger(new ColorConsoleLoggerConfiguration
    {
        LogLevel = LogLevel.Debug,
        Color = ConsoleColor.Gray
    });

    // Custom registration with a configuration object.
    loggerFactory.AddColorConsoleLogger(c =>
    {
        c.LogLevel = LogLevel.Information;
        c.Color = ConsoleColor.Blue;
    });

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }
    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

上記のコードでは、ILoggerFactory に少なくとも 1 つの拡張メソッドを指定します。For the preceding code, provide at least one extension method for the ILoggerFactory:

public static class ColorConsoleLoggerExtensions
{
    public static ILoggerFactory AddColorConsoleLogger(
                                      this ILoggerFactory loggerFactory, 
                                      ColorConsoleLoggerConfiguration config)
    {
        loggerFactory.AddProvider(new ColorConsoleLoggerProvider(config));
        return loggerFactory;
    }
    public static ILoggerFactory AddColorConsoleLogger(
                                      this ILoggerFactory loggerFactory)
    {
        var config = new ColorConsoleLoggerConfiguration();
        return loggerFactory.AddColorConsoleLogger(config);
    }
    public static ILoggerFactory AddColorConsoleLogger(
                                    this ILoggerFactory loggerFactory, 
                                    Action<ColorConsoleLoggerConfiguration> configure)
    {
        var config = new ColorConsoleLoggerConfiguration();
        configure(config);
        return loggerFactory.AddColorConsoleLogger(config);
    }
}

その他の技術情報Additional resources

作成者: Tom DykstraSteve SmithBy Tom Dykstra and Steve Smith

.NET Core では、組み込みやサード パーティ製のさまざまなログ プロバイダーと連携するログ API がサポートされています。.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. この記事では、組み込みプロバイダーと共にログ API を使用する方法について説明します。This article shows how to use the logging API with built-in providers.

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

プロバイダーを追加するAdd providers

ログ プロバイダーによってログが表示または格納されます。A logging provider displays or stores logs. たとえば、Console プロバイダーによってコンソール上にログが表示され、Azure Application Insights プロバイダーによってそれらが Azure Application Insights に格納されます。For example, the Console provider displays logs on the console, and the Azure Application Insights provider stores them in Azure Application Insights. 複数のプロバイダーを追加することで、複数の宛先にログを送信することができます。Logs can be sent to multiple destinations by adding multiple providers.

プロバイダーを追加するには、Program.cs でプロバイダーの Add{provider name} 拡張メソッドを呼び出します。To add a provider, call the provider's Add{provider name} extension method in Program.cs:

public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            var env = hostingContext.HostingEnvironment;
            config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                  .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                      optional: true, reloadOnChange: true);
            config.AddEnvironmentVariables();
        })
        .ConfigureLogging((hostingContext, logging) =>
        {
            // Requires `using Microsoft.Extensions.Logging;`
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
            logging.AddDebug();
            logging.AddEventSourceLogger();
        })
        .UseStartup<Startup>()
        .Build();

    webHost.Run();
}

上記のコードには、Microsoft.Extensions.LoggingMicrosoft.Extensions.Configuration への参照が必要です。The preceding code requires references to Microsoft.Extensions.Logging and Microsoft.Extensions.Configuration.

既定のプロジェクト テンプレートでは、次のログ プロバイダーを追加する CreateDefaultBuilder が呼び出されます。The default project template calls CreateDefaultBuilder, which adds the following logging providers:

  • コンソールConsole
  • デバッグDebug
  • EventSource (ASP.NET Core 2.2 以降)EventSource (starting in ASP.NET Core 2.2)
public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>();

CreateDefaultBuilder を使用する場合は、既定のプロバイダーを自分で選択したものと置き換えることができます。If you use CreateDefaultBuilder, you can replace the default providers with your own choices. ClearProviders を呼び出し、目的のプロバイダーを追加します。Call ClearProviders, and add the providers you want.

public static void Main(string[] args)
{
    var host = CreateWebHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

この記事の後半では、組み込みログ プロバイダーサードパーティ製ログ プロバイダーについて説明します。Learn more about built-in logging providers and third-party logging providers later in the article.

ログを作成するCreate logs

ログを作成するには、ILogger<TCategoryName> オブジェクトを使用します。To create logs, use an ILogger<TCategoryName> object. Web アプリまたはホステッド サービスで、依存関係の挿入 (DI) から ILogger を取得します。In a web app or hosted service, get an ILogger from dependency injection (DI). ホスト コンソール以外のアプリでは、LoggerFactory を使用して ILogger を作成します。In non-host console apps, use the LoggerFactory to create an ILogger.

次の ASP.NET Core の例では、カテゴリが TodoApiSample.Pages.AboutModel のロガーを作成します。The following ASP.NET Core example creates a logger with TodoApiSample.Pages.AboutModel as the category. ログの "カテゴリ" は、各ログに関連付けられている文字列です。The log category is a string that is associated with each log. DI で提供される ILogger<T> インスタンスでは、カテゴリとして型 T の完全修飾名を持つログが作成されます。The ILogger<T> instance provided by DI creates logs that have the fully qualified name of type T as the category.

public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }

次の ASP.NET Core とコンソール アプリの例では、ロガーを使用して、レベルが Information のログを作成します。In the following ASP.NET Core and console app examples, the logger is used to create logs with Information as the level. ログの "レベル" は、ログに記録されるイベントの重大度を示します。The Log level indicates the severity of the logged event.

public void OnGet()
{
    Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
    _logger.LogInformation("Message displayed: {Message}", Message);
}

レベルカテゴリの詳細については、この記事で後ほど説明します。Levels and categories are explained in more detail later in this article.

Startup でログを作成するCreate logs in Startup

Startup クラスでログを作成するには、コンストラクター シグネチャに ILogger パラメーターを追加します。To write logs in the Startup class, include an ILogger parameter in the constructor signature:

public class Startup
{
    private readonly ILogger _logger;

    public Startup(IConfiguration configuration, ILogger<Startup> logger)
    {
        Configuration = configuration;
        _logger = logger;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        // Add our repository type
        services.AddSingleton<ITodoRepository, TodoRepository>();
        _logger.LogInformation("Added TodoRepository to services");
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            _logger.LogInformation("In Development environment");
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseCookiePolicy();

        app.UseMvc();
    }
}

Program クラスでログを作成するCreate logs in the Program class

Program クラスでログを作成するには、DI から ILogger インスタンスを取得します。To write logs in the Program class, get an ILogger instance from DI:

public static void Main(string[] args)
{
    var host = CreateWebHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

ホストの構築時のログ記録は、直接サポートされていません。Logging during host construction isn't directly supported. ただし、別のロガーを使用することができます。However, a separate logger can be used. 次の例では、CreateWebHostBuilder でログを記録するために、Serilog ロガーが使用されています。In the following example, a Serilog logger is used to log in CreateWebHostBuilder. AddSerilog では、Log.Logger で指定された静的な構成が使用されます。AddSerilog uses the static configuration specified in Log.Logger:

using System;
using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var builtConfig = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddCommandLine(args)
            .Build();

        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .WriteTo.File(builtConfig["Logging:FilePath"])
            .CreateLogger();

        try
        {
            return WebHost.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddMvc();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {
                    logging.AddSerilog();
                })
                .UseStartup<Startup>();
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}

非同期でないロガー メソッドNo asynchronous logger methods

ログ記録は高速に実行され、非同期コードのパフォーマンス コストを下回る必要があります。Logging should be so fast that it isn't worth the performance cost of asynchronous code. ログ記録のデータ ストアが低速の場合は、そこへ直接書き込むべきではありません。If your logging data store is slow, don't write to it directly. まずログ メッセージを高速なストアに書き込んでから、後で低速なストアに移動する方法を検討してください。Consider writing the log messages to a fast store initially, then move them to the slow store later. たとえば、SQL Server にログインしている場合、それを Log メソッドで直接実行したくはないでしょう。Log が同期メソッドであるためです。For example, if you're logging to SQL Server, you don't want to do that directly in a Log method, since the Log methods are synchronous. 代わりに、ログ メッセージをインメモリ キューに同期的に追加し、バックグラウンド ワーカーにキューからメッセージをプルさせて、SQL Server にデータをプッシュする非同期処理を実行させます。Instead, synchronously add log messages to an in-memory queue and have a background worker pull the messages out of the queue to do the asynchronous work of pushing data to SQL Server. 詳細については、この GitHub の問題を参照してください。For more information, see this GitHub issue.

構成Configuration

ログ プロバイダーの構成は、1 つまたは複数の構成プロバイダーによって提供されます。Logging provider configuration is provided by one or more configuration providers:

  • ファイル形式 (INI、JSON、および XML)。File formats (INI, JSON, and XML).
  • コマンド ライン引数。Command-line arguments.
  • 環境変数。Environment variables.
  • メモリ内 .NET オブジェクト。In-memory .NET objects.
  • 暗号化されていないシークレット マネージャーの記憶域。The unencrypted Secret Manager storage.
  • Azure Key Vault などの暗号化されたユーザー ストア。An encrypted user store, such as Azure Key Vault.
  • カスタム プロバイダー (インストール済みまたは作成済み)。Custom providers (installed or created).

たとえば、一般的に、ログの構成はアプリ設定ファイルの Logging セクションで指定されます。For example, logging configuration is commonly provided by the Logging section of app settings files. 次の例は、一般的な appsettings.Development.json ファイルの内容を示しています。The following example shows the contents of a typical appsettings.Development.json file:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    },
    "Console":
    {
      "IncludeScopes": true
    }
  }
}

Logging プロパティには LogLevel およびログ プロバイダーのプロパティ (Console が示されています) を含めることができます。The Logging property can have LogLevel and log provider properties (Console is shown).

Logging の下の LogLevel プロパティでは、選択したカテゴリに対するログの最小のレベルが指定されます。The LogLevel property under Logging specifies the minimum level to log for selected categories. この例では、SystemMicrosoft カテゴリが Information レベルで、その他はすべて Debug レベルでログに記録します。In the example, System and Microsoft categories log at Information level, and all others log at Debug level.

Logging の下のその他のプロパティではログ プロバイダーが指定されます。Other properties under Logging specify logging providers. この例では、Console プロバイダーです。The example is for the Console provider. プロバイダーでログのスコープがサポートされている場合、IncludeScopes によってそれを有効にするかどうかが指定されます。If a provider supports log scopes, IncludeScopes indicates whether they're enabled. プロバイダーのプロパティ (例の Console など) では、LogLevel プロパティが指定される場合があります。A provider property (such as Console in the example) may also specify a LogLevel property. プロバイダーの下の LogLevel では、そのプロバイダーのログのレベルが指定されます。LogLevel under a provider specifies levels to log for that provider.

Logging.{providername}.LogLevel でレベルが指定される場合、それによって Logging.LogLevel で設定されたものはすべてオーバーライドされます。If levels are specified in Logging.{providername}.LogLevel, they override anything set in Logging.LogLevel. たとえば、次の JSON について考えます。For example, consider the following JSON:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

上記の JSON では、Console プロバイダーの設定によって上記の (既定の) ログ レベルがオーバーライドされます。In the preceding JSON, the Console provider settings overrides the preceding (default) log level.

ログ API には、アプリの実行中にログ レベルを変更するシナリオは含まれていません。The Logging API doesn't include a scenario to change log levels while an app is running. ただし、一部の構成プロバイダーは構成を再読み込みすることができ、ログ構成に直ちに影響します。However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. たとえば、設定ファイルを読み取るために CreateDefaultBuilder によって追加される ファイル構成プロバイダーは、既定でログ構成を再読み込みします。For example, the File Configuration Provider, which is added by CreateDefaultBuilder to read settings files, reloads logging configuration by default. アプリの実行中にコードの構成が変更された場合、アプリは IConfigurationRoot.Reload を呼び出して、アプリのログ構成を更新できます。If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

構成プロバイダーの実装について詳しくは、ASP.NET Core の構成 をご覧ください。For information on implementing configuration providers, see ASP.NET Core の構成.

サンプルのログ記録の出力Sample logging output

前のセクションで紹介したサンプル コードでは、コマンド ラインからアプリを実行するとコンソールにログが表示されます。With the sample code shown in the preceding section, logs appear in the console when the app is run from the command line. コンソールの出力例は次のとおりです。Here's an example of console output:

info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 42.9286ms
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 148.889ms 404

前のログは、http://localhost:5000/api/todo/0 のサンプル アプリに向けて HTTP Get 要求を作成することで生成されました。The preceding logs were generated by making an HTTP Get request to the sample app at http://localhost:5000/api/todo/0.

Visual Studio でサンプル アプリを実行したときに [デバッグ] ウィンドウに表示されるログと同じログの例を、次に示します。Here's an example of the same logs as they appear in the Debug window when you run the sample app in Visual Studio:

Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request starting HTTP/1.1 GET http://localhost:53104/api/todo/0  
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
TodoApi.Controllers.TodoController:Information: Getting item 0
TodoApi.Controllers.TodoController:Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult:Information: Executing HttpStatusCodeResult, setting HTTP status code 404
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 152.5657ms
Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request finished in 316.3195ms 404

前のセクションで紹介した ILogger の呼び出しで作成されるログは、"TodoApi" から始まります。The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApi". "Microsoft" カテゴリから始まるログは、ASP.NET Core のフレームワークのコードからのログです。The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core とアプリケーション コードでは、同じログ API とログ プロバイダーが使用されています。ASP.NET Core and application code are using the same logging API and providers.

以降、この記事では、ログ記録の詳細とオプションについて説明します。The remainder of this article explains some details and options for logging.

NuGet パッケージNuGet packages

ILogger および ILoggerFactory インターフェイスは、Microsoft.Extensions.Logging.Abstractions 内にあり、それらの既定の実装は Microsoft.Extensions.Logging 内にあります。The ILogger and ILoggerFactory interfaces are in Microsoft.Extensions.Logging.Abstractions, and default implementations for them are in Microsoft.Extensions.Logging.

ログのカテゴリLog category

ILogger オブジェクトが作成されるときに、"カテゴリ" が指定されます。When an ILogger object is created, a category is specified for it. このカテゴリは、ILogger のインスタンスによって作成される各ログ メッセージと共に含められます。That category is included with each log message created by that instance of ILogger. カテゴリには任意の文字列を指定できますが、"TodoApi.Controllers.TodoController" などのクラス名を使用するのが慣例です。The category may be any string, but the convention is to use the class name, such as "TodoApi.Controllers.TodoController".

ILogger<T> を使用して、カテゴリとして T の完全修飾型名が使用される ILogger インスタンスを取得します。Use ILogger<T> to get an ILogger instance that uses the fully qualified type name of T as the category:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }

カテゴリを明示的に指定するには、ILoggerFactory.CreateLogger を呼び出します。To explicitly specify the category, call ILoggerFactory.CreateLogger:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILoggerFactory logger)
    {
        _todoRepository = todoRepository;
        _logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
    }

ILogger<T> は、T の完全修飾型名を使用した CreateLogger の呼び出しと同じです。ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

ログ レベルLog level

すべてのログで LogLevel 値が指定されます。Every log specifies a LogLevel value. ログ レベルは、重大度または重要度を示します。The log level indicates the severity or importance. たとえば、メソッドが正常に終了した場合は Information ログを、メソッドが 404 Not Found 状態コードを返した場合は Warning ログを書き込む場合があります。For example, you might write an Information log when a method ends normally and a Warning log when a method returns a 404 Not Found status code.

Information および Warning ログを作成するコードを次に示します。The following code creates Information and Warning logs:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

上記のコードでは、MyLogEvents.GetItem パラメーターと MyLogEvents.GetItemNotFound パラメーターは ログ イベント IDです。In the preceding code, the MyLogEvents.GetItem and MyLogEvents.GetItemNotFound parameters are the Log event ID. 2 つ目のパラメーターは、他のメソッド パラメーターによって提供される引数値のプレースホルダーを含むメッセージ テンプレートです。The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. メソッド パラメーターについては、この記事の「ログ メッセージ テンプレート」のセクションで説明されています。The method parameters are explained in the Log message template section in this article.

メソッド名にレベルを含むログ メソッド (たとえば LogInformationLogWarning) は、ILogger の拡張メソッドです。Log methods that include the level in the method name (for example, LogInformation and LogWarning) are extension methods for ILogger. これらのメソッドでは、LogLevel パラメーターを受け取る Log メソッドが呼び出されます。These methods call a Log method that takes a LogLevel parameter. これらの拡張メソッドのいずれかではなく、Log メソッドを直接呼び出すことができますが、構文は比較的複雑です。You can call the Log method directly rather than one of these extension methods, but the syntax is relatively complicated. 詳細については、ILogger およびロガー拡張ソース コードに関するページを参照してください。For more information, see ILogger and the logger extensions source code.

ASP.NET Core には、次のログ レベルが定義されています (重大度の低いものから高い順)。ASP.NET Core defines the following log levels, ordered here from lowest to highest severity.

  • Trace = 0Trace = 0

    通常はデバッグでのみ役立つ情報の場合。For information that's typically valuable only for debugging. これらのメッセージには機密性の高いアプリケーション データが含まれる可能性があるため、運用環境は有効にしないことをお勧めします。These messages may contain sensitive application data and so shouldn't be enabled in a production environment. 既定で無効です。Disabled by default.

  • Debug = 1Debug = 1

    開発とデバッグで役立つ可能性がある情報の場合。For information that may be useful in development and debugging. 例:Entering method Configure with flag set to true.``Debug レベルのログは、ログのサイズが大きくなるため、トラブルシューティングの場合を除き運用環境では有効にしません。Example: Entering method Configure with flag set to true. Enable Debug level logs in production only when troubleshooting, due to the high volume of logs.

  • Information = 2Information = 2

    アプリの一般的なフローを追跡する場合。For tracking the general flow of the app. 通常、これらのログには、長期的な値があります。These logs typically have some long-term value. 例 : Request received for path /api/todoExample: Request received for path /api/todo

  • Warning = 3Warning = 3

    アプリのフローで異常なイベントや予期しないイベントが発生した場合。For abnormal or unexpected events in the app flow. アプリの停止の原因にはならないが、調査する必要があるエラーやその他の状態がここに含まれる場合があります。These may include errors or other conditions that don't cause the app to stop but might need to be investigated. Warning ログ レベルが使用される一般的な場所として、例外の処理があります。Handled exceptions are a common place to use the Warning log level. 例 : FileNotFoundException for file quotes.txt.Example: FileNotFoundException for file quotes.txt.

  • Error = 4Error = 4

    処理できないエラーと例外の場合。For errors and exceptions that cannot be handled. これらのメッセージは、アプリ全体のエラーではなく、現在のアクティビティまたは操作 (現在の HTTP 要求など) におけるエラーを示します。These messages indicate a failure in the current activity or operation (such as the current HTTP request), not an app-wide failure. ログ メッセージの例: Cannot insert record due to duplicate key violation.Example log message: Cannot insert record due to duplicate key violation.

  • Critical = 5Critical = 5

    即時の注意が必要なエラーの場合。For failures that require immediate attention. 例: データ損失のシナリオ、ディスク領域不足。Examples: data loss scenarios, out of disk space.

ログ レベルを使用して、特定のストレージ メディアまたは表示ウィンドウに書き込むログの出力量を制御します。Use the log level to control how much log output is written to a particular storage medium or display window. 次に例を示します。For example:

  • 運用環境:In production:
    • Trace から Information までのレベルでログを記録すると、詳細なログ メッセージが大量に生成されます。Logging at the Trace through Information levels produces a high-volume of detailed log messages. コストを制御し、データ ストレージの上限を超えないようにするには、Trace から Information のレベルのメッセージを、大量の低コストのデータ ストアに記録します。To control costs and not exceed data storage limits, log Trace through Information level messages to a high-volume, low-cost data store.
    • Warning から Critical までのレベルでログを記録すると、通常はより少ないログ メッセージが生成されます。Logging at Warning through Critical levels typically produces fewer, smaller log messages. そのため、コストとストレージの制限は通常は問題にならないため、データ ストアの選択肢がより柔軟になります。Therefore, costs and storage limits usually aren't a concern, which results in greater flexibility of data store choice.
  • 開発中:During development:
    • コンソールに Warning から Critical のメッセージを記録します。Log Warning through Critical messages to the console.
    • トラブルシューティングの際に Trace から Information のメッセージを追加します。Add Trace through Information messages when troubleshooting.

この記事で後述する「ログのフィルター処理」セクションでは、プロバイダーで処理するログ レベルの制御方法について説明します。The Log filtering section later in this article explains how to control which log levels a provider handles.

ASP.NET Core では、フレームワーク イベントのログが書き込まれます。ASP.NET Core writes logs for framework events. この記事の前のログの例では、Information レベル以下のログを除外したため、Debug または Trace レベルのログは作成されませんでした。The log examples earlier in this article excluded logs below Information level, so no Debug or Trace level logs were created. Debug ログを示すために構成したサンプル アプリを実行することで生成されるコンソールのログの例を、次に示します。Here's an example of console logs produced by running the sample app configured to show Debug logs:

info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:62555/api/todo/0
dbug: Microsoft.AspNetCore.Routing.Tree.TreeRouter[1]
      Request successfully matched the route with name 'GetTodo' and template 'api/Todo/{id}'.
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Update (TodoApi)' with id '089d59b6-92ec-472d-b552-cc613dfd625d' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Delete (TodoApi)' with id 'f3476abe-4bd9-4ad3-9261-3ead09607366' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action TodoApi.Controllers.TodoController.GetById (TodoApi)
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action method TodoApi.Controllers.TodoController.GetById (TodoApi), returned result Microsoft.AspNetCore.Mvc.NotFoundResult.
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 0.8788ms
dbug: Microsoft.AspNetCore.Server.Kestrel[9]
      Connection id "0HL6L7NEFF2QD" completed keep alive response.
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 2.7286ms 404

ログ イベント IDLog event ID

各ログで "イベント ID" を指定できます。Each log can specify an event ID. サンプル アプリでは、この処理にローカルで定義された LoggingEvents クラスを使用します。The sample app does this by using a locally defined LoggingEvents class:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public class LoggingEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems = 1001;
    public const int GetItem = 1002;
    public const int InsertItem = 1003;
    public const int UpdateItem = 1004;
    public const int DeleteItem = 1005;

    public const int GetItemNotFound = 4000;
    public const int UpdateItemNotFound = 4001;
}

イベント ID によって一連のイベントが関連付けられます。An event ID associates a set of events. たとえば、ページ上に項目の一覧を表示する機能に関連するすべてのログを 1001 に設定します。For example, all logs related to displaying a list of items on a page might be 1001.

ログ プロバイダーでは、ID フィールドやログ メッセージにイベント ID が格納されたり、またはまったく格納されなかったりする場合があります。The logging provider may store the event ID in an ID field, in the logging message, or not at all. Debug プロバイダーでイベント ID が表示されることはありません。The Debug provider doesn't show event IDs. Console プロバイダーでは、カテゴリの後のブラケット内にイベント ID が表示されます。The console provider shows event IDs in brackets after the category:

info: TodoApi.Controllers.TodoController[1002]
      Getting item invalidid
warn: TodoApi.Controllers.TodoController[4000]
      GetById(invalidid) NOT FOUND

ログ メッセージ テンプレートLog message template

各ログでメッセージ テンプレートが指定されます。Each log specifies a message template. メッセージ テンプレートには、指定される引数のためのプレースホルダーを含めることができます。The message template can contain placeholders for which arguments are provided. プレースホルダーには、数値ではなく名前を使用します。Use names for the placeholders, not numbers.

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

プレースホルダーの名前ではなく、プレースホルダーの順序によって、値の指定に使用されるパラメーターが決まります。The order of placeholders, not their names, determines which parameters are used to provide their values. 次のコードでは、パラメーター名がメッセージ テンプレート内のシーケンスの外にあることに注意してください。In the following code, notice that the parameter names are out of sequence in the message template:

string p1 = "parm1";
string p2 = "parm2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

このコードでは、シーケンス内のパラメーター値を含むログ メッセージが作成されます。This code creates a log message with the parameter values in sequence:

Parameter values: parm1, parm2

ログ プロバイダーがセマンティック ログ記録 (または構造化ログ記録)を実装できるようにするために、ログ フレームワークはこのように動作します。The logging framework works this way so that logging providers can implement semantic logging, also known as structured logging. 書式設定されたメッセージ テンプレートだけでなく、引数自体がログ システムに渡されます。The arguments themselves are passed to the logging system, not just the formatted message template. この情報により、ログ プロバイダーはフィールドとしてパラメーター値を格納することができます。This information enables logging providers to store the parameter values as fields. たとえば、つぎのようなロガー メソッドの呼び出しがあるとします。For example, suppose logger method calls look like this:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

Azure Table Storage にログを送信する場合、各 Azure Table エンティティに ID および RequestTime プロパティを指定し、ログ データのクエリを簡略化することができます。If you're sending the logs to Azure Table Storage, each Azure Table entity can have ID and RequestTime properties, which simplifies queries on log data. クエリによって指定した RequestTime の範囲内のすべてのログを検索できます。テキスト メッセージから時間を解析する必要はありません。A query can find all logs within a particular RequestTime range without parsing the time out of the text message.

ログ記録の例外Logging exceptions

ロガー メソッドには、次の例のように、例外で渡すことができるオーバーロードがあります。The logger methods have overloads that let you pass in an exception, as in the following example:

catch (Exception ex)
{
    _logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({Id}) NOT FOUND", id);
    return NotFound();
}
return new ObjectResult(item);

プロバイダーごとに、例外情報の処理方法は異なります。Different providers handle the exception information in different ways. 前述のコードの Debug プロバイダーの出力の例を次に示します。Here's an example of Debug provider output from the code shown above.

TodoApiSample.Controllers.TodoController: Warning: GetById(55) NOT FOUND

System.Exception: Item not found exception.
   at TodoApiSample.Controllers.TodoController.GetById(String id) in C:\TodoApiSample\Controllers\TodoController.cs:line 226

ログのフィルター処理Log filtering

特定のプロバイダーとカテゴリ、またはすべてのプロバイダーまたはすべてのカテゴリに最小ログ レベルを指定できます。You can specify a minimum log level for a specific provider and category or for all providers or all categories. 最小レベルを下回るログは、そのプロバイダーに渡されないので、表示または保存されません。Any logs below the minimum level aren't passed to that provider, so they don't get displayed or stored.

すべてのログを抑制するには、最小ログ レベルに LogLevel.None を指定します。To suppress all logs, specify LogLevel.None as the minimum log level. LogLevel.None の整数値は 6 であり、LogLevel.Critical (5) を超えます。The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

構成にフィルター規則を作成するCreate filter rules in configuration

プロジェクト テンプレート コードは CreateDefaultBuilder を呼び出して、コンソール、デバッグ、EventSource (ASP.NET Core 2.2 以降) のプロバイダーのログ記録を設定します。The project template code calls CreateDefaultBuilder to set up logging for the Console, Debug, and EventSource (ASP.NET Core 2.2 or later) providers. Loggingこの記事で既に説明したように、CreateDefaultBuilder メソッドでは、 セクションで構成を検索するようにログが設定されます。The CreateDefaultBuilder method sets up logging to look for configuration in a Logging section, as explained earlier in this article.

次の例のように、構成データでは、プロバイダーとカテゴリごとに最小ログ レベルを指定します。The configuration data specifies minimum log levels by provider and category, as in the following example:

{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": false,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

この JSON では、6 個のフィルター規則を作成します。1 つは Debug プロバイダー用、4 つは Console プロバイダー用、1 つはすべてのプロバイダー用です。This JSON creates six filter rules: one for the Debug provider, four for the Console provider, and one for all providers. ILogger オブジェクトが作成されると、各プロバイダーに対して 1 つの規則が選択されます。A single rule is chosen for each provider when an ILogger object is created.

コードのフィルター規則Filter rules in code

コードにフィルター規則を登録する方法を次の例に示します。The following example shows how to register filter rules in code:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging =>
        logging.AddFilter("System", LogLevel.Debug)
               .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace));

2 つ目の AddFilter では、プロバイダーの種類名を使用して Debug プロバイダーを指定します。The second AddFilter specifies the Debug provider by using its type name. 1 つ目の AddFilter は、プロバイダーの種類を指定していないため、すべてのプロバイダーに適用されます。The first AddFilter applies to all providers because it doesn't specify a provider type.

フィルター規則を適用する方法How filtering rules are applied

前の例の構成データと AddFilter コードでは、次の表に示す規則を作成します。The configuration data and the AddFilter code shown in the preceding examples create the rules shown in the following table. 最初の 6 つは構成例、最後の 2 つはコード例のものです。The first six come from the configuration example and the last two come from the code example.

数値Number プロバイダーProvider 以下から始まるカテゴリCategories that begin with ... 最小ログ レベルMinimum log level
11 デバッグDebug すべてのカテゴリAll categories 情報Information
22 コンソールConsole Microsoft.AspNetCore.Mvc.Razor.InternalMicrosoft.AspNetCore.Mvc.Razor.Internal 警告Warning
33 コンソールConsole Microsoft.AspNetCore.Mvc.Razor.RazorMicrosoft.AspNetCore.Mvc.Razor.Razor デバッグDebug
44 コンソールConsole Microsoft.AspNetCore.Mvc.RazorMicrosoft.AspNetCore.Mvc.Razor ErrorError
55 コンソールConsole すべてのカテゴリAll categories 情報Information
66 すべてのプロバイダーAll providers すべてのカテゴリAll categories デバッグDebug
77 すべてのプロバイダーAll providers システムSystem デバッグDebug
88 デバッグDebug MicrosoftMicrosoft トレースTrace

ILogger オブジェクトを作成すると、ILoggerFactory オブジェクトによって、そのロガーに適用するプロバイダーごとに 1 つの規則が選択されます。When an ILogger object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. ILogger インスタンスによって書き込まれるすべてのメッセージは、選択した規則に基づいてフィルター処理されます。All messages written by an ILogger instance are filtered based on the selected rules. 使用できる規則から、各プロバイダーとカテゴリのペアごとに該当する最も限定的な規則が選択されます。The most specific rule possible for each provider and category pair is selected from the available rules.

特定のカテゴリに ILogger が作成されるときに、各プロバイダーに次のアルゴリズムが使用されます。The following algorithm is used for each provider when an ILogger is created for a given category:

  • プロバイダーとそのエイリアスと一致するすべての規則が選択されます。Select all rules that match the provider or its alias. 一致が見つからない場合は、空のプロバイダーですべての規則が選択されます。If no match is found, select all rules with an empty provider.
  • 前の手順の結果、最も長いカテゴリのプレフィックスが一致する規則が選択されます。From the result of the preceding step, select rules with longest matching category prefix. 一致が見つからない場合は、カテゴリを指定しないすべての規則が選択されます。If no match is found, select all rules that don't specify a category.
  • 複数の規則が選択されている場合は、最後の 1 つが使用されます。If multiple rules are selected, take the last one.
  • 規則が選択されていない場合は、MinimumLevel が使用されます。If no rules are selected, use MinimumLevel.

前の規則一覧を使用して、カテゴリ "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine" に ILogger オブジェクトを作成するとします。With the preceding list of rules, suppose you create an ILogger object for category "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":

  • Debug プロバイダーの場合、規則 1、6、8 が適用されます。For the Debug provider, rules 1, 6, and 8 apply. 規則 8 が最も限定的なので、規則 8 が選択されます。Rule 8 is most specific, so that's the one selected.
  • Console プロバイダーの場合、規則 3、4、5、6 が適用されます。For the Console provider, rules 3, 4, 5, and 6 apply. 規則 3 が最も限定的です。Rule 3 is most specific.

作成される ILogger インスタンスでは、Debug プロバイダーに Trace レベル以上のログが送信されます。The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Debug レベル以上のログが Console プロバイダーに送信されます。Logs of Debug level and above are sent to the Console provider.

プロバイダーのエイリアスProvider aliases

各プロバイダーでは "エイリアス" が定義されます。これは構成で完全修飾型名の代わりに使用できます。Each provider defines an alias that can be used in configuration in place of the fully qualified type name. 組み込みのプロバイダーの場合は、次のエイリアスを使用してください。For the built-in providers, use the following aliases:

  • コンソールConsole
  • デバッグDebug
  • EventSourceEventSource
  • EventLogEventLog
  • TraceSourceTraceSource
  • AzureAppServicesFileAzureAppServicesFile
  • AzureAppServicesBlobAzureAppServicesBlob
  • ApplicationInsightsApplicationInsights

既定の最小レベルDefault minimum level

指定したプロバイダーとカテゴリに適用される構成またはコードの規則がない場合にのみ反映される最小レベルの設定があります。There's a minimum level setting that takes effect only if no rules from configuration or code apply for a given provider and category. 最小レベルを設定する方法を次の例に示します。The following example shows how to set the minimum level:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning));

最小レベルを明示的に設定しない場合、既定値は Information です。これは、Trace および Debug ログが無視されることを意味します。If you don't explicitly set the minimum level, the default value is Information, which means that Trace and Debug logs are ignored.

フィルター関数Filter functions

フィルター関数は、構成またはコードによって規則が割り当てられていないすべてのプロバイダーとカテゴリについて呼び出されます。A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code. 関数内のコードから、プロバイダーの種類、カテゴリ、ログ レベルにアクセスすることができます。Code in the function has access to the provider type, category, and log level. 次に例を示します。For example:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logBuilder =>
    {
        logBuilder.AddFilter((provider, category, logLevel) =>
        {
            if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
                category == "TodoApiSample.Controllers.TodoController")
            {
                return false;
            }
            return true;
        });
    });

システムのカテゴリとレベルSystem categories and levels

ASP.NET Core と Entity Framework Core によって使用されるいくつかのカテゴリと、それらから想定されるログの種類に関するメモを、次に示します。Here are some categories used by ASP.NET Core and Entity Framework Core, with notes about what logs to expect from them:

カテゴリCategory メモNotes
Microsoft.AspNetCoreMicrosoft.AspNetCore ASP.NET Core の一般的な診断。General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection どのキーが検討、検索、および使用されたか。Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering 許可されるホスト。Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting HTTP 要求が完了するまでにかかった時間と、それらの開始時刻。How long HTTP requests took to complete and what time they started. どのホスティング スタートアップ アセンブリが読み込まれたか。Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc MVC と Razor の診断。MVC and Razor diagnostics. モデルの構築、フィルター処理の実行、ビューのコンパイル、アクションの選択。Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing 一致する情報をルーティングします。Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server 接続の開始、停止、キープ アライブ応答。Connection start, stop, and keep alive responses. HTTPS 証明書情報。HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles 提供されるファイル。Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore Entity Framework Core の一般的な診断。General Entity Framework Core diagnostics. データベースのアクティビティと構成、変更の検出、移行。Database activity and configuration, change detection, migrations.

ログのスコープLog scopes

"スコープ" では、論理操作のセットをグループ化できます。A scope can group a set of logical operations. このグループ化を使用して、セットの一部として作成される各ログに同じデータをアタッチすることができます。This grouping can be used to attach the same data to each log that's created as part of a set. たとえば、トランザクション処理の一部として作成されるすべてのログに、トランザクション ID を含めることができます。For example, every log created as part of processing a transaction can include the transaction ID.

スコープは BeginScope メソッドから返される IDisposable の種類であり、破棄されるまで継続します。A scope is an IDisposable type that's returned by the BeginScope method and lasts until it's disposed. ロガーの呼び出しを using ブロックでラップすることによって、スコープを使用します。Use a scope by wrapping logger calls in a using block:

public IActionResult GetById(string id)
{
    TodoItem item;
    using (_logger.BeginScope("Message attached to logs created in the using block"))
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        item = _todoRepository.Find(id);
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
    }
    return new ObjectResult(item);
}

次のコードでは、Console プロバイダーのスコープを有効にしています。The following code enables scopes for the console provider:

Program.cs:Program.cs:

.ConfigureLogging((hostingContext, logging) =>
{
    logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
    logging.AddConsole(options => options.IncludeScopes = true);
    logging.AddDebug();
})

注意

スコープベースのログ記録を有効にするには、IncludeScopes コンソールのロガー オプションを構成する必要があります。Configuring the IncludeScopes console logger option is required to enable scope-based logging.

構成について詳しくは、「構成」セクションをご覧ください。For information on configuration, see the Configuration section.

各ログ メッセージには、スコープ内の情報が含まれます。Each log message includes the scoped information:

info: TodoApiSample.Controllers.TodoController[1002]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      GetById(0) NOT FOUND

組み込みのログ プロバイダーBuilt-in logging providers

ASP.NET Core には次のプロバイダーが付属しています。ASP.NET Core ships the following providers:

ASP.NET Core モジュールを使用した stdout およびデバッグ ログの詳細については、「Azure App Service および IIS での ASP.NET Core のトラブルシューティング」および「ASP.NET Core モジュール」を参照してください。For information on stdout and debug logging with the ASP.NET Core Module, see Azure App Service および IIS での ASP.NET Core のトラブルシューティング and ASP.NET Core モジュール.

Console プロバイダーConsole provider

Microsoft.Extensions.Logging.Console プロバイダー パッケージは、ログ出力をコンソールに送信します。The Microsoft.Extensions.Logging.Console provider package sends log output to the console.

logging.AddConsole();

コンソールのログ出力を確認するには、プロジェクト フォルダーでコマンド プロンプトを開き、次のコマンドを実行します。To see console logging output, open a command prompt in the project folder and run the following command:

dotnet run

Debug プロバイダーDebug provider

Microsoft.Extensions.Logging.Debug プロバイダー パッケージは、System.Diagnostics.Debug クラス (Debug.WriteLine メソッドの呼び出し) を使用してログの出力を書き込みます。The Microsoft.Extensions.Logging.Debug provider package writes log output by using the System.Diagnostics.Debug class (Debug.WriteLine method calls).

Linux では、このプロバイダーから /var/log/message にログが書き込まれます。On Linux, this provider writes logs to /var/log/message.

logging.AddDebug();

イベント ソース プロバイダーEvent Source provider

Microsoft.Extensions.Logging.EventSource プロバイダー パッケージでは、Microsoft-Extensions-Logging という名前でイベント ソース クロスプラットフォームに書き込みます。The Microsoft.Extensions.Logging.EventSource provider package writes to an Event Source cross-platform with the name Microsoft-Extensions-Logging. Windows では、プロバイダーによって ETW が使用されます。On Windows, the provider uses ETW.

logging.AddEventSourceLogger();

イベント ソース プロバイダーは、ホストをビルドするために CreateDefaultBuilder が呼び出されたときに、自動的に追加されます。The Event Source provider is added automatically when CreateDefaultBuilder is called to build the host.

ログの収集と表示には、PerfView ユーティリティを使用します。Use the PerfView utility to collect and view logs. ETW ログを表示できる他のツールはありますが、ASP.NET Core から出力される ETW イベントを操作する場合、PerfView は最適なエクスペリエンスを提供します。There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by ASP.NET Core.

このプロバイダーでログに記録されるイベントを収集するように PerfView を構成するには、 [追加プロバイダー] の一覧に文字列 *Microsoft-Extensions-Logging を追加しますTo configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. (文字列の先頭に忘れずにアスタリスクを付けてください)。(Don't miss the asterisk at the start of the string.)

Perfview の追加プロバイダー

Windows EventLog プロバイダーWindows EventLog provider

Microsoft.Extensions.Logging.EventLog プロバイダー パッケージは、ログ出力を Windows イベント ログに送信します。The Microsoft.Extensions.Logging.EventLog provider package sends log output to the Windows Event Log.

logging.AddEventLog();

AddEventLog のオーバーロードを使用すると、EventLogSettings を渡すことができます。AddEventLog overloads let you pass in EventLogSettings. null または指定しない場合は、次の既定の設定が使用されます。If null or not specified, the following default settings are used:

  • LogName:"Application"LogName: "Application"
  • SourceName: ".NET Runtime"SourceName: ".NET Runtime"
  • MachineName:ローカル コンピューター名が使用されます。MachineName: The local machine name is used.

警告レベル以上のイベントがログに記録されます。Events are logged for Warning level and higher. 次の例では、イベント ログの既定のログ レベルを LogLevel.Information に設定します。The following example sets the Event Log default log level to LogLevel.Information:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

TraceSource プロバイダーTraceSource provider

Microsoft.Extensions.Logging.TraceSource プロバイダー パッケージでは、TraceSource ライブラリとプロバイダーが使用されます。The Microsoft.Extensions.Logging.TraceSource provider package uses the TraceSource libraries and providers.

logging.AddTraceSource(sourceSwitchName);

AddTraceSource オーバーロードを使用すると、ソース スイッチとトレース リスナーを渡すことができます。AddTraceSource overloads let you pass in a source switch and a trace listener.

このプロバイダーを使用するには、アプリを (.NET Core ではなく) .NET Framework 上で実行する必要があります。To use this provider, an app has to run on the .NET Framework (rather than .NET Core). このプロバイダーでは、サンプル アプリで使用されている TextWriterTraceListener など、さまざまなリスナーにメッセージをルーティングさせることができます。The provider can route messages to a variety of listeners, such as the TextWriterTraceListener used in the sample app.

Azure App Service プロバイダーAzure App Service provider

Microsoft.Extensions.Logging.AzureAppServices プロバイダー パッケージは、Azure App Service アプリのファイル システムのテキスト ファイルと、Azure Storage アカウントの BLOB ストレージにログを書き込みます。The Microsoft.Extensions.Logging.AzureAppServices provider package writes logs to text files in an Azure App Service app's file system and to blob storage in an Azure Storage account.

logging.AddAzureWebAppDiagnostics();

プロバイダー パッケージは、Microsoft.AspNetCore.App メタパッケージには含まれません。The provider package isn't included in the Microsoft.AspNetCore.App metapackage. .NET Framework をターゲットとする場合、または Microsoft.AspNetCore.App を参照している場合は、プロバイダー パッケージをプロジェクトに追加します。When targeting .NET Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the project.

AddAzureWebAppDiagnostics のオーバーロードによって AzureAppServicesDiagnosticsSettings を渡すことができます。An AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings. 設定オブジェクトで既定の設定をオーバーライドできます。たとえば、ログの出力テンプレート、BLOB 名、ファイル サイズの制限などです。The settings object can override default settings, such as the logging output template, blob name, and file size limit. ("出力テンプレート" は、ILogger メソッドの呼び出しと共に指定されるものに加えて、すべてのログに適用されるメッセージ テンプレートです。)(Output template is a message template that's applied to all logs in addition to what's provided with an ILogger method call.)

アプリケーションを App Service アプリにデプロイすると、Azure portal の [App Service] ページの [App Service ログ] セクションで指定された設定が適用されます。When you deploy to an App Service app, the application honors the settings in the App Service logs section of the App Service page of the Azure portal. 次の設定が更新されると、アプリの再起動や再デプロイを必要とせずに、変更がすぐに有効になります。When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • [アプリケーション ログ (ファイル システム)]Application Logging (Filesystem)
  • [アプリケーション ログ (BLOB)]Application Logging (Blob)

ログ ファイルの既定の場所は、D:\home\LogFiles\Application です。既定のファイル名は diagnostics-yyyymmdd.txt です。The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. 既定のファイル サイズ制限は 10 MB です。保持されるファイルの既定の最大数は 2 です。The default file size limit is 10 MB, and the default maximum number of files retained is 2. 既定の BLOB 名は {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt です。The default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

このプロバイダーは、プロジェクトが Azure 環境で実行される場合にのみ機能します。The provider only works when the project runs in the Azure environment. プロジェクトをローカルで実行しても、効果はありません—BLOB のローカル ファイルまたはローカル開発ストレージへの書き込みは行われません。It has no effect when the project is run locally—it doesn't write to local files or local development storage for blobs.

Azure ログのストリーミングAzure log streaming

Azure ログのストリーミングを使用すると、以下からリアル タイムでログ アクティビティを確認できます。Azure log streaming lets you view log activity in real time from:

  • アプリ サーバーThe app server
  • Web サーバーThe web server
  • 失敗した要求のトレースFailed request tracing

Azure ログのストリーミングを構成するにはTo configure Azure log streaming:

  • アプリのポータル ページから [App Service ログ] ページに移動します。Navigate to the App Service logs page from your app's portal page.
  • [アプリケーション ログ (ファイル システム)][オン] に設定します。Set Application Logging (Filesystem) to On.
  • ログ [レベル] を選択します。Choose the log Level. この設定は、Azure ログのストリーミングにのみ適用され、アプリ内の他のログ プロバイダーには適用されません。This setting only applies to Azure log streaming, not other logging providers in the app.

[ログ ストリーム] ページに移動して、アプリのメッセージを確認します。Navigate to the Log Stream page to view app messages. これらはアプリによって、ILogger インターフェイスを介してログに記録されます。They're logged by the app through the ILogger interface.

Azure Application Insights のトレース ログAzure Application Insights trace logging

Microsoft.Extensions.Logging.ApplicationInsights プロバイダー パッケージでは、Azure Application Insights にログを書き込みます。The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Application Insights は、Web アプリを監視するサービスであり、クエリを実行してテレメトリ データを分析するためのツールを提供します。Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. このプロバイダーを使用する場合は、Application Insights ツールを使ってクエリを実行し、ログを分析できます。If you use this provider, you can query and analyze your logs by using the Application Insights tools.

ログ プロバイダーは、Microsoft.ApplicationInsights.AspNetCore の依存関係として組み込まれており、ASP.NET Core で利用可能なすべてのテレメトリを提供するパッケージです。The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the package that provides all available telemetry for ASP.NET Core. このパッケージを使用する場合は、プロバイダー パッケージをインストールする必要はありません。If you use this package, you don't have to install the provider package.

ASP.NET 4.x. に対応している Microsoft.ApplicationInsights.Web パッケージを使用しないでください。Don't use the Microsoft.ApplicationInsights.Web package—that's for ASP.NET 4.x.

詳細については、次のリソースを参照してください。For more information, see the following resources:

サードパーティ製のログ プロバイダーThird-party logging providers

ASP.NET Core で使用できるサードパーティ製のログ記録フレームワークをいくつか紹介します。Third-party logging frameworks that work with ASP.NET Core:

一部のサードパーティ製フレームワークは、セマンティック ログ記録 (構造化ログ記録とも呼ばれます) を実行できます。Some third-party frameworks can perform semantic logging, also known as structured logging.

サード パーティ製フレームワークを使用することは、組み込みのプロバイダーのいずれかを使用することと似ています。Using a third-party framework is similar to using one of the built-in providers:

  1. プロジェクトに NuGet パッケージを追加します。Add a NuGet package to your project.
  2. ログ記録フレームワークによって提供される ILoggerFactory 拡張メソッドを呼び出します。Call an ILoggerFactory extension method provided by the logging framework.

詳細については、各プロバイダーのドキュメントをご覧ください。For more information, see each provider's documentation. サード パーティ製のログ プロバイダーは、Microsoft ではサポートされていません。Third-party logging providers aren't supported by Microsoft.

その他の技術情報Additional resources