NAME

Log::Syslog::Fast - Perl extension for sending syslog messages over TCP, UDP, or UNIX sockets with minimal CPU overhead.

SYNOPSIS

  use Log::Syslog::Fast ':all';
  my $logger = Log::Syslog::Fast->new(LOG_UDP, "127.0.0.1", 514, LOG_LOCAL0, LOG_INFO, "mymachine", "logger");
  $logger->send("log message", time);

DESCRIPTION

This module sends syslog messages over a network socket. It works like Sys::Syslog in setlogsock's 'udp', 'tcp', or 'unix' modes, but without the significant CPU overhead of that module when used for high-volume logging. Use of this specialized module is only recommended if 1) you must use network syslog as a messaging transport but 2) need to minimize the time spent in the logger.

This module supercedes the less general Log::Syslog::UDP.

METHODS

Log::Syslog::Fast->new($proto, $hostname, $port, $facility, $severity, $sender, $name);

Create a new Log::Syslog::Fast object with the following parameters:

$proto

The transport protocol: one of LOG_TCP, LOG_UDP, or LOG_UNIX.

If LOG_TCP or LOG_UNIX is used, calls to $logger->send() will block until remote receipt of the message is confirmed. If LOG_UDP is used, the call will never block and may fail if insufficient buffer space exists in the network stack.

$hostname

For LOG_TCP and LOG_UDP, the destination hostname where a syslogd is running. For LOG_UNIX, the path to the UNIX socket where syslogd is listening (typically /dev/log).

$port

For LOG_TCP and LOG_UDP, the destination port where a syslogd is listening, usually 514. Ignored for LOG_UNIX.

$facility

The syslog facility constant, eg 16 for 'local0'. See RFC3164 section 4.1.1 (or <sys/syslog.h>) for appropriate constant values. See EXPORTS below for making these available by name.

$severity

The syslog severity constant, eg 6 for 'info'. See RFC3164 section 4.1.1 (or <sys/syslog.h>) for appropriate constant values. See EXPORTS below for making these available by name.

$sender

The originating hostname. Sys::Hostname::hostname is typically a reasonable source for this.

$name

The program name or tag to use for the message.

$logger->send($logmsg, [$time])

$logger->emit($logmsg, [$time])

Send a syslog message through the configured logger. If $time is not provided, CORE::time() will be called for you. That doubles the syscalls per message, so try to pass it if you're already calling time() yourself.

emit is an alias for send.

NEWLINE CAVEAT

Note that send does not add any newline character(s) to its input. You will certainly want to do this yourself for TCP connections, or the server will not treat each message as a separate line. However with UDP the server should accept a message without a trailing newline (though some implementations may have difficulty with that).

$logger->set_receiver($hostname, $port)

Change the destination host and port. This will force a reconnection in LOG_TCP or LOG_UNIX mode.

$logger->set_priority($facility, $severity)

Change the syslog facility and severity.

$logger->set_sender($sender)

Change what is sent as the hostname of the sender.

$logger->set_name($name)

Change what is sent as the name of the sending program.

$logger->set_pid($name)

Change what is sent as the process id of the sending program.

EXPORTS

Use Log::Syslog::Constants to export priority constants, e.g. LOG_INFO.

SEE ALSO

Log::Syslog::Constants

Sys::Syslog

AUTHOR

Adam Thomason, <athomason@sixapart.com>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Six Apart, Ltd.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.