NLog
The default logging provider used by Anthology is NLog. NLog allows you to set up log targets, levels, rules, layouts, etc. through configuration.
Configure Logging
To configure logging, you need to modify the nlog.config
file contained within the application’s executing directory. For web applications, this file exists alongside the web.config
file.
<?xml version="1.0" encoding="utf-8"?> <nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <targets> <target name="file" xsi:type="File" layout="${longdate} ${threadid:padding=3} ${level:padding=-30} ${logger:padding=-30} ${message} ${exception:format=tostring}" fileName="${basedir}logs/${shortdate}.txt" keepFileOpen="true" /> <target name="console" xsi:type="ColoredConsole" layout="${date:format=HH\:MM\:ss} ${threadid:padding=3} ${logger:padding=-30} ${message}" /> </targets> <rules> <logger name="*" minLevel="Error" writeTo="file" /> </rules> </nlog>
Above is an example of a config file that is configured with two targets: file and console. The logging rules define which target is executed based on level (Trace
, Debug
, Information
, Warning
, Error
, and Fatal
). The configuration above logs to a subfolder off the base directory whenever an Error
or Fatal
level is logged by the application. To log verbose diagnostic information, you can change the minLevel
to Trace
, which will log all levels of diagnostic information.
For additional information regarding the configuration file, see https://github.com/nlog/NLog/wiki/Configuration-file.
For supported NLog targets, see https://github.com/nlog/NLog/wiki/Targets.
Write Logs
Three public types are associated with the logging framework:
- ILoggerFactory
- ILogger
- LoggerExtensions (extensions methods for ILogger)
There are two ways to enable logging in your class. The preferred way is to receive an ILogger interface as a constructor dependency. The IoC container ensures that this dependency is wired for you.
If your class is a legacy class that does not support DI, you can use the ServiceLocator to retrieve an ILoggerFactory to create the logger.
Add Log Messages to Classes
Once you have a logger in a class, it is important to add the relevant LOG messages to it that will help us all in debugging and understanding how this class is behaving.
Log Non-Exception Messages
Trace Messages
Use these messages to trace which lines of source code are being executed; they will log what is going on with the code.
Usage: _log.Trace(“Your message.”)
Debug Messages
Use these messages to output the contents or values of variables or properties during the execution of source code; they will log the important values of objects that may affect how the code will execute.
Usage: _log.Debug(“Your message. variable1={0}.”, variable1)
Info Messages
Use these messages to log information that may be useful to know about the normal operation of the application (such as environment variables, paths, etc.).
Usage: _log.Info(“Your message. variable1={0}.”, variable1)
Warning Messages
Use these messages to log messages that we are not sure are acceptable or to track variable/property values that may be close to being out of the acceptable range.
Usage: _log.Warn(“Your message. variable1={0}.”, variable1)
Error Messages
Use these messages to log any exceptions we have that are not being handled. This is typically used in the CATCH of a TRY/CATCH block.
Usage: See Log Exception Messages.
Fatal Messages
Use these messages to log special conditions that indicate that something went terribly wrong in the execution of the code.
Usage: See Log Exception Messages.
Log Exception Messages
To properly log an exception, you should follow one of the patterns shown below. This will allow you to capture the full exception details and also include (if necessary) any other values that may be important for debugging.
Scenario 1: Log a custom message, a variable value, and an exception
Result log message:
[Your message (if any)]. [Variable Name] = 'abc'. System.FormatException: The string was not recognized as a valid DateTime. There is an unknown word starting at index 0. at System.DateTime.Parse(String s) at Cmc.UI.Web.EcoSysW3C.------() in \DEV\DEV\Cmc\UI\Web\Cmc.UI.Web.EcoSysW3C\------.cs:line xx
Scenario 2: Log a variable value and an exception
Result log message:
[Variable Name] = 'abc'. System.FormatException: The string was not recognized as a valid DateTime. There is an unknown word starting at index 0. at System.DateTime.Parse(String s) at Cmc.UI.Web.EcoSysW3C.------() in \DEV\DEV\Cmc\UI\Web\Cmc.UI.Web.EcoSysW3C\------.cs:line xx
Scenario 3: Log only an exception
Result log message:
System.FormatException: The string was not recognized as a valid DateTime. There is an unknown word starting at index 0. at System.DateTime.Parse(String s) at Cmc.UI.Web.EcoSysW3C.------() in \DEV\DEV\Cmc\UI\Web\Cmc.UI.Web.EcoSysW3C\------.cs:line xx
Note: You must always inject the exception to the string message using {0}!
If you log an exception as shown below, it will fail to include the exception in the log message. See result of this message below:
Result log message:
message
Read Log Messages to Debug or Troubleshoot
There are three different ways to see your log messages when you wish to debug or troubleshoot an issue:
- Access the SQL server and get values from the LOGS table (if they are being logged to the DB)
- Access the local log files being saved in (webroot)/LOGS
- Use a real-time viewer
You can download the FREE LOG viewer from: http://www.legitlog.com/Products/LegitLogViewer.
Once you install it, you can use it to:
- Read the log text file, or
- View messages in real-time as they are added to the logger.
To enable real-time logging, follow these steps:
- Select Logs >> Live Capture Log.
- Select Start capture global.
You should now start seeing any log messages as they are added into the logger.
For additional information, see the NLog website: http://nlog-project.org.