Time Source

Valeriu Caraulean edited this page Jul 14, 2016 · 9 revisions

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:

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 fastest
AccurateLocal No AccurateLocalTimeSource local 1ms slow
AccurateUTC No AccurateUtcTimeSource UTC 1ms fast

Performance benchmarks for time source implementations (used BenchmarkDotNet):

Method Median StdDev
FastLocal 5.7752 ns 0.3450 ns
FastUtc 5.8330 ns 0.4939 ns
AccurateLocal 784.4354 ns 61.6136 ns
AccurateUtc 7.0547 ns 0.3934 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>
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.