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.
- Microsoft .NET Framework 4.5+ or .NET Core 2.0+
- New Relic .NET agent 8.21+
- New Relic .NET agent API 8.21+
- NLog 4.5+
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:
The above diagram highlights the main components of the NLog Logs-in-Context solution:
New Relic JSON Layout: The
NewRelicJsonLayoutadds 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
FileTargetdefines a file on disk where log messages will be written. Adding the
NewRelicJsonLayoutto 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:
- Enable New Relic Logs with a compatible log forwarding plugin.
- Install or update the .NET agent.
- Configure the NLog extension.
- Check for logging data.
Enable New Relic Logs
Install or update the .NET agent
Configure the NLog extension
To configure logs in context with the NLog extension, complete the following steps:
In your application code, update your logging configuration to add the
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.jsonfor 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.
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.
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.
The example code below creates a logger based on settings contained in an App.config file.
Instantiating Logger using
var logger = LogManager.GetLogger("NewRelicLog"); logger.Info("Hello, New Relic!");
<?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>
Now that you've set up APM logs in context, here are some potential next steps:
- Explore your data using the Logs UI.
- Troubleshoot errors with distributed tracing, stack traces, application logs, and more.
- Query your data and create custom dashboards, charts, or alerts.