Christian Reile > perl-Hardware-UPS-Perl-0.43 > Hardware::UPS::Perl::Logging

Download:
UPS/perl-Hardware-UPS-Perl-0.43.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.09   Source  

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.

syntax highlighting: