.NET: Configure with NLog

New Relic offers an NLog extension for New Relic Logs, allowing you link to your log data with related data across the rest of the New Relic platform. This document explains how to configure logs in context and start getting log data.

Compatibility and Requirements

To use New Relic logs in context with NLog, ensure your configuration meets the following requirements:

Access to logs in context requires a New Relic APM Pro subscription and​ enabling of distributed tracing. Before enabling distributed tracing, read the transition guide to learn about the effects on existing APM features and set-up recommendations.

Overview

NLog works by having Layouts (which guide what data is added to log events and in what format) and Targets (which control where logging data is sent.) The New Relic Logs NLog extension provides a NewRelicJsonLayout which formats a log event in the way required by the New Relic logging endpoint, and adds contextual information from the .NET agent when attached to your application. A target can then be configured to write logging data to an output folder, which can be monitored by a log forwarder to incrementally send log information to New Relic.

This diagram illustrates the flow of log messages through NLog:

Logs In Context - NLog
This diagram illustrates the flow of log messages through NLog, highlighting specific components of the New Relic NLog extension.

The above diagram highlights the main components of the NLog Logs-in-Context solution:

  • New Relic JSON Layout: The NewRelicJsonLayout adds contextual information from the .NET agent (using the API) to the log events generated by the application, and outputs log messages in the JSON format expected by New Relic. This contextual information, known as linking metadata, is used by New Relic to link log messages to the transactions and spans from which they were created.

  • File Target: A FileTarget defines a file on disk where log messages will be written. Adding the NewRelicJsonLayout to that target will cause the output to be formatted correctly for forwarding to New Relic.

  • New Relic Log Forwarder: The log forwarder is configured to send the log data from the FileTarget's output to New Relic. The example below uses the New Relic Fluentd log forwarder, however there are many other log forwarders that can be used. For more information, see Introduction to New Relic Logs.

For more information about logging with NLog, see the NLog Getting started documentation.

Configure logs in context with New Relic Logs

To configure New Relic logs in context with NLog:

  1. Enable New Relic Logs with a compatible log forwarding plugin.
  2. Install or update the .NET agent.
  3. Configure the NLog extension.
  4. Check for logging data.

Enable New Relic Logs

Confirm that you have New Relic Logs enabled, with a compatible log forwarding plugin installed to send your application logs to New Relic.

Install or update the .NET agent

Install or update to the most recent .NET agent version, and enable Distributed tracing.

Configure the NLog extension

To configure logs in context with the NLog extension, complete the following steps:

  1. Using the Visual Studio NuGet Package Manager, locate and install the NewRelic.LogEnrichers.NLog package.

  2. In your application code, update your logging configuration to add the NewRelicJsonLayout.

    The following code example enriches log events with New Relic linking metadata. In addition to the existing log files, it outputs new log files in a specific JSON format at C:\logs\NLogExample.log.json for consumption by the Log Forwarder:

      var loggerConfig = new LoggingConfiguration();
      
      var newRelicFileTarget = new FileTarget("NewRelicFileTarget");
      newRelicFileTarget.Layout = new NewRelicJsonLayout();
      newRelicFileTarget.FileName = "C:\logs\NLogExample.json";
      loggerConfig.AddTarget(newRelicFileTarget);
      loggerConfig.AddRuleForAllLevels("NewRelicFileTarget");
      LogManager.Configuration = loggerConfig;
      var logger = LogManager.GetLogger("Example");
    

    The above configuration results in new JSON files that are written to disk. Some of these configuration options may be useful in managing the amount of disk space used and/or the performance of the target.

    • archiveAboveSize
    • maxArchiveFiles
    • bufferSize
    • enableArchiveFileCompression
    • autoFlush
    • concurrentWrites

    Though not required, using the NLog AsyncWrapper Target may help improve the performance by performing formatting and output of log files on a different thread.​

  3. Once you have configured the NLog extension and updated your logging file, you can configure your extension to send data to New Relic Logs. See below for an example of this configuration using the Fluentd plugin for New Relic Logs:

    <!--NewRelicLoggingExample.conf-->
    <source> 
        @type tail 
        path C:\logs\NLogExample.log.json
        pos_file C:\logs\NLogExample.log.json.pos 
        tag logfile.*
     <parse> 
        @type json 
    </parse>
    </source>
    <match **> 
        @type newrelic 
        license_key <YOUR NEW_RELIC_LICENSE_KEY>
        base_uri https://log-api.newrelic.com/log/v1
    </match>

File Based Configuration

Configuration of the New Relic Logs NLog extension may also be accomplished with file based configuration providers.

.Config based configuration

The example code below creates a logger based on settings contained in an App.config file.

Instantiating Logger using .config file

var logger = LogManager.GetLogger("NewRelicLog");
logger.Info("Hello, New Relic!");
        

Sample App.config file

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog"/>
  </configSections>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" />
  </startup>
  <nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <extensions>
      <add assembly="NewRelic.LogEnrichers.NLog" />
    </extensions>
    <targets>
      <target name="NewRelicLogFile" xsi:type="File" fileName="C:/path/to/NewRelicLog.json">
        <layout xsi:type="newrelic-jsonlayout">
        </layout>
      </target>
    </targets>
    <rules>
      <logger name="NewRelicLog" minlevel="Info" writeTo="newRelicLogFile" />
    </rules>
  </nlog>
</configuration>

What's next?

Now that you've set up APM logs in context, here are some potential next steps:

For more help

Recommendations for learning more: