Perlbal::Plugin::Syslogger - Perlbal plugin that adds low-impact syslog capabilities to client plugins
# plugin package Perlbal::Plugin::MyPlugin; use Perlbal::Plugin::Syslogger 'send_syslog_msg'; sub register { my ($class, $svc) = @_; # explicit mode send_syslog_msg($svc, 'Registering MyPlugin'); $svc->register_hook('MyPlugin', 'start_http_request' => sub { send_syslog_msg($svc, 'Handling request in MyPlugin'); }); # implicit mode Perlbal::Plugin::Syslogger::replace_perlbal_log($svc); Perlbal::log(info => "log message"); } # perlbal config CREATE SERVICE fakeproxy SET role = reverse_proxy SET listen = 127.0.0.1:8080 # set these after role/listen and before plugins SET syslog_host = log-host SET syslog_port = 514 SET syslog_source = perlbal-host SET syslog_name = perlbal SET syslog_facility = 21 SET syslog_severity = 5 SET plugins = Syslogger, MyPlugin ENABLE fakeproxy
There are two (non-exclusive) ways of using the plugin. The explicit mode requires you to call send_syslog_msg for every log message. The implicit mode replaces Perlbal's standard Perlbal::log function.
send_syslog_msg($svc, $message)
Sends a single message via the transport specified by the service configuration (see below). The facility and severity cannot be changed.
send_syslog_msg does not append a newline to the message.
replace_perlbal_log($svc)
Replaces the current Perlbal::log with one described below that uses the service's configured transport. Any future calls to Perlbal::log--even if made in the context of another service's hook--will go through the provided service's transport.
Returns a reference to the previous implementation of Perlbal::log.
Perlbal::log($level, $message, [@values])
A non-blocking, compatible replacement for the normal STDOUT or Sys::Syslog implementation. $level is a string matching a Sys::Syslog severity level like "info" or "warning". If no @values are provided, $message is just a string. If @values are provided, $message is a printf format string and the @values are the printf values to be interpolated. A newline is appended if one is not present.
This function does not change the severity level used by send_syslog_msg.
capture_std_handles($svc)
Similar to replace_perlbal_log, this redirects all output destined for STDOUT and STDERR to go through the service's configured transport.
The following options are configurable with the SET command within the perlbal configuration file:
syslog_transport
Transport type: udp, tcp, or unix. Default udp.
syslog_host
For udp and tcp, host where the syslogd is running. For unix, path to UNIX socket. Default 127.0.0.1.
syslog_port
Port on syslog_host where syslogd listens. Default 514.
syslog_source
Name of the submitting service. Default "PerlbalSyslogger".
syslog_name
Host of the submitting service. Defaults to the local hostname, or "localhost" if that can't be determined.
syslog_facility
Numeric facility number to log to. Default LOG_LOCAL0.
syslog_severity
Numeric severity level to log to. Default LOG_NOTICE.
Although logging calls made with this module are non-blocking with both UDP or TCP transports, the choice impacts its efficiency and reliability characteristics.
UDP
In UDP mode, speed is emphasized over reliability; errors in sending typically result in lost messages. A fast XS path (via Log::Syslog::Fast) is used to construct log messages. Network errors (such as ICMP reject notifications) are ignored, as are OS errors (such as a filled send buffer).
TCP
In TCP mode, reliability is emphasized over speed. String manipulation is done in perl. Receipt of the log message by the remote syslogd is ensured by TCP acknowledgement. If the socket send buffer is full, unsent data will be buffered until it is writable again.
If the connection to syslogd is lost, the client will attempt to reconnect automatically. However, log messages which were not flushed before the connection was lost will not be resent.
Adam Thomason, <athomason@cpan.org>
Copyright (C) 2007-2010 by Six Apart, <cpan@sixapart.com>
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.6 or, at your option, any later version of Perl 5 you may have available.
To install Perlbal::Plugin::Syslogger, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Perlbal::Plugin::Syslogger
CPAN shell
perl -MCPAN -e shell install Perlbal::Plugin::Syslogger
For more information on module installation, please visit the detailed CPAN module installation guide.