Often times we want to create a log of what steps a program
takes during run-time. Maybe our program works fine during a
debug build but crashes during a release build. Or maybe we
are developing on WinNT, but testing on Win98 without a development
environment on the Win98 machine. Since we can’t debug in these cases,
it would be nice to have a log of all the steps a program took before
This is a set of small projects (all working together) that can ease
creating a log of your program’s code path at run-time. Some features
- Easy installation / integration into any project (MFC, Non-MFC, Console
apps… all app types on Windows platforms.)
- No need to create message strings ahead of time… log functions accept
sprintf-style messages with variable length parameter lists.
include date/time, and code filename/line number in every message.
- Log to any file, or log straight to an MFC-based Log Window which opens
automagically on demand during run-time (see picture below).
- When using the Log Window, double-click on any log entry to jump
straight to that location in your code in MSDEV.
- Log Window will remain open when your app crashes/closes.
- Send different types of log messages (Debug, Release, Critical, Warning,
Normal, Trace, or add your own fairly easily) and then filter out any types of
messages you are not currently interested in without re-compiling.
- For each message, individually specify if the message is to be sent in either
debug, release, or both builds.
- For each message, individually specify if the message is to be sent to a file,
the Log Window, or both.
- Have multiple simultaneous logs, specifying output location for
each log individually (unique or shared file, and unique or shared Log Window,
- Append logs over multiple runs, or erase log before starting each new run.
- Completely remove all logging code from your project by simply defining
“_SS_LOG_INACTIVE” in the pre-compiler (NOTE: this removes only the global log
code, but not local logs if any are defined).
- SS_Log — This project includes the main logging classes, and can
be used without the other projects if you desire only to output your logs
to a file.
- SS_Log_Window — This project is the Log Window mentioned above,
which will automatically open during your program’s run-time and start
accepting logs from the SS_Log class.
- SS_Log_AddIn — This project is an MSDEV add-in that allows you to
double-click in the Log Window and have MSDEV jump to the associated line
of code in your project.
- SS_Log_Test — This project is simply an example of how to use the
SS_Log logging class. It uses a global log and 2 local logs, and
demonstrates a few of the features available.
- Utils — This project is a helper library. It contains only a
registry key class. Nothing too interesting here…
To install the projects, simply place the SS_Log_Window.exe and SS_Log_AddIn.dll
files in your %SYSTEMROOT% folder (ex. c:\winnt or c:\windows.). Don’t worry
about installing the add-in, as the first time you double-click on a log entry
in the SS_Log_Window.exe application, it will ask you if you want to install the
To integrate the log into your projects, follow 3 these steps:
- Place the SS_Log_Include.h and SS_Log.h files in your project’s include
- Add the SS_LogD.lib and UtilsD.lib to your debug project, and add SS_Log.lib
and Utils.lib to your release project. (Project->Settings->”Link” tab->
- #include “SS_Log_Include.h” in any file you would like to produce logs from
(do not include “SS_Log.h”).
- If you would like, you can add the SS_Log_Include.cpp, SS_Log.cpp, and
SS_RegistryKey.cpp files to your project instead of adding SS_Log.lib
and SS_LogD.lib as in step 2.
We will talk about 2 different log types: a) the global log, and b) local logs.
By #including “SS_Log_Include.h” in your project, a global log is created
for you (assuming you don’t have _SS_LOG_INACTIVE #defined). To use the global
log, all you have to do is enter a line as follows:
Log(“some message here, %d, %s”, nValue, szText, … );
This line will use the global log’s defaults, sending the message to the global
log with a “CRITICAL” level. The message goes to a Log Window in debug builds
and to the file “\SS_Log.log” during release builds by default. To override the
global log’s defaults, use these calls:
LogFilter( DWORD dwFilter );
LogRemoveFilters( DWORD dwFilter );
LogAddFilters( DWORD dwFilter );
LogFilename( TCHAR* szFilename );
LogWindowName( TCHAR* szWindowName );
Log( TCHAR* pMessage, … );
Log( DWORD dwFilter, TCHAR* pMessage, … );
When the above global log functions are used, all messages in all threads will
go to the same place (specified file, specified log window, or both). If you
want to send some messages to a different location, you may create multiple
simultaneous logs by defining “local logs” with the following code:
The following calls can be used for local logs:
myLog.Filter( DWORD dwFilter );
myLog.RemoveFilters( DWORD dwFilter );
myLog.AddFilters( DWORD dwFilter );
myLog.Filename( TCHAR* szFilename );
myLog.WindowName( TCHAR* szWindowName );
Log( SS_Log* pLog, TCHAR* pMessage, … );
Log( SS_Log* pLog, DWORD dwFilter, TCHAR* pMessage, … );
Note that if you don’t call the myLog.Filename(…) and
myLog.WindowName(…) functions, the local log will default
to the same window and file that the global log defaults to, and hence,
all messages from both logs will go to the same file/window. An example
for a complete local log would be:
myLog.WindowName(“My Local Log”);
Log( &myLog, “message to local log here, %d, %s”, nValue1, szText1 );
Log( “message to global log here, %s, %s”, szText2, szText3 );
The first Log(…) call above will send it’s message to the local log, while
the second one will send it’s message to the global log.
Filters are assigned to each log individually by default, but each log’s
default values can be overridden. In addition, every message sent to a log
can contain filters that overriding the log’s default filters. You may
then turn each filter type “on” and “off” by setting registry values (created
automatically by the SS_Log class). Any message with a filter type that is
turned off in the registry will not get sent to the log. This allows you to
turn on and off the filters without re-compiling.
(Registry key: “HKEY_CURRENT_USER\Software\SS_Log”. For all values, 1=on
and 0=off. You can also set the default log file here.)
You set log filters with the LogAddFilters(…),
LogFilter(…) global calls. The following
filters are pre-defined (the code includes instructions for adding your
own filter types):
Builds — These are handled automatically. You typically won’t need
to change the Builds filters unless you want messages to be sent *only* in
debug (or release) builds.
Outputs — These determine where the messages go during run-time.
By default, debug builds send messages to Log Windows, and release builds
send messages to a file (\SS_Log.log). You can have messages go to both
a window and a file simultaneously, or you can specify that messages always
go to the Log Window (or a file) as opposed being dependant on the build type.
Levels — You may specify one or more of these types (though I can’t
really think of why you’d specify more than one for any given message).
By default, all messages get the LOGTYPE_CRITICAL level. Note that unlike
the Builds and Outputs types, the Levels types combine. That is, if a log
or individual message has the LOGTYPE_WARNING and the LOGTYPE_TRACE types
specified, then BOTH types must be turned on in the registry for the message
to be sent.
While the LogAddFilters(…) and
LogRemoveFilters(…) calls work as you’d expect, the
LogFilter(…) call does not. The
LogFilter(…) does not “set” a log’s filter exactly
as specified in the parameter list. Instead, the function is “smart” and tries to figure
out what type of filter (Builds, Outputs, Levels, or some combination thereof) the user
is trying to set. For example, if the user calls
LogFilter( LOGTYPE_TRACE ), the function
will set only the Levels type, ignoring the Builds and Outputs types currently set in the
filter. Specifically, the function would remove the LOGTYPE_CRITICAL filter (which was
there by default), add the LOGTYPE_TRACE filter, and leave the Builds and Outputs types
alone. Note the difference if the user had called
LogAddFilters( LOGTYPE_TRACE ) instead,
where the function would have added the LOGTYPE_TRACE filter and kept the LOGTYPE_CRITICAL
For more examples and detail, see the example project “SS_Log_Test”.
A few problems that should be mentioned:
Log Windows and log files are both appended by default. This means that over
time, if a program is writing to some log file every time it runs, the file
could grow quite large. You should call LogEraseLog() at the beginning of every
program in order to ensure that your files remain small. I will consider adding
a set-able max file size if enough people request it.
#define-ing _SS_LOG_INACTIVE will remove any code that accesses the global log
from your project. However, it does not remove local logs. Maybe there are
situations where this behavior would actually be desirable, but the real reason
it behaves like that is because I couldn’t figure out how to do it otherwise.
Typically you will not need to call the three global log functions that have no
parameters (i.e. LogFilter(), LogFilename(), and LogWindowName()). These
functions return the associated value that the global log currently holds. Just
be aware that if you use these three functions in your code, they will cause a
compile error if _SS_LOG_INACTIVE is ever #defined.
Many file-writing functions (streams) will accept information to be written to a
file but wait to write out to the file until a “convenient” time, which ensures
fluid program flow. However, if the program crashes before the stream “flushes”
its contents to the file, some information may not get written. In the case of our
log messages, some final messages could get lost. This is a problem, so in order
to be completely sure that all log messages get written out to their destinations
before a program crash occurs, we tell the stream to flush after every message call.
This, however, is inefficient use of system resources, and can slow your program’s
execution substantially. I have no way around this problem. Furthermore, currently
the registry is called to determine which filters are on and off for every message
sent. This is also inefficient (and easily fix-able), but I’ve chosen to leave it
this way so that the filters can be turned on and off during run-time (no need to
restart the program). Just be aware of this fact: The SS_Log logging class can
significantly reduce your program’s performance (speed). The up-side is, assuming
that you use only the global log (no local logs) in your code, you should regain 100%
of your program’s efficiency by #declare-ing “_SS_LOG_INACTIVE” for the pre-compiler.