Message::Passing::Manual::Cookbook(3pm)

NAME
Message::Passing::Manual::Cookbook - Common recipies

Aggregating logs

  Logging from an application.
You can use Log::Dispatch, or any log system which will output into Log::Dispatch.

    use Log::Dispatch;
    use Log::Dispatch::Message::Passing;
    use Message::Passing::Filter::Encoder::JSON;
    use Message::Passing::Output::ZeroMQ;

    my $log = Log::Dispatch->new;

    $log->add(Log::Dispatch::Message::Passing->new(
        name      => 'myapp_aggregate_log',
        min_level => 'debug',
        output    => Message::Passing::Filter::Encoder::JSON->new(
            output_to => Message::Passing::Output::ZeroMQ->new(
                connect => 'tcp://192.168.0.1:5558',
            ),
        ),
    ));

    $log->warn($_) for qw/ foo bar baz /;

  Aggregating this log
As simple as using the command line interface:

    message-pass --input ZeroMQ --input_options '{"socket_bind":"tcp://192.168.0.1:5558"}' \
        --output File --output_options '{"filename":"/tmp/mylog"}'

And you've now got a multi-host log aggregation system for your application!

  Doing it manually
You don't have to do any of the above, if you don't want to - you can easily reuse the ZeroMQ output yourself:

    my $log = Message::Passing::Output::ZeroMQ->new(
        connect => 'tcp://192.168.0.1:5558',
        linger  => 1,  # make sure message is sent (flushed) before thread dies
    );
    $log->consume("A log message");

  A note about outputs
ZeroMQ is the recommended output for sending messages from within your application. This is because ZeroMQ uses a different (POSIX) thread to send messages - meaning that it transports messages independently to whatever your perl code is doing.

This is not the case for other message outputs, and therefore they are unlikely to work well, or at all, unless your application is already asynchronous and using an AnyEvent supported event library.

  A note about ZeroMQ
By default Message::Passing::ZeroMQ will use PUB/SUB sockets for logging, with a finite 'high water mark'.

This means that if your application logs significantly more data than you can fit down the network, you will drop logs.

If your application needs to do this, you can either increase this high water mark, or disable it (so ZeroMQ will buffer an infinite number of messages at the sending client - potentially using infinite RAM).

The default setting is for the output to buffer up to 10000 messages on the output side, which should be enough to manage short term peaks, but is low enough to be reasonably safe in terms of memory consumption for buffering

Aggregating syslog
Assuming that you've got a regular syslogd setup and working, then you probably want to keep that. Having some of the log files on individual hosts can be very useful. Also, we'd like to avoid the script being a privileged user (which would be needed to get the standard port).

Therefore, we'll run a syslog listener on a high port (5140), and get the regular syslogd to ship messages to it. The listener will then forward from each host to a central aggregate logger (which is setup as above).

  On host collector
    message-pass --input Syslog --output ZeroMQ --output_options '{"connect":"tcp://192.168.0.1:5558"}'

  Configuring your syslogd
This should be easy, here's an example of what to add to rsyslogd.conf to get the syslog resent.

    *.* =192.168.0.1:5140

Aggregating everything
If you have hosts with both applications and syslog that you want to aggregate, then you can easily do both at once. This also means that your apps ship logs to a local buffer process rather than directly across the network - which is more resilient to short network outages.

AUTHOR, COPYRIGHT & LICENSE
See Message::Passing.