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\n");
mylog "this is the same as the above\n";
mylog sprintf ("Hello, %s\n", $user);

decorate Log::Channel "topic", "%d: (%t) %m\n";
mylog "this msg will be prefixed with 'timestamp: (topic) ' and end with newline";

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, but not stderr";

DESCRIPTION

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.

Yes, this is yet another logging module. Some differences between Log::Channel and other logging packages:

• Log::Channel does not define a strict classification of logging "levels" (debug, info, warn, crit, etc.). You may define a priority for a channel using set_priority(), but this is optional, and you can name your priority levels anything you want.

• Able to take over carp and croak events from other modules and route the output according to the Log::Channel configuration.

CONFIGURATION

If $ENV{LOG_CHANNEL_CONFIG} is set, then this is taken as the name of a file containing log configuration instructions which will be loaded the first time a Log::Channel is created. Config file syntax is XML:

<channel_config>
  <dispatch_config>/home/user/configs/log_disp.conf</dispatch_config>
  <channel>
    <topic>One</topic>
    <active />
    <decoration>%t %d: %m</decoration>
    <dispatch>stderr</dispatch>
  </channel>
  <channel>
    <topic>Two::Three</topic>
    <dispatch>Log::Dispatch</dispatch>
    <priority>crit</priority>
  </channel>
  <channel>
    <topic>Four</topic>
    <suppress />
    <dispatch>Log::Dispatch</dispatch>
    <priority>crit</priority>
  </channel>
</channel_config>

• If <dispatch> is omitted, logging defaults to STDERR.

• Logging defaults on for all topics without an explicit <active> or <suppress> directive. Omitted topics default on as well.

• To use Log::Dispatch for message dispatch, specify Log::Dispatch for <dispatch>. If a filename is specified in <dispatch_config>, then the Log::Dispatch module will be configured from that file (see Log::Dispatch::Config), otherwise Log::Dispatch must be initialized explicitly

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. This seems to me to be an appropriate use of closures.

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";

If omitted, topic will default to the name of the current package. A channel must have something for the topic, so the parameter is required for channels created in the main package.

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.

Recursively disables sub-topics.

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.

Recursively enables sub-topics.

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.

_carp

This is the function that is used to supersede the regular Carp::carp whenever Carp is commandeered on a module. Note that we still use Carp::shortmess to generate the actual text, so that if Carp verbose mode is specified, the full verbose text will go to the log channel.

_croak

Substitute for Carp::croak. Note that in this case the message will be output to two places - the channel, and STDERR (or whatever die() does).

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". The formatting options have been modeled on the log4j system. Options include:

  %t - channel topic name
  %d{format} - current timestamp; defaults to 'scalar localtime', but
	if an optional strftime format may be provided
  %F - filename where the log message is generated from
  %L - line number
  %p - priority string for this channel (see set_priority)
  %x - context string for this channel (see set_context)
  %m - log message text

Any other textual elements will be transmitted verbatim, eg. e.g. "%t: %m", "(%t) [%d] %m\n", etc.

Comment on performance: I haven't benchmarked the string formatting here. s///egx might not be the fastest way to do this.

set_context

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

Associate 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 for 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.

undispatch

undispatch Log::Channel "topic";

Restore a channel to its default destination (ie. STDERR).

Any existing dispatchers for this channel will be closed.

set_priority

# if we need to be able to associate priority (debug, info, emerg, etc.) # with each log message, this might be enough. It's by channel, though, # not per message. Since the overhead of creating a channel is minimal, # I prefer to associate one priority to all messages on the channel. # This also means that a module developer doesn't have to specify the # priority of a message - a user of the module can set a particular # channel to a different priority. # Valid priority values are not enforced here. These could potentially # vary between dispatchers. UNIX syslog specifies one set of priorities # (emerg, alert, crit, err, warning, notice, info, debug). # The log4j project specifies a smaller set (error, warn, info, debug, log). # Priority ranking is also controlled by the dispatcher, not the 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.

TO DO

• Syntax-checking on decorator format strings.

• Status reporting available for what log classes have been initiated, activation status, and where the messages are going.

• Ability to commandeer "print STDERR". To pick up other types of module logging - and capture die() messages.

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 Log::AndError