NAME

Log::Channel - yet another logging package

SYNOPSIS

use Log::Channel;
my $log = new Log::Channel("topic");
sub mylog { $log->(@_) }

$log->("this is a log message, by default going to stderr");
mylog "this is the same as the above";
mylog sprintf ("Hello, %s", $user);

decorate Log::Channel "topic", "timestamp: (topic) ";
mylog "this message will be prefixed with 'timestamp: (topic) '";

use Log::Dispatch::File;
Log::Channel::dispatch("topic",
                       new Log::Dispatch::File(name => 'file1',
                                               min_level => 'info',
                                               filename  => 'foo.log',
                                               mode      => 'append'
                                              ));
mylog "now the message, with decorations, will go to the file";

DESCRIPTION

This is alpha software.

Allows for code to specify channels for delivery of logging messages, and for users of the code to control the delivery and formatting of the messages.

METHODS

new

my $log_coderef = new Log::Channel "topic";

Define a new channel for logging messages. All new logs default to output to stderr. Specifying a dispatcher (see dispatch method below) will override this behavior. Logs default active, but can be disabled.

Note that the object returned from the constructor is a coderef, not the usual hashref. The channel will remember the topic specified when it was created, prepended by the name of the current package.

Suggested usage is

sub logme { $log_coderef->(@_) }

So that you can write logging entries like

logme "This is the message\n";

disable

disable Log::Channel "topic";

No further log messages will be transmitted on this topic. Any dispatchers configured for the channel will not be closed.

A channel can be disabled before it is created.

When topic is a package name, recursively disables any sub-packages of that package.

enable

enable Log::Channel "topic";

Restore transmission of log messages for this topic. Any dispatchers configured for the channel will start receiving the new messages.

A channel can be enabled before it is created.

When topic is a package name, recursively enables any sub-packages of that package.

commandeer

Log::Channel::commandeer ([$package, $package...]);

Take over delivery of 'carp' log messages for specified packages. If no packages are specified, all currently-loaded packages will be commandeered.

When a package is taken over in this fashion, messages generated via 'carp', 'croak' and so on will be delivered according to the active dispatch instructions. Remember, Log::Channel defaults all message delivery to OFF.

Note that the Carp verbose setting should still work correctly.

decorate

decorate Log::Channel "topic", "decoration-string";

Specify the prefix elements that will be included in each message logged to the channel identified by "topic". Options include:

topic - channel topic name, prefixed with package::

timestamp - current timestamp ('scalar localtime')

The decorator-string can contain these elements with other punctuation, e.g. "topic: ", "(topic) [timestamp] ", etc.

Comment on performance: It would probably be quicker to parse the string here and construct a list of items that will be processed in _construct() rather than doing string replacements.

decorate

set_context Log::Channel "topic", $context;

Associated some information (a string) with a log channel, specified by topic. This string will be included in log messages if the 'context' decoration is activated.

This is intended when messages should include reference info that changes from call to call, such as a current session id, user id, transaction code, etc.

dispatch

dispatch Log::Channel "topic", (new Log::Dispatch::Xyz(...),...);

Map a logging channel to one or more Log::Dispatch dispatchers.

Any existing dispatchers for this channel will be closed.

Dispatch instructions can be specified for a channel that has not been created.

The only requirement for the dispatcher object is that it supports a 'log' method. Every configured dispatcher on a channel will receive all messages on that channel.

status

status Log::Channel;

Return a blob of information describing the state of all the configured logging channels, including suppression state, decorations, and dispatchers.

Currently does nothing.

AUTHOR

Jason W. May <jmay@pobox.com>

COPYRIGHT

Copyright (C) 2001,2002 Jason W. May. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Log::Dispatch and Log::Dispatch::Config
http://jakarta.apache.org/log4j

And many other logging modules: Log::Agent CGI::Log Log::Common Log::ErrLogger Log::Info Log::LogLite Log::Topics Log::TraceMessages Pat::Logger POE::Component::Logger Tie::Log Tie::Syslog Logfile::Rotate Net::Peep::Log Devel::TraceFuncs Devel::TraceMethods