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

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

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 semantics (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 benefits.

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 logfiles, based on its own configuration.

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: Returns true when both channels CW$chan1 and CW$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 duplicating messages to the same output when Carp::Datum is installed and activated. Emit the log entry held in CW$logstring, at priority CW$priority and through the specfied CW$channel name. A trailing \n is to be added if needed, but the CW$logstring should not already have one. The CW$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 CWerror, CWoutput or CWdebug for channel names. The CW$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 CW$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 CW$str variable and let the overloaded stringification perform its magic. Or you may return the CW$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 implementation 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() implementation, 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 inheriting 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): Log message to the given channel, at the specified priority/level, obtained through a call to map_pri().

logsay($str)

Log message to the CWoutput channel, at the CWnotice priority.

logwarn($str)

Log warning to the CWerror channel at the CWwarning priority. Log warning to the CWerror channel at the CWwarning priority, from the perspective of the caller. An additional CW$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 CWerror channel at the CWerror priority.

logdie($str)

Log fatal error to the CWerror channel at the CWcritical priority and then call die() with $str\n as argument. Log a fatal error, from the perspective of the caller. The error is logged to the CWerror channel at the CWcritical priority and then Carp::croak() is called with $str\n as argument. An additional CW$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 CWerror channel at the CWcritical priority and then Carp::confess() is called with $str\n as argument.

The following routines have a default implementation but may be redefined for specific drivers: This is a convenient wrapper that calls:

 write($channel, $self->priority($prio), $self->prefix_msg($str))

The following routine is frozen. There is no way in Perl to freeze a routine, i.e. to explicitely forbid any redefinition, 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 hardwired priority strings, as documented above. It derives a logging level from the CW$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 Records the CWprefix attribute, as well as the Carp CWpenalty (amount of extra stack frames to skip). Should be called in the constructor of all the drivers.

Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>, currently maintained by Mark Rogaski <mrogaski@cpan.org>.

  Copyright (C) 1999 Raphael Manfredi.
  Copyright (C) 2002 Mark Rogaski; all rights reserved.

See Log::Agent(3) or the README file included with the distribution for license information.

Log::Agent(3), Log::Agent::Driver::Default(3), Log::Agent::Driver::File(3), Log::Agent::Driver::Fork(3), Log::Agent::Driver::Silent(3), Log::Agent::Driver::Syslog(3), Carp::Datum(3).