Karambolo.Extensions.Logging.File

This class library contains a lightweight implementation of the Microsoft.Extensions.Logging.ILoggerProvider interface for file logging. Runs on all .NET platforms which implement .NET Standard 2.0+ including .NET Core 2 (ASP.NET Core 2.1+), .NET Core 3 and .NET 5+.

The code is based on ConsoleLogger whose full feature set is implemented (including log scopes and configuration reloading). The library has no 3rd party dependencies. No I/O blocking occurs as processing of log messages is done in the background. File system access is implemented on top of the Microsoft.Extensions.FileProviders.IFileProvider abstraction so it's even possible to use a custom backing storage. As of version 3.3.0 JSON structured logging (following the format established by the JSON formatter of the built-in console logger) is also available.

Additional features:

• Flexible configuration:
  • Hierarchical (two-level) log file settings.
  • Fine-grained control over log message filtering.
• File path templates for including log entry date (or other user-defined tokens) in log file paths/names.
• Rolling log files with customizable counter format.
• Fully customizable log text formatting.
• Designed with extensibility/customizability in mind.
• Support for multiple providers with different settings.

Important notes for existing consumers

Version 3.0 is a major revision with many improvements involving some breaking changes:

• Regular users should adjust their logger configuration as the configuration system went through a substantial rework.
• Consumers using advanced features or customization should expect some more work to do because internals were changed extensively too.

Thus, version 3.0 is not backward compatible with previous versions. If you want to upgrade from older versions, please read up on the new configuration system to be able to make the necessary adjustments.

However, you may stay with version 2.1 as it continues to work on .NET Core 3 according to my tests (but please note that it isn't developed actively any more).

Installation

Add the Karambolo.Extensions.Logging.File NuGet package to your application project:

dotnet add package Karambolo.Extensions.Logging.File

or, if you want structured logging, add Karambolo.Extensions.Logging.File.Json NuGet package instead:

dotnet add package Karambolo.Extensions.Logging.File.Json

If you have a .NET Core/.NET 5+ project other than an ASP.NET Core web application (e.g. a console application), also add explicit references to the following NuGet packages with the version matching your .NET runtime. For example if your project runs on .NET 6.0.0:

dotnet add package Microsoft.Extensions.FileProviders.Physical -v 6.0.0
dotnet add package Microsoft.Extensions.Logging.Configuration -v 6.0.0
dotnet add package Microsoft.Extensions.Options.ConfigurationExtensions -v 6.0.0

Configuration

If you've chosen structured logging, replace calls to AddFile(...) with AddJsonFile(...) in the following samples.

.NET Core 3, .NET 5+

• ASP.NET Core 6+ application (minimal hosting model)

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddFile(o => o.RootPath = o.RootPath = builder.Environment.ContentRootPath);

var app = builder.Build();

// ...

• ASP.NET Core 3.0+, ASP.NET Core 5+ application

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
                    .ConfigureLogging((ctx, builder) =>
                    {
                        builder.AddConfiguration(ctx.Configuration.GetSection("Logging"));
                        builder.AddFile(o => o.RootPath = ctx.HostingEnvironment.ContentRootPath);
                    })
                    .UseStartup<Startup>();
            });
}

• Console application

// build configuration
// var configuration = ...;

// configure DI
var services = new ServiceCollection();

services.AddLogging(builder =>
{
    builder.AddConfiguration(configuration.GetSection("Logging"));
    builder.AddFile(o => o.RootPath = AppContext.BaseDirectory);
});

// create logger factory
await using (var sp = services.BuildServiceProvider())
{
    var loggerFactory = sp.GetService<ILoggerFactory>();
    // ...
}

.NET Core 2

• ASP.NET Core 2.1+ application

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureLogging((ctx, builder) =>
            {
                builder.AddConfiguration(ctx.Configuration.GetSection("Logging"));
                builder.AddFile(o => o.RootPath = ctx.HostingEnvironment.ContentRootPath);
            })
            .UseStartup<Startup>();
}

• Console application

// build configuration
// var configuration = ...;

// configure DI
var services = new ServiceCollection();

services.AddLogging(builder =>
{
    builder.AddConfiguration(configuration.GetSection("Logging"));
    builder.AddFile(o => o.RootPath = AppContext.BaseDirectory);
});

// create logger factory
using (var sp = services.BuildServiceProvider())
{
    var loggerFactory = sp.GetService<ILoggerFactory>();
    // ...
}

Advanced use cases

Using multiple providers with different settings

First of all, you need a little bit of boilerplate code:

[ProviderAlias("File2")]
class AltFileLoggerProvider : FileLoggerProvider
{
    public AltFileLoggerProvider(FileLoggerContext context, IOptionsMonitor<FileLoggerOptions> options, string optionsName) : base(context, options, optionsName) { }
}

And a setup like this:

services.AddLogging(builder =>
{
    builder.AddConfiguration(config.GetSection("Logging"));
    builder.AddFile(o => o.RootPath = AppContext.BaseDirectory);
    builder.AddFile<AltFileLoggerProvider>(configure: o => o.RootPath = AppContext.BaseDirectory);
});

Now, you have two independent file logger providers. One of them picks up its configuration from the standard configuration section "File" while the other one from section "File2" as specified by the ProviderAlias attribute.

You may check out this demo application which shows a complete example of this advanced setup.

Settings

Provider settings

There are some settings which are configured on provider level only (FileLoggerOptions):

Log file settings

These settings can be configured on log file level only (LogFileOptions):

Globally configurable log file settings

The log file settings below can be specified globally (per provider) and individually (per log file) as well. File-level settings always override provider-level settings. (In practice this means if a setting property is null for a given file, the value of the same property of the provider-level settings applies. If that is null too, a default value is used.)

Sample JSON configuration

{
  "Logging": {
    // global filter settings
    "LogLevel": {
        "Default": "Information"
    },
    // provider level settings
    "File": {
      "BasePath": "Logs",
      "FileAccessMode": "KeepOpenAndAutoFlush",
      "FileEncodingName": "utf-8",
      "DateFormat": "yyyyMMdd",
      "CounterFormat": "000",
      "MaxFileSize": 10485760,
      "TextBuilderType": "MyApp.CustomLogEntryTextBuilder, MyApp",
      // first-level filters
      "LogLevel": {
        "MyApp": "Information",
        "Default": "Debug" // first-level filters can loosen the levels specified by the global filters
      },
      "IncludeScopes": true,
      "MaxQueueSize": 100,
      "Files": [
        // a simple log file definition which inherits all settings from the provider (will produce files like "default-000.log")
        {
          "Path": "default-<counter>.log"
        },
        // another log file definition which defines extra filters and overrides the Counter property (will produce files like "2019/08/other-00.log")
        {
          "Path": "<date:yyyy>/<date:MM>/other-<counter>.log",
          // second-level filters
          "MinLevel": {
            "MyApp.SomeClass": "Warning",
            "Default": "Trace" // this has no effect as second-level filters can only be more restrictive than first-level filters!
          },
          "CounterFormat": "00"
        }
      ]
    }
  }
}

Troubleshooting

If you have added the right NuGet package and configured logging in your application by the above but the application outputs no log files, check the following points:

• Have you defined at least one log file in the Files collection? If so, have you specified the Path property of that file? (See also this issue.)
• Are the Path properties of the defined log files valid paths on the operating system you use? If you use path templates (that is, paths containing placeholders like <date> or <counter>), are they resolved to valid paths?
• Do the combined paths of the defined log files point inside RootPath (or more precisely, inside the root path of FileAppender.FileProvider)? (See also this issue.)
• Does the application's process have the sufficient file system permissions to create and write files in RootPath\BasePath? (See also this issue.)

If none of these helps, since version 3.2.0 you can track down the problem by observing the file logger's diagnostic events:

// this subscription should happen before anything is logged,
// so place it in your code early enough (preferably, before configuration of logging)
FileLoggerContext.Default.DiagnosticEvent += e =>
{
    // examine the diagnostic event here:
    // print it to the debug window, set a breakpoint and inspect internal state on break, etc.
    Debug.WriteLine(e);
};