Edit

Share via

IIS log creation and redirection

  • Article

Note

This isn't the latest version of this article. For the current release, see the .NET 8 version of this article.

Warning

This version of ASP.NET Core is no longer supported. For more information, see .NET and .NET Core Support Policy. For the current release, see the .NET 8 version of this article.

Important

This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

For the current release, see the .NET 8 version of this article.

The ASP.NET Core Module redirects stdout and stderr console output to disk if the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element are set. Any folders in the stdoutLogFile path are created by the module when the log file is created. The app pool must have write access to the location where the logs are written (use IIS AppPool\{APP POOL NAME} to provide write permission, where the placeholder {APP POOL NAME} is the app pool name).

Logs aren't rotated, unless process recycling/restart occurs. It's the responsibility of the hoster to limit the disk space the logs consume.

Using the stdout log is only recommended for troubleshooting app startup issues when hosting on IIS or when using development-time support for IIS with Visual Studio, not while debugging locally and running the app with IIS Express.

Don't use the stdout log for general app logging purposes. For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. For more information, see third-party logging providers.

A timestamp and file extension are added automatically when the log file is created. The log file name is composed by appending the timestamp, process ID, and file extension (.log) to the last segment of the stdoutLogFile path (typically stdout) delimited by underscores. If the stdoutLogFile path ends with stdout, a log for an app with a PID of 1934 created on 2/5/2018 at 19:42:32 has the file name stdout_20180205194132_1934.log.

If stdoutLogEnabled is false, errors that occur on app startup are captured and emitted to the event log up to 30 KB. After startup, all additional logs are discarded.

The following sample aspNetCore element configures stdout logging at the relative path .\log\. Confirm that the AppPool user identity has permission to write to the path provided.

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="true"
    stdoutLogFile=".\logs\stdout"
    hostingModel="inprocess">
</aspNetCore>

When publishing an app for Azure App Service deployment, the Web SDK sets the stdoutLogFile value to \\?\%home%\LogFiles\stdout. The %home environment variable is predefined for apps hosted by Azure App Service.

To create logging filter rules, see the Apply log filter rules in code section of the ASP.NET Core logging documentation.

For more information on path formats, see File path formats on Windows systems.

Enhanced diagnostic logs

The ASP.NET Core Module is configurable to provide enhanced diagnostics logs. Add the <handlerSettings> element to the <aspNetCore> element in web.config. Setting the debugLevel to TRACE exposes a higher fidelity of diagnostic information:

<aspNetCore processPath="dotnet"
    arguments=".\MyApp.dll"
    stdoutLogEnabled="false"
    stdoutLogFile="\\?\%home%\LogFiles\stdout"
    hostingModel="inprocess">
  <handlerSettings>
    <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
    <handlerSetting name="debugLevel" value="FILE,TRACE" />
  </handlerSettings>
</aspNetCore>

Any folders in the path (logs in the preceding example) are created by the module when the log file is created. The app pool must have write access to the location where the logs are written (use IIS AppPool\{APP POOL NAME} to provide write permission, where the placeholder {APP POOL NAME} is the app pool name).

Debug level (debugLevel) values can include both the level and the location.

Levels (in order from least to most verbose):

  • ERROR
  • WARNING
  • INFO
  • TRACE

Locations (multiple locations are permitted):

  • CONSOLE
  • EVENTLOG
  • FILE

The handler settings can also be provided via environment variables:

  • ASPNETCORE_MODULE_DEBUG_FILE: Path to the debug log file. (Default: aspnetcore-debug.log)
  • ASPNETCORE_MODULE_DEBUG: Debug level setting.

Warning

Do not leave debug logging enabled in the deployment for longer than required to troubleshoot an issue. The size of the log isn't limited. Leaving the debug log enabled can exhaust the available disk space and crash the server or app service.

See Configuration of ASP.NET Core Module with web.config for an example of the aspNetCore element in the web.config file.