Logging

CrispyWaffle logging is a static facade, LogConsumer, that fans each message out to every registered log provider. Providers decide where messages go (console, rolling text files, Log4Net, Redis, RabbitMQ, Elasticsearch, Windows Event Log). Filters decide which provider receives which message, and an exception handler decides what happens to exceptions passed to LogConsumer.Handle.

Use it when you want one logging call site in your code and the freedom to add or swap destinations at startup without touching that code.

How it works

The pipeline has four kinds of parts:

• LogConsumer is the static entry point. It holds a list of providers, a list of filters and one exception handler.
• Providers (ILogProvider) receive a category and a message for each level. You register them with LogConsumer.AddProvider.
• Adapters (ILogAdapter and friends) do the actual writing for the two core providers. ConsoleLogProvider writes through an IConsoleLogAdapter and TextFileLogProvider writes through an ITextFileLogAdapter, both resolved from the service locator.
• Filters (ILogFilter) are checked per provider, per message.

Sending a message

When you call LogConsumer.Info("...") (or any other level), the consumer:

1. Resolves a category by walking the stack trace. It skips frames whose declaring type is in CrispyWaffle.Log* or is a CrispyWaffle type whose name ends with LogProvider, then uses the declaring type's full name (for example MyApp.Services.OrderService). A leading CrispyWaffle. prefix is removed. For async methods and lambdas this is the compiler-generated type name (for example MyApp.OrderService+<RunAsync>d__0). If no frame qualifies, the category is CrispyWaffle.
2. For each provider, calls every registered filter with the provider's full type name, the level, the category and the message. The provider receives the message only if all filters return true.
3. Calls the matching method on each provider that passed, synchronously and in registration order.

LogTo<TLogProvider> and DebugTo<TLogProvider> skip the fan-out and target the one registered provider whose runtime type is exactly TLogProvider. They return false when no such provider is registered or a filter rejects the message.

The overloads that take params object[] arguments format the message with string.Format(CultureInfo.InvariantCulture, ...) before it reaches the providers.

Levels

LogLevel is a [Flags] enum. Each provider (through its adapter) keeps its own level and drops messages whose level flag is not set. LogConsumer itself does not check levels. The built-in adapters start at LogLevel.Production (Fatal, Error, Warning, Info), so Trace and Debug messages are dropped until you call SetLevel on the provider:

LogConsumer.AddProvider<ConsoleLogProvider>().SetLevel(LogLevel.All);

Exceptions

LogConsumer.Handle(exception) (and the two event-handler overloads) forward to the current IExceptionHandler. The handler is chosen the first time LogConsumer is used (static constructor): it resolves IExceptionHandler from the service locator and, if that fails, falls back to DefaultExceptionHandler and passes it the resolution error. Without a registration, resolution normally fails because the core package already contains two implementations (DefaultExceptionHandler and NullExceptionHandler) and auto-registration refuses to pick one. Register your handler before the first logging call, or replace it later with LogConsumer.SetHandler.

DefaultExceptionHandler does not write to the providers registered on LogConsumer. It keeps its own static list of providers, added with AddLogProvider<T>(ExceptionLogType), TryAddConsoleLogProvider() or TryAddTextFileLogProvider(). When it handles an exception it:

1. Resolves a category from the stack trace, the same way LogConsumer does.
2. Unwraps the exception chain (innermost first) and calls TelemetryAnalytics.TrackException for each inner exception type (see Telemetry).
3. Calls Error(category, message) on each ExceptionLogType.Message provider once per exception in the chain, with just that exception's Message.
4. Calls Error(category, details) once on each ExceptionLogType.Full provider, where details contains every exception's message, type name and stack trace, with Exception rethrow at [n]: markers between them.

With no providers added, DefaultExceptionHandler only tracks telemetry.

Integration packages

Other CrispyWaffle packages add providers and handlers that plug into the same pipeline:

Threading

LogConsumer holds providers and filters in plain collections with no locking, so register them at startup before logging from multiple threads. StandardConsoleLogAdapter and RollingTextFileLogAdapter lock around each write, so concurrent logging through them is safe.

Getting started

Register an adapter and an exception handler, add a provider, then log.

using System;
using CrispyWaffle.Composition;
using CrispyWaffle.Log;
using CrispyWaffle.Log.Adapters;
using CrispyWaffle.Log.Handlers;
using CrispyWaffle.Log.Providers;

public static class Program
{
    public static void Main()
    {
        // Adapter used by ConsoleLogProvider.
        ServiceLocator.Register<IConsoleLogAdapter, StandardConsoleLogAdapter>(Lifetime.Singleton);

        // Must be registered before the first LogConsumer call.
        ServiceLocator.Register<IExceptionHandler, NullExceptionHandler>(Lifetime.Singleton);

        LogConsumer.AddProvider<ConsoleLogProvider>().SetLevel(LogLevel.All);

        LogConsumer.Info("Hello world Crispy Waffle");
        LogConsumer.Debug("Current time: {0:HH:mm:ss}", DateTime.Now);
        LogConsumer.Warning("Press any key to close the program!");

        Console.ReadKey();
    }
}

Reference

LogConsumer

public static class LogConsumer — static facade that sends messages to every registered provider and exceptions to the exception handler.

Methods without a To suffix return void and write to every provider that passes the filters. The category is resolved from the caller; see How it works.

LogLevel

[Flags] public enum LogLevel — severity flags. Each value has a [HumanReadable] name used in log output.

LogMessage

[Serializer(SerializerFormat.Json)] public sealed class LogMessage — the record RollingTextFileLogAdapter writes for each entry. Also usable by custom providers.

All properties have public getters and setters.

The rolling adapter fills Application, Hostname, IpAddress, IpAddressRemote, Operation, ProcessId and UserAgent from EnvironmentHelper (see Infrastructure).

ILogProvider

public interface ILogProvider — a log destination registered with LogConsumer. Implement it to add your own destination.

IExceptionHandler

public interface IExceptionHandler — handles exceptions passed to LogConsumer.Handle.

ILogFilter

public interface ILogFilter — decides whether a provider receives a message.

ILogAdapter

public interface ILogAdapter : IDisposable — low-level writer used by providers.

ICategorizedLogAdapter

public interface ICategorizedLogAdapter : ILogAdapter — adapter that also records a category with each entry.

IConsoleLogAdapter

public interface IConsoleLogAdapter : ILogAdapter — marker interface for console adapters. ConsoleLogProvider depends on it. Adds no members.

ITextFileLogAdapter

public interface ITextFileLogAdapter : ICategorizedLogAdapter — marker interface for text file adapters. TextFileLogProvider depends on it. Adds no members.

ConsoleLogProvider

public sealed class ConsoleLogProvider : ILogProvider — writes to the console through an IConsoleLogAdapter.

The adapter is stored in a static field: the first ConsoleLogProvider constructed keeps its adapter for the life of the process, and later instances reuse it and ignore the adapter passed to them. The category is ignored; console output does not include it.

TextFileLogProvider

public sealed class TextFileLogProvider : ILogProvider — writes to files through an ITextFileLogAdapter, keeping the category.

StandardConsoleLogAdapter

public sealed class StandardConsoleLogAdapter : IConsoleLogAdapter — writes colored lines to the console.

Each line is HH:mm:ss message. Colors: Fatal and Error red, Warning yellow, Info green, Trace dark green, Debug gray; the foreground color is reset to white after each write. Writes are serialized with a static lock. The constructor checks whether standard input is available; if it is not (for example in a Windows service), nothing is written.

RollingTextFileLogAdapter

public sealed class RollingTextFileLogAdapter : ITextFileLogAdapter — writes entries to files in a folder, starting a new file when a message count or size limit is reached.

Files are named LogFile-{fileNameSeed}-[{n}].txt (or .json). On start and on each roll, n is increased until the name does not collide with an existing file. Before each write the adapter checks the current file: when it holds maxMessageCount messages or its length has reached maxFileSize, it closes it and opens the next one, so a file can exceed the size limit by one entry. Writes are serialized with a lock per instance. Use one instance per seed; two instances with the same seed and folder write to different numbers but may race on creating them.

Each entry is a LogMessage. In LogFileType.Text files, entries are separated by a ---------- line and each property is written as Name: value (N.A. for empty values). In LogFileType.Json files, the file is kept as a valid JSON array of entries. Exceptions are written as [MainException][Type]: message followed by one [InnerException][Type]: message line per inner exception, without stack traces. The default category is N.A..

Unit

public enum Unit — size unit for RollingTextFileLogAdapter's maxFileSize. The numeric value is the number of bytes per unit.

LogFileType

public enum LogFileType — output format of RollingTextFileLogAdapter. The [InternalValue] is the file extension.

CategoryLogFilter

public class CategoryLogFilter : ILogFilter — filters messages by category, optionally for one provider type only.

DefaultExceptionHandler

public class DefaultExceptionHandler : IExceptionHandler — logs exceptions to its own list of providers and tracks exception telemetry. Used when no IExceptionHandler is registered. See Exceptions for the exact output.

The provider list is static, shared by all instances. Adding the same provider twice makes it log each exception twice.

NullExceptionHandler

public sealed class NullExceptionHandler : IExceptionHandler — ignores all exceptions.

FailoverExceptionHandler

public static class FailoverExceptionHandler — last-resort exception logging that falls back to a file if logging itself fails.

ExceptionLogType

public enum ExceptionLogType — how an exception handler writes to a provider.

Examples

Rolling text files

Write to text files that roll every 100 messages or 10 KB. Register the adapter as a singleton so every resolution of TextFileLogProvider shares the same files.

using System;
using CrispyWaffle.Composition;
using CrispyWaffle.Log;
using CrispyWaffle.Log.Adapters;
using CrispyWaffle.Log.Handlers;
using CrispyWaffle.Log.Providers;

ServiceLocator.Register<ITextFileLogAdapter>(
    () => new RollingTextFileLogAdapter(
        AppDomain.CurrentDomain.BaseDirectory, // folder, must exist
        "textFileLogs",                        // file name seed
        100,                                   // max messages per file
        (Unit.KByte, 10),                      // max file size
        LogFileType.Text),
    Lifetime.Singleton);

ServiceLocator.Register<IExceptionHandler, NullExceptionHandler>(Lifetime.Singleton);

LogConsumer.AddProvider<TextFileLogProvider>();

LogConsumer.Info("Hello world Crispy Waffle");
LogConsumer.Warning("Warning message!");

Logging unhandled exceptions

Use the default handler, write exception messages to the console and full details to text files, and hook process-wide unhandled exceptions.

using System;
using CrispyWaffle.Composition;
using CrispyWaffle.Log;
using CrispyWaffle.Log.Adapters;
using CrispyWaffle.Log.Handlers;
using CrispyWaffle.Log.Providers;

ServiceLocator.Register<IConsoleLogAdapter, StandardConsoleLogAdapter>(Lifetime.Singleton);
ServiceLocator.Register<ITextFileLogAdapter>(
    () => new RollingTextFileLogAdapter("Logs", "app", 1000, (Unit.MByte, 5), LogFileType.Json),
    Lifetime.Singleton);
ServiceLocator.Register<IExceptionHandler, DefaultExceptionHandler>(Lifetime.Singleton);

DefaultExceptionHandler.TryAddConsoleLogProvider();
DefaultExceptionHandler.TryAddTextFileLogProvider();

AppDomain.CurrentDomain.UnhandledException += LogConsumer.Handle;

try
{
    throw new InvalidOperationException("Something failed");
}
catch (Exception e)
{
    LogConsumer.Handle(e);
}

The Logs folder must exist before the adapter is created.

Filtering by category

Drop messages from one namespace for the console provider only.

using CrispyWaffle.Log;
using CrispyWaffle.Log.Filters;
using CrispyWaffle.Log.Providers;

LogConsumer.AddFilter(
    new CategoryLogFilter(typeof(ConsoleLogProvider), isExclusive: true)
        .AddCategory("MyApp.Services.NoisyService"));

The category is the caller's full type name, so add one entry per type you want to filter.

Dumping an object for debugging

Serialize an object to every provider at Debug level.

using CrispyWaffle.Log;
using CrispyWaffle.Serialization;

LogConsumer.Debug(new Order { Id = 1, Total = 9.90m }, "order-1", SerializerFormat.Json);

[Serializer(SerializerFormat.Json)]
public class Order
{
    public int Id { get; set; }
    public decimal Total { get; set; }
}

The provider must have LogLevel.Debug enabled (for example SetLevel(LogLevel.All)) for the entry to be written.

Writing a custom provider

Implement ILogProvider and add an instance.

using System;
using CrispyWaffle.Log;
using CrispyWaffle.Log.Providers;
using CrispyWaffle.Serialization;

LogConsumer.AddProvider(new DebugOutputLogProvider()).SetLevel(LogLevel.All);
LogConsumer.Info("Custom provider registered");

public sealed class DebugOutputLogProvider : ILogProvider
{
    private LogLevel _level = LogLevel.Production;

    public void SetLevel(LogLevel level) => _level = level;

    private void Write(LogLevel level, string category, string message)
    {
        if (_level.HasFlag(level))
        {
            System.Diagnostics.Debug.WriteLine($"[{level}] {category}: {message}");
        }
    }

    public void Fatal(string category, string message) => Write(LogLevel.Fatal, category, message);
    public void Error(string category, string message) => Write(LogLevel.Error, category, message);
    public void Warning(string category, string message) => Write(LogLevel.Warning, category, message);
    public void Info(string category, string message) => Write(LogLevel.Info, category, message);
    public void Trace(string category, string message) => Write(LogLevel.Trace, category, message);
    public void Trace(string category, string message, Exception exception) =>
        Write(LogLevel.Trace, category, $"{message}: {exception}");
    public void Trace(string category, Exception exception) =>
        Write(LogLevel.Trace, category, exception.ToString());
    public void Debug(string category, string message) => Write(LogLevel.Debug, category, message);
    public void Debug(string category, string content, string identifier) =>
        Write(LogLevel.Debug, category, $"{identifier}: {content}");
    public void Debug<T>(string category, T content, string identifier, SerializerFormat customFormat)
        where T : class, new() =>
        Write(LogLevel.Debug, category, $"{identifier}: {content}");
}

See also

• Service locator
• Telemetry
• Serialization
• Infrastructure
• Diagrams