Adapting your .NET Application's NLog logging to include Loupe

To convert your .NET application's existing use of the NLog logging framework to include Loupe you need:

• The Loupe Agent redistributable files.
• The Gibraltar.Agent.NLog2.dll assembly or the class file GibraltarTarget.cs for your version of NLog. (Found in the SDK\NLog\2.0 directory of Loupe)
• Your NLog configuration file (app.config, NLog.config, NLog.dll.nlog, etc), or source code if programmatic configuration is used.

Adding the Gibraltar.Agent.NLog2 Assembly to your Solution

Using the Distributed Assembly

If you reference the NLog.dll distributed with Loupe or the same version retrieved directly from the NLog Project site it then you may add this distribution's Gibraltar.Agent.NLog2.dll binary to your references rather than include the GibraltarTarget class in your project.  You can also get this assembly from NuGet.  This is the simplest way to use the Loupe NLog Target because we've already created a strong named assembly linked to the distribution of the Loupe Agent included in this release and NLog 2.

Building your Own Assembly

If you reference the distributed NLog.dll distributed with this release then you may add this distribution's Gibraltar.Agent.NLog2.dll binary to your references rather than include the GibraltarTarget class in your project. If you instead wish to rebuild Gibraltar.Agent.NLog2 from source code:

1. Add the GibraltarTarget.cs class to your own application from the SDK\NLog\2.0 folder.
2. Check that the Reference to the NLog library points to where you have it on your system or build process. If needed, either add the correct reference and delete the broken one, or else edit the project file directly and correct the path.
3. Confirm that the Reference to the Gibraltar.Agent library is valid, or correct it. If you installed Loupe in the default location it should be in one of these locations:
   • C:\Program Files\Gibraltar Software\Loupe\SDK\Redist\Gibraltar.Agent.dll
   • C:\Program Files (x86)\Gibraltar Software\Loupe\SDK\Redist\Gibraltar.Agent.dll (if your computer is running a 64-bit operating system)
4. Build this project and either add this project to your application as a dependency or copy the assembly it builds to wherever you keep external library dependencies.
5. Also include the Gibraltar.Agent.dll in your distribution and installation in the directory for your application executable.

Adjust your configuration to use the GibraltarTarget

Loupe is intended as a top-level catch-all to collect all of your logging in one managed place so you can filter as needed dynamically during analysis. To do this, modify the extensions, targets, and rules sections of your NLog configuration as follows:

• Include Gibraltar.Agent.NLog as an extension:
  <add assembly="Gibraltar.Agent.NLog2" />
• Add the GibraltarTarget as a target:
  <target name="Gibraltar" xsi:type="Gibraltar" />
  (or drop the "xsi:" prefix--just type="Gibraltar"--if not using explicit namespaces)
• Add a rule sending all logging to the GibraltarTarget:
  <logger name="*" minlevel="Trace" writeTo="Gibraltar" />
  (we recommend that it be the first rule—or at least before any "final" rules—to avoid missing any).

If you find minlevel="Trace" too voluminous for normal collection, the minlevel may be set at "Debug" instead. Also, see the example App.config file in the Gibraltar.Agent.NLog project, and consult the NLog configuration documentation as needed.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog"/>
  </configSections>
  <!-- In an NLog.config file only this "nlog" section is needed as the root.  App.config also needs the rest. -->
  <nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <extensions>
      <add assembly="Gibraltar.Agent.NLog2" /> <!--Contains GibraltarTarget class marked as "Gibraltar" target type-->
    </extensions>
    <targets>
      <target name="Gibraltar" xsi:type="Gibraltar" /> <!--Define a named target using the "Gibraltar" target type-->
    </targets>
    <rules>
      <logger name="*" minlevel="Trace" writeTo="Gibraltar" /> <!--Send all logging to the "Gibraltar" named target-->
    </rules>
  </nlog>
</configuration>

In the above example no Loupe Agent configuration information was included.  You can add in any necessary Loupe Agent configuration manually or via NuGet.

Usage Tips

Make sure to log something to Loupe early in your application (e.g. before Application.Run) to load the Loupe Agent and initialize its automatic monitoring features. For example:

mainLogger.LogInfo("Entering application.");

You can also take either of the approaches listed in Developer's Guide for WinForms - Ensuring the Loupe Agent gets Loaded.

Ensuring your Application Exits

Because NLog doesn't have any way of signaling to its logging targets that the log system is shutting down you should follow the instructions in Developer's Guide - .NET Framework - Ensuring Your Application Exits to ensure that your application exits.  As an example, the following line placed just before the routine exit of your application will ensure it exits quickly:

Gibraltar.Agent.Log.EndSession("Application Exiting Normally");