NAME

Perlbal::Plugin::Syslogger - Perlbal plugin that adds low-impact syslog capabilities to client plugins

SYNOPSIS

    # 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

FUNCTIONS

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.

CONFIGURATION

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.

TRANSPORTS

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.

AUTHOR

Adam Thomason, <athomason@cpan.org>

COPYRIGHT AND LICENSE

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.