$Log: _welcome.txt,v $
Revision 1.0 2002-01-05 13:01:52-06 wsenn
Initial revision
$Id: _welcome.txt,v 1.0 2002-01-05 13:01:52-06 wsenn Exp wsenn $
Copyright (c) 2002 Will Senn
All rights reserved.
The full text of the Copyright and Permission Notice
is at bottom of this document.
========================================================================
Hi,
This article is intended to explain my motivation for creating a CLog
and CLogAppender class heirarchy.
I was introduced to *log4j from the Apache group by a friend. log4j is
part of the Jakarta SubProject - check it out.
http://jakarta.apache.org/log4j/docs/index.html
I was told that my current method for logging was substandard. I did
not beleive this of course, however, 5 minutes with log4j and I knew
it for truth! So, logically I went looking for Log4C++. Well they have
2 *Log4CPP projects listed.
http://sourceforge.net/projects/log4cpp/
http://log4cplus.sourceforge.net/
I checked them out and although they have merits, they were
too complicated for me. Thus were born my CLog and CLogAppender
classes.
I wanted to create a class with a really simple syntax. You
know something along the lines of:
CLog myCLog(source);
myCLog.writeLog(debuglevel, message);
Well as it turns out, it's not quite that easy, but it's close.
I know that log4j didn't think up the idea for severities and
thresholds (my vernacular, not theirs), but they sure sold me
on the idea.
The bottom line is:
A message with severity x is written to a log appender
with threshold y if x >= y.
severity and threshold values:
debug < info < warn < error < fatal
description:
debug: detailed programmatic informational messages
used as an aid in troubleshooting problems by
programmers
info: brief informative messages to use as an aid in
troubleshooting problems by production support
and programmers
warn: messages intended to notify help desk, production
support and programmers of possible issues with
respect to the running application
error: messages that detail a programmatic error,
these are typically messages intended for help
desk, production support, programmers and
occasionally users.
fatal: most severe messages that are programmatic
violations that will usually result in application
failure. These messages are intended for help
desk, production support, programmers and possibly
users.
What all this gobbledegook means is that you, as the programmer
has the duty to create meaningful messages and assign them the
proper severity. If you are good at this, then, you will reap
the benefit of incredibly informative logs with a standardized
look and feel. Making everyones life easier.
The details:
This set of classes consists of a number of files, I will lay them
out here for your perusal with a brief description.
First, the headers:
Utility.h contains a number of useful helper data structures
Log.h the main CLog Class Definition
LogAppender.h the abstract CLogAppender Class Definition that the
specific log appenders are derived from
ConsoleLogAppender.h the specific Console log appender class definition
FileLogAppender.h the specific File log appender class definition
EventLogAppender.h the specific Event log appender class definition
Next, the implementation files:
Utility.cpp contains a number of useful helper data structures
Log.cpp the main CLog Class Implementation
LogAppender.cpp the abstract CLogAppender Class Implementation
ConsoleLogAppender.cpp the specific Console log appender class implementation
FileLogAppender.cpp the specific File log appender class implementation
EventLogAppender.cpp the specific Event log appender class implementation
And, for fun the test application:
LogDriver.cpp the simple test application that will use the log and
log appender class to write to the console, test.dat,
and the event log.
More detail:
In order to use the logging classes here is a description of what is required.
- You will need to create a cpp file that will 'drive' the logger - in my case
this was LogDriver.cpp.
- include log.h, this will bring in the needed definitions, etc.
#include "../inc/log.h"
- instantiate an instance of the CLog class, this will be the 'source' of log
messages
CLog myLog("LogDriver");
- instantiate and add as many log appenders as you like
CConsoleLogAppender * pConsoleLogAppender = new CConsoleLogAppender(nsCLog::info);
CFileLogAppender * pFileLogAppender = new CFileLogAppender(nsCLog::warning, "test.dat");
CEventLogAppender * pEventLogAppender = new CEventLogAppender(nsCLog::debug);
myLog.addAppender(pConsoleLogAppender);
myLog.addAppender(pFileLogAppender);
myLog.addAppender(pEventLogAppender);
- write to the log(s) througout your codebase
myLog.writeLog(nsCLog::warning, "This is my test log message");
What you will have done is this:
Created a logger that's source is "LogDriver"
Created a log appender for console messages
Created a log appender to write to test.dat
Created a log appender to write to the event log
Told the LogDriver logger about the 3 appenders
Written to the various logs
What the messages will look like is:
01052002_124658 | LogDriver | warning | This is my test log message
The event log message is going to appear a little differently, but basically
the same. Because I'm lazy it will probably be like:
The entry in Event Viewer:
Type Error
Date 1/5/2002
Time 12:46:58 PM
Source LogDriver
Category (1500)
Event 0
User N/A
Computer Your Computer Name
The message (double click the entry):
The description for Event ID ( 0 ) in Source ( LogDriver ) cannot be
found. The local computer may not have the necessary registry
information or message DLL files to display messages from a remote
computer. The following information is part of the event:
01052002_124658 | LogDriver | warning | This is my test log message.
Let me know what you think - preferably constructive if not positive,
I'm not asking for flames :)
Read the _todo.txt document before sending me - it oughta do X!
messages.
That's it really.
Contact Information:
Will Senn
2219 Lilac Circle
McKinney, TX 75071
wsenn@bigfoot.com
-----------------------------------------------------------------------
COPYRIGHT AND PERMISSION NOTICE
Copyright (c) 2002 Will Senn
All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, and/or sell copies of the Software, and to permit persons
to whom the Software is furnished to do so, provided that the above
copyright notice(s) and this permission notice appear in all copies of
the Software and that both the above copyright notice(s) and this
permission notice appear in supporting documentation.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Except as contained in this notice, the name of a copyright holder
shall not be used in advertising or otherwise to promote the sale, use
or other dealings in this Software without prior written authorization
of the copyright holder.