[libmessage-passing-zeromq-perl] 08/78: More docs

[Jonas Smedegaard]

This is an automated email from the git hooks/post-receive script.

js pushed a commit to branch master
in repository libmessage-passing-zeromq-perl.

commit a82088a51c7fcd38f43d66486bf721097c145f9e
Author: Tomas Doran <bobtfish at bobtfish.net>
Date:   Sat Feb 25 20:49:14 2012 +0000

    More docs
---
 lib/Log/Stash/Output/ZeroMQ.pm |   29 +++++++++++++++++++++++++++++
 lib/Log/Stash/ZeroMQ.pm        |   38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)

diff --git a/lib/Log/Stash/Output/ZeroMQ.pm b/lib/Log/Stash/Output/ZeroMQ.pm
index eae3ba8..0981e66 100644
--- a/lib/Log/Stash/Output/ZeroMQ.pm
+++ b/lib/Log/Stash/Output/ZeroMQ.pm
@@ -50,8 +50,37 @@ with 'Log::Stash::Role::Output';
 
 Log::Stash::Output::ZeroMQ - output logstash messages to ZeroMQ.
 
+=head1 SYNOPSIS
+
+    use Log::Stash::Output::ZeroMQ;
+    
+    my $logger = Log::Stash::Output::ZeroMQ->new;
+    $logger->consume({data => { some => 'data'}, '@metadata' => 'value' });
+
+    # You are expected to produce a logstash message format compatible message,
+    # see the documentation in Log::Stash for more details.
+    
+    # Or see Log::Dispatch::Log::Stash for a more 'normal' interface to
+    # simple logging.
+    
+    # Or use directly on command line:
+    logstash --input STDIN --output ZeroMQ
+    {"data":{"some":"data"},"@metadata":"value"}
+
 =head1 DESCRIPTION
 
+A L<Log::Stash> L<ZeroMQ> output class.
+
+Can be used as part of a chain of classes with the L<logstash> utility, or directly as
+a logger in normal perl applications.
+
+=head1 CAVEAT
+
+You cannot send ZeroMQ messages and then call fork() and send more ZeroMQ messages!
+
+If you need to call fork(), and you're not going to immediately exec() another process, you B<MUST>
+call FIXME MAKE THIS WORK!!!! 
+
 =head1 SEE ALSO
 
 =over
diff --git a/lib/Log/Stash/ZeroMQ.pm b/lib/Log/Stash/ZeroMQ.pm
index f54b7d0..2d9e2db 100644
--- a/lib/Log/Stash/ZeroMQ.pm
+++ b/lib/Log/Stash/ZeroMQ.pm
@@ -12,8 +12,46 @@ $VERSION = eval $VERSION;
 
 Log::Stash::ZeroMQ - input and output logstash messages to ZeroMQ.
 
+=head1 SYNOPSIS
+
+    # Terminal 1:
+    $ logstash --input STDIN --output ZeroMQ
+    {"data":{"some":"data"},"@metadata":"value"}
+    
+    # Terminal 2:
+    $ logstash --output STDOUT --input ZeroMQ
+    {"data":{"some":"data"},"@metadata":"value"}
+
 =head1 DESCRIPTION
 
+A L<ZeroMQ> transport for L<Log::Stash>.
+
+Designed for use as a log transport and aggregation mechanism for perl applications, allowing you
+to aggregate structured and non-structured log messages across the network in a non-blocking manor.
+
+Clients (I.e. users of the L<Log::Stash::Output::ZeroMQ> class) connect to a server (I.e. a user of the
+L<Log::Stash::Input::ZeroMQ class) via ZeroMQ's pub/sub sockets. These are setup to be lossy and non-blocking,
+meaning that if the log-receiver process is down or slow, then the application will queue a small (and configurable)
+amount of logs on it's side, and after that log messages will be dropped.
+
+Whilst throwing away log messages isn't a good thing to do, or something that you want to happen regularly,
+in many (especially web application) contexts, network logging being a single point of failure is
+unaccaptable from a reliablilty and graceful degredation standpoint.
+
+The application grinding to a halt as a non-essential centralised resource is unavailable (e.g. the log aggregation
+server) is significnalty less acceptable than the loss of non-essential logging data.
+
+=head1 HOW TO USE
+
+In your application emitting messages, you can either use L<Log::Stash::Output::ZeroMQ> directly, of you can use
+it via L<Log::Dispatch::Log::Stash>.
+
+    # FIXME - Example code, including overriding IP to connect to here
+
+On your log aggregation server, just run the logstash utility:
+
+    # FIXME - Example command line here
+
 =head1 SEE ALSO
 
 =over

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libmessage-passing-zeromq-perl.git