NAME

UniLog - Perl module for unified logging on Unix and Win32

Version 0.14

SYNOPSIS

  use UniLog qw(:levels syslog);
  use UniLog qw(:options :facilities); # Not useful on Win32

  $Logger=UniLog->new(Ident    => "MyProgram",
                                  # The log source identification
                      Options  => LOG_PID|LOG_CONS|LOG_NDELAY,
                                  # Logger options, see "man 3 syslog"
                      Facility => LOG_USER,
                                  # Logger facility, see "man 3 syslog"
                      Level    => LOG_INFO,
                                  # The log level                       
                      StdErr   => 1)
                                  # Log messages also to STDERR
       or die "Can not create the logger: $!";

  $Logger->Message(LOG_NOTICE, "Message text here, time: %d", time())
        or die "Logging error: $!";
           # Send message to the log

  $Logger->Message(LOG_DEBUG, "You should not see this");
           # Will not be logged
  $Logger->Level(LOG_DEBUG);
  $Logger->Message(LOG_DEBUG, "You should see this now");
           # Will be logged

  $Logger->StdErr(0);
           # Stop logging to STDERR
  $Logger->Message(LOG_INFO, "Should not be logged to STDERR");
           # Send message to the log

  $Logger->Close();

DESCRIPTION

This module provides a unified way to send log messages on Unix and Win32. Messages are logged using syslog on Unix and using EventLog on Win32.

This module uses Unix::Syslog Perl module on Unix and Win32::EventLog Perl module on Win32.

The idea was to give a programmer a possibility to write a program which will be able to run on Unix and on Win32 without code adjusting and with the same logging functionality.

Notes:

Win32::EventLog does not support any Win32 platform except WinNT. So, UniLog provides only STDERR and file logging on these platforms.

Logging to remote server is not supported in this release.

Module was tested on FreeBSD 4.2, Win2000, Win98 and Solaris 7.

Note about system logging

To utilize the OS logging facilities UniLog is using external modules. These modules are not available on some platforms. On these platforms you can use UniLog for STDERR and/or file logging, you just have to prevent UniLog from attempt to load system logging module. It can be done by importing 'fake' function nosyslog. You would typically do it by saying

  perl -MUniLog=nosyslog script.pl

or by including the string -MUniLog=nosyslog in the PERL5OPT environment variable. Also, the command

  use UniLog qw(:levels :options :facilities nosyslog);

can be used inside of perl script.

See also the EXPORT section.

The UniLog methods

new(%PARAMHASH);

The new method creates the logger object and returns a handle to it. This handle is then used to call the methods below.

The %PARAMHASH could contain the following keys:

Ident

Ident field specifies a string which will be used as message source identifier. syslogd(8) will print it into every message and EventLog will put it to the "Source" message field.

Default is $0, the name of the program being executed.

Options

This is an integer value which is the result of ORed options: LOG_CONS, LOG_NDELAY, LOG_PID.

See Unix::Syslog, syslog(3) for details.

Default is LOG_PID|LOG_CONS.

This field is ignored on Win32.

Facility

This is an integer value which specifies the part of the system the message should be associated with (e.g. kernel message, mail subsystem).

Could be LOG_AUTH, LOG_CRON, LOG_DAEMON, LOG_KERN, LOG_LPR, LOG_MAIL, LOG_NEWS, LOG_SYSLOG, LOG_USER, LOG_UUCP, LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7.

See Unix::Syslog, syslog(3) for details.

Default is LOG_USER.

This field is ignored on Win32.

Level

This is an integer value which specifies log level. The message with Level greater than Level will not be logged. You will be able to change Level using Level method. See Message method description for available log levels.

Default log level is LOG_INFO.

SysLog

If this flag have a 'true' value all messages are logged using Unix::Syslog or Win32::EventLog, if possible.

You will be able to change this flag using SysLog method.

Default is 1 - log to system log.

StdErr

If this flag have a 'true' value all messages are logged to STDERR in addition to syslog/EventLog. You will be able to change this flag using StdErr method.

Default is 0 - do not log to STDERR.

LogFile

The name for the log file. If defined, all messages are logged to this file in addition to syslog/EventLog and STDERR.

The LogFile have to be treated as a template for the file name because it is processed by POSIX::strftime function before actual file opening. See POSIX::strftime for details.

Of course, the log file will be automatically changed if necessary. For example, new log file will be created every hour if LogFile contains '%H'. Of course, all necessary directories will be created.

FilePerms

The permissions for log file. Default is 0640

DirPerms

The permissions for directories created for log file. Default is 0750

Truncate

If this flag have a 'true' value the log file will be truncated before start logging. You will be able to change this flag using Truncate method.

Default is 0 - do not truncate file.

SafeStr

If 'true' all the 'dangerous' symbols will be printed as their hex codes.

Default is 1 - change dangerous symbols to their hex codes.

In case of fatal error new() returns undef. $! variable will contain the error message.

Message($Level, $Format, @SprintfParams);

The Message method send a log string to the syslog or EventLog and, if allowed, to STDERR. Log string will be formed by sprintf function from $Format format string and parameters passed in @SprintfParams. Of course, @SprintfParams could be empty if no parameters required by format string. See sprintf in perlfunc for details.

The $Level should be an integer and could be:

LOG_EMERG

Value 0. Will be logged as LOG_EMERG in syslog, as EVENTLOG_ERROR_TYPE in EventLog.

LOG_ALERT

Value 1. Will be logged as LOG_ALERT in syslog, as EVENTLOG_ERROR_TYPE in EventLog.

LOG_CRIT

Value 2. Will be logged as LOG_CRIT in syslog, as EVENTLOG_ERROR_TYPE in EventLog.

LOG_ERR

Value 3. Will be logged as LOG_ERR in syslog, as EVENTLOG_ERROR_TYPE in EventLog.

LOG_WARNING

Value 4. Will be logged as LOG_WARNING in syslog, as EVENTLOG_WARNING_TYPE in EventLog.

LOG_NOTICE

Value 5. Will be logged as LOG_NOTICE in syslog, as EVENTLOG_INFORMATION_TYPE in EventLog.

LOG_INFO

Value 6. Will be logged as LOG_INFO in syslog, as EVENTLOG_INFORMATION_TYPE in EventLog.

LOG_DEBUG

Value 7. Will be logged as LOG_DEBUG in syslog, as EVENTLOG_INFORMATION_TYPE in EventLog.

Default is LOG_INFO.

See Unix::Syslog(3) for "LOG_*" description, see Win32::EventLog(3) for "EVENTLOG_*_TYPE" descriptions.

In case of fatal error Message() returns undef. $! variable will contain the error message.

emergency($Format, @SprintfParams);

Just a synonym for Message(LOG_EMERG, $Format, @SprintfParams)

alert($Format, @SprintfParams);

Just a synonym for Message(LOG_ALERT, $Format, @SprintfParams)

critical($Format, @SprintfParams);

Just a synonym for Message(LOG_CRIT, $Format, @SprintfParams)

error($Format, @SprintfParams);

Just a synonym for Message(LOG_ERR, $Format, @SprintfParams)

warning($Format, @SprintfParams);

Just a synonym for Message(LOG_WARNING, $Format, @SprintfParams)

notice($Format, @SprintfParams);

Just a synonym for Message(LOG_NOTICE, $Format, @SprintfParams)

info($Format, @SprintfParams);

Just a synonym for Message(LOG_INFO, $Format, @SprintfParams)

debug($Format, @SprintfParams);

Just a synonym for Message(LOG_DEBUG, $Format, @SprintfParams)

Level([$LogLevel]);

If $LogLevel is not specified Level returns a current log level. If $LogLevel is specified Level sets the log level to the new value and returns a previous value.

SysLog([$Flag]);

If $Flag is not specified SysLog returns a current state of logging-to-system-log flag. If $Flag is specified SysLog sets the logging-to-system-log flag to the new state and returns a previous state.

StdErr([$Flag]);

If $Flag is not specified StdErr returns a current state of logging-to-STDERR flag. If $Flag is specified StdErr sets the logging-to-STDERR flag to the new state and returns a previous state.

LogFile([$NewLogFileName, [$FilePerms]]);

If $NewLogFileName is not specified LogFile returns a current log file name. Not the "log file name template" but the actual file name.

If $NewLogFileName is specified LogFile sets the "log file name template" to the $NewLogFileName and returns a previous log file name (the actual file name). The actual closing old file and opening ne one will be done during next Message() call.

Note: you can specify an empty line as a $NewLogFileName parameter. It will mean "disable file logging".

Permissions([$FilePerms, [$DirPerms]]);

If no parameters is specified Permissions returns the current permissions used for new log file creation.

If $FilePerms is specified Permissions sets the log file permissions to the $FilePerms and returns a previous value.

If $DirPerms is specified Permissions sets the new directories permissions to the $DirPerms.

In scalar context Permissions returns the previous log file permissions value. In list context Permissions returns an two-elements array, firs is original log file permissions, second is directories permissions.

Truncate([$Flag]);

If $Flag is not specified Truncate returns a current state of Truncate flag. If $Flag is specified Truncate sets the Truncate flag to the new state and returns a previous state.

CloseLogFile([$NewLogFileName]);

Enforce UniLog to close log file temporary. It will be re-opened for next message. If you set the Truncate flag to 'true' value file will be truncated during re-opening.

Close();

Close the logger.

SafeStr($Str);

Just change all dangerous symbols (\x00-\x1F and \xFF) in a $Str to their hexadecimal codes and returns the updated string.

EXPORT

None by default.

:levels

All Levels, described in the Message method documentation

:options

All Options, described in the new method documentation

:facilities

All Facilities, described in the new method documentation

:functions

All auxiliary functions. Just SafeStr() at the moment.

SafeStr

SafeStr() function.

syslog

Fake symbol, tells UniLog to try to load the system logging module at the module load time.

nosyslog

Fake symbol, tells UniLog do not to try to load the system logging module at the module load time. The logging to Syslog/EventLog will be disabled.

If no syslog nor nosyslog present, UniLog will try to load the system logging module at the first new method call.

Known problems

Problem with Perl2Exe utility.

UniLog is using external module (Unix::Syslog or Win32::Event) for actual logging. The appropriate module is loading during runtime (in eval section) so Perl2Exe is not able to determinate this module have to be compiled in. You have to include "use Unix::Syslog;" or "use Win32::EventLog;" to your script or disable syslog usage.

Uptate (Jan 10 2005): forget about Perl2Exe, use PAR instead (see bundled pp utility).

AUTHOR

Daniel Podolsky, <tpaba@cpan.org>

SEE ALSO

Unix::Syslog, Win32::EventLog, syslog(3).

cpanm UniLog

perl -MCPAN -e shell
install UniLog