Time Source

NLog allows for a custom time source to be provided when timestamping log entries. In addition, NLog provides a few default time sources that can easily be configured via XML or code.

By default, NLog uses the FastLocal as the default time source.

Note that the time source is used mostly for accuracy, so there might be some quirks if using different time zones.

The following sections were based and/or provided by Robert Važan’s blog:

• NLog timestamps with millisecond accuracy

• How to configure NLog time source

• How to write custom NLog time source

Configure Via XML

The time source can be configured via XML by setting the time element with the XML name. The provided time sources don’t include “TimeSource” in their XML names.

<nlog>
    <time type="FastLocal" />
    <!-- Rest of Configuration -->
</nlog>

Configure Via Runtime Configuration

The time source can be configured by inserting the following before any log messages are printed:

TimeSource.Current = new FastLocalTimeSource();

Provided Time Sources

The provided time sources range from accurate to fast with options for a Local or UTC time.

The accuracy relates directly to Windows and how it balances accuracy, speed, and efficiency (i.e. battery life). By default, Windows is set to 16ms of accuracy, but can be changed via the API calls of timeBeginPeriod and timeEndPeriod. The AccurateLocal and AccurateUTC both utilize this API to provide a more accurate time reading.

The speed of UTC is faster than the local variant, as the time zone conversion can take some time.

Below are the provided time sources with NLog:

XML Configuration	Is Default?	Runtime Configuration	Time	Accuracy	Speed
FastLocal	Yes	FastLocalTimeSource	local	16ms	very fast
FastUTC	No	FastUtcTimeSource	UTC	16ms	very fast
AccurateLocal	No	AccurateLocalTimeSource	local	1ms	slow
AccurateUTC	No	AccurateUtcTimeSource	UTC	1ms	fast

Performance benchmarks for time source implementations (used BenchmarkDotNet):

Method	32-bit Mean	64-bit Mean
FastLocal	5.205 ns	3.546 ns
FastUtc	5.202 ns	3.541 ns
AccurateLocal	190.481 ns	85.927 ns
AccurateUtc	137.258 ns	66.451 ns

Custom Time Source

Before implementing your own time source, see the provided time sources first. If none of those fit your needs, this section will guide you through the process.

Create a class that inherits from TimeSource and implement the inherited property getter Time and method FromSystemTime.

• The property getter Time provides the current time instance.

• The method FromSystemTime converts the system time to the same form as if the time source provided it.

[TimeSource("CustomTimeZone")]
public class CustomTimeZoneTimeSource : TimeSource
{
    string ZoneName;
    TimeZoneInfo ZoneInfo;

    [Required]
    public string Zone
    {
        get { return ZoneName; }
        set
        {
            ZoneName = value;
            ZoneInfo
                = TimeZoneInfo.FindSystemTimeZoneById(value);
        }
    }
    
    public override DateTime Time
    {
        get
        {
            return TimeZoneInfo.ConvertTimeFromUtc(
                DateTime.UtcNow, ZoneInfo);
        }
    }
    
    public override DateTime FromSystemTime(DateTime systemTime)
    {
        return TimeZoneInfo.ConvertTimeFromUtc(systemTime, ZoneInfo);
    }
}

In addition, add an attribute to the top that provides the name when specifying the type via XML.

Your custom time source can be loaded by NLog just like any other NLog extension. See how to use the custom target / layout renderer.

The Runtime Configuration would look like this:

TimeSource.Current = new CustomTimeZoneTimeSource()
{
    Zone = "Central Standard Time"
}

The XML Configuration would look like this:

<nlog>
    <time type="CustomTimeZone" zone="Central Standard Time" />
</nlog>