Hardware::UPS::Perl::Logging - package of methods for logging.
use Hardware::UPS::Perl::Logging; $logger = Hardware::UPS::Perl::Logging->new(); $logger = Hardware::UPS::Perl::Logging->new( File => "/var/log/ups.log" Period => 84600, ); $logger = Hardware::UPS::Perl::Logging->new( File => "/var/log/ups.log" Size => 5, ); $logger = Hardware::UPS::Perl::Logging->new( File => "/var/log/ups.log" Scheme => "daily", ); $logger->debug("this is a debug message"); $logger->info("this is a information message"); $logger->error("this is an error message"); $logger->fatal("this is a fatal error message"); $logger->print("this is a message"); $logger->write( Format => $formatString, Arguments => \%formatArguments, ); $logger->syslog( level => "LOG_DEBUG", message => "this is a debug message for syslog" ); $logger->sendmail( MailTo => root, Subject => "fatal error", message => "there was a fatal error", ); $logger->rotate(); undef $logger; # closes log file
Hardware::UPS::Perl::Logging provides methods to print debug, info, non-fatal and fatal error messages to log files, to syslog or sending them per mail.
The log files can be rotated automatically using an ALARM signal handler due to a certain scheme saving up to 10 files on a FIFO basis. The naming convention for such log files is file.YYYY-MM-DD.x with x ranging from 0 to 9. The current log file is always available by the symbolic link file. In case of a restart, the counter x is incremented as well.
The printing operation to log files blocks the rotation to avoid loss of information. If no log file is specified, all messages are printed on STDERR.
new - creates a new logging object
$logger = Hardware::UPS::Perl::Logging->new(); $logger = Hardware::UPS::Perl::Logging->new({ File => $file, Period => $period, }); $logger = Hardware::UPS::Perl::Logging->new({ File => $file, Scheme => "period", }); $logger = Hardware::UPS::Perl::Logging->new({ File => $file, Size => $size, }); $logger = Hardware::UPS::Perl::Logging->new({ File => $file, Scheme => "size", }); $logger = Hardware::UPS::Perl::Logging->new({ File => $file, Scheme => "daily", });
new initializes a logging object $logger by opening the log file named $file.YYYY-MM-DD.x, where x denotes the current log file index in the rotation sequence ranging form 0 to 9, and creates the symbolic link named $file to it. If the log file does not exist, it will be created. If it is already available, the file will be truncated. The log file will be automatically rotated due to one of the schemes described below.
new expects the options as an anonymous hash.
File => $file
optional; the basename of the log file; if omitted, all output will be sent to STDERR.
MailTo => $mailTo
optional; the mail address a message is sent to; if not specified, the default mail address UPSMAILTO supplied by package Hardware::UPS::Perl::Constants will be used.
Period => $period
optional; the rotation period in seconds; if not specified and the rotation scheme period is selected, a default rotation period of 86400 seconds, i.e. 1 day will be used.
Scheme => $scheme
optional; the rotation scheme; overrides the scheme set by the Period or Size option; the following schemes are available:
none
The log file will not be rotated at all except at restart.
daily
The log file will be rotated on a daily basis.
period
The log file will be rotated after a certain period of time.
size
The log file will be rotated after it has reached a certain size in megabytes.
Size => $size
optional; the rotation size in megabytes; if not supplied and the size based rotation scheme is choosen, a default rotation size of 1 megabyte will be used.
"debug", "error", "fatal", "getHandle", "getLogFile", "getMailTo", "getRotationPeriod", "getRotationScheme", "getRotationSize", "info", "print", "rotate". "sendmail", "setMailTo", "syslog", "write"
getErrorMessage - gets the internal error message
$logger = Hardware::UPS::Perl::Logging->new(); unless(defined $logger) { print STDERR $logger->getErrorMessage(), "\n"; exit 0; }
getErrorMessage returns the internal error message, if something went wrong.
getHandle - gets the filehandle of the current log file
$logger = Hardware::UPS::Perl::Net->new( File => $file. ); $fh = $logger->getHandle();
getHandle returns the filehandle of the current log file used for logging.
"new", "getLogFile"
getLogFile - gets the current log file
$logger = Hardware::UPS::Perl::Net->new( File => "$HOME/tmp.log", ); $file = $logger->getLogFile();
getLogFile returns the current log file used for logging.
"new", "getHandle", "getRotationPeriod", "getRotationScheme", "getRotationSize", "rotate"
getRotationPeriod - gets the current rotation period
$logger = Hardware::UPS::Perl::Net->new( File => "$HOME/tmp.log", ); $period = $logger->getRotationPeriod();
getRotationPeriod returns the rotation period in minutes.
"new", "getHandle", "getLogFile", "getRotationScheme", "getRotationSize", "rotate"
getRotationScheme - gets the current rotation scheme
$logger = Hardware::UPS::Perl::Net->new( File => "$HOME/tmp.log", ); $scheme = $logger->getRotationScheme();
getRotationScheme returns the rotation scheme.
"new", "getHandle", "getLogFile", "getMailTo", "getRotationPeriod", "getRotationSize", "rotate"
getRotationSize - gets the current rotation scheme
$logger = Hardware::UPS::Perl::Net->new( File => "$HOME/tmp.log", Scheme => "size", ); $scheme = $logger->getRotationSize();
getRotationSize returns the rotation size in megabytes.
"new", "getHandle", "getLogFile", "getMailTo", "getRotationPeriod", "getRotationScheme", "rotate"
rotate - forces rotation of log file
$logger = Hardware::UPS::Perl::Net->new( File => "$HOME/tmp.log", ); $logger->rotate();
rotate forces the rotation of the log file.
"new", "getHandle", "getLogFile", "getRotationPeriod", "getRotationScheme", "getRotationSize"
debug - prints a debug message to log file
$logger = Hardware::UPS::Perl::Net->new( File => "$HOME/tmp.log", ); $logger->debug("This is a debug message");
debug prints a debug message to the current log file.
$debugMessage
string; the debug message.
"new", "error", "getHandle", "getLogFile", "info", "fatal", "print", "syslog", "write"
info - prints an info message to log file
$logger = Hardware::UPS::Perl::Net->new( File => "$HOME/tmp.log", ); $logger->info("This is an info message");
info prints an info message to the current log file.
$infoMessage
string; the info message.
"new", "debug", "error", "getHandle", "getLogFile", "fatal", "print", "syslog", "write"
error - prints a non-fatal error message to log file
$logger = Hardware::UPS::Perl::Net->new( File => "$HOME/tmp.log", ); $logger->error("This is an error message");
error prints a non-fatal error message to the current log file.
$errorMessage
string; the error message.
"new", "debug", "getHandle", "getLogFile", "info", "fatal", "print", "syslog", "write"
fatal - prints a fatal error message to log file and dies
$logger = Hardware::UPS::Perl::Net->new( File => "$HOME/tmp.log", ); $logger->fatal("This is a fatal error message");
fatal prints a fatal error message to the current log file and to STDERR using Carp::croak thus causing the script to die.
$fatalMessage
string; the fatal error message.
"new", "debug", "error", "getHandle", "getLogFile", "info", "fatal", "print", "syslog", "write"
print - prints a general log message to the log file
$logger = Hardware::UPS::Perl::Net->new( File => "$HOME/tmp.log", ); $logger->print("This is a normal log message");
prints prints a normal log message to the current log file. The message is prepended by the current date in the format %b %d %T, e.g. Feb 03 15:24:52, and the script name separated by colons. While printing to the log file, the rotation is blocked.
$message
string; the message.
"new", "debug", "error", "getHandle", "getLogFile", "info", "fatal", "syslog", "write"
write - writes a formatted log message to the log file
$logger = Hardware::UPS::Perl::Net->new({ File => "$HOME/tmp.log", }); $logger->write({ Format => $formatString, Arguments => \%formatArguments, });
write prints a formatted log message to the current log file. The message is prepended by the current date in the format %b %d %T, e.g. Feb 03 15:24:52, and the script name separated by colons. While printing to the log file, the rotation is blocked.
write expects the options as an anonymous hash.
Format => $formatString
required; the string declaring a format.
Arguments => \%arguments
required; an hash reference holding the arguments required by the format and their values.
"new", "debug", "error", "fatal", "getHandle", "getLogFile", "info", "print", "syslog"
syslog - prints a message to syslog
$logger = Hardware::UPS::Perl::Net->new(); $logger->syslog({ level => "LOG_DEBUG", message => "This is a LOG_DEBUG level message" });
syslog prints a message to syslog using Perl5 extension package Sys:Syslog at the facility "UPS".
syslog expects the options as an anonymous hash.
level => $level
string; the priority level; if not specified, LOG_DEBUG is assumed.
message => $message
setMailTo - gets the current mail address
$logger = Hardware::UPS::Perl::Net->new(); $oldMailto = $logger->setMailTo($mailto);
setMailto sets the mail address being used to send mail to. It returns the previously used mail address.
$mailto
string; a valid mail address.
"new", "getMailTo", "sendmail"
getMailTo - gets the current mail address
$logger = Hardware::UPS::Perl::Net->new(); $mailto = $logger->getMailTo();
getMailto returns the current mail address used to send mails to.
"new", "setMailTo", "sendmail"
sendmail - prints a message to syslog
$logger = Hardware::UPS::Perl::Net->new(); $logger->sendmail({ MailTo => $mailto, Subject => "This is the mail message", Message => "This is the mail subject", });
sendmail sends a message to the current mail recipient using Perl5 extension package Mail:Send. The subject is prepended by the name of the calling script and the hostname, the script is running on.
sendmail expects the options as an anonymous hash.
MailTo => $mailto
string; the mail address; if not specified, UPSMAILTO provided by Hardware::UPS::Perl::Constants is used.
Message => $message
string; the mail message; if not specified, the string event occured at $date is used, where $date denotes the current date.
Subject => $subject
string; the mail subject; the mail subject is prepended by the string UPSSCRIPT at UPSHOSTNAME: , both as provided by package Hardware::UPS::Perl::Constants; if the subject is not specified, the colon and the space at the end are omitted.
"new", "getMailTo", "setMailTo"
Carp(3pm), Date::Format(3pm), Fcntl(3pm), File::Basename(3pm), File::Find(3pm), FileHandle(3pm), Mail::Send(3pm), Sys::Syslog(3pm), Time::HiRes(3pm), Hardware::UPS::Perl::Connection(3pm), Hardware::UPS::Perl::Connection::Net(3pm), Hardware::UPS::Perl::Connection::Serial(3pm), Hardware::UPS::Perl::Constants(3pm), Hardware::UPS::Perl::Driver(3pm), Hardware::UPS::Perl::Driver::Megatec(3pm), Hardware::UPS::Perl::General(3pm), Hardware::UPS::Perl::PID(3pm), Hardware::UPS::Perl::Utils(3pm)
Hardware::UPS::Perl::Logging was inspired by many Perl modules dealing with logging. Unfortunately, either those modules are not included in a standard SuSE 10.1 Linux distribution, or they did not quite fit to my needs.
Hardware::UPS::Perl::Logging was developed using perl 5.8.8 on a SuSE 10.1 Linux distribution.
There are plenty of them for sure. Maybe the embedded pod documentation has to be revised a little bit.
Suggestions to improve Hardware::UPS::Perl::Logging are welcome, though due to the lack of time it might take a while to incorporate them.
Copyright (c) 2007 by Christian Reile, <Christian.Reile@t-online.de>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. For further licensing details, please see the file COPYING in the distribution.
To install Hardware::UPS::Perl::PID, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Hardware::UPS::Perl::PID
CPAN shell
perl -MCPAN -e shell install Hardware::UPS::Perl::PID
For more information on module installation, please visit the detailed CPAN module installation guide.