Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Hardware::UPS::Perl::Logging
package of methods for logging.

Hardware::UPS::Perl::Logging - package of methods for logging.



NAME

Hardware::UPS::Perl::Logging - package of methods for logging.


SYNOPSIS


    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


DESCRIPTION

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.


LIST OF METHODS

new

Name:
new - creates a new logging object

Synopsis:

        $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",

    });
Description:
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.

Arguments:
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.

See Also:
debug, error, fatal, getHandle, getLogFile, getMailTo, getRotationPeriod, getRotationScheme, getRotationSize, info, print, rotate. sendmail, setMailTo, syslog, write

getErrorMessage

Name:
getErrorMessage - gets the internal error message

Synopsis:

        $logger = Hardware::UPS::Perl::Logging->new();

        unless(defined $logger) {

            print STDERR $logger->getErrorMessage(), "\n";

            exit 0;

        }
Description:
getErrorMessage returns the internal error message, if something went wrong.

getHandle

Name:
getHandle - gets the filehandle of the current log file

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new(

            File    => $file.

        );

        $fh = $logger->getHandle();
Description:
getHandle returns the filehandle of the current log file used for logging.

See Also:
new, getLogFile

getLogFile

Name:
getLogFile - gets the current log file

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new(

            File    => "$HOME/tmp.log",

        );

        $file = $logger->getLogFile();
Description:
getLogFile returns the current log file used for logging.

See Also:
new, getHandle, getRotationPeriod, getRotationScheme, getRotationSize, rotate

getRotationPeriod

Name:
getRotationPeriod - gets the current rotation period

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new(

            File    => "$HOME/tmp.log",

        );

        $period = $logger->getRotationPeriod();
Description:
getRotationPeriod returns the rotation period in minutes.

See Also:
new, getHandle, getLogFile, getRotationScheme, getRotationSize, rotate

getRotationScheme

Name:
getRotationScheme - gets the current rotation scheme

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new(

            File    => "$HOME/tmp.log",

        );

        $scheme = $logger->getRotationScheme();
Description:
getRotationScheme returns the rotation scheme.

See Also:
new, getHandle, getLogFile, getMailTo, getRotationPeriod, getRotationSize, rotate

getRotationSize

Name:
getRotationSize - gets the current rotation scheme

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new(

            File    => "$HOME/tmp.log",

            Scheme  => "size",

        );

        $scheme = $logger->getRotationSize();
Description:
getRotationSize returns the rotation size in megabytes.

See Also:
new, getHandle, getLogFile, getMailTo, getRotationPeriod, getRotationScheme, rotate

rotate

Name:
rotate - forces rotation of log file

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new(

            File    => "$HOME/tmp.log",

        );

        $logger->rotate();
Description:
rotate forces the rotation of the log file.

See Also:
new, getHandle, getLogFile, getRotationPeriod, getRotationScheme, getRotationSize

debug

Name:
debug - prints a debug message to log file

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new(

            File    => "$HOME/tmp.log",

        );

        $logger->debug("This is a debug message");
Description:
debug prints a debug message to the current log file.

Arguments:
$debugMessage
string; the debug message.

See Also:
new, error, getHandle, getLogFile, info, fatal, print, syslog, write

info

Name:
info - prints an info message to log file

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new(

            File    => "$HOME/tmp.log",

        );

        $logger->info("This is an info message");
Description:
info prints an info message to the current log file.

Arguments:
$infoMessage
string; the info message.

See Also:
new, debug, error, getHandle, getLogFile, fatal, print, syslog, write

error

Name:
error - prints a non-fatal error message to log file

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new(

            File    => "$HOME/tmp.log",

        );

        $logger->error("This is an error message");
Description:
error prints a non-fatal error message to the current log file.

Arguments:
$errorMessage
string; the error message.

See Also:
new, debug, getHandle, getLogFile, info, fatal, print, syslog, write

fatal

Name:
fatal - prints a fatal error message to log file and dies

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new(

            File    => "$HOME/tmp.log",

        );

        $logger->fatal("This is a fatal error message");
Description:
fatal prints a fatal error message to the current log file and to STDERR using Carp::croak thus causing the script to die.

Arguments:
$fatalMessage
string; the fatal error message.

See Also:
new, debug, error, getHandle, getLogFile, info, fatal, print, syslog, write

print

Name:
print - prints a general log message to the log file

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new(

            File    => "$HOME/tmp.log",

        );

        $logger->print("This is a normal log message");
Description:
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.

Arguments:
$message
string; the message.

See Also:
new, debug, error, getHandle, getLogFile, info, fatal, syslog, write

write

Name:
write - writes a formatted log message to the log file

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new({

            File    => "$HOME/tmp.log",

    });

        $logger->write({

        Format      => $formatString,

        Arguments   => \%formatArguments,

    });
Description:
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.

Arguments:
Format => $formatString
required; the string declaring a format.

Arguments => \%arguments
required; an hash reference holding the arguments required by the format and their values.

See Also:
new, debug, error, fatal, getHandle, getLogFile, info, print, syslog

syslog

Name:
syslog - prints a message to syslog

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new();

        $logger->syslog({

            level   => "LOG_DEBUG",

            message => "This is a LOG_DEBUG level message"

    });
Description:
syslog prints a message to syslog using Perl5 extension package Sys:Syslog at the facility ``UPS''.

syslog expects the options as an anonymous hash.

Arguments:
level => $level
string; the priority level; if not specified, LOG_DEBUG is assumed.

message => $message
string; the message.

See Also:
new, debug, error, getHandle, getLogFile, info, fatal, print, syslog, write

setMailTo

Name:
setMailTo - gets the current mail address

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new();

        $oldMailto = $logger->setMailTo($mailto);
Description:
setMailto sets the mail address being used to send mail to. It returns the previously used mail address.

Arguments:
$mailto
string; a valid mail address.

See Also:
new, getMailTo, sendmail

getMailTo

Name:
getMailTo - gets the current mail address

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new();

        $mailto = $logger->getMailTo();
Description:
getMailto returns the current mail address used to send mails to.

See Also:
new, setMailTo, sendmail

sendmail

Name:
sendmail - prints a message to syslog

Synopsis:

        $logger = Hardware::UPS::Perl::Net->new();

        $logger->sendmail({

            MailTo  => $mailto,

            Subject => "This is the mail message",

            Message => "This is the mail subject",

    });
Description:
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.

Arguments:
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.

See Also:
new, getMailTo, setMailTo


SEE ALSO

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)


NOTES

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.


BUGS

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.


AUTHOR

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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy