Serilog

Source
NuGet Package NServiceBus.Serilog (6.x) | License
This is a community maintained project. License and support are independent of Particular Software.
Target NServiceBus Version: 7.x

Support for writing all NServiceBus log entries to Serilog.

Usage

Log.Logger = new LoggerConfiguration()
    .WriteTo.File("log.txt")
    .CreateLogger();

LogManager.Use<SerilogFactory>();

Seq

To log to Seq:

Log.Logger = new LoggerConfiguration()
    .WriteTo.Seq("http://localhost:5341")
    .MinimumLevel.Information()
    .CreateLogger();

LogManager.Use<SerilogFactory>();

Filtering

NServiceBus can write a significant amount of information to the log. To limit this information use the filtering features of the underlying logging framework.

For example to limit log output to a specific namespace.

Here is a code configuration example for adding a Filter.

Log.Logger = new LoggerConfiguration()
    .WriteTo.File(
        path:"log.txt",
        restrictedToMinimumLevel: LogEventLevel.Debug
    )
    .Filter.ByIncludingOnly(
        inclusionPredicate: Matching.FromSource("MyNamespace"))
    .CreateLogger();

LogManager.Use<SerilogFactory>();

Tracing

Writing diagnostic log entries to Serilog. Plugs into the low level pipeline to give more detailed diagnostics.

When using Serilog for tracing, it is optional to use Serilog as the main NServiceBus logger. i.e. there is no need to include LogManager.Use<SerilogFactory>();.

Create an instance of a Serilog logger

var tracingLog = new LoggerConfiguration()
    .WriteTo.File("log.txt")
    .MinimumLevel.Information()
    .CreateLogger();

Configure the tracing feature to use that logger

var serilogTracing = endpointConfiguration.EnableSerilogTracing(tracingLog);
serilogTracing.EnableMessageTracing();

Contextual logger

Serilog tracing injects a contextual Serilog.Ilogger into the NServiceBus pipeline.

Saga and message tracing will use the current contextual logger.

There are several layers of enrichment based on the pipeline phase.

Endpoint enrichment

All loggers for an endpoint will have the the property ProcessingEndpoint added that contains the current endpoint name.

Incoming message enrichment

When a message is received, the following enrichment properties are added:

Handler enrichment

When a handler is invoked, a new logger is forked from the above enriched physical logger with a new enriched property named Handler that contains the the FullName of the current handler.

Outgoing message enrichment

When a message is sent, the same properties as described in "Incoming message enrichment" will be added to the outgoing pipeline. Note that if a handler sends a message, the logger injected into the outgoing pipeline will be forked from the logger instance as described in "Handler enrichment". As such it will contain a property Handler for the handler that sent the message.

Accessing the logger

The contextual logger instance can be accessed from anywhere in the pipeline via SerilogTracingExtensions.Logger(this IPipelineContext context).

public class TheHandler : IHandleMessages<TheMessage>
{
    public Task Handle(TheMessage message, IMessageHandlerContext context)
    {
        var logger = context.Logger();
        logger.Information("Hello from {@Handler}.");
        return Task.CompletedTask;
    }
}

Exception enrichment

When an exception occurs in the message processing pipeline, the current pipeline state is added to the exception. When that exception is logged that state can be add to the log entry.

The type added to the exception data is ExceptionLogState. It contains the following data:

The instance of ExceptionLogState can be accessed using the following.

var data = exception.Data;
if (data.Contains("ExceptionLogState"))
{
    var logState = (ExceptionLogState) data["ExceptionLogState"];
    string endpoint = logState.ProcessingEndpoint;
    string messageId = logState.MessageId;
    string messageType = logState.MessageType;
    string correlationId = logState.CorrelationId;
    string conversationId = logState.ConversationId;
}

When routing the NServiceBus log event with LogManager.Use<SerilogFactory>();, the above properties will be promoted to the log event.

Saga tracing

var serilogTracing = endpointConfiguration.EnableSerilogTracing(logger);
serilogTracing.EnableSagaTracing();

Message tracing

Both incoming and outgoing messages will be logged at the Information level. The current message will be included in a property named Message. For outgoing messages any unicast routes will be included in a property named UnicastRoutes.

var serilogTracing = endpointConfiguration.EnableSerilogTracing(logger);
serilogTracing.EnableMessageTracing();

Seq

To log to Seq:

var tracingLog = new LoggerConfiguration()
    .WriteTo.Seq("http://localhost:5341")
    .MinimumLevel.Information()
    .CreateLogger();

Samples

Related Articles

  • Logging
    Manage and integrate with NServiceBus logging.

Last modified