Bleess.Extensions.Logging.File
2.0.0-rc1
See the version list below for details.
dotnet add package Bleess.Extensions.Logging.File --version 2.0.0-rc1
NuGet\Install-Package Bleess.Extensions.Logging.File -Version 2.0.0-rc1
<PackageReference Include="Bleess.Extensions.Logging.File" Version="2.0.0-rc1" />
paket add Bleess.Extensions.Logging.File --version 2.0.0-rc1
#r "nuget: Bleess.Extensions.Logging.File, 2.0.0-rc1"
// Install Bleess.Extensions.Logging.File as a Cake Addin #addin nuget:?package=Bleess.Extensions.Logging.File&version=2.0.0-rc1&prerelease // Install Bleess.Extensions.Logging.File as a Cake Tool #tool nuget:?package=Bleess.Extensions.Logging.File&version=2.0.0-rc1&prerelease
Bleess.Extensions.Logging.File
Simple rolling file logger for Microsoft.Extensions.Logging with no 3rd party dependencies
Very similar implementation to other standard MS logging providers such as Console Logger in dotnet 5.
Features
- Rolling files
- Text or Json output
- Standard idomatic configuration (similar to other MS logging providers) using IConfiguration or configuration callbacks
- Plugable custom formatters
- Abitity to update settings such as log level, filter rules, or log file path while application is running
- Logging scopes and activity tracking support
- High performance using dedicated write thread and message queue
- Ability to specify multiple log files with independent settings
This project is very similar to nReco/logging with a few additions: multiple files, logging scopes, json output, streamlined configuration, and abiltity to modify settings while running.
Usage
Add the nuget package Bleess.Extensions.Logging.File
The log provider is configured just like any other Microsoft.Extensions.Logging providers. There are extensions methods on the ILogBuilder to add the provider.
When using Host.CreateDefaultBuilder you only need to call AddFile(), and the logger will be configured using configuration providers. There are also other overloads to configure the logger using options callbacks etc.
logBuilder.AddFile();
Configuration
Below is a sample configuration for the file provider. The values shown are the defaults.
{
"Logging": {
"File": {
"IncludeScopes": true, // this is can also be set in the formatter options
"Path": "logs/log.txt", // can contain environment variables
"RollInteral" : "Infinite", // can be (Year, Month, Day, Hour) appends _yyyyMMddHH to the file name
"MaxNumberFiles": 7,
"MaxFileSizeInMB": 50, // this can be decimal
"FormatterName": "simple", // simple or json
"Append": true,
"formatterOptions" : {
// see formatter options below
}
"logLevel": {
"default": "Information"
}
},
"logLevel": {
"default": "Information"
}
}
}
Formatting
There are two built in formatters. Simple text and Json. The formatters have a few limited options.
// simple text
"FormatterOptions": {
"IncludeScopes" : false,
"SingleLine" : false,
"EmptyLineBetweenMessages" : true,
"TimestampFormat" : "yyyy-MM-dd h:mm tt",
"UseUtcTimestamp" : false
}
// json formatter
"FormatterOptions" : {
"IncludeScopes" : false,
"EmptyLineBetweenMessages" : true,
"TimestampFormat" : "yyyy-MM-dd h:mm tt",
"UseUtcTimestamp" : false,
"JsonWriterOptions" : {
// see https"://docs.microsoft.com/en-us/dotnet/api/system.text.json.jsonwriteroptions?view=netcore-3.1
}
}
Custom formatters can be added using extensions method .AddFileFormatter<TFormatter, TOptions>(this ILoggingBuilder builder, Action<TOptions> configure). The Formatter name of the log provider will need to be set in order to use the formatter.
Multiple log files
Multiple log files are supported. Example below:
l.AddFiles(b =>
{
// example adding log provider, will use settings in configuration
b.AddFile("TraceLog");
// example configuration certain properties in code, which would override config settings
b.AddFile("ErrorLog")
.WithOptions(o =>
{
o.Path = "logs/errors.json";
})
.WithJsonFormatter(o =>
{
o.IncludeScopes = true;
o.EmptyLineBetweenMessages = false;
o.TimestampFormat = "dd h:mm tt";
})
.WithMinLevel(LogLevel.Error);
});
Example configuration
"Logging": {
"Files": {
"TraceLog": {
"Path": "logs/trace.txt",
"FormatterOptions": {
"IncludeScopes": false,
"SingleLine": true,
"EmptyLineBetweenMessages": false,
"TimestampFormat": "yyyy-MM-dd h:mm tt",
"UseUtcTimestamp": true
},
"logLevel": {
"Default": "Trace",
"Microsoft": "Warning"
}
},
"ErrorLog": {} // defined in code
},
Rolling Behavior
Log files can have a max file size at which time a new file will be create with a incremented id appended. You may also specify a maximum number of files to retain. Once the maximum number of files has been reached, the oldest will be overwritten. Using RollInterval setting, you can also specify that a date will be appended to the file name and the files will roll according to the date in 'yyyyMMddHH' format.
Credits
- Most of the code was a adapted from dotnet source code (specifically Microsoft.Extensions.Logging.Console) https://github.com/dotnet/runtime/tree/master/src/libraries/Microsoft.Extensions.Logging.Console
- The FileWriter was adapted from https://github.com/nreco/logging
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 is compatible. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net5.0
- Microsoft.Extensions.Logging (>= 5.0.0)
- Microsoft.Extensions.Logging.Configuration (>= 5.0.0)
- Microsoft.SourceLink.GitHub (>= 8.0.0)
- System.Text.Json (>= 5.0.2)
-
net6.0
- Microsoft.Extensions.Logging (>= 6.0.0)
- Microsoft.Extensions.Logging.Configuration (>= 6.0.0)
- Microsoft.SourceLink.GitHub (>= 8.0.0)
- System.Text.Json (>= 6.0.9)
-
net7.0
- Microsoft.Extensions.Logging (>= 7.0.0)
- Microsoft.Extensions.Logging.Configuration (>= 7.0.0)
- Microsoft.SourceLink.GitHub (>= 8.0.0)
- System.Text.Json (>= 7.0.4)
-
net8.0
- Microsoft.Extensions.Logging (>= 8.0.0)
- Microsoft.Extensions.Logging.Configuration (>= 8.0.0)
- Microsoft.SourceLink.GitHub (>= 8.0.0)
- System.Text.Json (>= 8.0.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
How to use: https://github.com/pableess/Bleess.Extensions.Logging.File
- Basic file logging features: rolling files by date, maximum file length, max number of files, etc
- Simple text and json formatters with options for single line, multi-line, and separated log statements
- Support for logging scopes
- Support for idiomatic configuration via IConfiguration sources or in code
- Ability to change settings without restarting application
- Dedicated file writing thread for high log throughput and performance
- Support for multiple log files with independent settings