(Yet) Another .NET Logger

Currently the project is DISCONTINUED. However, feel free to fork it and continue its development!

Fast and lightweight key/value pair logger for .NET Core projects.

Contents

1. Features
2. Quick start
3. Why Anlog?
4. Sinks
5. Formatters
6. Minimum log level
7. Object logging
8. License

Features

• Key/value pair approach ensures a standardization on logs.
• Writes to file or memory.
• Easy to use through a static Log object.
• Fast when formatting and writing.

Quick start

Install Anlog from the NuGet Gallery:

Install-Package Anlog

Create a console application and configure the logger:

using Anlog;
using Anlog.Factories;
using Anlog.Sinks.Console;

namespace QuickStart
{
    class Program
    {
        static void Main(string[] args)
        {
            // Creates the logger.
            Log.Logger = new LoggerFactory()
                .MinimumLevel.Debug() // Minimum log level to write. In this case, Debug.
                .WriteTo.Console() // Write to the console.
                .CreateLogger();
            
            // Writes the log to console.
            Log.Append("key", "value").Info();
            
            // If possible, when the application ends, dispose the logger to ensure all logs are written.
            Log.Dispose();
        }
    }
}

Log produced: 2018-03-29 22:22:07.656 [INF] Program.Main:17 key=value

Why Anlog?

Keeping logs standardized for an entire application is no easy task. The idea of Anlog is to help make logs follow a default convention by using key/value pairs and default formats for different kinds of values.

Key/value pairs also offer an easy and compact way to analyze system logs, making it easier to read, find and standardize.

History

Anlog started as an extension of the great (and widely used) Serilog (that’s why it bears some resemblance!). However, due to difficulties of actually implementing it as planned, the project deviated from its original intention and began growing as a full-fledged component.

Sinks

Sinks are objects that write the log to some output, like a file or memory.

Console

Writes the log to the console.

Log.Logger = new LoggerFactory()
    .WriteTo.Console()
    .CreateLogger();

Settings

• async: True if write to the console should be asynchronous, otherwise false. Provides fast writing to console, however due to run in a separated thread, the last log(s) in case of a crash may not be written. The default is false.
• *theme: Output color theme. The default is none.
• minimumLevel: Minimum log level. The default is the logger minimum level.
• formatter: Log formatter to be used. The default is CompactKeyValueFormatter.

Rolling File

Writes the output to files by period and max file size. Each time a period or a max file size is reached, a new file is created.

Log.Logger = new LoggerFactory()
    .WriteTo.RollingFile()
    .CreateLogger();

Periods

Periods are defined by constants in the class Anlog.Sinks.RollingFile.RollingFilePeriod.

• Day: Generates a new file each day. File name format: log-yyyyMMdd-{fileNumber}.txt.
• Hour: Generates a new file each hour. File name format: log-yyyyMMddHH-{fileNumber}.txt.

* fileNumber default value is 1 and raises automatically creating a new log file every time log reaches the maximum size value configured.

Settings

• logFileFolder: Log files folder path. The default is the application running folder.
• period: Period for rolling the files. The default is RollingFilePeriod.Day.
• async: True if write to the console should be asynchronous, otherwise false. Provides fast writing to console, however due to run in a separated thread, the last log(s) in case of a crash may not be written. The default is false.
• maxFileSize: Max file size in bytes. The default is 100mb (104,857,600 bytes).
• fileExpiryPeriod: File expiry period in days. The default is 0 (never).
• encoding: File encoding. The default is UTF8.
• bufferSize: Buffer size to be used. The default is 4096.
• minimumLevel: Minimum log level. The default is the logger minimum level.
• formatter: Log formatter to be used. The default is CompactKeyValueFormatter.

Single File

Writes the log to a single file with unlimited size.

Log.Logger = new LoggerFactory()
    .WriteTo.SingleFile()
    .CreateLogger();

Settings

• logFilePath: Log path, including file name and extension. The default is a log.txt file in the application running folder.
• async: True if write to the console should be asynchronous, otherwise false. Provides fast writing to console, however due to run in a separated thread, the last log(s) in case of a crash may not be written. The default is false.
• encoding: file encoding. The default is UTF8.
• bufferSize: buffer size to be used. The default is 4096.
• minimumLevel: Minimum log level. The default is the logger minimum level.
• formatter: Log formatter to be used. The default is CompactKeyValueFormatter.

In Memory

Writes the log to a memory buffer.

It's recommended to use only in tests.

Log.Logger = new LoggerFactory()
    .WriteTo.InMemory()
    .CreateLogger();

To get the written logs, use Log.GetSink():

var logs = Log.GetSink<InMemorySink>()?.GetLogs();

xUnit

Allows writing of logs to the xUnit test console using Anlog.

Please refer to the project repository.

Settings

• appendNewLine: Indicates whether a new line should be appended at the end of each log. The default is true.
• minimumLevel: Minimum log level. The default is the logger minimum level.
• formatter: Log formatter to be used. The default is CompactKeyValueFormatter.

Formatters

Formats the key/value entries. All formatters include class, method name and line number of the log call.

CompactKeyValue

Formats the key/value entries using a compact approach.

2018-03-29 22:22:07.656 [INF] c=Program.Main:17 key=value.

This is the default formatter for all sinks.

Formats

• Strings: use the given string. E.g.: key=text
• Numbers: use ToString(culture). E.g.: key=24.11
• Dates: use ToString(dateTimeFormat). E.g.: date=2018-03-25 23:00:00.000
• Enums: use ToString(). E.g.: key=Value
• Arrays and IEnumerable: writes the items between [] separated by comma. E.g.: key=[11.1,24.2,69.3,666.4]
• Classes with fields and/or properties: writes the fields/properties as key/value pairs between {}. E.g.: {field=24 property=666.11}

Minimum log level

It's possible to set the minimum log level to write to sinks by using the MinimumLevel property in the LoggerFactory:

Log.Logger = new LoggerFactory()
    .MinimumLevel.Warn()
    .CreateLogger();

It's also possible to set the log level by using the LogLevel enumeration:

Log.Logger = new LoggerFactory()
    .MinimumLevel.Set(LogLevel.Info)
    .CreateLogger();

Each sink can override the logger minimum level. Please consult the Sinks topic for settings of each sink.

Available log levels

1. Debug: internal system logs that are usually intented for developers.
2. Info: general informative logs.
3. Warn: the system may not be behaving as expected.
4. Error: an unexpected issue occured.

The default minimum log level is Info.

Object logging

Ignoring fields/properties

If some field/property in an object needs to be ignored for logging, use the LogIgnore atribute:

public class Model
{
    [LogIgnore]
    public int IgnoreProperty { get; set; }
}

Caching

Any object with a DataContract attribute will be cached for logging during initialization:

[DataContract]
public class Model
{
    ...
}

License

Licensed under the The MIT License (MIT). Please see LICENSE for more information.