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.