NAME
Message::Passing - a simple way of doing messaging.
SYNOPSIS
message-pass --input STDIN --output STDOUT
{"foo": "bar"}
{"foo":"bar"}
DESCRIPTION
A library for building high performance, loosely coupled and
reliable/reseliant applications, structured as small services which
communicate over the network by passing messages.
BASIC PREMISE
You have data for discrete events, represented by a hash (and serialized
as JSON).
This could be a text log line, an audit record of an API event, a metric
emitted from your application that you wish to aggregate and process -
anything that can be a simple hash really..
You want to be able to shove these events over the network easily, and
aggregate them / filter and rewrite them / split them into worker
queues.
This module is designed as a simple framework for writing components
that let you do all of these things, in a simple and easily extensible
manor.
For a practical example, You generate events from a source (e.g. ZeroMQ
output of logs and performance metrics from your Catalyst FCGI or
Starman workers) and run one script that will give you a central
application log file, or push the logs into ElasticSearch.
There are a growing set of components you can plug together to make your
solution.
Getting started is really easy - you can just use the "message-passing"
command installed by the distribution. If you have a common config that
you want to repeat, or you want to write your own server which does
something more flexible than the normal script allows, then see
Message::Passing::DSL.
To dive straight in, see the documentation for the command line utility
message-passing, and see the examples in
Message::Passing::Manual::Cookbook.
For more about how the system works, see
Message::Passing::Manual::Concepts.
COMPONENTS
Below is a non-exhaustive list of components available.
INPUTS
Inputs receive data from a source (usually a network protocol).
They are responsible for decoding the data into a hash before passing it
onto the next stage.
Inputs include:
Message::Passing::Input::STDIN
Message::Passing::Input::ZeroMQ
Message::Passing::Input::STOMP
Message::Passing::Input::AMQP
Message::Passing::Input::Syslog
Message::Passing::Input::Redis
Message::Passing::Input::Test
You can easily write your own input, just use AnyEvent, and consume
Message::Passing::Role::Input.
FILTER
Filters can transform a message in any way.
Examples include:
Message::Passing::Filter::Null - Returns the input unchanged.
Message::Passing::Filter::All - Stops any messages it receives from
being passed to the output. I.e. literally filters all input out.
Message::Passing::Filter::T - Splits the incoming message to multiple
outputs.
You can easily write your own filter, just consume
Message::Passing::Role::Filter.
Note that filters can be chained, and a filter can return undef to stop
a message being passed to the output.
OUTPUTS
Outputs send data to somewhere, i.e. they consume messages.
Message::Passing::Output::STDOUT
Message::Passing::Output::AMQP
Message::Passing::Output::STOMP
Message::Passing::Output::ZeroMQ
Message::Passing::Output::WebHooks
Message::Passing::Output::ElasticSearch - COMING SOON
(<https://github.com/suretec/Message-Passing-Output-ElasticSearch>)
Message::Passing::Output::Redis
Message::Passing::Output::Test
SEE ALSO
Message::Passing::Manual - The manual (incomplete currently)!
<http://www.slideshare.net/bobtfish/messaging-interoperability-and-log-a
ggregation-a-new-framework> - Slide deck!
Log::Message::Structured - For creating your log messages.
Log::Dispatch::Message::Passing - use Message::Passing outputs from
Log::Dispatch.
THIS MODULE
This is a simple MooX::Options script, with one input, one filter and
one output. To build your own similar scripts, see:
Message::Passing::DSL - To declare your message chains
Message::Passing::Role::CLIComponent - To provide "foo" and
"foo_options" attribute pairs.
Message::Passing::Role::Script - To provide daemonization features.
METHODS
build_chain
Builds and returns the configured chain of input => filter => output
start
Class method to call the run_message_server function with the results of
having constructed an instance of this class, parsed command line
options and constructed a chain.
This is the entry point for the script.
AUTHOR
Tomas (t0m) Doran <bobtfish@bobtfish.net>
SUPPORT
Bugs
Please log bugs at rt.cpan.org. Each distribution has a bug tracker link
in it's metacpan.org page.
Discussion
#message-passing on irc.perl.org.
Source code
Source code for all modules is available at <http://github.com/suretec>
and forks / patches are very welcome.
SPONSORSHIP
This module exists due to the wonderful people at Suretec Systems Ltd.
<http://www.suretecsystems.com/> who sponsored its development for its
VoIP division called SureVoIP <http://www.surevoip.co.uk/> for use with
the SureVoIP API -
<http://www.surevoip.co.uk/support/wiki/api_documentation>
COPYRIGHT
Copyright Suretec Systems Ltd. 2012.
Logstash (upon which many ideas for this project is based, but which we
do not reuse any code from) is copyright 2010 Jorden Sissel.
LICENSE
GNU Affero General Public License, Version 3
If you feel this is too restrictive to be able to use this software,
please talk to us as we'd be willing to consider re-licensing under less
restrictive terms.