observability 0.1.0

data/lib/observability/event.rb

@@ -0,0 +1,103 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'time'
+require 'forwardable'
+require 'loggability'
+require 'concurrent'
+
+require 'observability' unless defined?( Observability )
+
+
+class Observability::Event
+	extend Loggability,
+		Forwardable
+
+
+	# The event format version to send with all events
+	FORMAT_VERSION = 1
+
+
+	# Loggability API -- send logs to the top-level module's logger
+	log_to :observability
+
+
+	### Create a new event
+	def initialize( type, **fields )
+		@type      = type.freeze
+		@timestamp = Time.now
+		@start     = Concurrent.monotonic_time
+		@fields    = fields
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The type of the event, which should be a string of the form: 'foo.bar.baz'
+	attr_reader :type
+
+	##
+	# The Time the event was created
+	attr_reader :timestamp
+
+	##
+	# The monotonic clock time of when the event was created
+	attr_reader :start
+
+	##
+	# A Symbol-keyed Hash of values that make up the event data
+	attr_reader :fields
+
+
+	##
+	# Delegate some read-only methods to the #fields Hash.
+	def_instance_delegators :fields, :[], :keys
+
+
+	### Merge the specified +fields+ into the event's data.
+	### :TODO: Handle conflicts?
+	def merge( fields )
+		self.fields.merge!( fields )
+	rescue FrozenError => err
+		raise "event is already resolved", cause: err
+	end
+
+
+	### Finalize all of the event's data and return it as a Hash.
+	def resolve
+		unless @fields.frozen?
+			self.log.debug "Resolving event %#x" % [ self.object_id ]
+			data = self.fields.merge(
+				:@type => self.type,
+				:@timestamp => self.timestamp,
+				:@version => FORMAT_VERSION
+			)
+			data = data.transform_values( &self.method(:resolve_value) )
+			@fields = data.freeze
+		end
+
+		return @fields
+	end
+	alias_method :to_h, :resolve
+
+
+	### Resolve the given +value+ into a serializable object.
+	def resolve_value( value )
+		case
+
+		when value.respond_to?( :call ) # Procs, Methods
+			return value.call( self )
+
+		when value.respond_to?( :iso8601 ) # Time, Date, DateTime, etc.
+			return value.iso8601( 6 )
+
+		else
+			return value
+		end
+	end
+
+end # class Observability::Event
+

data/lib/observability/observer.rb

@@ -0,0 +1,296 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'concurrent'
+require 'loggability'
+
+require 'observability' unless defined?( Observability )
+
+
+class Observability::Observer
+	extend Loggability
+
+
+	# Pattern for finding places for underscores when changing a camel-cased string
+	# to a snake-cased one.
+	SNAKE_CASE_SEPARATOR = /(\P{Upper}\p{Upper}|\p{Lower}\P{Lower})/
+
+
+	# Log to Observability's internal logger
+	log_to :observability
+
+
+	### Create a new Observer that will send events via the specified +sender+.
+	def initialize( sender_type=nil )
+		@sender = self.configured_sender( sender_type )
+		@event_stack = Concurrent::ThreadLocalVar.new( &Array.method(:new) )
+		@context_stack = Concurrent::ThreadLocalVar.new( &Array.method(:new) )
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The Observability::Sender used to deliver events
+	attr_reader :sender
+
+
+	### Start recording events and sending them.
+	def start
+		self.sender.start
+	end
+
+
+	### Stop recording and sending events.
+	def stop
+		self.sender.stop
+	end
+
+
+	### Create a new event with the specified +type+ and make it the current one.
+	def event( type, **options, &block )
+		type = self.type_from_object( type )
+		fields = self.fields_from_options( options )
+
+		event = Observability::Event.new( type, **fields )
+		@event_stack.value.push( event )
+
+		new_context = @context_stack.value.last&.dup || {}
+		@context_stack.value.push( new_context )
+
+		return self.finish_after_block( event.object_id, &block ) if block
+		return event.object_id
+	end
+
+
+	### Finish the and send the current event, comparing it against +event_marker+
+	### and raising an exception if it's provided but doesn't match.
+	### --
+	### :TODO: Instead of raising, dequeue events up to the given marker if it
+	###        exists in the queue?
+	def finish( event_marker=nil )
+		raise "Event mismatch" if
+			event_marker && @event_stack.value.last.object_id != event_marker
+
+		event = @event_stack.value.pop
+		context = @context_stack.value.pop
+		self.log.debug "Adding context %p (%d left) to finishing event." %
+			[ context, @context_stack.value.length ]
+		event.merge( context )
+
+		self.log.debug "Finishing event: %p" % [ event ]
+		self.sender.enqueue( event )
+
+		return event
+	end
+
+
+	### Call the given +block+, then when it returns, finish the event that
+	### corresponds to the given +marker+.
+	def finish_after_block( event_marker=nil, &block )
+		block.call( self )
+	rescue Exception => err
+		self.add( err )
+		raise
+	ensure
+		self.finish( event_marker )
+	end
+
+
+	### Add an +object+ and/or a Hash of +fields+ to the current event.
+	def add( object=nil, **fields )
+		self.log.debug "Adding %p" % [ object || fields ]
+		event = @event_stack.value.last or return
+
+		if object
+			object_fields = self.fields_from_object( object )
+			fields = fields.merge( object_fields )
+		end
+
+		event.merge( fields )
+	end
+
+
+	### Add the specified +fields+ to the current event and any that are created
+	### before the current event is finished.
+	def add_context( object=nil, **fields )
+		self.log.debug "Adding context from %p" % [ object || fields ]
+		current_context = @context_stack.value.last or return
+
+		if object
+			object_fields = self.fields_from_object( object )
+			fields = fields.merge( object_fields )
+		end
+
+		current_context.merge!( fields )
+	end
+
+
+	### Return the depth of the stack of pending events.
+	def pending_event_count
+		return @event_stack.value.length
+	end
+
+
+	### Returns +true+ if the Observer has events that are under construction.
+	def has_pending_events?
+		return self.pending_event_count.nonzero? ? true : false
+	end
+	alias_method :pending_events?, :has_pending_events?
+
+
+	#########
+	protected
+	#########
+
+	#
+	# Types
+	#
+
+	### Derive an event type from the specified +object+ and an optional +block+
+	### that provides additional context.
+	def type_from_object( object, block=nil )
+		case object
+		when Module
+			self.log.debug "Deriving a type from module %p" % [ object ]
+			return self.type_from_module( object )
+
+		when Method, UnboundMethod
+			self.log.debug "Deriving a type from method %p" % [ object ]
+			return self.type_from_method( object )
+
+		when Array
+			self.log.debug "Deriving a type from context %p" % [ object ]
+			return self.type_from_context( *object )
+
+		when Proc
+			self.log.debug "Deriving a type from context proc %p" % [ object ]
+			return self.type_from_context_proc( object )
+
+		when String
+			self.log.debug "Using string %p as type" % [ object ]
+			return object
+
+		else
+			raise "don't know how to derive an event type from a %p" % [ object.class ]
+		end
+	end
+
+
+	### Derive an event type from the specified Class or Module +object+.
+	def type_from_module( object )
+		if ( name = object.name )
+			name = name.split( '::' ).collect do |part|
+				part.gsub( SNAKE_CASE_SEPARATOR ) do |m|
+					"%s_%s" % [ m[0], m[1] ]
+				end
+			end.join( '.' )
+
+			return name.downcase
+		else
+			return "anonymous_%s_%d" % [ object.class.name.downcase, object.object_id ]
+		end
+	end
+
+
+	### Derive an event type from the specified Method or UnboundMethod +object+.
+	def type_from_method( object )
+		name = object.original_name
+		mod = object.owner
+
+		return [ self.type_from_module(mod), name.to_s ].join( '.' )
+	end
+
+
+	### Derive an event type from the specified Method and a +detail+.
+	def type_from_context( context, *details )
+		prefix = self.type_from_object( context )
+		suffix = details.map {|detail| detail.to_s }
+
+		return ([prefix] + suffix).join( '.' )
+	end
+
+
+	### Derive an event type from the specified Proc, which should be a block passed
+	### to an observed method.
+	def type_from_context_proc( object )
+		bind = object.binding
+		recv = bind.receiver
+		methname = bind.eval( "__method__" )
+		meth = recv.method( methname )
+
+		return self.type_from_object( meth )
+	end
+
+
+	#
+	# Fields
+	#
+
+	### Extract fields specified by the specified +options+ and return them all
+	### merged into one Hash.
+	### :TODO: Handle options like :model, :timed, etc.
+	def fields_from_options( options )
+		fields = {}
+
+		options.each do |key, value|
+			self.log.debug "Applying option %p: %p" % [ key, value ]
+			case key
+			when :add
+				fields.merge!( value )
+			when :timed
+				duration_callback = lambda {|ev| Concurrent.monotonic_time - ev.start }
+				fields.merge!( duration: duration_callback )
+			else
+				raise "unknown event option %p" % [ key ]
+			end
+		end
+
+		return fields
+	end
+
+
+	### Return a Hash of fields to add to the current event derived from the given
+	### +object+.
+	def fields_from_object( object )
+		case object
+		when ::Exception
+			return self.fields_from_exception( object )
+		else
+			if object.respond_to?( :to_h )
+				return object.to_h
+			else
+				raise "don't know how to derive fields from a %p" % [ object.class ]
+			end
+		end
+	end
+
+
+	### Return a Hash of fields to add to the current event derived from the given
+	### +exception+ object.
+	def fields_from_exception( exception )
+		trace_frames = exception.backtrace_locations.map do |loc|
+			{ label: loc.label, path: loc.absolute_path, lineno: loc.lineno }
+		end
+
+		return {
+			error: {
+				type: exception.class.name,
+				message: exception.message,
+				backtrace: trace_frames
+			}
+		}
+	end
+
+
+	### Create an instance of the given +sender_type+, or the type specified in the
+	### configuration if +sender_type+ is nil.
+	def configured_sender( sender_type )
+		return Observability::Sender.create( sender_type ) if sender_type
+		return Observability::Sender.configured_type
+	end
+
+end # class Observability::Observer
+

data/lib/observability/observer_hooks.rb

@@ -0,0 +1,28 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'observability' unless defined?( Observability )
+
+
+# A mixin that allows events to be created for any current observers at runtime.
+module Observability::ObserverHooks
+
+	### Create an event at the current point of execution, make it the innermost
+	### context, then yield to the method's block. Finish the event when the yield
+	### returns, handling exceptions that are being raised automatically.
+	def observe( detail, **options, &block )
+		raise LocalJumpError, "no block given" unless block
+
+		marker = Observability.observer.event( [block, detail], **options )
+		Observability.observer.finish_after_block( marker, &block )
+	end
+
+
+	### Return the current Observability observer agent.
+	def observability
+		return Observability.observer
+	end
+
+end # module Observability::ObserverHooks
+
+

data/lib/observability/sender.rb

@@ -0,0 +1,127 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'json'
+require 'concurrent'
+require 'pluggability'
+
+require 'observability' unless defined?( Observability )
+
+
+class Observability::Sender
+	extend Pluggability,
+		Loggability,
+		Configurability
+
+
+	# Logs go to the main module
+	log_to :observability
+
+	# Set the prefix for derivative classes
+	plugin_prefixes 'observability/sender'
+
+	# Configuration settings
+	configurability( 'observability.sender' ) do
+
+		##
+		# The sender type to use
+		setting :type, default: :null
+
+	end
+
+
+
+	# Prevent direct instantiation
+	private_class_method :new
+
+	### Let subclasses be inherited
+	def self::inherited( subclass )
+		super
+		subclass.public_class_method( :new )
+	end
+
+
+	### Return an instance of the configured type of Sender.
+	def self::configured_type
+		return self.create( self.type )
+	end
+
+
+	### Set up some instance variables
+	def initialize # :notnew:
+		@executor = nil
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The processing executor.
+	attr_reader :executor
+
+
+	### Start sending queued events.
+	def start
+		self.log.debug "Starting a %p" % [ self.class ]
+		@executor = Concurrent::SingleThreadExecutor.new( fallback_policy: :abort )
+		@executor.auto_terminate = true
+	end
+
+
+	### Stop the sender's executor.
+	def stop
+		self.log.debug "Stopping the %p" % [ self.class ]
+		return if !self.executor || self.executor.shuttingdown? || self.executor.shutdown?
+
+		self.log.debug "  shutting down the executor"
+		self.executor.shutdown
+		unless self.executor.wait_for_termination( 3 )
+			self.log.debug "  killing the executor"
+			self.executor.halt
+			self.executor.wait_for_termination( 3 )
+		end
+	end
+
+
+	### Queue up the specified +events+ for sending.
+	def enqueue( *events )
+		posted_event = Concurrent::Event.new
+
+		unless self.executor
+			self.log.debug "No executor; dropping %d events" % [ events.length ]
+			posted_event.set
+			return posted_event
+		end
+
+		self.executor.post( *events ) do |*ev|
+			serialized = self.serialize_events( ev.flatten )
+			serialized.each do |ev|
+				self.send_event( ev )
+			end
+			posted_event.set
+		end
+
+		return posted_event
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Serialize each the given +events+ and return the results.
+	def serialize_events( events )
+		return events.map( &:resolve )
+	end
+
+
+	### Send the specified +event+.
+	def send_event( event )
+		self.log.warn "%p does not implement required method %s" % [ self.class, __method__ ]
+	end
+
+end # class Observability::Sender
+
+