rec 1.0.1 → 1.0.2

data/lib/rec/correlator.rb

@@ -1,11 +1,14 @@
 require 'rec/rule'
 
-module REC
+module REC	# :nodoc:
 
 # The Correlator reads in log entries, matching them against the ruleset,
 # creates states as necessary, generates new (correlated) events, and sends alerts.
 class Correlator
 
+	# The current time from the perspective of the latest event processed,
+	# not necessarily actual clock time.
+	@@now = Time.now()
 	@@eventsIn = 0
 	@@eventsMissed = 0
 
@@ -16,9 +19,14 @@ class Correlator
 		self.new().start()
 	end
 
+	# Makes the current processing time effectively global
+	def self.now()
+		@@now
+	end
+
 	# Create a new Correlator
 	def initialize()
-		@time = @startupTime = Time.now()
+		@startupTime = Time.now()
 		@year = @startupTime.year
 		@running = false
 	end
@@ -26,7 +34,7 @@ class Correlator
 	# Start a Correlator. +INT+ and +TERM+ signals will stop the Correlator.
 	# +USR1+ signal will cause Correlator to display statistics and continue running.
 	#
-	# Missed events are written to IO Stream 3, in case they are of interest
+	# Missed events are written to File Descriptor 3, in case they are of interest
 	# (typically while testing rulesets)
 	def start()
 		Signal.trap("INT")  { finish() }
@@ -55,17 +63,17 @@ class Correlator
 			logLine.strip!()
 			next if logLine.empty?
 			@@eventsIn += 1
-			@time, message = parse(logLine)
+			@@time, message = parse(logLine)
 			$stderr.puts("< "+message) if $debug
-			State.expire_states(@time)	# remove expired states before we check the rules
+			State.expire_states()	# remove expired states before we check the rules
 			eventMatched = false
 			Rule.each { |rule|
 				title = rule.check(message)
 				eventMatched = true unless title.nil?	# empty match is still a match
 				next if title.nil?
 				break if title.empty?	# match without a message means 'swallow this event'
-				state = State[title] || rule.create_state(title, @time)
-				rule.react(state, @time, logLine)
+				state = State[title] || rule.create_state(title)
+				rule.react(state, logLine)
 				$stderr.puts("breaking after rule #{rule.rid}") unless (!$debug or rule.continue())
 				break unless rule.continue()
 			}
@@ -110,7 +118,7 @@ class Correlator
 			end
 			message = $'
 		else
-			time = @time	# time stands still
+			time = Correlator.now().freeze()	# time stands still
 			message = logLine
 		end
 		[time, message]

data/lib/rec/{mock-alert.rb → mock-notify.rb}

@@ -1,23 +1,27 @@
-module REC
-# :nodoc:all
-# mock the Alert class for testing purposes
-class Alert
+module REC	# :nodoc:
+
+# mock the Notify class for testing purposes
+# :nodoc:
+class Notify
 
 	@@emailsSent = []
 	@@jabbersSent = []
-
+	# :nodoc:
 	def self.email(alert, recipient=@@emailTo, subject=@@defaultSubject)
 		@@emailsSent << [alert, recipient, subject]
 	end
 
+	# :nodoc:
 	def self.jabber(alert, recipient=@@jabberTo, subject=@@defaultSubject)
 		@@jabbersSent << [alert, recipient, subject]
 	end
 
+	# :nodoc:
 	def emailsSent()
 		@@emailsSent
 	end
 
+	# :nodoc:
 	def jabbersSent()
 		@@jabberSent
 	end

data/lib/rec/{alert.rb → notify.rb}

@@ -2,33 +2,34 @@ require 'rubygems'
 require 'net/smtp'
 require 'xmpp4r'
 
-module REC
+module REC	# :nodoc:
+
 # Provides the capability to send alerts
 # == mail
 # The simplest approach is to use the native +mail+ program (no credentials required)
-#	Alert.mail(alert)
+#	Notify.mail(alert)
 #
 # == email and jabber
 # You can also send emails and instant messages via servers, but you'll need to provide
 # credentials to do that.
-# 	Alert.smtp_credentials(user, password, domain, server, port)
-#	Alert.jabber_credentials(user, password, server)
+# 	Notify.smtp_credentials(user, password, domain, server, port)
+#	Notify.jabber_credentials(user, password, server)
 #
 # Then you can send messages:
-#	Alert.email(alert)
-#	Alert.jabber(alert)
+#	Notify.email(alert)
+#	Notify.jabber(alert)
 # or send messages to another recipient, with another subject
-#	Alert.email(alert, you@example.com, "Serious problem")
-#	Alert.jabber(alert, boss@example.com)
+#	Notify.email(alert, you@example.com, "Serious problem")
+#	Notify.jabber(alert, boss@example.com)
 #
 # == Sleeping
 # If you want to avoid being sent instant messages during sleeping hours, you can
 # specify a range of working hours during which urgent alerts may be sent by jabber
 # and outside those working hours the alert will be sent by email instead
-#	Alert.workHours(9,18)		# IMs only between 9am and 6pm
-#	Alert.urgent(alert)		# sent as instant message if during work hours, else by email
-#	Alert.jabber(alert)		# sent as instant message regardless of the time
-#	Alert.normal(alert)		# sent by email
+#	Notify.workHours(9,18)		# IMs only between 9am and 6pm
+#	Notify.urgent(alert)		# sent as instant message if during work hours, else by email
+#	Notify.jabber(alert)		# sent as instant message regardless of the time
+#	Notify.normal(alert)		# sent by email
 #
 # == Securing credentials
 # In order to keep email/messaging credentials secure, they can be provided in
@@ -36,13 +37,13 @@ module REC
 # so the rules script need not contain passwords.
 #	load("/home/rec/alert.conf")
 # Loads the credentials into the rules. The file can contain something like:
-# 	Alert.email_credentials("rec@gmail.com", "tricky", "mydomain.com")
-#	Alert.jabber_credentials("rec@gmail.com", "tricky")
+# 	Notify.email_credentials("rec@gmail.com", "tricky", "mydomain.com")
+#	Notify.jabber_credentials("rec@gmail.com", "tricky")
 # <code>/home/rec/alert.conf</code> should be readable only by the otherwise
 # unprivileged user (sec) running the script.
 #
-# While we're on the topic of security, just a reminder that Alert::mail requires no credentials.
-module Alert
+# While we're on the topic of security, just a reminder that Notify::mail requires no credentials.
+module Notify
 
 	# Sets the default subject for alerts, overriding the system default of "Alert"
 	def self.default_subject(subject)
@@ -100,7 +101,7 @@ module Alert
 	end
 
 	# define the working hours during which instant messages are allowed
-	# Note that Alert.work_hours(7,21) means "7am-9pm" as you would assume, so from 07:00 to 20:59
+	# Note that Notify.work_hours(7,21) means "7am-9pm" as you would assume, so from 07:00 to 20:59
 	def self.work_hours(start, finish)
 		@@workHours = start..finish
 	end
@@ -115,7 +116,7 @@ module Alert
 		end
 	end
 
-	# Alias for Alert::email
+	# Alias for Notify::email
 	def self.normal(alert)
 		self.email(alert)
 	end

data/lib/rec/rule.rb

@@ -1,6 +1,6 @@
 require 'rec/state'
 
-module REC
+module REC	# :nodoc:
 
 # A Rule specifies which log entries to match, what to remember, and what to do about them.
 class Rule
@@ -71,21 +71,38 @@ class Rule
 	#	}) { |state|
 	#		state.alert_first_only()
 	#	}
-	attr_reader :action
+	def action()
+		@params[:action]
+	end
 
 	# Creates a new rule. +rid+ must be unique.
+	# +action+ may be supplied as a block argument:
+	#		:lifespan => 479
+	#	}) { |state|
+	#		state.alert_first_only()
+	#	}
+	# or as a Proc.new value to the :action key:
+	#		:lifespan => 479,
+	#		:action => Proc.new { |state|
+	#			state.alert_first_only()
+	#		}
+	#	})
+	# In most cases, an action is required when a state reacts with an event, but
+	# only in certain cases do we need an :onexpiry block. That is why the action
+	# may be supplied as a block if desired.
+	#
 	def initialize(rid, params={}, &action)
 		@rid = rid
 		@pattern = params[:pattern] || raise("No pattern specified for rule #{@ruleId}")
 		@message = params[:message] || ""	# no message means no state created - ie. ignore event
 		@lifespan = params[:lifespan] || 0
-		@alert = params[:alert] || @message
 		@allstates = params[:allstates] || []
 		@anystates = params[:anystates] || []
 		@notstates = params[:notstates] || []
 		@details = params[:details] || []
 		@params = params
-		@action = action
+		@params[:action] = action unless action.nil?	# store the action into the params
+		@params[:alert] = @params[:message] unless @params.has_key?(:alert)	# default alert if absent
 		@matches = nil
 		Rule << self
 	end
@@ -107,18 +124,18 @@ class Rule
 	end
 
 	# Creates a state with the given title at the specified time
-	def create_state(title, time)
+	def create_state(title)
 		@@created[@rid] += 1
 		$stderr.puts("+ Creating new state  #{title}") if $debug
-		State.new(title, time, @lifespan, @params)
+		State.new(title, @lifespan, @params)
 	end
 
 	# Executes any action specified by the rule
-	def react(state, time, logLine)
+	def react(state, logLine)
 		@@reacted[@rid] += 1
-		state.update(time, @rid, @matches, @alert, logLine)
+		state.update(@rid, @matches, logLine)
 		$stderr.puts("~ Rule #{@rid}, state = #{state.inspect()}") if $debug
-		@action.call(state) if @action
+		action().call(state) if action()
 	end
 
 	# Returns the +continue+ parameter. If false, stop processing rules for this event.

data/lib/rec/state.rb

@@ -1,6 +1,6 @@
 require 'time'
 
-module REC
+module REC	# :nodoc:
 
 # A State is an object that represents the memory of something having happened.
 # For example, "server terra is down".
@@ -17,6 +17,22 @@ module REC
 # of what has gone before. You cannot *correlate* events without keeping State.
 class State
 
+	# shortcut action to generate a message on each event
+	Generate = Proc.new { |state|
+		state.generate()
+	}
+
+	# shortcut action to generate a message and release the state immediately
+	Generate_and_release = Proc.new { |state|
+		state.generate()
+		state.release()
+	}
+
+	# shortcut action to generate a message on first event only
+	Generate_first_only = Proc.new { |state|
+		state.generate_first_only()
+	}
+
 	# A array of Timeouts. A Timeout struct has two elements:
 	# - timestamp at which to expire
 	# - key of the state to be expired
@@ -49,10 +65,10 @@ class State
 		end
 	end
 
-	# Deletes all expired states
-	def self.expire_states(time)
+	# Deletes all expired states, executing :onexpiry blocks before deletion
+	def self.expire_states()
 		timeout = @@timeouts.first()
-		while @@timeouts.length > 0 and timeout.expiry < time do
+		while @@timeouts.length > 0 and timeout.expiry < Correlator.now() do
 			state = State[timeout.key]
 			if state.nil?
 				@@timeouts.shift
@@ -60,6 +76,8 @@ class State
 				next
 			end
 			#$stderr.puts("Releasing state #{state.title} with count of #{state.count}")
+			final = Rule[state.rid].params[:final]
+			final.call(state) if final
 			@@states.delete(@@timeouts.shift().key)
 			timeout = @@timeouts.first()
 		end
@@ -73,6 +91,18 @@ class State
 		[statesCount, @@eventsOut]
 	end
 
+	# Returns a matching state or nil.
+	#
+	# This is used to locate a state, typically the other state created by a pair of
+	# rules. For example, in a rule handling "Server earth is up" we want to find the state
+	# corresponding to "Server earth is down"
+	# - template is a string like "Server %host$s is down"
+	# - state is the current state
+	def self.find(template, state)
+		title = template.sprinth(state.params)
+		@@states[title]
+	end
+
 	# unique ID of the rule which gave rise to this state
 	attr_reader :rid
 	# The unique title for this state (eg. "server earth is down")
@@ -81,6 +111,8 @@ class State
 	attr_reader :lifespan
 	# An alert message to be sent if subsequent events warrant it
 	attr_reader :alert
+	# An alert message to be sent when the state expires
+	attr_reader :final
 	# Hash of parameters of the rule that created this state
 	attr_reader :params
 	# Number of times this state has been matched
@@ -89,31 +121,28 @@ class State
 	attr_reader :created
 	# last time this state was updated
 	attr_reader :updated
-	# age of this state
-	attr_reader :dur
 	# Hash of custom fields to be remembered
 	attr_reader :details
+	# Array of original log entries matching this state
+	attr_reader :logs
 
-	# Creates a new state with the given (unique) +title+, the +time+ of creation,
+	# Creates a new state with the given (unique) +title+,
 	# the +lifespan+ before the state is forgotten, and a hash of parameters.
 	#
 	# Note that the time is not necessarily 'now' because REC can be executed against
 	# historical log files. It uses the timestamp of the original log entry, not the
 	# current clock time.
-	def initialize(title, time, lifespan, params={})
+	def initialize(title, lifespan, params={})
+		@created = @updated = Correlator.now()
 		@title = title
 		@lifespan = lifespan.to_f
 		@params = params
 		@count = 0
-		@created = time
-		@updated = time
-		@dur = 0
 		@rid = 0
-		@alert = ""
 		@logs = []		# array of remembered logLines
 		@details = {}	# hash of remembered details
 		@@states[title] = self
-		State.timeout_at(time + @lifespan, @title)
+		State.timeout_at(@created + @lifespan, @title)
 	end
 
 	# Updates the statistics of this state (following a match).
@@ -123,18 +152,21 @@ class State
 	# - age of this state
 	# - the ID of the rule which last matched
 	# - more details (custom fields) may be added to memory
-	# - the alert message
+	# - message templates (for values to be interpolated into)
 	# - a list of the original log entries pertaining to this state
-	def update(time, rid, matches, alert, logLine=nil)
+	def update(rid, matches, logLine=nil)
 		@count = @count.succ
-		@updated = time
-		@dur = @updated - @created
+		@updated = Correlator.now()
 		@rid = rid
 		@details.merge!(matches)
-		@alert = alert
 		@logs << logLine if @params[:capture]
 	end
 
+	# Returns the age of this state
+	def age
+		Correlator.now() - @created
+	end
+
 	# Forget a state.
 	# -	if no pattern is provided, forget this state.
 	# -	if a pattern is provided, use the stats for this state to determine the title
@@ -145,35 +177,49 @@ class State
 		if pattern.nil?
 			@@states.delete(@title)
 		else
-			@@states.delete(pattern.sprinth(stats))
+			@@states.delete(pattern.sprinth(stats()))
 		end
 	end
 
+	# Resets the expiry time to be +dur+ seconds after current time (this may
+	# be shorter than the original lifetime)
+	def extend_for(dur)
+		n = @@timeouts.find_index { |to|
+			to.title == @title
+		}
+		@@timeouts[n..n] = [] unless n.nil?
+		expiry = Correlator.now() + dur
+		self.timeout_at(expiry, @title)
+	end
+
 	# Returns the details of the state (ie. whatever custom fields were defined, eg. userid)
 	# merged with the standard statistics:
 	# - count: number of matches so far
-	# - dur: age of the state
+	# - age: age of the state
 	# - created: time when this state was created
 	# - updated: time last updated (eg. when the latest event matched this state)
 	def stats()
-		@details.merge({"count"=>@count, "dur"=>@dur, "created"=>@created, "updated"=>@updated})
+		@details.merge({"count"=>@count, "age"=>age(), "created"=>@created, "updated"=>@updated})
 	end
 
 	# Creates a new event, writes it to the output log, and returns the event.
-	#
 	# An *event* (or 'log entry') is a timestamp followed by a *message*
-	def generate_alert()
-		message = @alert.sprinth(stats())
-		event = "%s %s" % [@created.iso8601, message] + @logs.join("\n")
-		print("> ") if $debug
-		puts(event)
-		@@eventsOut = @@eventsOut + 1
-		event
+	#
+	# Returns the message only (without the timestamp).
+	def generate(sym = :alert)
+		message = @params[sym].sprinth(stats())
+		if message.length > 0
+			event = "%s %s" % [@created.iso8601, message] + @logs.join("\n")
+			print("> ") if $debug
+			puts(event)
+			@@eventsOut = @@eventsOut + 1
+		end
+		message
 	end
 
 	# Creates a new event when this state is created, but ignores later occurrences
-	def alert_first_only()
-		generate_alert() if @count == 1
+	def generate_first_only(sym = :alert)
+		generate(sym) if @count == 1
 	end
 
 	# Allow access to any parameter by a convenience method

data/lib/rec.rb

@@ -1,132 +1,12 @@
-# Ruby Event Correlation
 require 'string'
 require 'rec/correlator'
-require 'rec/alert'
-
-=begin rdoc
-= Ruby Event Correlation
-REC correlates events in order to generate a smaller set of more meaningful events.
-
-== Installation
-1. Install the gem
-	$ sudo gem install rec
-
-2. Select a ruleset or create your own
-	#!/usr/bin/ruby
-	require 'rec'
-	include REC
-	require 'rulesets/postfix-rules'
-	Correlator::start()
-
-3. Start it up
-	$ rulesets/rules.rb < /var/log/mail.log 3>missed.log 2>control.log > newevents.log
-
-== 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.
-
-[Save time]
-	If you are lazy enough to not want to review all of your log files manually forever, and
-	smart enough to work out what needs monitoring and when you might want to pay attention,
-	then wouldn't it be good if you could define those rules and let the computer do what it
-	does best?
-
-[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.
-	Wouldn't it be good if we could summarise a bunch of low level events into a single
-	business event - and then just read the <em>business log</em>.
-
-== Alternatives
-There are several alternatives to REC which may suit your needs better:
-* splunk[www.splunk.com]
-* nagios[www.nagios.com]
-* scalextreme.com[www.scalextreme.com]
-While I like these options, I find they take a lot of configuring.
-They also has some dependencies that make them a bit heavier than you may want.
-If you just want to keep track of a few kinds of events, want a lot of flexibility
-and control without too much effort, then REC may be of some value.
-
-== How does REC work?
-Each entry in a log file is an *event*.
-The Correlator reads the events, and attempts to match an event against each Rule.
-If an event matches a rule, the rule creates a State which just means we're remembering
-that the event matched a rule. The pattern to match is a regexp, and the captured values
-are named. For example
-	# log entry => "nfs: server earth not responding"
-	pattern => /nfs\: server (\w+) not responding/
-	details => ['host']
-	# values of interest are captured into a hash => {'host' => 'earth' }
-	:message => "Server %host$s is down"
-	# interpolation with named parameters => "Server earth is down"
-
-A state has a fixed lifetime, set when it is created. At the end of its life, it may simply
-expire quietly, or a pre-defined action may be executed. For example, if we find a server is down,
-we may want to wait for 3 minutes and if it is not up again, then alert the administrator.
-The server being down is a state, and two states are distinguished by their *titles*. For example,
-"host earth is down" and "host terra is down".
-
-Now that we're remembering a set of states, we can match events against not only the event's
-message, but also other states. For example, we can match "host terra is up" against a previously
-created state "host terra is down", and generate a new event "host terra is back up after 14 minutes".
-We can also 'swallow' all of the rest of the "host terra is down" events because they add nothing new.
-This <em>event compression</em> means the administrator gets one important message, and not 27
-distracting alerts.
-
-An Alert can be sent by email or IM, depending on your preferences and working hours.
-The destinations and credentials are supplied to your ruleset:
-	# For better security, move the next few lines into a file readable only by
-	# the user running this script eg. /home/rec/alert.conf
-	# and then require that file
-	Alert.smtp_credentials("rec@gmail.com", "recret", "myfirm.com")
-	Alert.emailTo = "me@myfirm.com"
-	Alert.jabber_credentials("rec@gmail.com", "recret")
-	Alert.jabberTo = "me@myfirm.com"
-
-Rules can then send an alert when desired. Two common cases involve alerting immediately
-on the first event (eg. "host terra is down"), and alerting on expiry or at a subsequent event
-(eg. "host terra is back up").
-	state.alert_first_only()		# => generate a new event on first original event
-						# or
-	Alert.normal(state.alert_first_only())	# => log and also send the new event via email
-
-In most cases, however, it is not necessary to alert the administrator at all. It is enough to
-log the new event in the output logfile for later review.
-
-== Examples
-The best way to understand REC is to see how rules are written. The following examples were
-inspired by SEC (simple-evcorr.sourceforge.net), so they employ the same names.
-
-1.	Warn if an user is having trouble executing sudo commands
-	The log entry (/var/log/secure) looks like this:
-
-		Sep 16 07:09:22 earth sudo:  richard : 3 incorrect password attempts ;...
-
-	and the rule might look like this:
-
-		# single threshold rule
-		Rule.new(10034, {
-			:pattern => /\w+ sudo\:  (\w+) \: 3 incorrect password attempts/,
-			:details => ["userid"],
-			:message => "Failed sudo password for user %userid$s",
-			:lifespan => 60,
-			:alert => "'Too much sudo activity' userid=%userid$s attempts=%count$d dur=%dur$0.3fs ",
-			:threshold => 3,
-			:capture => true
-		}) { |state|
-		if state.count == state.threshold
-			Alert.urgent(state.generate_alert())
-			state.release()
-		end
-		}
-
-	This rule matches the log entry against the *pattern*. Note that the captured value
-	<code>(\w+)</code> is stored as the +userid+. The +details+ parameter specifies the names
-	of the captured values in the sequence they appear in the pattern.
-
-	The *message* specifies the title of the state that is created. If there is no title
-
-
-=end
+require 'rec/notify'
+
+# The REC module is a namespace containing:
+# - REC::Correlator
+# - REC::Rule
+# - REC::State
+# - REC::Alert
+#
 module REC
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 1
   - 0
-  - 1
-  version: 1.0.1
+  - 2
+  version: 1.0.2
 platform: ruby
 authors: 
 - Richard Kernahan
@@ -14,17 +14,17 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-09-06 00:00:00 +10:00
+date: 2012-09-17 00:00:00 +10:00
 default_executable: 
 dependencies: []
 
-description: "\tSifts through your log files in real time, using stateful intelligence to determine\n\
-  \twhat is really important. REC can alert you (by email or IM) or it can simply condense\n\
-  \ta large log file into a much shorter and more meaningful log.\n\
-  \tREC is inspired by Risto Vaarandi's brilliant *sec* (simple-evcorr.sourceforge.net)\n\
-  \tbut is original code and any defects are entirely mine.\n\
-  \tWhile event correlation is inherently complex, REC attempts to make common tasks easy\n\
-  \twhile preserving plenty of power and flexibility for ambitious tasks.\n"
+description: "\t\tSifts through your log files in real time, using stateful intelligence to determine\n\
+  \t\twhat is really important. REC can alert you (by email or IM) or it can simply condense\n\
+  \t\ta large log file into a much shorter and more meaningful log.\n\
+  \t\tREC is inspired by Risto Vaarandi's brilliant *sec* (simple-evcorr.sourceforge.net)\n\
+  \t\tbut is original code and any defects are entirely mine.\n\
+  \t\tWhile event correlation is inherently complex, REC attempts to make common tasks easy\n\
+  \t\twhile preserving plenty of power and flexibility for ambitious tasks.\n"
 email: dev.rec@finalstep.com.au
 executables: []
 
@@ -37,8 +37,8 @@ files:
 - lib/rec/rule.rb
 - lib/rec/state.rb
 - lib/rec/correlator.rb
-- lib/rec/alert.rb
-- lib/rec/mock-alert.rb
+- lib/rec/notify.rb
+- lib/rec/mock-notify.rb
 - lib/string.rb
 has_rdoc: true
 homepage: http://rubygems.org/gems/rec