NAME
Logging::MultiChannel - A full featured module for implimenting log messages on multiple channels to multiple targets.
FEATURES
Features: - Multi-channel logging, with the ablity to enable or disable channels dynamically.
- Channels can be mapped to multiple Log files for duplication of messages.
- Channels can be optional color coded. Each log file can enable or disable the color feature.
- Channels can be selectively enabled for messages from specific modules.
Advanced features:
- Channels can be mapped to your own handles (Eg. socket) for writting to things beside log files.
- Each Log file can use its own print function, or default to the one provided.
Features for limiting and cycling logs:
- Log files can optionally be limited to a specific line count.
- Old copies of log files can optional be perserved or overwritten.
- Old log files can be optionally moved to a different directory.
Coming soon:
- Thread safety.
AUTHOR
Paul LaPointe - <http://paullapointe.org>
LICENSE
This program is dual licensed under the (Perl) Artistic License 2.0, and the Lesser GNU General Public License 3.0 (LGPL).
BUGS
Please report any bugs or feature requests to bugs@paullapointe.org
METHODS
Log ( channel, message, additional args... )
Channel can be any string. Message is the log message to write. Additional args can be passed in for use by a custom log handler.
startLogging( filename, preserve, limit, oldDir, printHandler )
filename - the fully qualified filename for the log
preserve - An option to retain old copies of the log before overwritting (0 or 1).
limit - An optional limit on the number of lines that can be written before cycling this log
oldDir - Move old log files to this fully qualified directory when overwritting
printHandler - An optional special print handler for this file
startLoggingOnHandle ( filename, printHandler )
filename - the fully qualified filename for the log
printHandler - An optional special print handler for this file
stopLogging ( Log filename )
This will stop logging to the given log file.
mapChannel ( Channel, Log filename1, Log filename2, ... )
This will map a channel to one or more log files by their name.
mapChannelToLog ( Channel, Log filename )
Maps a channel to this specific log name.
unmapChannel ( Channel )
Unmaps all logs from a channel.
enableChannel ( Channel )
Enables log messages from a specific channel.
disableChannel ( Channel )
Disables log messages from a specific channel.
enableChannelForModule ( Channel, Module )
Enables log messages from a specific module for the given channel. disableChannelForModule ( Channel, Module )
Disabled log messages from a specific module for the given channel (overriden by channel control).
assignColorCode ( Channel , Ascii color code )
Assigns a (typically) ASCII color code to a specific channel
enableColor ( Channel )
Enables color on a specific channel.
disableColor ( Channel )
Disables color on a specific channel.
logStats ()
Returns a list with a count of all messages logged to each channel.
EXAMPLES
Example 1: The simplest use case:
use Logging::MultiChannel qw(Log);
Logging::MultiChannel::startLogging('myLogFile.log');
Log('INF','This is an info message'); # This will default to the last log openned
...
Logging::MultiChannel::stopLogging('myLogFile.log');
exit;Example 2: Using multiple logs and channels:
use Logging::MultiChannel qw(Log);
Logging::MultiChannel::startLogging('myLogFile1.log');
Logging::MultiChannel::startLogging('myLogFile2.log');
Logging::MultiChannel::mapChannel('INF','myLogFile1.log'); # Put INF messages in myLogFile1.log
Logging::MultiChannel::mapChannel('ERR','myLogFile2.log'); # Put ERR messages in myLogFile2.log
Log('INF','This is an Error message for myLogFile1.log');
Log('ERR','This is an info message for myLogFile2.log');
Logging::MultiChannel::closeLogs(); # This will close ALL log files that are open
exit;
Example 3: Copying a channel to two log files
use Logging::MultiChannel qw(Log);
Logging::MultiChannel::startLogging('myLogFile1.log');
Logging::MultiChannel::startLogging('myLogFile2.log');
Logging::MultiChannel::mapChannel('INF','myLogFile1.log'); # Put INF messages in myLogFile1.log
Logging::MultiChannel::mapChannel('ERR','myLogFile1.log'); # Put ERR messages in myLogFile1.log
Logging::MultiChannel::mapChannel('ERR','myLogFile2.log'); # ALSO put ERR messages in myLogFile2.log
Log('INF','This is an info message for myLogFile1.log');
Log('ERR','This is an Error message for myLogFile1.log & myLogFile2.log');
Logging::MultiChannel::closeLogs(); # This will close ALL log files that are open
exit;Example 4: Providing your own filehandle # Note if you do this, the log cycle functions are # disabled. use strict; use Logging::MultiChannel qw(Log); my $filename='example4.log'; open (my $fh,">$filename") or die("Unable to open $filename");
Logging::MultiChannel::startLoggingOnHandle($fh);
Log('INF','This is an info message for myLogFile1.log');
Logging::MultiChannel::closeLogs(); # This will close ALL log files that are open
exit;
Example 5: Providing your own filehandle and using a custom print handler
Example 4 can be modified to specify a special print handler:
Logging::MultiChannel::startLoggingOnHandle($fh,\&eventLogger);The call back function will be passed these args:
# 0 - Epoch Time
# 1 - Local Time as a string
# 2 - Real Filehandle
# 3 - The Log object
# 4 - source module
# 5 - source filename
# 6 - source line #
# 7 - desired color
# 8 - channel name
# 9 - message
# 10 - extra field 1
# 11 - extra field 2
# 12 - extra field 3
# etc...Here's an example of a call back function:
sub eventLogger {
my $fh=$_[2];
my $fhObject=$_[3];
# Print the line content
print $fh "$_[0],";
for (my $i=8;$i<13;$i++) {
print $fh "\"$_[$i]\",";
}
print $fh "\"$_[1]\"\n";
}Example 6: Using log stats to see how many messages were printed on each channel:
# Print out # of messages printed on each channel
Log('INF','Log Stats:');
foreach my $line (Logging::MultiChannel::logStats()) { Log('INF',$line); }