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 (defined $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};
574 my $log_filename = "$self->{path}/$self->{name}";
576 open my $logfile, '<', $log_filename
577 or error "Unable to open logfile $log_filename", 1;
579 if ($mode eq 'html') {
580 $heading .= '<b>Logfile:</b> '
581 . "$self->{path}/$self->{name}"
583 $footing = '</pre><hr>'
599 or error "Unable to close logfile $log_filename", 1;
605 my ($self, $msg, $nolinefeed) = @_;
609 =head3 log ($msg, $nolinefeed)
611 Writes $msg to the log file. Note this is a "silent" log in that $msg
612 is simply written to the logfile and not possibly also echoed to
613 STDOUT (See the msg method).
617 =for html <blockquote>
623 Message to write to log file
627 If defined no linefeed is displayed at the end of the message.
631 =for html </blockquote>
635 =for html <blockquote>
643 =for html </blockquote>
647 $msg = "$me: " . YMDHM . ": $msg" if $self->{timestamped};
649 display $msg, $self->{handle}, $nolinefeed;
655 my ($self, $cmd) = @_;
661 Execute the command in $cmd storing all output into the logfile
663 =for html <blockquote>
669 The command $cmd is executed with the results logged to the logfile.
673 =for html </blockquote>
677 =for html <blockquote>
681 =item Scalar representing the exit status of $cmd and an array of the commands output.
685 =for html </blockquote>
689 display "\$ $cmd", $self->{handle} if get_debug;
691 my $status = open my $output, '-|', "$cmd 2>&1";
703 display $_, $self->{handle};
704 display $_ if get_debug;
708 or error "Unable to close output ($!)", 1;
710 return ($?, @output);
720 Returns an array of lines from the current logfile.
724 =for html <blockquote>
732 =for html </blockquote>
736 =for html <blockquote>
740 =item Array of lines from the logfile
744 =for html </blockquote>
748 return ReadFile "$self->{path}/$self->{name}";
752 my ($self, $msg, $warnno) = @_;
756 =head3 warn ($msg, $warnno)
758 Similar to error but logs the message as a warning. Increments the
759 warnings count in the object thus also affecting its disposition at
760 close time. Does not terminate the process if $warnno is specified.
764 =for html <blockquote>
770 Message to write to the logfile
774 Warning number to put in the warn message (if specified)
778 =for html </blockquote>
782 =for html <blockquote>
790 =for html </blockquote>
794 warning $msg, $warnno;
797 $msg = "WARNING #$warnno: $msg";
799 $msg = "WARNING: $msg";
815 Returns the number of errors encountered
819 =for html <blockquote>
827 =for html </blockquote>
831 =for html <blockquote>
839 =for html </blockquote>
843 return $self->{errors};
853 Returns the number of warnings encountered
857 =for html <blockquote>
865 =for html </blockquote>
869 =for html <blockquote>
877 =for html </blockquote>
881 return $self->{warnings};
887 close ($self->{handle});
889 if ($self->{disposition} eq 'temp') {
890 if ($self->{errors} == 0 and
891 $self->{warnings} == 0) {
892 unlink $self->fullname;
903 =head2 CONFIGURATION AND ENVIRONMENT
905 DEBUG: If set then $debug in this module is set.
907 VERBOSE: If set then $verbose in this module is set.
917 =head3 ClearSCM Perl Modules
919 =for html <p><a href="/php/scm_man.php?file=lib/DateUtils.pm">DateUtils</a></p>
921 =for html <p><a href="/php/scm_man.php?file=lib/Display.pm">Display</a></p>
923 =for html <p><a href="/php/scm_man.php?file=lib/Mail.pm">Mail</a></p>
925 =for html <p><a href="/php/scm_man.php?file=lib/OSDep.pm">OSDep</a></p>
927 =for html <p><a href="/php/scm_man.php?file=lib/Utils.pm">Utils</a></p>
929 =head2 INCOMPATABILITIES
933 =head2 BUGS AND LIMITATIONS
935 There are no known bugs in this module.
937 Please report problems to Andrew DeFaria <Andrew@ClearSCM.com>.
939 =head2 LICENSE AND COPYRIGHT
941 This Perl Module is freely available; you can redistribute it and/or
942 modify it under the terms of the GNU General Public License as
943 published by the Free Software Foundation; either version 2 of the
944 License, or (at your option) any later version.
946 This Perl Module is distributed in the hope that it will be useful,
947 but WITHOUT ANY WARRANTY; without even the implied warranty of
948 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
949 General Public License (L<http://www.gnu.org/copyleft/gpl.html>) for more
952 You should have received a copy of the GNU General Public License
953 along with this Perl Module; if not, write to the Free Software Foundation,
954 Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.