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.