Logging

Abstract

Logging in Sitecore Host applications.

Logging in Sitecore Host is simple because it makes use of the API provided by Microsoft in the Microsoft.Extensions.Logging.Abstractions and Microsoft.Extensions.Logging packages, instead of providing a custom layer. This means that if you understand the Microsoft Logging API, then you understand how to use logging in Sitecore.

By default, a Sitecore Host application logs content to the console and to a debug logger. You can use your own custom logging by implementing the IConfigureSitecoreLogging interface contained within the Sitecore.Framework.Runtime.Abstractions package. This provides the entry point for building and configuring your chosen logging implementation and makes it available to the Sitecore Host application.

Serilog is the default logger implementation. It is a simple yet powerful logging framework that is compatible with ASP .Net Core 2.x and the Microsoft Logging API.

It supports the use of structured logging and event data that enable a detailed analysis of log information through the use of a rich set of properties, entirely customizable to the needs of the application.

The Serilog Wiki has additional information.

This topic describes the following:

You configure logging in the sitecorehost.xml file because logging starts early when an application is executed. For example:

<Serilog>
    <Using>
        <Console>Serilog.Sinks.Console</Console>
        <Rolling>Serilog.Sinks.RollingFile</Rolling>
        <Environment>Serilog.Enrichers.Environment</Environment>
    </Using>
<Serilog>

A Sitecore Host application can use various Serilog sinks. A sink is a Serilog-specific way of piping logs to different outputs, for example, output to console and output to a file, too.

You configure the default sinks for an application in the sitecorehost.xml file:

<Serilog>
    <Using>
        <Console>Serilog.Sinks.Console</Console>
        <Rolling>Serilog.Sinks.RollingFile</Rolling>
        <Environment>Serilog.Enrichers.Environment</Environment>
    </Using>
<Serilog>

You can specify a minimum log level that covers all logging in the application. The following example sets the default log level to Debug:

<Serilog>
    <MinimumLevel>
        <Default>Debug</Default>  
    </MinimumLevel>
</Serilog>

You can also specify override filters based on namespace. Use this to log different log severity for different parts of the system.

If you want to override logging for a particular namespace (for example,  setting anything in the Microsoft namespace to output only to WARNING), use the Override element:

<Serilog>
    <MinimumLevel>
        <Default>Debug</Default>  
        <Override>  
            <Microsoft>Warning</Microsoft>  
            <System>Warning</System>  
        </Override>
    </MinimumLevel>
</Serilog>

Serilog allows you to enrich the logs with various properties. The default enricher provided is Environment, which provides the current machine name. Enrichers are included in a similar way to sinks:

<Serilog>
    <Enrich>
        <FromLogContext>FromLogContext</FromLogContext>
        <WithMachineName>WithMachineName</WithMachineName>  
    </Enrich>  
    <Properties>  
        <Application>SerilogSample</Application>  
    </Properties>
</Serilog>

The following is an example of how to create a Console logger in Serilog configuration:

<Serilog>
    <WriteTo>
        <ConsoleLogger>
            <Name>Console</Name>
            <Args>
                <theme>Serilog.Sinks.SystemConsole.Themes.AnsiConsoleTheme::Code, Serilog.Sinks.Console</theme>
                <outputTemplate>[{Timestamp:HH:mm:ss} {Level:u3}] {SourceContext} - {Message}{NewLine}{Exception}</outputTemplate>
            </Args>
        </ConsoleLogger>
    </WriteTo>
</Serilog>

The logger uses the  outputTemplate element when it formats each log line. The theme element specifies the color output on the console. The themes available are:

  • ConsoleTheme.None - no styling.

  • SystemConsoleTheme.Literate - styled to replicate Serilog.Sinks.Literate, using the System.Console coloring modes that are supported on all Windows/.NET targets. This is the default if you do not specify a theme.

  • SystemConsoleTheme.Grayscale - a theme that uses only shades of gray, white, and black.

  • AnsiConsoleTheme.Literate - an ANSI 16-color version of the Literate theme.

  • AnsiConsoleTheme.Grayscale - an ANSI 256-color version of the Grayscale theme.

  • AnsiConsoleTheme.Code - an ANSI 256-color Visual Studio Code-inspired theme.

Serilog Console Sink has more information.

The pathFormat element specifies the path and the file format and the outputTemplate element specifies the format of each log line:

<Serilog>
    <WriteTo>
        <FileLogger>  
            <Name>RollingFile</Name>  
            <Args>  
                <pathFormat>logs\SerilogSample-{Date}.log</pathFormat>  
                <outputTemplate>[{Timestamp:o}] [{Level:u3}] [{Application}/{MachineName}] {SourceContext} - {Message}{NewLine}{Exception}</outputTemplate>  
            </Args>  
        </FileLogger>
    </WriteTo>
</Serilog>