.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Message::Passing 3pm" .TH Message::Passing 3pm "2017-08-02" "perl v5.26.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Message::Passing \- a simple way of doing messaging. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& message\-pass \-\-input STDIN \-\-output STDOUT \& {"foo": "bar"} \& {"foo":"bar"} .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" A library for building high performance, loosely coupled and reliable/resilient applications, structured as small services which communicate over the network by passing messages. .SS "\s-1BASIC PREMISE\s0" .IX Subsection "BASIC PREMISE" You have data for discrete events, represented by a hash (and serialized as \s-1JSON\s0). .PP This could be a text log line, an audit record of an \s-1API\s0 event, a metric emitted from your application that you wish to aggregate and process \- anything that can be a simple hash really.. .PP 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. .PP 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. .PP For a practical example, You generate events from a source (e.g. ZeroMQ output of logs and performance metrics from your Catalyst \s-1FCGI\s0 or Starman workers) and run one script that will give you a central application log file, or push the logs into Elasticsearch. .PP There are a growing set of components you can plug together to make your solution. .PP Getting started is really easy \- you can just use the \f(CW\*(C`message\-passing\*(C'\fR 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. .PP To dive straight in, see the documentation for the command line utility message-passing, and see the examples in Message::Passing::Manual::Cookbook. .PP For more about how the system works, see Message::Passing::Manual::Concepts. .SH "COMPONENTS" .IX Header "COMPONENTS" Below is a non-exhaustive list of components available. .SS "\s-1INPUTS\s0" .IX Subsection "INPUTS" Inputs receive data from a source (usually a network protocol). .PP They are responsible for decoding the data into a hash before passing it onto the next stage. .PP Inputs include: .IP "Message::Passing::Input::STDIN" 4 .IX Item "Message::Passing::Input::STDIN" .PD 0 .IP "Message::Passing::Input::ZeroMQ" 4 .IX Item "Message::Passing::Input::ZeroMQ" .IP "Message::Passing::Input::STOMP" 4 .IX Item "Message::Passing::Input::STOMP" .IP "Message::Passing::Input::AMQP" 4 .IX Item "Message::Passing::Input::AMQP" .IP "Message::Passing::Input::Syslog" 4 .IX Item "Message::Passing::Input::Syslog" .IP "Message::Passing::Input::Redis" 4 .IX Item "Message::Passing::Input::Redis" .IP "Message::Passing::Input::Test" 4 .IX Item "Message::Passing::Input::Test" .PD .PP You can easily write your own input, just use AnyEvent, and consume Message::Passing::Role::Input. .SS "\s-1FILTER\s0" .IX Subsection "FILTER" Filters can transform a message in any way. .PP Examples include: .IP "Message::Passing::Filter::Null \- Returns the input unchanged." 4 .IX Item "Message::Passing::Filter::Null - Returns the input unchanged." .PD 0 .IP "Message::Passing::Filter::All \- Stops any messages it receives from being passed to the output. I.e. literally filters all input out." 4 .IX Item "Message::Passing::Filter::All - Stops any messages it receives from being passed to the output. I.e. literally filters all input out." .IP "Message::Passing::Filter::T \- Splits the incoming message to multiple outputs." 4 .IX Item "Message::Passing::Filter::T - Splits the incoming message to multiple outputs." .PD .PP You can easily write your own filter, just consume Message::Passing::Role::Filter. .PP Note that filters can be chained, and a filter can return undef to stop a message being passed to the output. .SS "\s-1OUTPUTS\s0" .IX Subsection "OUTPUTS" Outputs send data to somewhere, i.e. they consume messages. .IP "Message::Passing::Output::STDOUT" 4 .IX Item "Message::Passing::Output::STDOUT" .PD 0 .IP "Message::Passing::Output::AMQP" 4 .IX Item "Message::Passing::Output::AMQP" .IP "Message::Passing::Output::STOMP" 4 .IX Item "Message::Passing::Output::STOMP" .IP "Message::Passing::Output::ZeroMQ" 4 .IX Item "Message::Passing::Output::ZeroMQ" .IP "Message::Passing::Output::WebHooks" 4 .IX Item "Message::Passing::Output::WebHooks" .IP "Message::Passing::Output::Search::Elasticsearch" 4 .IX Item "Message::Passing::Output::Search::Elasticsearch" .IP "Message::Passing::Output::Redis" 4 .IX Item "Message::Passing::Output::Redis" .IP "Message::Passing::Output::Test" 4 .IX Item "Message::Passing::Output::Test" .PD .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "Message::Passing::Manual \- The manual (contributions cherished)" 4 .IX Item "Message::Passing::Manual - The manual (contributions cherished)" .PD 0 .IP " \- Slide deck!" 4 .IX Item " - Slide deck!" .IP "Log::Message::Structured \- For creating your log messages." 4 .IX Item "Log::Message::Structured - For creating your log messages." .IP "Log::Dispatch::Message::Passing \- use Message::Passing outputs from Log::Dispatch." 4 .IX Item "Log::Dispatch::Message::Passing - use Message::Passing outputs from Log::Dispatch." .PD .SH "THIS MODULE" .IX Header "THIS MODULE" This is a simple MooX::Options script, with one input, one filter and one output. To build your own similar scripts, see: .IP "Message::Passing::DSL \- To declare your message chains" 4 .IX Item "Message::Passing::DSL - To declare your message chains" .PD 0 .ie n .IP "Message::Passing::Role::CLIComponent \- To provide ""foo"" and ""foo_options"" attribute pairs." 4 .el .IP "Message::Passing::Role::CLIComponent \- To provide \f(CWfoo\fR and \f(CWfoo_options\fR attribute pairs." 4 .IX Item "Message::Passing::Role::CLIComponent - To provide foo and foo_options attribute pairs." .IP "Message::Passing::Role::Script \- To provide daemonization features." 4 .IX Item "Message::Passing::Role::Script - To provide daemonization features." .PD .SS "\s-1METHODS\s0" .IX Subsection "METHODS" \fIbuild_chain\fR .IX Subsection "build_chain" .PP Builds and returns the configured chain of input => filter => output .PP \fIstart\fR .IX Subsection "start" .PP 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. .PP This is the entry point for the script. .SH "AUTHOR" .IX Header "AUTHOR" Tomas (t0m) Doran .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs" .IX Subsection "Bugs" Please log bugs at rt.cpan.org. Each distribution has a bug tracker link in it's metacpan.org page. .SS "Discussion" .IX Subsection "Discussion" #message\-passing on irc.perl.org. .SS "Source code" .IX Subsection "Source code" Source code for all modules is available at and forks / patches are very welcome. .SH "SPONSORSHIP" .IX Header "SPONSORSHIP" This module exists due to the wonderful people at Suretec Systems Ltd. who sponsored its development for its VoIP division called SureVoIP for use with the SureVoIP \s-1API\s0 \- .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright Suretec Systems Ltd. 2012. .PP Logstash (upon which many ideas for this project is based, but which we do not reuse any code from) is copyright 2010 Jorden Sissel. .SH "LICENSE" .IX Header "LICENSE" \&\s-1GNU\s0 Library General Public License, Version 2.1