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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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"

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.

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

LIST OF METHODS

new

getErrorMessage

getHandle

getLogFile

getRotationPeriod

getRotationScheme

getRotationSize

rotate

debug

info

error

fatal

print

write

syslog

setMailTo

getMailTo

sendmail

SEE ALSO

NOTES

BUGS

AUTHOR

Module Install Instructions