/ 
Log-Channel-0.3
River stage zero No dependents
/ Log::Channel

NAME

Log::Channel - yet another logging package

SYNOPSIS

use Log::Channel qw(msg);
my $log = new Log::Channel("topic");
$log->("this is a log message, by default going to stderr");
msg "this is the same as the above";
msg sprintf ("Hello, %s", $user);

decorate Log::Channel "topic", "timestamp: (topic) ";
msg "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'
                                              ));
msg "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.

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.

msg
use Log::Channel qw(msg);
msg "this is my message";

Built-in logging directive. When exported, this sends the message to the logging channel that was most recently created in the current package. If no channel is explicitly created, msg will deliver to stderr.

This is not recommended when your package uses more than one channel.

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.

TEST SUITE

Sorry, don't have one yet.

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