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'.

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()

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:

RT: CPAN's request tracker (report bugs here)
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tie-Syslog>
AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/Tie-Syslog>
CPAN Ratings
<http://cpanratings.perl.org/d/Tie-Syslog>
Search CPAN
<http://search.cpan.org/dist/Tie-Syslog/>

ACKNOWLEDGEMENTS

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

LICENSE AND COPYRIGHT

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.