3 =head1 NAME $RCSfile: Logger.pm,v $
5 Object oriented interface to handling logfiles
13 Andrew DeFaria <Andrew@ClearSCM.com>
21 Fri Mar 12 10:17:44 PST 2004
25 $Date: 2012/01/06 22:00:09 $
31 Perl module for consistent creation and writing to logfiles
39 $log->msg ("This message might appear on STDOUT");
40 $log->log ("Stuff this message into the logfile");
42 if (!$log->logcmd ("ls /non-existant-dir")) {
43 $log->err ("Unable to proceed", 1);
47 to => "Andrew\@ClearSCM.com",
48 subject => "Logger test",
49 heading => "Results of Logging"
54 Logger creates a log object that provides easy methods to log messages, errors,
55 commands, etc. to log files. Logfiles can be created as being transient in that
56 they will automatically disappear (unless you call the err method). You can
57 capture the output of commands into log files and even have them autoamatically
58 timestamped. Finally you can have logfiles automatically mailed.
62 The following routines are exported:
84 my ($error_color, $warning_color, $command_color, $highlight_color, $normal) = "";
89 # Extract relative path and basename from script name.
90 $me = $FindBin::Script;
92 # Remove .pl for Perl scripts that have that extension
97 my ($class, %parms) = @_;
103 Construct a new Logger object. The following OO style arguments are
108 =for html <blockquote>
114 Name of the leaf portion of the log file. Default is the name of the
115 script with ".log" appended to the logfile name. So if the calling
116 script was called "getdb" the default log file would be called
117 "getdb.log" (Default: Script name).
121 Path to create the logfile in (Default: Current working directory)
125 One of "temp" or "perm". Logfiles that are of disposition temp will be
126 deleted when the process ends unless any calls have been made to the
127 err method (Default: perm)
131 If set to 0 then no timestamps will be used. If set to 1 then all
132 lines logged will be preceeded with a timestamp (Default: 0)
136 If defined the logfile will be appended to (Default: Overwrite)
140 If defined an alternate extension to use for the log file (e.g. log.html)
144 =for html </blockquote>
148 =for html <blockquote>
156 =for html </blockquote>
162 my $name = $parms{name} ? $parms{name} : $me;
163 my $path = $parms{path} ? $parms{path} : $cwd;
164 my $disposition = $parms{disposition} ? $parms{disposition} : 'perm';
165 my $timestamped = $parms{timestamped} ? $parms{timestamped} : 'FALSE';
166 my $append = $parms{append} ? '>>' : '>';
169 if ($parms{extension}) {
170 $name .= ".$parms{extension}" unless $parms{extension} eq '';
175 open $logfile, $append, "$path/$name"
176 or error "Unable to open logfile $path/$name - $!", 1;
178 # Set unbuffered output
179 $logfile->autoflush();
181 set_verbose if $ENV{VERBOSE};
182 set_debug if $ENV{DEBUG};
188 timestamped => $parms {timestamped},
189 disposition => $disposition,
196 my ($self, $filename) = @_;
200 =head3 append ($filename)
202 Appends $filename to the end of the current logfile
206 =for html <blockquote>
212 Filename to append to the logfile
216 =for html </blockquote>
220 =for html <blockquote>
228 =for html </blockquote>
232 open my $file, '<', $filename
251 Returns the leaf portion of logfile name.
255 =for html <blockquote>
263 =for html </blockquote>
267 =for html <blockquote>
271 =item Leaf node of log file name
275 =for html </blockquote>
279 return $self->{name};
289 Returns the full pathname to the logfile
293 =for html <blockquote>
301 =for html </blockquote>
305 =for html <blockquote>
309 =item Full pathname to the logfile
313 =for html </blockquote>
317 return "$self->{path}/$self->{name}";
321 my ($self, $msg, $nolinefeed) = @_;
325 =head3 msg ($msg, $nolinefeed)
327 Similar to log except verbose (See Display.pm) is used to possibly
328 additionally write the $msg to STDOUT.
332 =for html <blockquote>
342 If defined no linefeed is displayed at the end of the message.
346 =for html </blockquote>
350 =for html <blockquote>
358 =for html </blockquote>
362 $self->log ($msg, $nolinefeed);
364 verbose $msg, undef, $nolinefeed;
370 my ($self, $msg, $nolinefeed) = @_;
374 =head3 disp ($msg, $nolinefeed)
376 Similar to log except display (See Display.pm) is used to write the $msg to
377 STDOUT and to the log file.
381 =for html <blockquote>
391 If defined no linefeed is displayed at the end of the message.
395 =for html </blockquote>
399 =for html <blockquote>
407 =for html </blockquote>
411 $self->log ($msg, $nolinefeed);
413 display $msg, undef, $nolinefeed;
418 sub incrementErr(;$) {
419 my ($self, $increment) = @_;
423 =head3 incrementErr ($msg, $errno)
425 Increments the error count by $increment
429 =for html <blockquote>
435 Amount to increment (Default: 1)
439 =for html </blockquote>
443 =for html <blockquote>
451 =for html </blockquote>
457 $self->{errors} += $increment;
463 my ($self, $msg, $errno) = @_;
467 =head3 err ($msg, $errno)
469 Writes an error message to the log file. Error messages are prepended
470 with "ERROR" and optionally "#$errno" (if $errno is specified),
471 followed by the message. If $errno was specified then the string " -
472 terminating" is appended to the message. Otherwise the number of
473 errors in the log are incremented and used to determine the logfile's
474 disposition at close time.
478 =for html <blockquote>
488 Error number to display (also causes termination).
492 =for html </blockquote>
496 =for html <blockquote>
504 =for html </blockquote>
508 display_error ($msg, $errno);
511 $msg = "ERROR #$errno: $msg - terminating";
513 $msg = "ERROR: $msg";
520 exit $errno if $errno;
526 my ($self, %parms) = @_;
530 =head3 maillog (<parms>)
532 Mails the current logfile. "Parms" are the same as the parameters
533 described for Mail.pm.
537 =for html <blockquote>
543 Supports all parameters that Mail::mail supports.
547 =for html </blockquote>
551 =for html <blockquote>
559 =for html </blockquote>
563 my $from = $parms{from};
566 my $subject = $parms{subject};
567 my $heading = $parms{heading};
568 my $footing = $parms{footing};
569 my $mode = $parms{mode};
571 $mode = "plain" unless $mode;
573 my $log_filename = "$self->{path}/$self->{name}";
575 open my $logfile, '<', $log_filename
576 or error "Unable to open logfile $log_filename", 1;
578 if ($mode eq 'html') {
579 $heading .= '<b>Logfile:</b> '
580 . "$self->{path}/$self->{name}"
582 $footing = '</pre><hr>'
598 or error "Unable to close logfile $log_filename", 1;
604 my ($self, $msg, $nolinefeed) = @_;
608 =head3 log ($msg, $nolinefeed)
610 Writes $msg to the log file. Note this is a "silent" log in that $msg
611 is simply written to the logfile and not possibly also echoed to
612 STDOUT (See the msg method).
616 =for html <blockquote>
622 Message to write to log file
626 If defined no linefeed is displayed at the end of the message.
630 =for html </blockquote>
634 =for html <blockquote>
642 =for html </blockquote>
646 $msg = "$me: " . YMDHM . ": $msg" if $self->{timestamped};
648 display $msg, $self->{handle}, $nolinefeed;
654 my ($self, $cmd) = @_;
660 Execute the command in $cmd storing all output into the logfile
662 =for html <blockquote>
668 The command $cmd is executed with the results logged to the logfile.
672 =for html </blockquote>
676 =for html <blockquote>
680 =item Scalar representing the exit status of $cmd and an array of the commands output.
684 =for html </blockquote>
688 display "\$ $cmd", $self->{handle} if get_debug;
690 my $status = open my $output, '-|', "$cmd 2>&1";
702 display $_, $self->{handle};
703 display $_ if get_debug;
707 or error "Unable to close output ($!)", 1;
709 return ($?, @output);
719 Returns an array of lines from the current logfile.
723 =for html <blockquote>
731 =for html </blockquote>
735 =for html <blockquote>
739 =item Array of lines from the logfile
743 =for html </blockquote>
747 return ReadFile "$self->{path}/$self->{name}";
751 my ($self, $msg, $warnno) = @_;
755 =head3 warn ($msg, $warnno)
757 Similar to error but logs the message as a warning. Increments the
758 warnings count in the object thus also affecting its disposition at
759 close time. Does not terminate the process if $warnno is specified.
763 =for html <blockquote>
769 Message to write to the logfile
773 Warning number to put in the warn message (if specified)
777 =for html </blockquote>
781 =for html <blockquote>
789 =for html </blockquote>
793 warning $msg, $warnno;
796 $msg = "WARNING #$warnno: $msg";
798 $msg = "WARNING: $msg";
814 Returns the number of errors encountered
818 =for html <blockquote>
826 =for html </blockquote>
830 =for html <blockquote>
838 =for html </blockquote>
842 return $self->{errors};
846 my ($self, $msg) = @_;
848 $self->log("DEBUG: $msg") if get_debug;
860 Returns the number of warnings encountered
864 =for html <blockquote>
872 =for html </blockquote>
876 =for html <blockquote>
884 =for html </blockquote>
888 return $self->{warnings};
894 close ($self->{handle});
896 if ($self->{disposition} eq 'temp') {
897 if ($self->{errors} == 0 and
898 $self->{warnings} == 0) {
899 unlink $self->fullname;
910 =head2 CONFIGURATION AND ENVIRONMENT
912 DEBUG: If set then $debug in this module is set.
914 VERBOSE: If set then $verbose in this module is set.
924 =head3 ClearSCM Perl Modules
926 =for html <p><a href="/php/scm_man.php?file=lib/DateUtils.pm">DateUtils</a></p>
928 =for html <p><a href="/php/scm_man.php?file=lib/Display.pm">Display</a></p>
930 =for html <p><a href="/php/scm_man.php?file=lib/Mail.pm">Mail</a></p>
932 =for html <p><a href="/php/scm_man.php?file=lib/OSDep.pm">OSDep</a></p>
934 =for html <p><a href="/php/scm_man.php?file=lib/Utils.pm">Utils</a></p>
936 =head2 INCOMPATABILITIES
940 =head2 BUGS AND LIMITATIONS
942 There are no known bugs in this module.
944 Please report problems to Andrew DeFaria <Andrew@ClearSCM.com>.
946 =head2 LICENSE AND COPYRIGHT
948 This Perl Module is freely available; you can redistribute it and/or
949 modify it under the terms of the GNU General Public License as
950 published by the Free Software Foundation; either version 2 of the
951 License, or (at your option) any later version.
953 This Perl Module is distributed in the hope that it will be useful,
954 but WITHOUT ANY WARRANTY; without even the implied warranty of
955 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
956 General Public License (L<http://www.gnu.org/copyleft/gpl.html>) for more
959 You should have received a copy of the GNU General Public License
960 along with this Perl Module; if not, write to the Free Software Foundation,
961 Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.