agent::driver(3)

NAME

Log::Agent::Driver - ancestor class for all Log::Agent
drivers

SYNOPSIS

@Log::Agent::Driver::XXX::ISA = qw(Log::Agent::Driver);

DESCRIPTION

The Log::Agent::Driver class is the root class from which
all Log::Agent drivers inherit. It is a deferred class, meaning that it cannot be instantiated directly. All the
deferred routines need to be implemented by its heirs to
form a valid driver.

A deferred routine is a routine whose signature and seman tics (pre and post conditions, formally) are specified,
but not implemented. It allows specification of high-level
processings in terms of them, thereby factorizing common
code in the ancestors without loosing specialization bene
fits.

DRIVER LIST

The following drivers are currently fully implemented:

Log::Agent::Driver::Default: This is the default driver which remaps to simple
print(), warn() and die() Perl calls.
Log::Agent::Driver::File: This driver redirects logs to files. Each logging
channel may go to a dedicated file.
Log::Agent::Driver::Silent: Silence all the logxxx() routines.
Log::Agent::Driver::Syslog: This driver redirects logs to the syslogd(8) daemon, which will then handle the dispatching to various log
files, based on its own configuration.

INTERFACE

You need not read this section if you're only using
Log::Agent. However, if you wish to implement another driver, then you should probably read it a few times.

The following routines are deferred and therefore need to be defined by the heir:

channel_eq($chan1, $chan2): Returns true when both channels $chan1 and $chan2 send
their output to the same place. The purpose is not to
have a 100% accurate comparison, which is almost
impossible for the Log::Agent::Driver::File driver,
but to reasonably detect similarities to avoid dupli
cating messages to the same output when Carp::Datum is
installed and activated.
write($channel, $priority, $logstring): Emit the log entry held in $logstring, at priority
$priority and through the specfied $channel name. A
trailing "0 is to be added if needed, but the
$logstring should not already have one.; The $channel name is just a string, and it is up to
the driver to map that name to an output device using
its own configuration information. The generic
logxxx() routines use only "error", "output" or
"debug" for channel names.; The $priority entry is assumed to have passed through
the map_pri() routine, which by default returns an empty string (only the Log::Agent::Driver::Syslog
driver needs a priority, for now). Ignore if you don't
need that, or redefine map_pri().; The $logstring may not really be a plain string. It
can actually be a Log::Agent::Message object with an
overloaded stringification routine, so the illusion
should be complete.
make: This is the creation routine. Its signature varies for
each driver, naturally.
prefix_msg($str): Prefix the log message string (a Log::Agent::Message
object) with driver-specific information (like the
configured prefix, the PID of the process, etc...).; Must return the prefixed string, either as a
Log::Agent::Message object or as a plain string. This
means you may use normal string operations on the $str
variable and let the overloaded stringification per
form its magic. Or you may return the $str parameter
without modification.; There is no default implementation here because this
is too driver-specific to choose one good default. And
I like making things explicit sometimes.
The following routines are implemented in terms of
write(), map_pri() and prefix_msg(). The default implemen tation may need to be redefined for performance or tuning
reasons, but simply defining the deferred routines above
should bring a reasonable behaviour.
As an example, here is the default logsay() implementa tion, which uses the emit() wrapper (see below):: sub logsay {
my $self = shift;
my ($str) = @_;

$self->emit('output', 'notice', $str);; }
Yes, we do show the gory details in a manpage, but inher iting from a class is not for the faint of heart, and requires getting acquainted with the implementation, most of the time.
The order is not alphabetical here but by increased level of severity (as expected, anyway):
logwrite($channel, $priority, $level, $str): Log message to the given channel, at the specified
priority/level, obtained through a call to map_pri().
logsay($str): Log message to the "output" channel, at the "notice"
priority.
logwarn($str): Log warning to the "error" channel at the "warning"
priority.
logxcarp($offset, $str): Log warning to the "error" channel at the "warning"
priority, from the perspective of the caller. An
additional $offset stack frames are skipped to find
the caller (added to the hardwired fixed offset
imposed by the overall Log::Agent architecture).
logerr($str): Log error to the "error" channel at the "error" prior
ity.
logdie($str): Log fatal error to the "error" channel at the "criti
cal" priority and then call die() with "$str0 as
argument.
logxcroak($offset, $str): Log a fatal error, from the perspective of the caller.
The error is logged to the "error" channel at the
"critical" priority and then Carp::croak() is called with "$str0 as argument. An additional $offset
stack frames are skipped to find the caller (added to
the hardwired fixed offset imposed by the overall
Log::Agent architecture).
logconfess($str): Confess a fatal error. The error is logged to the
"error" channel at the "critical" priority and then
Carp::confess() is called with "$str0 as argument.
The following routines have a default implementation but may be redefined for specific drivers:
emit($channel, $prio, $str): This is a convenient wrapper that calls:

write($channel, $self->priority($prio), $self->pre

fix_msg($str)); using dynamic binding.
map_pri($priority, $level): Converts a ("priority", level) tupple to a single pri
ority token suitable for emit(). By default, returns
an empty string, which is OK only when emit() does not care!
The following routine is frozen. There is no way in Perl
to freeze a routine, i.e. to explicitely forbid any redef
inition, so this is an informal notification:
priority($priority): This routine returns the proper priority for emit()
for each of the following strings: "critical",
"error", "warning" and "notice", which are the hard
wired priority strings, as documented above.; It derives a logging level from the $priority given
and then returns the result of:

map_pri($priority, $level);
Therefore, only map_pri() should be redefined.
Finally, the following initialization routine is provided: to record the
_init($prefix, $penalty): Records the "prefix" attribute, as well as the Carp
"penalty" (amount of extra stack frames to skip).
Should be called in the constructor of all the
drivers.

AUTHOR

Raphael Manfredi <Raphael_Manfredi@pobox.com>

docs.sk

comprehensive documentation repository

See also