Jason W. May > Log-Channel-0.7 > Log::Channel

Download:
Log-Channel-0.7.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.7   Source  

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:

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>

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.

export
  $channel->export("subname");

Exports a logging subroutine into the calling package's namespace. Does the same thing as

  sub mylog { $channel->(@_) }

TO DO ^

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

syntax highlighting: