/ 
Tie-Syslog-2.04.03
River stage one • 1 direct dependent • 1 total dependent
/ Tie::Syslog

NAME

Tie::Syslog - Tie a filehandle to Syslog.

VERSION

2.04.03

v2.00 is a complete rewrite of Tie::Syslog. If you used v1.x and something broke after upgrade, please report the problem back and I'll try to fix it asap. Thanks.

SYNOPSIS

use Tie::Syslog;

$Tie::Syslog::ident  = "my logging tag";
$Tie::Syslog::logopt = "pid,ndelay";

# Tie STDOUT to Syslog, so that every print()ed message will be logged
tie *STDOUT, 'Tie::Syslog', {
    facility => 'LOG_LOCAL0',
    priority => 'LOG_INFO',
};

# Now tie STDERR also, getting parameters from the tied STDOUT
tie *STDERR, { tied *STDOUT };

# ...or...

# tie STDERR with defaults from tied STDOUT, but override priority:
tie *STDERR, { tied *STDOUT }, {
    priority => 'LOG_ERR',
};

###### 
# Compatibility with old configuration style:

tie *STDOUT, 'Tie::Syslog', 
    'local0.error',         # facility.loglevel
    'myname',               # identity 
    'pid,ndelay',           # Other Sys::Syslog options, comma-separated
    'unix';                 # setlogsock socket type: unix or inet

tie *STDERR, 'Tie::Syslog', 
    'local0.warning',       # facility.loglevel
    'myname',               # USE THE SAME AS ABOVE!
    'pid,ndelay',           # USE THE SAME AS ABOVE!
    'unix';                 # USE THE SAME AS ABOVE!

# Tying by copying from another tied handle is not supported in 
# old-compatibility-mode

# old-compatibility-mode defaults to 'local0.error'

# socket type is IGNORED

DESCRIPTION

This module lets you tie a filehandle to Sys::Syslog, providing an easy way to redirect messages to system logs.

$Tie::Syslog::ident  = 'DEBUG :: myprocess';
$Tie::Syslog::logopt = 'pid,ndelay';

tie *DEBUG, 'Tie::Syslog', {
    facility => 'LOG_LOCAL0',
    priority => 'LOG_DEBUG',
};

print DEBUG "This is a debug message - won't probably get to system logs.";

By tying STDOUT and/or STDERR you can easily redirect all messages to system logs, including those of warn() and die().

Tipically, you'll want to tie STDOUT with a lower priority than STDERR.

OPTIONS

$Tie::Syslog::ident

Identity set for logging. This is a global option, and will be valid from the moment you set it onward. The default value is the last field of $0 split on '/'.

$Tie::Syslog::logopt

Logging options. These are standard Sys::Syslog logopts. See Sys::Syslog man page for details. This is a global option, default is 'pid,ndelay'.

facility

One of the default Sys::Syslog facilities available on your system. See Sys::Syslog man page for details. You can have different facilities for different filehandles, but this is not recommended, and will prevent Tie::Syslog from calling closelog() (see "CAVEATS" for details).

You can redefine a the facility for a given filehandle on the fly:

my $fho = tied *MYFH;
$fho->facility('LOG_MAIL');

# better: 

(tied *MYFH)->facility('LOG_MAIL');

# better yet: don't do it

but please note that this is against Sys::Syslog rule:

  • "The Fourth Rule of Sys::Syslog is: One facility, one priority." (from Sys::Syslog man page).

priority

One of the default Sys::Syslog priorities available on your system. See Sys::Syslog man page for details. You can have different priorities for different filehandles.

You can redefine the priority for a given filehandle on the fly:

my $fho = tied *MYFH;
$fho->priority('LOG_CRIT');

# better: 

(tied *MYFH)->priority('LOG_CRIT');

CAVEATS

  • We set the most permissive mask for log levels, so that nothing should be filtered by Sys::Syslog itself, but some messages may still be filtered, according to your syslog daemon configuration. Consult your local syslog daemon documentation.

  • We do not call closelog() in case multiple facilities are in use

    In general, openlog() is called automatically whenever syslog() is called on a new facility (although we call it explicitly on tie()). Since closelog() would work just once and on the last opened connetion to syslog, it could close a connection completely unrelated to the filehandle currently being closed/untied/destroyed. In case you tied multiple filehandles over multiple faiclities (you shouldn't, see Sys::Syslog for details), closelog() won't be called at all.

  • ident and/or logopt should be set once, before tying handles.

    If change these variables after tying handles, the behavior is undetermined. At best, nothing should change; or settings could change if another openlog() is called afterwards, but don't rely on this. Also, if settings change, they will affect all tied filehandles. For these reasons, either:

    • Set them once at the beginning, or

    • if you're tying two or more handles using old-style syntax, use the same values for all of them.

  • Old method ExtendedSTDERR() is no-op by default.

    It is still supported for backward compatibility, but warn() and die() print by default to STDERR so there should be no need to change them directly.

  • We do not call setlogsock()

SEE ALSO

Log priorities, facilities and valid values for logopt are listed in Sys::Syslog man page.

Read syslog(3) for details on syslog.

AUTHOR

Broc Seib, bseib at purdue.edu - up to 1.07

Giacomo Montagner, <kromg at entirelyunlike.net> - from 2.00 onward.

BUGS

Please report any bugs or feature requests to bug-tie-syslog at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Tie-Syslog. I'will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Tie::Syslog

You can also look for information at:

ACKNOWLEDGEMENTS

Many thanks to Broc Seib, who wrote this module back in 1999.

LICENSE AND COPYRIGHT

Copyright (C) 1999-2001 Broc Seib

Copyright (C) 2012 Giacomo Montagner.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/ for more information.