arborist 0.3.0 → 0.4.0

data/History.md

@@ -1,3 +1,17 @@
+## v0.4.0 [2018-11-21] Mahlon E. Smith <mahlon@martini.nu>
+
+Enhancements:
+
+- Add an 'informational' predicate for node events.
+- Introduce basic flap heuristics for node state changes.
+
+
+Fixes:
+
+- Clean up excess ruby warnings.
+
+
+
 ## v0.3.0 [2018-08-29] Michael Granger <ged@FaerieMUD.org>
 
 Enhancements:

data/Rakefile

@@ -38,7 +38,7 @@ hoespec = Hoe.spec 'arborist' do |spec|
 	spec.developer 'Michael Granger', 'ged@FaerieMUD.org'
 	spec.developer 'Mahlon E. Smith', 'mahlon@martini.nu'
 
-	spec.dependency 'schedulability', '~> 0.1'
+	spec.dependency 'schedulability', '~> 0.4'
 	spec.dependency 'loggability', '~> 0.12'
 	spec.dependency 'configurability', '~> 3.0'
 	spec.dependency 'pluggability', '~> 0.4'

data/lib/arborist.rb

@@ -14,10 +14,10 @@ module Arborist
 	       Configurability
 
 	# Package version
-	VERSION = '0.3.0'
+	VERSION = '0.4.0'
 
 	# Version control revision
-	REVISION = %q$Revision: db70f921e653 $
+	REVISION = %q$Revision$
 
 
 	# The name of the environment variable which can be used to set the config path

data/lib/arborist/client.rb

@@ -242,7 +242,7 @@ class Arborist::Client
 	### Modify operational attributes of a node.
 	def modify( *args )
 		request = self.make_modify_request( *args )
-		response = self.send_tree_api_request( request )
+		self.send_tree_api_request( request )
 		return true
 	end
 
@@ -263,7 +263,7 @@ class Arborist::Client
 	### +time+ of now.
 	def acknowledge( *args )
 		request = self.make_acknowledge_request( *args )
-		response = self.send_tree_api_request( request )
+		self.send_tree_api_request( request )
 		return true
 	end
 	alias_method :ack, :acknowledge
@@ -286,7 +286,7 @@ class Arborist::Client
 	### Clear the acknowledgement for a node.
 	def clear_acknowledgement( *args )
 		request = self.make_unack_request( *args )
-		response = self.send_tree_api_request( request )
+		self.send_tree_api_request( request )
 		return true
 	end
 	alias_method :unack, :clear_acknowledgement

data/lib/arborist/command/summary.rb

@@ -22,7 +22,7 @@ module Arborist::CLI::Summary
 
 	desc 'Summarize known problems'
 
-	command :summary do |cmd|
+	command [ :summary, :status ] do |cmd|
 
 		cmd.flag [:s, :sort],
 			type: String,

data/lib/arborist/event.rb

@@ -45,6 +45,14 @@ class Arborist::Event
 	end
 
 
+	### Returns +true+ if the event contains node information other than about a
+	### change in its state.
+	def informational?
+		return false
+	end
+	alias_method :is_informational?, :informational?
+
+
 	### Match operator -- returns +true+ if the other object matches this event.
 	def match( object )
 		rval = object.respond_to?( :event_type ) &&

data/lib/arborist/event/node.rb

@@ -41,9 +41,10 @@ class Arborist::Event::Node < Arborist::Event
 	### Inject useful node metadata into the generated hash.
 	def to_h
 		return super.merge(
-			identifier: self.node.identifier,
-			parent:     self.node.parent,
-			nodetype:   self.node.type
+			identifier:  self.node.identifier,
+			parent:      self.node.parent,
+			nodetype:    self.node.type,
+			flapping:    self.node.flapping?
 		)
 	end
 

data/lib/arborist/event/node_delta.rb

@@ -25,6 +25,13 @@ class Arborist::Event::NodeDelta < Arborist::Event::Node
 	end
 
 
+	### Returns +true+ if the event contains node information other than about a
+	### change in its state.
+	def informational?
+		return true
+	end
+
+
 	### Returns +true+ if the specified +object+ matches this event.
 	def match( object )
 		rval = super &&

data/lib/arborist/event/node_update.rb

@@ -7,4 +7,11 @@ require 'arborist/event/node'
 # An event sent on every node update, regardless of whether or not the update resulted in
 # any changes
 class Arborist::Event::NodeUpdate < Arborist::Event::Node
+
+	### Returns +true+ if the event contains node information other than about a
+	### change in its state.
+	def informational?
+		return true
+	end
+
 end # class Arborist::Event::NodeUpdate

data/lib/arborist/monitor/socket.rb

@@ -110,7 +110,7 @@ module Arborist::Monitor::Socket
 			sock = conn_hash[:conn]
 			# Why getpeername? Testing socket success without read()ing, I think?
 			# FreeBSD source?
-			res = sock.getpeername
+			sock.getpeername
 			return {
 				tcp_socket_connect: { duration: duration }
 			}

data/lib/arborist/monitor_runner.rb

@@ -169,8 +169,8 @@ class Arborist::MonitorRunner
 				err.message
 			]
 			self.log.error "%s\n%s" % [ errmsg, err.backtrace.join("\n  ") ]
-			nodes.keys.each_with_object({}) do |id, results|
-				results[id] = { error: errmsg }
+			nodes.keys.each_with_object({}) do |id, node_results|
+				node_results[id] = { error: errmsg }
 			end
 		end
 
@@ -230,8 +230,6 @@ class Arborist::MonitorRunner
 
 	### Register a timer for the specified +monitor+.
 	def add_timer_for( monitor )
-		interval = monitor.interval
-
 		if monitor.splay.nonzero?
 			self.add_splay_timer_for( monitor )
 		else

data/lib/arborist/node.rb

@@ -7,8 +7,10 @@ require 'time'
 require 'pathname'
 require 'state_machines'
 
+require 'configurability'
 require 'loggability'
 require 'pluggability'
+
 require 'arborist' unless defined?( Arborist )
 require 'arborist/mixins'
 require 'arborist/exceptions'
@@ -23,6 +25,7 @@ class Arborist::Node
 	        Arborist::HashUtilities
 	extend Loggability,
 	       Pluggability,
+	       Configurability,
 	       Arborist::MethodUtilities
 
 
@@ -46,6 +49,7 @@ class Arborist::Node
 		last_contacted
 		ack
 		errors
+		warnings
 		quieted_reasons
 		config
 	]
@@ -69,6 +73,17 @@ class Arborist::Node
 	plugin_prefixes 'arborist/node'
 
 
+	# Configurability API
+	configurability( 'arborist.node' ) do
+
+		# How many status entries to keep in a ring buffer
+		setting :status_history_size, default: 0
+
+		# How many status transitions in the history constitutes flapping
+		setting :flap_threshold, default: 0
+	end
+
+
 	##
 	# :method: unknown?
 	# Returns +true+ if the node is in an 'unknown' state.
@@ -166,6 +181,9 @@ class Arborist::Node
 		after_transition any => any, do: :update_status_changed
 
 		after_transition do: :add_status_to_update_delta
+
+		after_transition do: :record_status_history
+		after_failure do: :record_status_history
 	end
 
 
@@ -308,11 +326,15 @@ class Arborist::Node
 		@source          = nil
 		@children        = {}
 		@dependencies    = Arborist::Dependency.new( :all )
+		@flap_threshold  = nil
+		@flapping        = false
+		@status_history_size = nil
 
 		# Primary state
 		@status          = 'unknown'
 		@status_changed  = Time.at( 0 )
 		@status_last_changed = Time.at( 0 )
+		@status_history  = []
 
 		# Attributes that govern state
 		@errors          = {}
@@ -407,6 +429,14 @@ class Arborist::Node
 	# type of dependency it came from (either :primary or :secondary).
 	attr_reader :quieted_reasons
 
+	##
+	# An array of statuses, retained after an update.
+	attr_reader :status_history
+
+	##
+	# The current flapping state of this node.
+	attr_predicate_accessor :flapping
+
 
 	### Set the source of the node to +source+, which should be a valid URI.
 	def source=( source )
@@ -501,6 +531,22 @@ class Arborist::Node
 	end
 
 
+	### Get or set the number of entries to store for the status
+	### history.
+	def status_history_size( new_size=nil )
+		@status_history_size = new_size if new_size
+		return @status_history_size || Arborist::Node.status_history_size || 0
+	end
+
+
+	### Get or set the number of transitions in the status
+	### history to determine if a node is considering 'flapping'.
+	def flap_threshold( new_count=nil )
+		@flap_threshold = new_count if new_count
+		return @flap_threshold || Arborist::Node.flap_threshold || 0
+	end
+
+
 	#
 	# :section: Manager API
 	# Methods used by the manager to manage its nodes.
@@ -813,8 +859,8 @@ class Arborist::Node
 			self.log.debug "No handler for a %s event!" % [ event.type ]
 		end
 
-		self.log.debug ">>> Pending change events before: %p" % [ self.pending_change_events ]
-
+		# Don't transition on informational events
+		return if event.informational?
 		super # to state-machine
 
 		results = self.pending_change_events.clone
@@ -1054,14 +1100,17 @@ class Arborist::Node
 	### used to overlay selective bits of the saved node tree to the equivalent nodes loaded
 	### from node definitions.
 	def restore( old_node )
-		@status          = old_node.status
-		@properties      = old_node.properties.dup
-		@ack             = old_node.ack.dup if old_node.ack
-		@last_contacted  = old_node.last_contacted
-		@status_changed  = old_node.status_changed
-		@errors          = old_node.errors
-		@warnings        = old_node.warnings
-		@quieted_reasons = old_node.quieted_reasons
+		@status              = old_node.status
+		@properties          = old_node.properties.dup
+		@ack                 = old_node.ack.dup if old_node.ack
+		@last_contacted      = old_node.last_contacted
+		@status_changed      = old_node.status_changed
+		@status_history      = old_node.status_history
+		@status_history_size = old_node.status_history_size
+		@flapping            = old_node.flapping?
+		@errors              = old_node.errors
+		@warnings            = old_node.warnings
+		@quieted_reasons     = old_node.quieted_reasons
 		@status_last_changed = old_node.status_last_changed
 
 		# Only merge in downed dependencies.
@@ -1088,6 +1137,9 @@ class Arborist::Node
 			last_contacted: self.last_contacted ? self.last_contacted.iso8601 : nil,
 			status_changed: self.status_changed ? self.status_changed.iso8601 : nil,
 			status_last_changed: self.status_last_changed ? self.status_last_changed.iso8601 : nil,
+			status_history: self.status_history,
+			status_history_size: self.status_history_size,
+			flapping: self.flapping?,
 			errors: self.errors,
 			warnings: self.warnings,
 			dependencies: self.dependencies.to_h,
@@ -1117,29 +1169,32 @@ class Arborist::Node
 	### previously-marshalled node.
 	def marshal_load( hash )
 		self.log.debug "Restoring from serialized hash: %p" % [ hash ]
-		@identifier      = hash[:identifier]
-		@properties      = hash[:properties]
+		@identifier          = hash[:identifier]
+		@properties          = hash[:properties]
 
-		@parent          = hash[:parent]
-		@description     = hash[:description]
-		@tags            = Set.new( hash[:tags] )
-		@config          = hash[:config]
-		@children        = {}
+		@parent              = hash[:parent]
+		@description         = hash[:description]
+		@tags                = Set.new( hash[:tags] )
+		@config              = hash[:config]
+		@children            = {}
 
-		@status          = hash[:status]
-		@status_changed  = Time.parse( hash[:status_changed] )
+		@status              = hash[:status]
+		@status_changed      = Time.parse( hash[:status_changed] )
 		@status_last_changed = Time.parse( hash[:status_last_changed] )
-		@ack             = Arborist::Node::Ack.from_hash( hash[:ack] ) if hash[:ack]
-
-		@errors          = hash[:errors]
-		@warnings        = hash[:warnings]
-		@properties      = hash[:properties] || {}
-		@last_contacted  = Time.parse( hash[:last_contacted] )
-		@quieted_reasons = hash[:quieted_reasons] || {}
+		@status_history      = hash[:status_history]
+		@status_history_size = hash[:status_history_size]
+		@flapping            = hash[:flapping]
+		@ack                 = Arborist::Node::Ack.from_hash( hash[:ack] ) if hash[:ack]
+
+		@errors              = hash[:errors]
+		@warnings            = hash[:warnings]
+		@properties          = hash[:properties] || {}
+		@last_contacted      = Time.parse( hash[:last_contacted] )
+		@quieted_reasons     = hash[:quieted_reasons] || {}
 		self.log.debug "Deps are: %p" % [ hash[:dependencies] ]
-		@dependencies    = hash[:dependencies]
+		@dependencies        = hash[:dependencies]
 
-		@update_delta    = Hash.new do |h,k|
+		@update_delta        = Hash.new do |h,k|
 			h[ k ] = Hash.new( &h.default_proc )
 		end
 
@@ -1164,6 +1219,23 @@ class Arborist::Node
 	protected
 	#########
 
+	### Detects if this node is considered 'flapping', returning +true+ if so.
+	def check_flapping
+		return false if self.flap_threshold.zero?
+
+		runs = self.status_history.each_cons( 2 ).count do |status_1, status_2|
+			status_1 != status_2
+		end
+
+		self.log.debug "Observed %d changes in %d samples." % [
+			runs,
+			self.status_history.size
+		]
+
+		return runs >= self.flap_threshold
+	end
+
+
 	### Ack the node with the specified +ack_data+, which should contain
 	def ack=( ack_data )
 		if ack_data
@@ -1356,6 +1428,30 @@ class Arborist::Node
 	end
 
 
+	### Add a flap change to the delta event.
+	def add_flap_to_update_delta( from, to )
+		return if from == to
+		self.update_delta[ 'flapping' ] = [ from, to ]
+	end
+
+
+	### Retain the status in the node's history.
+	###
+	def record_status_history
+		retain = self.status_history_size
+		return if retain.zero?
+
+		pre_state = self.flapping?
+		self.status_history << self.status
+		self.flapping = self.check_flapping
+
+		current_size = self.status_history.size
+		self.status_history.slice!( 0, current_size - retain ) if current_size >= retain
+
+		self.add_flap_to_update_delta( pre_state, self.flapping? )
+	end
+
+
 	#######
 	private
 	#######

data/lib/arborist/node/root.rb

@@ -37,7 +37,7 @@ class Arborist::Node::Root < Arborist::Node
 	def initialize( * )
 		super( '_' ) do
 			description "The root node."
-			source = URI( __FILE__ )
+			self.source = URI( __FILE__ )
 		end
 
 		@status = 'up'

data/lib/arborist/observer/action.rb

@@ -19,12 +19,13 @@ class Arborist::Observer::Action
 	### Create a new Action that will call the specified +block+ +during+ the given schedule,
 	### but only +after+ the specified number of events have arrived +within+ the given
 	### time threshold.
-	def initialize( within: 0, after: 1, during: nil, &block )
+	def initialize( within: 0, after: 1, during: nil, ignore_flapping: false, &block )
 		raise ArgumentError, "Action requires a block" unless block
 
 		@block           = block
 		@time_threshold  = within
 		@schedule        = Schedulability::Schedule.parse( during ) if during
+		@ignore_flapping = ignore_flapping
 
 		if within.zero?
 			@count_threshold = after
@@ -58,6 +59,11 @@ class Arborist::Observer::Action
 	# The schedule that applies to this action.
 	attr_reader	:schedule
 
+	##
+	# Take no action if the node the event belongs to is in a flapping
+	# state.
+	attr_reader	:ignore_flapping
+
 	##
 	# The Hash of recent events, keyed by their arrival time.
 	attr_reader :event_history
@@ -66,7 +72,7 @@ class Arborist::Observer::Action
 	### Call the action for the specified +event+.
 	def handle_event( event )
 		self.record_event( event )
-		self.call_block( event ) if self.should_run?
+		self.call_block( event ) if self.should_run? && ! self.flapping?( event )
 	end
 
 
@@ -107,6 +113,13 @@ class Arborist::Observer::Action
 	end
 
 
+	### Returns +true+ if this observer respects the flapping state of
+	### a node, and the generated event is attached to a flapping node.
+	def flapping?( event )
+		return self.ignore_flapping && event[ 'flapping' ]
+	end
+
+
 	### Returns +true+ if the time between the first and last event in the #event_history is
 	### less than the #time_threshold.
 	def time_threshold_exceeded?