rec 1.0.9 → 1.1.0

data/.yardopts

@@ -1 +1 @@
---title "Ruby Event Correlation" -m rdoc --main README lib/**/*.rb - README EXAMPLES 
+--title "Ruby Event Correlation" -m rdoc --main README lib/**/*.rb - README EXAMPLES MULTIPLEX

data/CHANGELOG

@@ -1,14 +1,18 @@
+Version 1.1.0::
+    - Added mplex.rb to support merging of event streams
+    - Added MULTIPLEX documentation
+
 Version 1.0.9::
-    Removed mock-notify.rb
+    - Removed mock-notify.rb
 
 Version 1.0.7::
-	Simplified rdoc markup for the benefit of yard.
+	- Simplified rdoc markup for the benefit of yard.
 
 Version 1.0.6::
-	Restructured for better compatibility with gem standards
+	- Restructured for better compatibility with gem standards
 
 Version 1.0.4::
-	Added examples
+	- Added examples
 
 Version 1.0.1::
-	Initial version
+	- Initial version

data/EXAMPLES

@@ -223,3 +223,7 @@ can be abbreviated in this way:
     :message => "User %user$s signed in via SSH from %ip$s",
     :action => State::Generate_and_release
   })
+
+To write rules across multiple event streams, you'll need a way to +tail+ several log
+files and merge the streams into a single input stream for REC. The mplex.rb tool does
+that for you - for more details, see the MULTIPLEX file.

data/MULTIPLEX

@@ -0,0 +1,36 @@
+= MULTIPLEX
+Merging and broadcasting event streams with +mplex.rb+ command line tool.
+
+== Purpose
+REC can correlate events from a single event source (a log file), and that can
+help to sift through each log and summarise it to a smaller set of meaningful
+events.
+
+But in more ambitious scenarios, we may need to correlate events from several
+files. For example:
+- SSH logs show one of the admins logging on
+- Sudo logs show that admin executing commands to restart the web server
+- Availability logs show the website was down for a short period
+
+And we want to correlate these events and prevent the normal alert that would
+be sent when the site is down.
+
+To do that, we'll need to merge the event streams into a single stream. That is
+what +mplex.rb+ does. It can merge several input streams into a single combined
+stream. It can also distribute the combined stream to one or more output streams.
+
+== Usage
+  mplex [OPTION] -i infile [-i infile2...] -o outfile [-o outfile2...]
+where mplex reads from at least one infile and writes to at least one outfiles.
+  --input, -i   the path to a log file to read from
+  --output, -o  the path to a log file to write to
+  --help, -h    display usage
+  --version, -v show version
+  --debug, -d   display each line on stdout as it is passes through mplex
+
+== Examples
+  $ mplex -i input1.log -i input2.log -o output3.log
+    combines two input files into a single output stream
+  $ mplex -i in.log -i in2.log -o out3.log -o out4.log -o out5.log
+    combines two input streams and writes to 3 output streams
+

data/README

@@ -17,6 +17,15 @@ Correlates events in order to generate a smaller set of more meaningful events.
 
     $ rulesets/rules.rb < /var/log/mail.log 3>missed.log 2>control.log > newevents.log
 
+- Use mplex.rb to merge event streams if desired
+
+    $ cd /var/log
+    $ mplex -i messages -i deamon -i authlog -o node4 -o node5
+
+This would take input *lines* from each input and write out to two log files, named
++node4+ and +node5+ (which may be used by other REC processes). See the link:file.MULTIPLEX.html
+for more details.
+
 == Why correlate events?
 We all know that we should read our log files. But reading log files is *really* boring,
 and frankly its easy to miss important things in all the superfluous detail.
@@ -27,6 +36,11 @@ smart enough to work out what needs monitoring and when you might want to pay at
 then wouldn't it be good if you could define those rules and let the computer do what it
 does best?
 
+Aside::
+    Like most computer techie people, I'll happily spend 6 hours trying
+    to figure out how to do a 3 hour job in 10 minutes.
+    -- Rev. James Cort, ASR
+
 === Generate meaning
 The logs of many applications are filled with entries that are quite low level - perhaps
 wonderful for debugging, but typically not terribly meaningful in terms of business.
@@ -216,4 +230,4 @@ By the magic of Ruby's #method_missing method (Yes, I'm looking at you Java!) we
 refer to any parameter succinctly instead of a cumbersome hash notation, so:
   state.threshold === state.params['threshold']
 
-For more examples, see the EXAMPLES page.
+For more examples, see the link:file.EXAMPLES.html page.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rec
 version: !ruby/object:Gem::Version 
-  hash: 5
+  hash: 19
   prerelease: 
   segments: 
   - 1
+  - 1
   - 0
-  - 9
-  version: 1.0.9
+  version: 1.1.0
 platform: ruby
 authors: 
 - Richard Kernahan
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-09-18 00:00:00 Z
+date: 2012-09-19 00:00:00 Z
 dependencies: []
 
 description: "\t\tSifts through your log files in real time, using stateful intelligence to determine\n\
@@ -30,11 +30,8 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: 
-- README
-- EXAMPLES
-- LICENSE
-- CHANGELOG
+extra_rdoc_files: []
+
 files: 
 - lib/rec.rb
 - lib/rec/rule.rb
@@ -48,6 +45,7 @@ files:
 - .yardopts
 - README
 - EXAMPLES
+- MULTIPLEX
 - LICENSE
 - CHANGELOG
 homepage: http://rubygems.org/gems/rec