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       logcluck($str)
154           Emit a warning with a backtrace. The message is logged to the
155           "error" channel at the "warning" priority.
156
157       The following routines have a default implementation but may be
158       redefined for specific drivers:
159
160       emit($channel, $prio, $str)
161           This is a convenient wrapper that calls:
162
163            write($channel, $self->priority($prio), $self->prefix_msg($str))
164
165           using dynamic binding.
166
167       map_pri($priority, $level)
168           Converts a ("priority", level) tupple to a single priority token
169           suitable for emit(). By default, returns an empty string, which is
170           OK only when emit() does not care!
171
172       The following routine is frozen. There is no way in Perl to freeze a
173       routine, i.e. to explicitly forbid any redefinition, so this is an
174       informal notification:
175
176       priority($priority)
177           This routine returns the proper priority for emit() for each of the
178           following strings: "critical", "error", "warning" and "notice",
179           which are the hardwired priority strings, as documented above.
180
181           It derives a logging level from the $priority given and then
182           returns the result of:
183
184               map_pri($priority, $level);
185
186           Therefore, only map_pri() should be redefined.
187
188       Finally, the following initialization routine is provided: to record
189       the
190
191       _init($prefix, $penalty)
192           Records the "prefix" attribute, as well as the Carp "penalty"
193           (amount of extra stack frames to skip). Should be called in the
194           constructor of all the drivers.
195

AUTHORS

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

LICENSE

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

SEE ALSO

208       Log::Agent(3), Log::Agent::Driver::Default(3),
209       Log::Agent::Driver::File(3), Log::Agent::Driver::Fork(3),
210       Log::Agent::Driver::Silent(3), Log::Agent::Driver::Syslog(3),
211       Carp::Datum(3).
212
213
214
215perl v5.36.0                      2023-01-20                  Agent::Driver(3)
Impressum