[API Proposal]: ConsoleFormatterOptions.IncludeExceptions

[GerardSmit]

Background and motivation

Currently the console logger will always print exceptions:

runtime/src/libraries/Microsoft.Extensions.Logging.Console/src/SimpleConsoleFormatter.cs

Lines 121 to 125 in 9876ed1

	if (exception != null)
	{
	// exception message
	WriteMessage(textWriter, exception, singleLine);
	}

When I publish my .NET app with PublishAot without stack traces, the stack trace doesn't add any additional information:

warn: FtpServer.PassiveSocket[0]
      Could not discover NAT device
      SharpOpenNat.NatDeviceNotFoundException: Exception_WasThrown, SharpOpenNat.NatDeviceNotFoundException
         at FtpServer!<BaseAddress>+0xe65b4
      --- End of stack trace from previous location ---
         at FtpServer!<BaseAddress>+0x24d648
         at FtpServer!<BaseAddress>+0x24f7d2
         at FtpServer!<BaseAddress>+0x24f6f3
         at FtpServer!<BaseAddress>+0xaf55e

In this case I want to hide the stack trace. However, this isn't possible in the SimpleConsoleLogger. The only thing I can do is copy-paste the source code of SimpleConsole, but then textWriter.WriteColoredMessage can't be resolved because it's internal.

This is why I propose a new option so the stacktrace can be excluded. We currently already have an option called IncludeScopes, so to follow the naming convention the new property will be called IncludeExceptions.

By default, this property is set to true for backward compatibility. When the property is set to false, the exceptions will be excluded. The console message will be as following:

warn: FtpServer.PassiveSocket[0]
      Could not discover NAT device

---

The proposal is set to the class ConsoleFormatterOptions, so next to SimpleConsoleFormatter the class SystemdConsoleFormatter and JsonConsoleFormatter should also implement the new property:

runtime/src/libraries/Microsoft.Extensions.Logging.Console/src/SystemdConsoleFormatter.cs

Lines 97 to 101 in 9876ed1

	if (exception != null)
	{
	textWriter.Write(' ');
	WriteReplacingNewLine(textWriter, exception);
	}

runtime/src/libraries/Microsoft.Extensions.Logging.Console/src/JsonConsoleFormatter.cs

Lines 76 to 79 in 9876ed1

	if (exception != null)
	{
	writer.WriteString(nameof(Exception), exception);
	}

API Proposal

namespace Microsoft.Extensions.Logging.Console;

public partial class ConsoleFormatterOptions
{
    public ConsoleFormatterOptions() { }
+   public bool IncludeExceptions { get; set; } = true;
    public bool IncludeScopes { get; set; }
    [System.Diagnostics.CodeAnalysis.StringSyntaxAttribute("DateTimeFormat")]
    public string? TimestampFormat { get; set; }
    public bool UseUtcTimestamp { get; set; }
}

API Usage

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = Host.CreateEmptyApplicationBuilder(new HostApplicationBuilderSettings { Args = args });

builder.Logging.AddSimpleConsole(options =>
{
    // Excludes exceptions from the console
    options.IncludeExceptions = false;
});

Alternative Designs

Instead of ConsoleFormatterOptions the property can be added to SimpleConsoleFormatterOptions:

namespace Microsoft.Extensions.Logging.Console;

public partial class SimpleConsoleFormatterOptions : Microsoft.Extensions.Logging.Console.ConsoleFormatterOptions
{
    public SimpleConsoleFormatterOptions() { }
    public Microsoft.Extensions.Logging.Console.LoggerColorBehavior ColorBehavior { get; set; }
+   public bool IncludeExceptions { get; set; } = true;
    public bool SingleLine { get; set; }
}

Then the implementation should only be added to SimpleConsoleFormatter.

Risks

The only performance regression could be the new check if the option is set to true, but this can be checked after the exception != null which would be most of the times false.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-extensions-logging
See info in area-owners.md if you want to be subscribed.

[delixfe]

@GerardSmit Have a look at Microsoft.Extensions.Telemetry. This allows you to disable the stack trace.