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} ? '>>' : '>';
167 my $extension = $parms{extension} ? $parms{extension} : 'log';
170 $name = "$name.$extension";
172 open $logfile, $append, "$path/$name"
173 or error "Unable to open logfile $path/$name - $!", 1;
175 # Set unbuffered output
176 $logfile->autoflush ();
187 timestamped => $parms {timestamped},
188 disposition => $disposition,
195 my ($self, $filename) = @_;
199 =head3 append ($filename)
201 Appends $filename to the end of the current logfile
205 =for html <blockquote>
211 Filename to append to the logfile
215 =for html </blockquote>
219 =for html <blockquote>
227 =for html </blockquote>
231 open my $file, '<', $filename
250 Returns the leaf portion of logfile name.
254 =for html <blockquote>
262 =for html </blockquote>
266 =for html <blockquote>
270 =item Leaf node of log file name
274 =for html </blockquote>
278 return $self->{name};
288 Returns the full pathname to the logfile
292 =for html <blockquote>
300 =for html </blockquote>
304 =for html <blockquote>
308 =item Full pathname to the logfile
312 =for html </blockquote>
316 return "$self->{path}/$self->{name}";
320 my ($self, $msg, $nolinefeed) = @_;
324 =head3 msg ($msg, $nolinefeed)
326 Similar to log except verbose (See Display.pm) is used to possibly
327 additionally write the $msg to STDOUT.
331 =for html <blockquote>
341 If defined no linefeed is displayed at the end of the message.
345 =for html </blockquote>
349 =for html <blockquote>
357 =for html </blockquote>
361 $self->log ($msg, $nolinefeed);
363 verbose $msg, undef, $nolinefeed;
369 my ($self, $msg, $nolinefeed) = @_;
373 =head3 disp ($msg, $nolinefeed)
375 Similar to log except display (See Display.pm) is used to write the $msg to
376 STDOUT and to the log file.
380 =for html <blockquote>
390 If defined no linefeed is displayed at the end of the message.
394 =for html </blockquote>
398 =for html <blockquote>
406 =for html </blockquote>
410 $self->log ($msg, $nolinefeed);
412 display $msg, undef, $nolinefeed;
417 sub incrementErr (;$) {
418 my ($self, $increment) = @_;
422 =head3 incrementErr ($msg, $errno)
424 Increments the error count by $increment
428 =for html <blockquote>
434 Amount to increment (Default: 1)
438 =for html </blockquote>
442 =for html <blockquote>
450 =for html </blockquote>
456 $self->{errors} += $increment;
460 my ($self, $msg, $errno) = @_;
464 =head3 err ($msg, $errno)
466 Writes an error message to the log file. Error messages are prepended
467 with "ERROR" and optionally "#$errno" (if $errno is specified),
468 followed by the message. If $errno was specified then the string " -
469 terminating" is appended to the message. Otherwise the number of
470 errors in the log are incremented and used to determine the logfile's
471 disposition at close time.
475 =for html <blockquote>
485 Error number to display (also causes termination).
489 =for html </blockquote>
493 =for html <blockquote>
501 =for html </blockquote>
505 display_error ($msg, $errno);
508 $msg = "ERROR #$errno: $msg - terminating";
510 $msg = "ERROR: $msg";
517 exit $errno if $errno;
523 my ($self, %parms) = @_;
527 =head3 maillog (<parms>)
529 Mails the current logfile. "Parms" are the same as the parameters
530 described for Mail.pm.
534 =for html <blockquote>
540 Supports all parameters that Mail::mail supports.
544 =for html </blockquote>
548 =for html <blockquote>
556 =for html </blockquote>
560 my $from = $parms{from};
563 my $subject = $parms{subject};
564 my $heading = $parms{heading};
565 my $footing = $parms{footing};
566 my $mode = $parms{mode};
571 my $log_filename = "$self->{path}/$self->{name}";
573 open my $logfile, '<', $log_filename
574 or error "Unable to open logfile $log_filename", 1;
576 if ($mode eq 'html') {
577 $heading .= '<b>Logfile:</b> '
578 . "$self->{path}/$self->{name}"
580 $footing = '</pre><hr>'
596 or error "Unable to close logfile $log_filename", 1;
602 my ($self, $msg, $nolinefeed) = @_;
606 =head3 log ($msg, $nolinefeed)
608 Writes $msg to the log file. Note this is a "silent" log in that $msg
609 is simply written to the logfile and not possibly also echoed to
610 STDOUT (See the msg method).
614 =for html <blockquote>
620 Message to write to log file
624 If defined no linefeed is displayed at the end of the message.
628 =for html </blockquote>
632 =for html <blockquote>
640 =for html </blockquote>
644 $msg = "$me: " . YMDHM . ": $msg" if $self->{timestamped};
646 display $msg, $self->{handle}, $nolinefeed;
652 my ($self, $cmd) = @_;
658 Execute the command in $cmd storing all output into the logfile
660 =for html <blockquote>
666 The command $cmd is executed with the results logged to the logfile.
670 =for html </blockquote>
674 =for html <blockquote>
678 =item Scalar representing the exit status of $cmd and an array of the commands output.
682 =for html </blockquote>
686 display "\$ $cmd", $self->{handle} if get_debug;
688 my $status = open my $output, '-|', "$cmd 2>&1";
700 display $_, $self->{handle};
701 display $_ if get_debug;
705 or error "Unable to close output ($!)", 1;
707 return ($?, @output);
717 Returns an array of lines from the current logfile.
721 =for html <blockquote>
729 =for html </blockquote>
733 =for html <blockquote>
737 =item Array of lines from the logfile
741 =for html </blockquote>
745 return ReadFile "$self->{path}/$self->{name}";
749 my ($self, $msg, $warnno) = @_;
753 =head3 warn ($msg, $warnno)
755 Similar to error but logs the message as a warning. Increments the
756 warnings count in the object thus also affecting its disposition at
757 close time. Does not terminate the process if $warnno is specified.
761 =for html <blockquote>
767 Message to write to the logfile
771 Warning number to put in the warn message (if specified)
775 =for html </blockquote>
779 =for html <blockquote>
787 =for html </blockquote>
791 warning $msg, $warnno;
794 $msg = "WARNING #$warnno: $msg";
796 $msg = "WARNING: $msg";
812 Returns the number of errors encountered
816 =for html <blockquote>
824 =for html </blockquote>
828 =for html <blockquote>
836 =for html </blockquote>
840 return $self->{errors};
850 Returns the number of warnings encountered
854 =for html <blockquote>
862 =for html </blockquote>
866 =for html <blockquote>
874 =for html </blockquote>
878 return $self->{warnings};
884 close ($self->{handle});
886 if ($self->{disposition} eq 'temp') {
887 if ($self->{errors} == 0 and
888 $self->{warnings} == 0) {
889 unlink $self->fullname;
900 =head2 CONFIGURATION AND ENVIRONMENT
902 DEBUG: If set then $debug in this module is set.
904 VERBOSE: If set then $verbose in this module is set.
914 =head3 ClearSCM Perl Modules
916 =for html <p><a href="/php/scm_man.php?file=lib/DateUtils.pm">DateUtils</a></p>
918 =for html <p><a href="/php/scm_man.php?file=lib/Display.pm">Display</a></p>
920 =for html <p><a href="/php/scm_man.php?file=lib/Mail.pm">Mail</a></p>
922 =for html <p><a href="/php/scm_man.php?file=lib/OSDep.pm">OSDep</a></p>
924 =for html <p><a href="/php/scm_man.php?file=lib/Utils.pm">Utils</a></p>
926 =head2 INCOMPATABILITIES
930 =head2 BUGS AND LIMITATIONS
932 There are no known bugs in this module.
934 Please report problems to Andrew DeFaria <Andrew@ClearSCM.com>.
936 =head2 LICENSE AND COPYRIGHT
938 This Perl Module is freely available; you can redistribute it and/or
939 modify it under the terms of the GNU General Public License as
940 published by the Free Software Foundation; either version 2 of the
941 License, or (at your option) any later version.
943 This Perl Module is distributed in the hope that it will be useful,
944 but WITHOUT ANY WARRANTY; without even the implied warranty of
945 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
946 General Public License (L<http://www.gnu.org/copyleft/gpl.html>) for more
949 You should have received a copy of the GNU General Public License
950 along with this Perl Module; if not, write to the Free Software Foundation,
951 Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.