-
Notifications
You must be signed in to change notification settings - Fork 1.4k
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:
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>
The time source can be configured by inserting the following before any log messages are printed:
TimeSource.Current = new FastLocalTimeSource();
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 |
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>
- Troubleshooting Guide - See available NLog Targets and Layouts: https://nlog-project.org/config
- Getting started
- How to use structured logging
- Troubleshooting
- FAQ
-
All targets, layouts and layout renderers
Popular: - Using NLog with NLog.config
- Using NLog with appsettings.json