NAME

Log::MultiChannel - A full featured module for implementing 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

Please visit <http://paullapointe.org/MultiChannel> for complete documentation, examples, and more.

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. Three print handlers are included in the module itself: - logPrint - This is includes the date (only when it changes), time, channel, source filename, source line. E.g: ---- 2014 Oct 8 ---- 17.50.49 INF t/smokeTest.t-25 This is a test.

                  - logPrintVerbose - This is includes the date and time, channel, source filename, source line. E.g:
                  INF Wed Oct  8 23:42:25 2014 t/smokeTest.t-101 This is the logPrintVerbose handler.

                  - logPrintSimple - E.g:
                  INF This is the logPrintSimple handler.

startLoggingOnHandle ( name, fileHandle, printHandler )

name - Any arbitrary name for this log.

filehandle - The filehandle to log with.

printHandler - An optional special print handler for this file

stopLogging ( Log filename )

This will stop logging to the given log file.

closeLogs();

This will stop logging to ALL files (including any custom filehandles).

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, [Log filename] )

Unmaps all logs from a channel, or from a specific log file.

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 ( LogFilename )

Enables color on a specific log filename.

disableColor ( LogFilename )

Disables color on a specific log filename.

logStats ()

Returns a list with a count of all messages logged to each channel.

EXAMPLES

Example 1: The simplest use case:

 use Log::MultiChannel qw(Log);
 Log::MultiChannel::startLogging('myLogFile.log');
 Log('INF','This is an info message'); # This will default to the last log openned
 ...
 Log::MultiChannel::stopLogging('myLogFile.log');
 exit;

Example 2: Using multiple logs and channels:

 use Log::MultiChannel qw(Log);
 Log::MultiChannel::startLogging('myLogFile1.log');
 Log::MultiChannel::startLogging('myLogFile2.log');

 Log::MultiChannel::mapChannel('INF','myLogFile1.log'); # Put INF messages in myLogFile1.log
 Log::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');

 Log::MultiChannel::closeLogs(); # This will close ALL log files that are open
 exit;

Example 3: Tee-ing output to STDOUT and a log file:

 #!/usr/bin/perl
 # Example 8:  This will tee (copy) the output that is sent to a log file
 # to STDOUT, so it can be seen as the program runs.
 use strict;
 use warnings;
 use Log::MultiChannel qw(Log);

 Log::MultiChannel::startLogging('myLogFile1.log');
 Log::MultiChannel::startLoggingOnHandle('STDOUT',\*STDOUT);

 Log::MultiChannel::mapChannel('INF','myLogFile1.log','STDOUT'); # Put INF messages in myLogFile1.log

 Log('INF','This is an Error message for myLogFile1.log, that will also be printed on STDOUT');

 Log::MultiChannel::closeLogs(); # This will close ALL log files that are open
 exit;

More Examples are available in the distribution and at http://paullapointe.org/MultiChannel

cpanm Log::MultiChannel

perl -MCPAN -e shell
install Log::MultiChannel