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