1NAME
2 Luka - Exception handling and reporting framework
3
4SYNOPSIS
5 use Error qw(:try);
6 use Luka;
7
8 try {
9
10 $ftp->login("someuser", "somepass") ||
11 throw Luka::Exception::External
12 ( error => $ftp->message . $@, id => "login",
13 context => "FTP error: couldn't login", severity => 3,
14 args => "user=someuser,pass=somepass" );
15
16 } catch Luka::Exception with {
17
18 my $e = shift;
19 $e->report;
20 return 17;
21
22 } catch Error with {
23
24 my $e = shift;
25 $e->report;
26 return 18;
27
28 };
29
30DESCRIPTION
31 Luka is an exception handling and reporting framework. It's useful to
32 look at it as an event handling framework.
33
34 It comes from operational understanding of networks.
35
36 Scenario that Luka is addressing is following: on a network with
37 multiple hosts running multiple applications, it is very difficult to
38 track operational status of all the functionality that those
39 applications and hosts are meant to deliver. In order to make it easier,
40 we decided to specify the error handling and reporting data model that
41 each component delivering functionality has to conform to. What is a
42 component? In most cases, it is a script, often run from cronjob, in
43 some cases it is a class in an application. In all cases, a component
44 has to successfully complete a task on which functionality of an
45 application, or entire network, relies on.
46
47 It is common practice that programmers choose their way of handling
48 errors and reporting. Luka is an attempt to standardize that process.
49 Its primary goal is to make it easier for smaller number of people to
50 keep larger number of applications and networks running.
51
52 Policy on script error handling that Luka suggests:
53
54 NO ERROR CODES are used, instead exceptions are thrown
55 Already a common practice, especially in applications/components
56 that are not small.
57
58 Standard set of error english names is established (network connection
59 error)
60 As opposed to each network library, for example, having it's own way
61 to report connection error.
62
63 Page for each component (script/class) documenting relevant details
64 Already a common practice. Luka suggests that link to page
65 describing all possible errors, along with dependencies and
66 schedules (for components that run regularly), should exist. It is
67 part of the Luka event data model.
68
69 EACH time an error occurs following MUST be attempted:
70
71 1. Capture defined data set
72 2. Log summary to to system log
73 3. attempt delivery to end points
74
75 Example config
76 [global]
77 debug=0
78 single_char_error_code=E
79 single_char_success_code=I
80 doc_base=http://localhost/
81 email_domain=lists.mydomain.org
82 syslogopt=pid,nowait
83 syslogfacility=daemon
84 expected_ip=10.1.8
85
86 [myscript.pl]
87 on_success=Task completed
88 doc=LukaTests
89 about=this library does something useful
90 from=root@localhost
91 cc=me@mydomain.org
92 nomail=0
93
94 Example of error report
95 On an error caught, in syslog:
96
97 Feb 26 15:34:39 localhost myscript.pl[1298]: Luka initiating...
98 Feb 26 15:34:39 localhost myscript.pl[1298]: Error at line 20: Net::FTP: Bad hostname 'bla.org' at myscript.pl line 324.
99 Feb 26 15:34:39 localhost myscript.pl[1298]: Error report sent to myscript.pl@lists.mydomain.org,me@mydomain.org
100
101 Email headers:
102
103 From: root@localhost
104 To: myscript.pl@lists.mydomain.org
105 Cc: me@mydomain.org
106 Subject: [galeb][2006-2-26T15:34:42][E] Net::FTP: Bad hostname 'bla.org'
107
108 Event (used verbatim in email body):
109
110 this library does something useful
111
112 http://localhost/LukaTests#ftp_object_creation
113
114 host=galeb
115 hosterr=
116 ipaddr=10.1.8.18
117 time=2006-2-26T15:34:42
118 script=myscript.pl
119 path=/home/toni/dev/cvs/perl/modules/luka
120 line=245
121 pid=1298
122 severity=3
123 context=FTP error: couldn't create object
124 args=ftp.false
125 id=ftp_object_creation
126 error=Net::FTP: Bad hostname 'bla.org'
127
128 Trace begun at myscript.pl line 245
129 main::__ANON__ at /usr/local/share/perl/5.8.7/Error.pm line 372
130 eval {...} at /usr/local/share/perl/5.8.7/Error.pm line 371
131 Error::subs::try at myscript.pl line 255
132 main::ftp_luka_catch at myscript.pl line 123
133 main::__ANON__ at /usr/local/share/perl/5.8.7/Test/Exception.pm line 281
134 eval {...} at /usr/local/share/perl/5.8.7/Test/Exception.pm line 281
135 Test::Exception::lives_and at myscript.pl line 124
136
137 Example of success report
138 On a captured report, in syslog:
139
140 Feb 26 15:34:22 localhost myscript.pl[1273]: Luka initiating...
141 Feb 26 15:34:22 localhost myscript.pl[1273]: Success report sent to myscript.pl@lists.mydomain.org,me@mydomain.org
142
143 Email headers:
144
145 From: root@localhost
146 To: myscript.pl@lists.mydomain.org
147 Cc: me@mydomain.org
148 Subject: [galeb][2006-2-26T15:34:22][I] Task completed
149
150 Event (used verbatim in email body):
151
152 this library does something useful
153
154 http://localhost/LukaTests
155
156 host=galeb
157 hosterr=
158 ipaddr=10.1.8.18
159 time=2006-2-26T15:34:22
160 script=myscript.pl
161 pid=1273
162
163LUKA EVENT DATA MODEL
164 Structure
165 ABOUT COMPONENT
166 \n
167 DOC
168 \n
169 attribute=value
170 attribute=value
171 attribute=value
172 attribute=attribute=value,attribute=value
173 attribute=value
174 \n
175 \n
176 STACKTRACE
177
178 Fields
179 ABOUT COMPONENT Comes from config file component section.
180
181 DOC Location of the documentation. Can be URL, or some other
182 protocol address. Can be specific to the error reported, or
183 component general. Comes from config file component section.
184
185 host - Name of the host where the event originates from. Collected.
186
187 hosterr - Name of the services that Luka couldn't use as expected on
188 the host. Collected. The only possible value is, at the moment,
189 *syslogd*.
190
191 ipaddr - IP address of the host. Collected. When multiple IPs
192 present (most cases), regular expression matching one from the
193 configuration file field "expected_ip" will be chosen.
194
195 time - Timestamp, conforming to RFC3339 "Date and Time on the
196 Internet: Timestamps", see <http://www.ietf.org/rfc/rfc3339.txt>.
197 Example: "2006-2-26T15:34:42". Constructed out of host time.
198
199 script - Name of the component that generated event. Collected.
200
201 pid - Process ID of the component that generated the event.
202 Collected from the host.
203
204 path - Path to the component that generated event. Collected. Error
205 event only.
206
207 line - Line number where event generation occurred. Collected. Error
208 event only. Error event only.
209
210 severity - Severity level of the event (ambiguous, see TODO
211 section). Supplied by the programmer at the location of event
212 creation. Error event only.
213
214 context - Descriptive text, context of the event. Specific to the
215 functionality that components performs from the user perspective,
216 rather than from the strictly technical perspective of programming
217 libraries. Supplied by the programmer at the location of event
218 creation. Error event only.
219
220 args - Arguments relevant for the event generated (passed to the
221 function, object). Supplied by the programmer at the location of
222 event creation. Error event only.
223
224 id - ID of the event. Supplied by the programmer at the location of
225 event creation. Matches the documentation for the component. Error
226 event only.
227
228 error - Technical text of the error. Supplied by the programmer at
229 the location of event creation. Supplement to the "context" field,
230 from the technical perspective, can contain error text returned by
231 used programming library. Error event only.
232
233METHODS
234 report
235 Luka report to syslog what happens by default.
236
237 Aug 26 11:27:49 localhost myscript.pl[1038]: Error at line 46: Net::FTP: Bad hostname
238 'ftp.bla.bla' at myscript.pl line 80.
239
240 Aug 26 11:27:49 localhost myscript.pl[1038]: Error report sent to myscript.pl@lists.mydomain.org
241
242 report_success( $message )
243 If the $message is not supplied, value of the field "on_success" from
244 the component section of Luka configuration file will be used.
245
246DIAGNOSTICS
247 "Luka system not functional for '%s' script. Couldn't read its section
248 '%s' in config file '%s'"
249 Throws Luka::Exception::Program exception. Luka can not deliver
250 event if section for given script is missing in given config.
251 Sections are by default named by the script name.
252
253 "Luka system disabled. Couldn't read its config file '%s': %s"
254 Throws Luka::Exception::Program exception. Luka can not do anything
255 if its config file is missing or can not be parsed. However, if
256 syslogd is running, it will place a warning in syslog:
257
258 Feb 26 12:26:59 localhost Luka::Conf[30438]: Luka system disabled. Couldn't read its config file 'bla.txt':
259 Failed to open bla.txt: No such file or directory at lib/Luka/Conf.pm line 63
260
261 "Couldn't report by email to:%s;cc:%s;from:%s"
262 Throws Luka::Exception::External. If MTA is not running, or if Luka
263 can not connect to it, stdout will receive:
264
265 ERROR: Can't connect to localhost:25
266 Couldn't report by email to:test@localhost;cc:toni@localhost;from:root@localhost
267
268 In the syslog, warning will be:
269
270 Feb 26 13:42:08 localhost myscript.pl[3071]: Couldn't report by email: to: myscript.pl@lists.mydomain.org,
271 cc: me@mydomain.org, from: root@localhost
272
273 Feb 26 13:42:08 localhost myscript.pl[3071]: Mail system reported: ERROR: Can't connect to localhost:25
274
275CONFIGURATION
276 global section
277 Single section, applies to the host on which Luka runs.
278
279 [global]
280 debug=0
281 single_char_error_code=E
282 single_char_success_code=I
283 doc_base=http://localhost/
284 email_domain=lists.mydomain.org
285 syslogopt=pid,nowait
286 syslogfacility=daemon
287 expected_ip=10.1.8
288
289 Fields:
290
291 debug - Turns debugging mode on when set to 1.
292
293 single_char_error_code - Delivery field. Single character error
294 code. Default is "E". In email delivery, part of header SUBJECT
295 field.
296
297 single_char_success_code - Delivery field. Single character success
298 code. Default is "I". In email delivery, part of header SUBJECT
299 field.
300
301 doc_base - Event field. Base part of the DOC field in the event data
302 model.
303
304 email_domain Delivery field. Email. Domain part of the header TO
305 field.
306
307 syslogopt *$logopt* options passed to Sys::Syslog's *openlog*
308 function
309
310 syslogfacility *$facility* option passed to Sys::Syslog's *openlog*
311 function
312
313 expected_ip Event field. See above IPADDR field in the event data
314 model. Luka discovers IPs on the host. Since multiple IPs are
315 present in most cases, regular expression matching one from this
316 configuration file field *expected_ip* will be selected. This would
317 be a drawback on a host with many interfaces, and solution with
318 fixed IP would be a lot more efficient in that case.
319
320 component sections
321 One or more sections, applies to components programmed to use Luka.
322
323 [myscript.pl]
324 on_success=Task completed
325 doc=LukaTests
326 about=this library does something useful
327 from=root@localhost
328 cc=me@mydomain.org
329 nomail=0
330
331 Fields:
332
333 on_success - Delivery field. In email delivery, part of header
334 SUBJECT field.
335
336 doc - Event field. Component part of the DOC field in the event data
337 model.
338
339 about - Event field. See above COMPONENT field in the event data
340 model.
341
342 from - Delivery field. Email. Header FROM field.
343
344 cc - Delivery field. Email. Header CC field.
345
346 nomail - If set to 1, event will not be delivered via email.
347
348DEPENDENCIES
349 * Error - implementation of try/catch syntax
350
351 * Exception::Class - easy definition of hierarchy of exception classes
352
353 * Config::IniFiles - config file handling
354
355 * Sys::Syslog - writing to syslog
356
357 * Sys::Hostname - determining hostname
358
359 * Sys::Hostname::Long - determining hostname
360
361 * Mail::SendEasy - sending reports by email
362
363 * Class::Std - inside/out classes builder
364
365INCOMPATIBILITIES
366 Mod-perl, due to use of Class::Std. I wasn't aware of Class::Std
367 limitations at the time of writing Luka. There are other implementations
368 of inside-out classes on CPAN that should be used as replacements in of
369 next releases of Luka. At the moment, best candidate seems to be
370 Object::InsideOut.
371
372BUGS AND LIMITATIONS
373 Please report any bugs or feature requests to "bug-luka@rt.cpan.org", or
374 through the web interface at <http://rt.cpan.org>.
375
376TODO
377 mod-perl compatibility
378 Migration from Class::Std to Object::InsideOut, or some other
379 inside-out class.
380
381 severity definitions
382 Severity needs defining, according to appropriate existing standard.
383
384 date-time format, timezone missing
385 Timezone needs adding to the date-time (RFC 3339) format.
386
387 report delivery mechanism abstraction
388 Reporting is also event delivery, and event delivery can be done in
389 many ways. Currently, email is hardcoded as a delivery mechanism.
390 Instead, reporting delivery has to be configurable. It could be done
391 via dynamic loading (from a value in the config) of class
392 implementing desired mechanism.
393
394 reporting to syslog config setting
395 It is default now that Luka method "report" uses syslog for short
396 reporting. It should be made optional, in global, and script,
397 setting. Global config setting should be default; individual script
398 setting should override it.
399
400 event delivery on missing component section
401 When a section for component is missing in the config file,
402 exception is thrown (see DIAGNOSTICS above). Instead, event should
403 still be delivered, as long as relevant details about the
404 destination of delivery are in the global part of the Luka
405 configuration file.
406
407 improve documentation
408 Documentation needs careful re-reading and improving. Any comments
409 on this especially appreciated.
410
411ACKNOWLEDGEMENTS
412 Ideas for underlining premises of Luka came out of discussions with Bill
413 Hulley.
414
415AUTHOR
416 Toni Prug <toni@irational.org>
417
418COPYRIGHT
419 Copyright (c) 2006. Toni Prug. All rights reserved.
420
421 This program is free software; you can redistribute it and/or modify it
422 under the terms of the GNU General Public License as published by the
423 Free Software Foundation; either version 2 of the License, or (at your
424 option) any later version.
425
426 This program is distributed in the hope that it will be useful, but
427 WITHOUT ANY WARRANTY; without even the implied warranty of
428 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
429 Public License for more details.
430
431 You should have received a copy of the GNU General Public License along
432 with this program; if not, write to the Free Software Foundation, Inc.,
433 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
434
435 See <http://www.gnu.org/licenses/gpl.html>
436
437