Log::Agent::Driver(3pm)

1Agent::Driver(3)      User Contributed Perl Documentation     Agent::Driver(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

12       The Log::Agent::Driver class is the root class from which all
13       Log::Agent drivers inherit. It is a deferred class, meaning that it
14       cannot be instantiated directly. All the deferred routines need to be
15       implemented by its heirs to form a valid driver.
16
17       A deferred routine is a routine whose signature and semantics (pre and
18       post conditions, formally) are specified, but not implemented. It
19       allows specification of high-level processings in terms of them,
20       thereby factorizing common code in the ancestors without loosing
21       specialization benefits.
22

DRIVER LIST

24       The following drivers are currently fully implemented:
25
26       Log::Agent::Driver::Default
27           This is the default driver which remaps to simple print(), warn()
28           and die() Perl calls.
29
30       Log::Agent::Driver::File
31           This driver redirects logs to files. Each logging channel may go to
32           a dedicated file.
33
34       Log::Agent::Driver::Silent
35           Silence all the logxxx() routines.
36
37       Log::Agent::Driver::Syslog
38           This driver redirects logs to the syslogd(8) daemon, which will
39           then handle the dispatching to various logfiles, based on its own
40           configuration.
41

INTERFACE

43       You need not read this section if you're only using Log::Agent.
44       However, if you wish to implement another driver, then you should
45       probably read it a few times.
46
47       The following routines are deferred and therefore need to be defined by
48       the heir:
49
50       channel_eq($chan1, $chan2)
51           Returns true when both channels $chan1 and $chan2 send their output
52           to the same place.  The purpose is not to have a 100% accurate
53           comparison, which is almost impossible for the
54           Log::Agent::Driver::File driver, but to reasonably detect
55           similarities to avoid duplicating messages to the same output when
56           Carp::Datum is installed and activated.
57
58       write($channel, $priority, $logstring)
59           Emit the log entry held in $logstring, at priority $priority and
60           through the specfied $channel name. A trailing "\n" is to be added
61           if needed, but the $logstring should not already have one.
62
63           The $channel name is just a string, and it is up to the driver to
64           map that name to an output device using its own configuration
65           information. The generic logxxx() routines use only "error",
66           "output" or "debug" for channel names.
67
68           The $priority entry is assumed to have passed through the map_pri()
69           routine, which by default returns an empty string (only the
70           Log::Agent::Driver::Syslog driver needs a priority, for now).
71           Ignore if you don't need that, or redefine map_pri().
72
73           The $logstring may not really be a plain string. It can actually be
74           a Log::Agent::Message object with an overloaded stringification
75           routine, so the illusion should be complete.
76
77       make
78           This is the creation routine. Its signature varies for each driver,
79           naturally.
80
81       prefix_msg($str)
82           Prefix the log message string (a Log::Agent::Message object) with
83           driver-specific information (like the configured prefix, the PID of
84           the process, etc...).
85
86           Must return the prefixed string, either as a Log::Agent::Message
87           object or as a plain string. This means you may use normal string
88           operations on the $str variable and let the overloaded
89           stringification perform its magic. Or you may return the $str
90           parameter without modification.
91
92           There is no default implementation here because this is too driver-
93           specific to choose one good default. And I like making things
94           explicit sometimes.
95
96       The following routines are implemented in terms of write(), map_pri()
97       and prefix_msg(). The default implementation may need to be redefined
98       for performance or tuning reasons, but simply defining the deferred
99       routines above should bring a reasonable behaviour.
100
101       As an example, here is the default logsay() implementation, which uses
102       the emit() wrapper (see below):
103
104           sub logsay {
105               my $self = shift;
106               my ($str) = @_;
107               $self->emit('output', 'notice', $str);
108           }
109
110       Yes, we do show the gory details in a manpage, but inheriting from a
111       class is not for the faint of heart, and requires getting acquainted
112       with the implementation, most of the time.
113
114       The order is not alphabetical here but by increased level of severity
115       (as expected, anyway):
116
117       logwrite($channel, $priority, $level, $str)
118           Log message to the given channel, at the specified priority/level,
119           obtained through a call to map_pri().
120
121       logsay($str)
122           Log message to the "output" channel, at the "notice" priority.
123
124       logwarn($str)
125           Log warning to the "error" channel at the "warning" priority.
126
127       logxcarp($offset, $str)
128           Log warning to the "error" channel at the "warning" priority, from
129           the perspective of the caller.  An additional $offset stack frames
130           are skipped to find the caller (added to the hardwired fixed offset
131           imposed by the overall Log::Agent architecture).
132
133       logerr($str)
134           Log error to the "error" channel at the "error" priority.
135
136       logdie($str)
137           Log fatal error to the "error" channel at the "critical" priority
138           and then call die() with "$str\n" as argument.
139
140       logxcroak($offset, $str)
141           Log a fatal error, from the perspective of the caller. The error is
142           logged to the "error" channel at the "critical" priority and then
143           Carp::croak() is called with "$str\n" as argument.  An additional
144           $offset stack frames are skipped to find the caller (added to the
145           hardwired fixed offset imposed by the overall Log::Agent
146           architecture).
147
148       logconfess($str)
149           Confess a fatal error. The error is logged to the "error" channel
150           at the "critical" priority and then Carp::confess() is called with
151           "$str\n" as argument.
152
153       The following routines have a default implementation but may be
154       redefined for specific drivers:
155
156       emit($channel, $prio, $str)
157           This is a convenient wrapper that calls:
158
159            write($channel, $self->priority($prio), $self->prefix_msg($str))
160
161           using dynamic binding.
162
163       map_pri($priority, $level)
164           Converts a ("priority", level) tupple to a single priority token
165           suitable for emit(). By default, returns an empty string, which is
166           OK only when emit() does not care!
167
168       The following routine is frozen. There is no way in Perl to freeze a
169       routine, i.e. to explicitly forbid any redefinition, so this is an
170       informal notification:
171
172       priority($priority)
173           This routine returns the proper priority for emit() for each of the
174           following strings: "critical", "error", "warning" and "notice",
175           which are the hardwired priority strings, as documented above.
176
177           It derives a logging level from the $priority given and then
178           returns the result of:
179
180               map_pri($priority, $level);
181
182           Therefore, only map_pri() should be redefined.
183
184       Finally, the following initialization routine is provided: to record
185       the
186
187       _init($prefix, $penalty)
188           Records the "prefix" attribute, as well as the Carp "penalty"
189           (amount of extra stack frames to skip). Should be called in the
190           constructor of all the drivers.
191

AUTHORS

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

LICENSE

197         Copyright (C) 1999 Raphael Manfredi.
198         Copyright (C) 2002 Mark Rogaski; all rights reserved.
199
200       See Log::Agent(3) or the README file included with the distribution for
201       license information.
202