1Agent::Driver(3) User Contributed Perl Documentation Agent::Driver(3)
2
6 Log::Agent::Driver - ancestor class for all Log::Agent drivers
7
9 @Log::Agent::Driver::XXX::ISA = qw(Log::Agent::Driver);
10
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 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
24 The following drivers are currently fully implemented:
25 Log::Agent::Driver::Default
27 This is the default driver which remaps to simple print(), warn()
28 and die() Perl calls.
29 Log::Agent::Driver::File
31 This driver redirects logs to files. Each logging channel may go to
32 a dedicated file.
33 Log::Agent::Driver::Silent
35 Silence all the logxxx() routines.
36 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
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 The following routines are deferred and therefore need to be defined by
48 the heir:
49 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 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 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 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 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 make
78 This is the creation routine. Its signature varies for each driver,
79 naturally.
80 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 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 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 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 As an example, here is the default logsay() implementation, which uses
102 the emit() wrapper (see below):
103 sub logsay {
105 my $self = shift;
106 my ($str) = @_;
107 $self->emit('output', 'notice', $str);
108 }
109 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 The order is not alphabetical here but by increased level of severity
115 (as expected, anyway):
116 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 logsay($str)
122 Log message to the "output" channel, at the "notice" priority.
123 logwarn($str)
125 Log warning to the "error" channel at the "warning" priority.
126 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 logerr($str)
134 Log error to the "error" channel at the "error" priority.
135 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 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 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 logcluck($str)
154 Emit a warning with a backtrace. The message is logged to the
155 "error" channel at the "warning" priority.
156 The following routines have a default implementation but may be
158 redefined for specific drivers:
159 emit($channel, $prio, $str)
161 This is a convenient wrapper that calls:
162 write($channel, $self->priority($prio), $self->prefix_msg($str))
164 using dynamic binding.
166 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 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 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 It derives a logging level from the $priority given and then
182 returns the result of:
183 map_pri($priority, $level);
185 Therefore, only map_pri() should be redefined.
187 Finally, the following initialization routine is provided: to record
189 the
190 _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
197 Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>,
198 currently maintained by Mark Rogaski <mrogaski@cpan.org>.
199
201 Copyright (C) 1999 Raphael Manfredi.
202 Copyright (C) 2002 Mark Rogaski; all rights reserved.
203 See Log::Agent(3) or the README file included with the distribution for
205 license information.
206
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).
212perl v5.36.0 2023-01-20 Agent::Driver(3)