Logging Destinations

Each call to a logging method like Logger.Info() or Logger.Debug() can send its output to any combination of four possible destinations.

Destination Controlled by Logger Property Initial Value in Root Logger
File FileTraceLevel TraceLevel.Info
Console (i.e. command window) ConsoleTraceLevel TraceLevel.Off
System.Diagnostics.Trace.!WriteLine DebugTraceLevel TraceLevel.Off
Event log EventLogTraceLevel TraceLevel.Off


The initial values of these properties for all Loggers you create is Undefined. Therefore, your Loggers will inherit the Root trace levels unless you explicitly overide them, which is not usually done. Most users just set the Root levels and let all other Loggers inherit them. A typical scenario would be for an application to set the following levels.

Logger.Root.FileTraceLevel =     TraceLevel.Debug;
Logger.Root.EventLogTraceLevel = TraceLevel.Error; 

This causes any log message with a level of Debug or lower to go to the file, and those with a level of Error or lower to also go to the event log.

The trace levels for any logger can be set in code or via XML (see XML Configuration).

Each of the four destinations has its own set of static properties and methods to configure/control it. These are described in the following sections.

File Logging

TracerX supports one output file per process. The log file is circular, which means that when it grows to the maximum size you specify, it wraps and new output replaces old output. A designated amount of the initial output is preserved so it is not lost when the log wraps. The file uses a proprietary binary format and is viewed with the TracerX.exe viewer application.

Logger.FileLogging is a static class with properties and methods applicable to the output file. For example, to set the directory where the file is created you might code something like this.

Logger.FileLogging.Directory = "C:\\Logs";

This table describes the relevant properties and methods of Logger.FileLogging. The properties should be set before calling Logger.FileLogging.Open() to open the output file. They can be set programatically or via XML (see XML Configuration).

Property Description
Directory The directory where the file is located. The default value is whatever Environment.GetFolderPath(System.Environment.SpecialFolder.LocalApplicationData) returns. On XP, this is typically "C:\Documents and Settings\<user name>\Local Settings\Application Data". Environment variables are expanded when this is set. Environment variables are mainly useful when setting the directory via XML. %LOCALAPPDATA% (not a real environment variable) is expanded to the current user's local (i.e. non-roaming) application data directory. This is the same as the default, but you can use this to specify a subdirectory such as %LOCALAPPDATA%\Idera\Logs. %EXEDIR% (not a real environment variable) is expanded to the directory of the executable, regardless of the Current Directory.
Name The name of the log file within the Directory. The default is based on the running executable name. The extension is always coerced to ".tx1" so the viewer can be associated with that extension.This property can be set programatically but not via XML. I feel the end user should not be able to change the name of the log file created by a given executable.
MaxSizeMb The approximate maximum size of the output log file in megabytes (1 Mb = 220 bytes). Values over 4095 are coerced to 4095. Default = 10.
Archives How many old versions of the output log file to keep (max of 9). Default = 3. When the log file is opened, the oldest version is deleted.
CircularStartSizeKb Circular logging will start when the log file reaches this size in Kilobytes, unless already started. All logging before this point is preserved when the log wraps. Set this to 0 to disable this feature.
CircularStartDelaySeconds Circular logging will start when the log file has been opened this many seconds, unless already started. All logging before this point is preserved when the log wraps. Set this to 0 to disable this feature.
Open() This method opens the log file using the current values of the above properties. This always opens a new file. There is no way to append to an existing file. If there is an existing file, it is "archived" by renaming it with 1, 2, etc.


When the file is opened, some "standard data" about the current execution environment is automatically logged for you through a Logger called StandardData. Here's a sample of that output, including the TraceLevel and Text columns.

Info,    EntryAssembly.Location = C:\PerforceRoot\projects\TracerX\V8InProgress\Tester\bin\Debug\Tester.exe
Info,    EntryAssembly.FullName = Tester, Version=1.2.0.0, Culture=neutral, PublicKeyToken=null
Info,    FileVersionInfo.FileVersion = 2.1.0.0
Info,    FileVersionInfo.ProductVersion = 2.1.0.0
Info,    Environment.OSVersion = Microsoft Windows NT 5.1.2600 Service Pack 2
Info,    Environment.CurrentDirectory = C:\PerforceRoot\projects\TracerX\V8InProgress\Tester\bin\Debug
Info,    Environment.UserInteractive = True
Debug,   Environment.CommandLine = "C:\PerforceRoot\projects\TracerX\V8InProgress\Tester\bin\Debug\Tester.vshost.exe"
Verbose, Environment.MachineName = P840
Verbose, Environment.UserDomainName = P840
Verbose, Environment.UserName = markl 


The purpose of the StandardData logger is to give you control of the above output. For example, the Verbose output might be considered sensitive, so you can suppress it by coding the following before opening the file.

Logger.StandardData.FileTraceLevel = TraceLevel.Debug;

You can suppress all of the above output by setting FileTraceLevel to TraceLevel.Off. This can also be done in XML.

Console Logging

You can see "live" logging from your application by directing it to the console (i.e. command window). Logger.ConsoleLogging is a static class used to configure this output. It only has one property, FormatString, that specifies which fields are written to the console by all Loggers where Logger.ConsoleTraceLevel is greater than or equal to the log statement's trace level. It can be set programatically or in XML.

FormatString uses the following substitution parameters (these also apply to debug logging and event logging).

Parameter Type Description
{line} uint Line number
{level} TracerX.TraceLevel Trace level
{logger} string Logger name
{thnum} uint Thread number
{thname} string Thread name
{time} DateTime Time stamp
{method} string Method name
{ind} string Indentation
{msg} string Message text


Format specifiers that are appropriate for the type of each substitution parameter can be included in the FormatString. For example, the default value of FormatString is "{time:HH:mm:ss.fff} {level} {thname} {logger}+{method} {ind}{msg}".

Debug Logging

This refers to output passed to System.Diagnostics.Trace.WriteLine(). This feature originally used Debug.WriteLine() (hence the term "debug logging"), but then I realized it might be useful in release builds (Debug.WriteLine() only functions in debug builds). This output appears in the Output window of Visual Studio when your app is executed in the debugger. There are also utilities that can intercept and display this output without Visual Studio.

Logger.DebugLogging is a static class used to configure this output. It only has one property, FormatString, that specifies which fields are passed to Trace.WriteLine() by all Loggers where Logger.DebugTraceLevel is greater than or equal to the log statement's trace level. The substitution parameters and default value are the same as Logger.ConsoleLogging.FormatString.

Event Logging

Logging can be sent to the event log of your choice, but this should probably be used sparingly compared to the other destinations. For example, you should probably restrict it to certain loggers and/or trace levels. Logger.EventLogging is a static class used to configure this feature. It has the following properties.

Property Description
EventLog Specifies the event log that TracerX uses for all event logging. The initial value is set to new EventLog("Application", ".", "TracerX - " + Path.GetFileNameWithoutExtension(Application.ExecutablePath)). Refer to the MSDN documentation for the EventLog class. This property cannot be set in XML. It should be set programaticaly before parsing the XML or opening the log file since those actions can generate internal events that also go to the event log specified by this property.
FormatString Specifies which fields are written to the event log by all Loggers where Logger.EventLogTraceLevel is greater than or equal to the log statement's level. See the Logger.ConsoleLogging topic for substitution parameters. The default value is "{time:HH:mm:ss.fff} {thname} {logger}+{method} {msg}".
MaxInternalEventNumber This applies to TracerX's internal events, not your log messages. It specifies the highest internal event number TracerX is allowed to log. More on this later. Default = 200.
InternalEventOffset A number added to TracerX's internal event numbers just before they are logged. Use this to prevent the event numbers logged by TracerX from conflicting with your application's event numbers. Default = 1000.
EventIdMap A Dictionary<TraceLevel, ushort> that specifies what event ID number to use for each TraceLevel value. This cannot be set in XML.
EventTypeMap A Dictionary<TraceLevel, EventLogEntryType> that specifies what EventLogEntryType to use for each TraceLevel value. This cannot be set in XML.


In addition to your log messages, TracerX can log internal events of its own, especially if it encounters errors opening the output file or parsing the XML configuration. The internal event numbers fall into three ranges.
  • 1-100 = Error events, such as failing to open the log file due to insufficient permission.
  • 101-200 = Warning events, such as the log file reaching the maximum size without engaging circular logging.
  • 201-300 = Info events, such as the log file being opened successfully.

If you want to suppress all of these events, you can set Logger.EventLogging.MaxInternalEventNumber to 0. However, the recommended (and default) value is 200 so errors and warnings will be logged if they occur.

Last edited Dec 14, 2007 at 7:23 PM by MarkLTX, version 4

Comments

No comments yet.