observability 0.1.0

data/lib/observability/sender/logger.rb

@@ -0,0 +1,37 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'observability/sender' unless defined?( Observability::Sender )
+
+
+# A sender that just logs events to the Observability logger.
+class Observability::Sender::Logger < Observability::Sender
+	extend Loggability
+
+
+	# Loggability API
+	log_as :observability_events
+
+
+	def start # :nodoc:
+		# No-op
+	end
+
+
+	def stop # :nodoc:
+		# No-op
+	end
+
+
+	### Output the +event+ to the logger.
+	def enqueue( *events )
+		events.each do |event|
+			data = event.resolve
+			msg = "«%s» %p" % [ data[:@type], data ]
+			self.log.debug( msg )
+		end
+	end
+
+end # class Observability::Sender::Log
+
+

data/lib/observability/sender/null.rb

@@ -0,0 +1,30 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'observability/sender' unless defined?( Observability::Sender )
+
+
+# A Sender that no-ops all observation routines. This effectively disables
+# Observability.
+class Observability::Sender::Null < Observability::Sender
+
+	### Overridden: Nothing to start.
+	def start
+		# No-op
+	end
+
+
+	### Overridden: Nothing to stop.
+	def stop
+		# No-op
+	end
+
+
+	### Overridden: Drop enqueued events.
+	def enqueue( * )
+		# No-op
+	end
+
+end # class Observability::Sender::Null
+
+

data/lib/observability/sender/testing.rb

@@ -0,0 +1,56 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'loggability'
+
+require 'observability/sender' unless defined?( Observability::Sender )
+
+
+# A sender that just enqueues events and then lets you make assertions about the
+# kinds of events that were sent.
+class Observability::Sender::Testing < Observability::Sender
+	extend Loggability
+
+
+	# Loggability API
+	log_to :observability
+
+
+	### Create a new testing sender.
+	def initialize( * )
+		@enqueued_events = []
+	end
+
+
+	##
+	# The Array of events which were queued.
+	attr_reader :enqueued_events
+
+
+	# No-ops; there is no sending thread, so nothing to start/stop.
+	def start( * ); end
+	def stop( * ); end
+
+
+	### Sender API -- add the specified +events+ to the queue.
+	def enqueue( *events )
+		@enqueued_events.concat( events )
+	end
+
+
+	### Return any enqueued events that are of the specified +type+.
+	def find_events( type )
+		return @enqueued_events.find_all do |event|
+			event.type == type
+		end
+	end
+
+
+	### Returns +true+ if at least one event of the specified +type+ was enqueued.
+	def event_was_sent?( type )
+		return !self.find_events( type ).empty?
+	end
+
+end # class Observability::Sender::Testing
+
+

data/lib/observability/sender/udp.rb

@@ -0,0 +1,88 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'socket'
+require 'configurability'
+
+require 'observability/sender' unless defined?( Observability::Sender )
+
+
+# A sender that sends events as JSON over UDP.
+class Observability::Sender::UDP < Observability::Sender
+	extend Configurability
+
+
+	# Number of seconds to wait between retrying a blocked write
+	RETRY_INTERVAL = 0.25
+
+	# The pipeline to use for turning events into network data
+	SERIALIZE_PIPELINE = :resolve.to_proc >> JSON.method(:generate)
+
+
+	# Declare configurable settings
+	configurability( 'observability.sender.udp' ) do
+
+		##
+		# The host to send events to
+		setting :host, default: 'localhost'
+
+		##
+		# The port to send events to
+		setting :port, default: 15775
+
+	end
+
+
+	### Create a new UDP sender
+	def initialize( * )
+		@socket = UDPSocket.new
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The socket to send events over
+	attr_reader :socket
+
+
+	### Start sending queued events.
+	def start
+		self.socket.connect( self.class.host, self.class.port )
+
+		super
+	end
+
+
+	### Stop the sender's executor.
+	def stop
+		super
+
+		self.socket.shutdown( :WR )
+	end
+
+
+	### Serialize each the given +events+ and return the results.
+	def serialize_events( events  )
+		return events.map( &SERIALIZE_PIPELINE )
+	end
+
+
+	### Send the specified +event+.
+	def send_event( data )
+		until data.empty?
+			bytes = self.socket.sendmsg_nonblock( data, 0, exception: false )
+
+			if bytes == :wait_writable
+				IO.select( nil, [self.socket], nil )
+			else
+				self.log.debug "Sent: %p" % [ data[0, bytes] ]
+				data[ 0, bytes ] = ''
+			end
+		end
+	end
+
+end # class Observability::Sender::UDP
+

data/spec/observability/event_spec.rb

@@ -0,0 +1,106 @@
+#!/usr/bin/env rspec -cfd
+
+require_relative '../spec_helper'
+
+require 'timecop'
+require 'observability/event'
+
+
+describe Observability::Event do
+
+	before( :all ) do
+		@real_tz = ENV['TZ']
+		ENV['TZ'] = 'America/Los_Angeles'
+	end
+
+	after( :all ) do
+		ENV['TZ'] = @real_tz
+	end
+
+
+	it "can be created with just a type" do
+		event = described_class.new( 'acme.daemon.start' )
+
+		expect( event ).to be_a( described_class )
+		expect( event.type ).to eq( 'acme.daemon.start' )
+	end
+
+
+	it "can be created with a type and one or more fields" do
+		event = described_class.new( 'acme.user.review', score: 100, time: 48 )
+
+		expect( event ).to be_a( described_class )
+		expect( event.type ).to eq( 'acme.user.review' )
+		expect( event.fields ).to eq( score: 100, time: 48 )
+	end
+
+
+	it "returns a structured log entry when resolved" do
+		event = described_class.new( 'acme.user.review', score: 100, time: 48 )
+		expect( event.resolve ).to be_a( Hash ).and( include(score: 100, time: 48) )
+	end
+
+
+	it "prevents adding more fields after it's been resolved" do
+		event = described_class.new( 'acme.user.review', score: 100, time: 48 )
+
+		event.resolve
+
+		expect {
+			event.merge( foo: 1 )
+		}.to raise_error( /already resolved/i )
+	end
+
+
+	it "adds its type to the resolved fields" do
+		event = described_class.new( 'acme.user.review' )
+		expect( event.resolve ).to include( :@type => event.type )
+	end
+
+
+	it "adds a timestamp to the resolved fields" do
+		Timecop.freeze( Time.at(1563821278.609382) ) do
+			expect( Time.now.to_f ).to eq( 1563821278.609382 )
+			event = described_class.new( 'acme.user.review' )
+			expect( event.resolve ).to include(
+				:@timestamp => a_string_matching( /2019-07-22T11:47:58\.\d{6}-07:00/ )
+			)
+		end
+	end
+
+
+	it "has a monotonic timestamp of when it was created" do
+		event = described_class.new( 'acme.daemon.start' )
+
+		expect( event.start ).to be_a( Float ).and( be < Concurrent.monotonic_time )
+	end
+
+
+	it "freezes its type" do
+		event = described_class.new( 'acme.daemon.start' )
+
+		expect( event.type ).to be_frozen
+	end
+
+
+	it "can merge new field data" do
+		event = described_class.new( 'acme.daemon.start', time: 1563379346 )
+
+		expect {
+			event.merge( end_time: 1563379417 )
+		}.to change { event.fields }.to( time: 1563379346, end_time: 1563379417 )
+	end
+
+
+	it "calls fields which are callables when it is resolved" do
+		event = described_class.new( 'acme.user.speed',
+			start: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+			duration: ->(ev){ Process.clock_gettime(Process::CLOCK_MONOTONIC) - ev[:start] } )
+
+		sleep 0.25
+
+		expect( event.resolve[:duration] ).to be_within( 0.01 ).of( 0.25 )
+	end
+
+end
+

data/spec/observability/observer_hooks_spec.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env rspec -cfd
+
+require_relative '../spec_helper'
+
+require 'observability/observer_hooks'
+
+
+describe Observability::ObserverHooks do
+
+	let( :hooks_mod ) { described_class.dup }
+
+	let( :observed_class ) do
+		new_class = Class.new do
+			def do_a_thing
+				self.observe( :thing_done ) do
+					self.do_it
+				end
+			end
+
+			def do_it
+				return :it_is_done
+			end
+		end
+		new_class.prepend( hooks_mod )
+
+		return new_class
+	end
+	let ( :expected_event_prefix ) { "anonymous_class_%d" % [ observed_class.object_id ] }
+
+
+	it "provides an #observe instance method for generating events" do
+		instance = observed_class.new
+
+		expect {
+			instance.do_a_thing
+		}.to emit_event( "#{expected_event_prefix}.do_a_thing.thing_done" )
+	end
+
+
+	it "provides an instance method alias to the current Observability observer" do
+		instance = observed_class.new
+
+		expect( instance.observability ).to be( Observability.observer )
+	end
+
+end
+

data/spec/observability/observer_spec.rb

@@ -0,0 +1,292 @@
+#!/usr/bin/env rspec -cfd
+
+require_relative '../spec_helper'
+
+require 'observability/observer'
+
+
+# A module and class for testing derived event types
+module FooLibrary
+	module Bar
+		class BazAdapter
+			def start; end
+		end
+	end
+end
+
+
+describe Observability::Observer do
+
+	it "can be created with a default sender" do
+		observer = described_class.new
+
+		expect( observer ).to be_a( described_class )
+		expect( observer.sender ).to be_a( Observability::Sender )
+	end
+
+
+	it "can create a new event" do
+		marker = nil
+		observer = described_class.new
+
+		expect {
+			marker = observer.event( 'acme.daemon.start' )
+		}.to change { observer.pending_event_count }.by( 1 )
+
+		expect( marker ).to be_an( Integer )
+	end
+
+
+	it "sends an event when it is finished" do
+		observer = described_class.new( :testing )
+		observer.event( 'acme.engine.throttle' )
+
+		expect {
+			observer.finish
+		}.to change { observer.sender.enqueued_events.length }.by( 1 )
+
+		event = observer.sender.enqueued_events.last
+		expect( event.type ).to eq( 'acme.engine.throttle' )
+	end
+
+
+	it "sends an event when it is finished with the correct marker" do
+		observer = described_class.new( :testing )
+		marker = observer.event( 'acme.startup' )
+
+		expect {
+			observer.finish( marker )
+		}.to change { observer.sender.enqueued_events.length }.by( 1 )
+	end
+
+
+	# :TODO: Should this behavior instead finish all events up to the specified marker instead?
+	it "raises when finished with the incorrect marker" do
+		observer = described_class.new( :testing )
+		first_marker = observer.event( 'acme.startup' )
+		second_marker = observer.event( 'acme.loop' )
+
+		expect {
+			observer.finish( first_marker )
+		}.to raise_error( /event mismatch/i )
+	end
+
+
+	it "creates and event and finishes it immediately when passed a block" do
+		observer = described_class.new( :testing )
+
+		expect {
+			observer.event( 'acme.gate' ) do |obs|
+				obs.add( state: 'open' )
+			end
+		}.to change { observer.sender.enqueued_events.length }.by( 1 )
+
+		event =  observer.sender.enqueued_events.last
+		expect( event.type ).to eq( 'acme.gate' )
+		expect( event.fields ).to eq( state: 'open' )
+	end
+
+
+	describe "event types" do
+
+		it "can be set directly by passing a String" do
+			observer = described_class.new( :testing )
+			observer.event( 'acme.factory.deploy' )
+
+			event = observer.finish
+
+			expect( event.type ).to eq( 'acme.factory.deploy' )
+		end
+
+
+		it "can be derived from a named Module" do
+			observer = described_class.new( :testing )
+			observer.event( FooLibrary::Bar )
+
+			event = observer.finish
+
+			expect( event.type ).to eq( 'foo_library.bar' )
+		end
+
+
+		it "can be derived from an anonymous Module" do
+			mod = Module.new
+			observer = described_class.new( :testing )
+			observer.event( mod )
+
+			event = observer.finish
+
+			expect( event.type ).to eq( "anonymous_module_#{mod.object_id}" )
+		end
+
+
+		it "can be derived from a named Class" do
+			observer = described_class.new( :testing )
+			observer.event( FooLibrary::Bar::BazAdapter )
+
+			event = observer.finish
+
+			expect( event.type ).to eq( "foo_library.bar.baz_adapter" )
+		end
+
+
+		it "can be derived from an anonymous Class" do
+			mod = Class.new
+			observer = described_class.new( :testing )
+			observer.event( mod )
+
+			event = observer.finish
+
+			expect( event.type ).to eq( "anonymous_class_#{mod.object_id}" )
+		end
+
+
+		it "can be derived from an UnboundMethod" do
+			observer = described_class.new( :testing )
+			observer.event( FooLibrary::Bar::BazAdapter.instance_method(:start) )
+
+			event = observer.finish
+
+			expect( event.type ).to eq( "foo_library.bar.baz_adapter.start" )
+		end
+
+
+		it "can be derived from a bound Method" do
+			observer = described_class.new( :testing )
+			observer.event( FooLibrary::Bar::BazAdapter.new.method(:start) )
+
+			event = observer.finish
+
+			expect( event.type ).to eq( "foo_library.bar.baz_adapter.start" )
+		end
+
+
+		it "can be derived from a Method and a Symbol" do
+			obj = FooLibrary::Bar::BazAdapter.new
+			meth = obj.method( :start )
+
+			observer = described_class.new( :testing )
+			observer.event( [meth, :loop] )
+
+			event = observer.finish
+
+			expect( event.type ).to eq( "foo_library.bar.baz_adapter.start.loop" )
+		end
+
+
+		it "can be derived from a Proc and a Symbol" do
+			obj = FooLibrary::Bar::BazAdapter.new
+			meth = obj.method( :start )
+
+			observer = described_class.new( :testing )
+			observer.event( [meth, :loop] )
+
+			event = observer.finish
+
+			expect( event.type ).to eq( "foo_library.bar.baz_adapter.start.loop" )
+		end
+
+	end
+
+
+	describe "event options" do
+
+		it "allows additions to be made to new events directly" do
+			observer = described_class.new( :testing )
+			observer.event( 'acme.engine.throttle', add: { factor: 7 } )
+			event = observer.finish
+
+			expect( event.resolve ).to include( factor: 7 )
+		end
+
+
+		describe ":model" do
+
+			it "adds fields germane to processes for the process model"
+			it "adds fields germane to threads for the thread model"
+			it "adds fields germane to loops for the loop model"
+
+		end
+
+
+		describe ":timed" do
+
+			it "adds a calculated duration field" do
+				observer = described_class.new( :testing )
+				observer.event( 'acme.engine.run', timed: true )
+				sleep 0.1
+				event = observer.finish
+
+				expect( event.resolve ).to include( duration: a_value > 0.1 )
+			end
+
+		end
+
+	end
+
+
+	describe "derived fields" do
+
+		it "can be added via an Exception" do
+			observer = described_class.new( :testing )
+			observer.event( 'acme.engine.start' )
+
+			expect {
+				observer.finish_after_block do
+					raise "misfire!"
+				end
+			}.to raise_error( RuntimeError, 'misfire!' )
+
+			event = observer.sender.enqueued_events.last
+			expect( event.type ).to eq( 'acme.engine.start' )
+
+			expect( event.fields ).to include(
+				error: a_hash_including(
+					type: 'RuntimeError',
+					message: 'misfire!',
+					backtrace: an_instance_of( Array )
+				)
+			)
+			expect( event.resolve[:error][:backtrace] ).
+				to all( be_a(Hash).and( include(:label, :path, :lineno) ) )
+		end
+
+
+		it "can be added for any object that responds to #to_h" do
+			observer = described_class.new( :testing )
+			observer.event( 'acme.engine.start' )
+
+			to_h_class = Class.new do
+				def to_h
+					return { sku: '121212', rev: '8c' }
+				end
+			end
+
+			observer.add( to_h_class.new )
+			event = observer.finish
+
+			expect( event.resolve ).to include( sku: '121212', rev: '8c' )
+		end
+
+	end
+
+
+
+	describe "context" do
+
+		it "can be added for all inner events" do
+			observer = described_class.new( :testing )
+			event = observer.event( 'acme.engine.start' ) do
+				observer.add_context( request_id: 'E30E90E0-585B-4015-9C96-AE6EC487970C' )
+
+				inner_event = observer.event( 'acme.engine.rev' ) {}
+			end
+
+			expect( observer.sender.enqueued_events.map(&:resolve) ).
+				to all( include( request_id: 'E30E90E0-585B-4015-9C96-AE6EC487970C' ) )
+		end
+
+	end
+
+end
+