Internal Logging

When Troubleshooting NLog logging issues, then it is a good idea to enable internal logging, which often helps to identify where the problem is. Internal log output can be sent to a file, console window or both.

Enabling internal logging using configuration file

When you configure NLog using Configuration File, you can enable internal logging by setting the following attribute on the <nlog> element:

• internalLogLevel="Off|Trace|Debug|Info|Warn|Error|Fatal" – determines internal log level. The higher the level, the less verbose the internal log output.

• internalLogFile="file.txt" - adding internalLogFile cause NLog to write its internal debugging messages to the specified file. This includes any exceptions that may be thrown during logging.

  Notice only basic layouts are supported, as the internal log needs to be as simple/stable as possible:

  • Environment Variables e.g. %appdata% or %HOME% (Introduced with NLog 4.6+).
  • ${currentdir} (Introduced with NLog 4.6+ but without options).
  • ${basedir} (Introduced with NLog 4.6+ but without options).
  • ${tempdir} (Introduced with NLog 4.6+ but without options).
  • ${processdir} (Introduced with NLog 4.7.1+ but without options).
  • ${commonApplicationDataDir}, ${userApplicationDataDir}, ${userLocalApplicationDataDir} (Introduced with NLog v5 but without options)

• internalLogToConsole="false|true" – sends internal logging messages to the console.

• internalLogToConsoleError="false|true" – sends internal logging messages to the console error output (stderr).

• internalLogToTrace="false|true" – sends internal logging messages to System.Diagnostics.Trace (introduced in NLog 4.3)

• internalLogIncludeTimestamp="false|true" - indicates whether timestamps should be included in the internal log output (NLog 4.3+)

Here is an example of a configuration file which enables internal logging to a file:

<nlog internalLogFile="c:\nlog-internal.txt" internalLogLevel="Trace">
   <targets>
      <!-- target configuration here -->
   </targets>
   <rules>
      <!-- log routing rules -->
   </rules>
</nlog>

If not getting internal logger output, then make sure the NLog.config file has Build Action set. See also Logging-troubleshooting. Alternative try to activate Internal Logging programmatically.

Enabling internal logging programmatically

Internal logging can be configured through code by setting the following properties on InternalLogger class:

• NLog.Common.InternalLogger.LogLevel - specifies internal logging level
• NLog.Common.InternalLogger.LogFile - specifies name of the log file (null will disable logging to a file)
• NLog.Common.InternalLogger.LogToConsole - enables or disables logging to the console
• NLog.Common.InternalLogger.LogToConsoleError - enables or disables logging to the console error stream
• NLog.Common.InternalLogger.LogWriter - specifies a TextWriter object to use for logging.
• NLog.Common.InternalLogger.LogToTrace - enables or disables logging to System.Diagnostics.Trace

  Introduced with NLog 4.3

• NLog.Common.InternalLogger.IncludeTimestamp - enables or disables whether timestamps should be included in the internal log output

  Introduced with NLog 4.3

• NLog.Common.InternalLogger.LogMessageReceived - Raises an event for every message received by InternalLogger

  Introduced with NLog 4.7

For best diagnostic output then make sure to enable NLog InternalLogger, before creating the first NLog Logger-object.

Here is an example of activating internal logging from code:

using NLog;
 
class Program
{
  static void Main()
  {
    // enable internal logging to the console
    NLog.Common.InternalLogger.LogToConsole = true;
 
    // enable internal logging to a file
    NLog.Common.InternalLogger.LogFile = "c:\\nlog-internal.txt"; // On Linux one can use "/home/nlog-internal.txt"

    // enable internal logging to a custom TextWriter
    NLog.Common.InternalLogger.LogWriter = new StringWriter(); //e.g. TextWriter writer = File.CreateText("C:\\perl.txt")

    // set internal log level
    NLog.Common.InternalLogger.LogLevel = NLog.LogLevel.Debug;

    // Perform test output, ensure first NLog Logger is created after InternalLogger is enabled.
    NLog.LogManager.GetLogger("Test").Info("Hello World");
  }
}

Enabling internal logging using environment variables

Before NLog 5.0 then environment variables and app.config settings would be automatically be applied on startup. But because of the startup overhead, then this has been disabled. Instead one now have to explicitly activate this behavior:

NLog.LogFactory.Setup().SetupInternalLogger(b => b.SetupFromEnvironmentVariables())

These are environment variables which control internal logging:

• NLOG_INTERNAL_LOG_LEVEL - sets the internal logging level. The available values are Trace, Debug, Info, Warn, Error or Fatal - the default is Info which should be appropriate for most cases, to get more detailed logging - set it to Debug or Trace.
• NLOG_INTERNAL_LOG_FILE - if this variable is found in the environment NLog will save internal log to the specified file. The file must be writable by the current user or it will not be created.
• NLOG_INTERNAL_LOG_TO_CONSOLE - if this variable is found in the environment, will outputs internal diagnostic information to the console
• NLOG_INTERNAL_LOG_TO_CONSOLE_ERROR - sets internalLogToConsoleError
• NLOG_INTERNAL_LOG_TO_TRACE - write internal log to System.Diagnostics.Trace (introduced in NLog 4.3)
• NLOG_INTERNAL_INCLUDE_TIMESTAMP - sets internalLogIncludeTimestamp (introduced in NLog 4.3)

Description of InternalLogger LogLevels

• LogLevel.Fatal - Just before application is going to crash.
• LogLevel.Error - Logging pipeline has failed, and logevents has been discarded.
• LogLevel.Warn - Detected invalid configuration but can recover. Detected connection lost but can recover.
• LogLevel.Info - Application lifetime events like logging configuration loaded, and shutting down logging engine.
• LogLevel.Debug - Reporting interesting events for detailed diagnostics. Having reflection issues when serializing logevents.
• LogLevel.Trace - Dumping verbose configuration details.