NLog .NET logging

Intro

NLog is “a free logging platform for .NET, Silverlight and Windows Phone with rich log routing and management capabilities. It makes it easy to produce and manage high-quality logs for your application regardless of its size or complexity.”

Papertrail supports aggregating messages from a native NLog target, providing a live searchable log console for your C# app.

If NLog isn’t already in use and a simpler solution is preferable, use SimpleSysLog instead.

Installation

Install NLog

Install NLog in your app. Here’s a few tutorials.

If you use NuGet, consider installing the NLog.Config package, which includes NLog, a default config file, and the related Visual Studio IntelliSense schema.

Install syslog target

NLog sends to Papertrail using the syslog protocol, which is supported by an open-source NLog extension. Download NLog.Targets.Syslog.

To install it, place the NLog.Targets.Syslog.dll file in the same location as the existing NLog.dll and NLog.config files. The target’s README has more.

Setup Papertrail destination

In NLog.config, add the new syslog extension, add a syslog target for Papertrail, and add a rule directing all log messages to the target. Here’s a sample NLog.config.

If the app is not yet using NLog, here’s how to generate messages.

Important: In the sample below, replace <host>.papertrailapp.com and XXXXX with the details from Papertrail’s Add Systems page.

<nlog xmlns="http://nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <extensions>
        <add assembly="NLog.Targets.Syslog" />
    </extensions>

    <targets>
        <target name="syslog" type="Syslog">
            <messageCreation>
                <facility>Local7</facility>
            </messageCreation>
            <messageSend>
                <protocol>TCP</protocol>
                <tcp>
                    <server><host>.papertrailapp.com</server>
                    <port>XXXXX</port>
                    <useTls>true</useTls>
                </tcp>
            </messageSend>
        </target>
    </targets>

    <rules>
        <logger name="*" minLevel="Trace" appendTo="syslog"/>
    </rules>
</nlog>

Note that a facility value is required but has no meaningful impact. We recommend leaving the value Local7 as shown.

Use

Here’s how to log messages and exceptions.

Explicit logging

Papertrail is just another NLog target, so no code changes should be needed. If you aren’t yet using NLog, generate log messages with:

using NLog;

Logger logger = LogManager.GetLogger("MyClassName");

public class LogHelper {
    private NLog.Logger logger;

    public LogHelper() {
      logger = NLog.LogManager.GetCurrentClassLogger();
    }
}

Customize sender name or identifier

To change the appearance of the sender name or program/calling method name in Papertrail, see message creation element. The hostname and appName (or tag) values control the orange and blue values in Papertrail’s event viewer.

Log exceptions

Here’s an example for ASP.NET (see How to: Handle Application-Level Errors). Add this to Global.asax:

protected void Application_Error() {
  Exception lastException = Server.GetLastError();
  NLog.Logger logger = NLog.LogManager.GetCurrentClassLogger();
  logger.Fatal(lastException);
}

This exception handler could also act on exceptions in other ways, such as passing some or all to ELMAH or filtering them.

To show the full stack trace, add the following layout attribute to the target node:

layout="${message} ${exception:format=tostring}"

Older Versions

NLog.Targets.Syslog v2, now obsolete, used a different syntax. Here’s a sample NLog.config using the obsolete syntax:

<nlog xmlns="http://nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <extensions>
        <add assembly="NLog.Targets.Syslog" />
    </extensions>

    <targets>
        <target name="syslog" type="Syslog"
                syslogserver="<host>.papertrailapp.com" port="XXXXX"
                protocol="tcp" ssl="true" facility="Local7"/>
    </targets>

    <rules>
        <logger name="*" minLevel="Trace" appendTo="syslog"/>
    </rules>
</nlog>

This syntax isn’t recognized by current versions of NLog.Targets.Syslog, and shouldn’t be used. It’s documented here for historical purposes only.