Eventlog target

Writes log message to the Windows Event Log.

Platforms Supported: Limited Windows only and requires nuget-package NLog.WindowsEventLog package with NLog 5.0

Configuration Syntax

<targets>
  <target xsi:type="EventLog"
          name="String"
          layout="Layout"
          machineName="String"
          source="Layout" 
          category="Layout"
          eventId="Layout"
          log="String"
          maxKilobytes="long"
          maxMessageLength="Integer" />
</targets>

Read more about using the Configuration File.

Parameters

General Options

• name - Name of the target.

Layout Options

• layout - Layout used to format log messages. Layout Required. Default: ${longdate}|${level:uppercase=true}|${logger}|${message:withexception=true}. Note: max size of 31839 characters (limitation of the EventLog API)

Event Log Options

• machineName - Name of the machine on which Event Log service is running. Default: .
• source - Value to be used as the event Source. By default this is the friendly name of the current AppDomain.

  Before NLog 4.0 then datatype was normal string without NLog Layout-support.

• category - Layout that renders event Category. The categories must be predefined for the specified source and needs to be numeric.

  Before NLog 5.0 then datatype was standard Layout, instead of typed-Layout.

• eventId - Layout that renders event ID.

  Before NLog 5.0 then datatype was standard Layout, instead of typed-Layout.

• eventLogEntryType - Layout that renders EventLogEntryType. Default: Use LogLevel

  Before NLog 5.0 then datatype was standard Layout, instead of typed-Layout.

• log - Name of the Event Log to write to. This can be System, Application or any user-defined name. Default: Application
• MaxMessageLength - The message length limit to write to the Event Log. There are various message length limit that depends on the OS. Therefore, be careful for the value. Default: 16,384. If given value is zero or negative, then Exception will be thrown. Introduced in NLog 4.3.
• onOverflow - Action to take when a log message is larger than the MaxMessageLength option. Available actions are:
  • Truncate - Truncates the message before writing to the Event Log. This is the default.
  • Split - Splits the message and writes multiple entries to the Event Log. Warning: the message layout will be spread across multiple Event Log entries; if there is an application reading and parsing the Event Log, split messages will not have the expected layout of a log entry.
  • Discard - Discards of the message. It will not be written to the Event Log.
• MaxKilobytes - maximum Event log size in kilobytes. null is default (512KB). Value should be multiples of 64 and between 64 and 4194240. Note, this requires admin rights. Introduced in NLog 4.4.10

Notes

When writing to the Windows EventLog, the EventLog-Source must be registered. NLog will automatically attempt to register the EventLog-Source if the application is running with necessary permissions. Alternatively, one must explicitly perform the EventLog-Source registration during application install.

• Installing Targets will only register EventLog-Source if source is static (Not using layout renderers).
• A simple PowerShell command can be used to register an EventLog-Source (run PowerShell as Administrator):

  New-EventLog -LogName Application -Source "MySourceName"

  NOTE: It may be necessary to restart the Windows Event Log Service (or, alternatively, reboot the computer) after making a change to the EventLog-Source registration in order for the change to take effect.

Notice a specific EventLog-source can only be registered for writing to a single named EventLog. Windows gives the illusion of multiple EventLogs, but all LogEvents are stored in the same blob where the EventLog-name is more like a category. The Windows Registry Database controls where the LogEvents from registered EventLog-source should be shown. If changing an EventLog-source to write to a different EventLog, then the change will not be applied until having restarted Windows (or restarted the EventLog-Windows-Service).

The Event Log has a limit in the number of bytes in a message. From MSDN:

The message string is longer than 31,839 bytes (32,766 bytes on Windows operating systems before Windows Vista).

Example

<targets>
    <target xsi:type="EventLog"
            name="EventLogTarget"
            source="MyApplicationName"
            eventId="${event-properties:EventId:whenEmpty=0}"
            layout="${message}${newline}${exception:format=ToString}" />
</targets>
<rules>
    <logger name="ApplicationEventLog" writeTo="EventLogTarget" />
</rules>

NLog.LogManager.GetLogger("ApplicationEventLog").WithProperty("EventdId", 42).Error("Kilroy was here");