Use our NLog extension to link to your log data with related data across the rest of the New Relic platform. Read on to learn how to configure logs in context and enrich your log data.
Compatibility and requirements
To use New Relic logs in context with NLog, ensure your configuration meets the following requirements:
- 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+
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 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:
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 theNewRelicJsonLayout
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 log management.
For more information about logging with NLog, see the NLog Getting started documentation.
Configure logs in context with log management
To configure logs in context with NLog:
- Enable log management with a compatible log forwarding plugin.
- Install or update the .NET agent.
- Configure the NLog extension.
- Check for logging data.
Enable log management
Confirm that you have log management 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:
Using the Visual Studio NuGet Package Manager, locate and install the
NewRelic.LogEnrichers.NLog
package.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");Caution
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
Important
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. See below for an example of this configuration using the Fluentd plugin for New Relic's log management:
<!--NewRelicLoggingExample.conf--><source>@type tailpath C:\logs\NLogExample.log.jsonpos_file C:\logs\NLogExample.log.json.postag logfile.*<parse>@type json</parse></source><match **>@type newreliclicense_key <YOUR NEW_RELIC_LICENSE_KEY>base_uri https://log-api.newrelic.com/log/v1</match>
File-based configuration
Configuration of the New Relic NLog extension may also be accomplished with file based configuration providers.
What's next?
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 or alerts.
For more help
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's data security and licenses documentation.