observability 0.1.0

data/Rakefile

@@ -0,0 +1,102 @@
+#!/usr/bin/env rake
+
+begin
+	require 'hoe'
+rescue LoadError
+	abort "This Rakefile requires hoe (gem install hoe)"
+end
+
+GEMSPEC = 'observability.gemspec'
+
+
+Hoe.plugin :mercurial
+Hoe.plugin :signing
+Hoe.plugin :deveiate
+
+Hoe.plugins.delete :rubyforge
+
+hoespec = Hoe.spec 'observability' do |spec|
+	spec.readme_file = 'README.md'
+	spec.history_file = 'History.md'
+
+	spec.extra_rdoc_files = FileList[ '*.rdoc', '*.md' ]
+	spec.license 'BSD-3-Clause'
+	spec.urls = {
+		home:   'http://bitbucket.org/ged/observability',
+		code:   'http://bitbucket.org/ged/observability',
+		docs:   'http://deveiate.org/code/observability',
+		github: 'http://github.com/ged/observability',
+	}
+
+	spec.developer 'Michael Granger', 'ged@FaerieMUD.org'
+
+	spec.dependency 'concurrent-ruby', '~> 1.1.5'
+	spec.dependency 'concurrent-ruby-ext', '~> 1.1.5'
+	spec.dependency 'loggability', '~> 0.11'
+	spec.dependency 'configurability', '~> 3.3'
+	spec.dependency 'pluggability', '~> 0.6'
+	spec.dependency 'msgpack', '~> 1.3'
+
+	spec.dependency 'timecop', '~> 0.9', :developer
+	spec.dependency 'hoe-deveiate', '~> 0.3', :developer
+	spec.dependency 'simplecov', '~> 0.7', :developer
+	spec.dependency 'rdoc-generator-fivefish', '~> 0.1', :developer
+
+	spec.require_ruby_version( '>=2.4.0' )
+	spec.hg_sign_tags = true if spec.respond_to?( :hg_sign_tags= )
+	spec.check_history_on_release = true if spec.respond_to?( :check_history_on_release= )
+
+	self.rdoc_locations << "deveiate:/usr/local/www/public/code/#{remote_rdoc_dir}"
+end
+
+
+ENV['VERSION'] ||= hoespec.spec.version.to_s
+
+# Run the tests before checking in
+task 'hg:precheckin' => [ :check_history, :check_manifest, :gemspec, :spec ]
+
+task :test => :spec
+
+# Rebuild the ChangeLog immediately before release
+task :prerelease => 'ChangeLog'
+CLOBBER.include( 'ChangeLog' )
+
+desc "Build a coverage report"
+task :coverage do
+	ENV["COVERAGE"] = 'yes'
+	Rake::Task[:spec].invoke
+end
+CLOBBER.include( 'coverage' )
+
+
+# Use the fivefish formatter for docs generated from development checkout
+if File.directory?( '.hg' )
+	require 'rdoc/task'
+
+	Rake::Task[ 'docs' ].clear
+	RDoc::Task.new( 'docs' ) do |rdoc|
+	    rdoc.main = "README.rdoc"
+		rdoc.markup = 'markdown'
+	    rdoc.rdoc_files.include( "*.rdoc", "ChangeLog", "lib/**/*.rb" )
+	    rdoc.generator = :fivefish
+		rdoc.title = 'Observability'
+	    rdoc.rdoc_dir = 'doc'
+	end
+end
+
+task :gemspec => GEMSPEC
+file GEMSPEC => __FILE__
+task GEMSPEC do |task|
+	spec = $hoespec.spec
+	spec.files.delete( '.gemtest' )
+	spec.signing_key = nil
+	spec.cert_chain = ['certs/ged.pem']
+	spec.version = "#{spec.version.bump}.0.pre#{Time.now.strftime("%Y%m%d%H%M%S")}"
+	File.open( task.name, 'w' ) do |fh|
+		fh.write( spec.to_ruby )
+	end
+end
+CLOBBER.include( GEMSPEC.to_s )
+
+task :default => :gemspec
+

data/bin/observability-collector

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+require 'configurability'
+require 'observability'
+require 'observability/collector'
+
+
+if ( configfile = ARGV.first )
+	config = Configurability::Config.load( configfile )
+else
+	config = Configurability.default_config
+end
+
+config.install
+Observability::Collector.start
+

data/examples/basic-usage.rb

@@ -0,0 +1,18 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'observability'
+
+
+class Server
+	extend Observability
+
+
+	observer 'udp://10.2.0.250:11311'
+
+	observe_around :handle_request
+	observe_around :handle_
+
+
+end # class Server
+

data/lib/observability.rb

@@ -0,0 +1,122 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'concurrent'
+require 'concurrent/configuration'
+require 'configurability'
+require 'loggability'
+
+
+# A mixin that adds effortless Observability to your systems.
+module Observability
+	extend Loggability
+
+
+	# Package version
+	VERSION = '0.1.0'
+
+	# Version control revision
+	REVISION = %q$Revision$
+
+
+	# Loggability -- Create a logger
+	log_as :observability
+	Concurrent.global_logger = lambda do |loglevel, progname, message=nil, &block|
+		Observability.logger.add( loglevel, message, progname, &block )
+	end
+
+	autoload :Collector, 'observability/collector'
+	autoload :Event, 'observability/event'
+	autoload :ObserverHooks, 'observability/observer_hooks'
+	autoload :Observer, 'observability/observer'
+	autoload :Sender, 'observability/sender'
+
+
+	@observer_hooks = Concurrent::Map.new
+	singleton_class.attr_reader :observer_hooks
+
+	@observer = Concurrent::IVar.new
+
+
+	### Get the observer hooks for the specified +mod+.
+	def self::[]( mod )
+		mod = mod.class unless mod.is_a?( Module )
+		return self.observer_hooks[ mod ]
+	end
+
+
+	### Extension callback
+	def self::extended( mod )
+		super
+
+		Observability.observer_hooks.compute_if_absent( mod ) do
+			observer_hooks = Observability::ObserverHooks.dup
+			mod.prepend( observer_hooks )
+			observer_hooks
+		end
+
+		mod.singleton_class.extend( Observability ) unless mod.singleton_class?
+	end
+
+
+	### Return the current Observer, creating it if necessary.
+	def self::observer
+		unless @observer.complete?
+			self.log.debug "Creating the observer agent."
+			@observer.try_set do
+				obs = Observability::Observer.new
+				obs.start
+				obs
+			end
+		end
+
+		return @observer.value!
+	end
+
+
+	### Reset all per-process Observability state. This should be called, for instance,
+	### after a fork or between tests.
+	def self::reset
+		@observer.value.stop if @observer.complete?
+		@observer = Concurrent::IVar.new
+	end
+
+
+	### Make a body for a wrapping method for the method with the given +name+ and
+	### +context+, passing the given +options+.
+	def self::make_wrapped_method( name, context, options, &callback )
+		return Proc.new do |*m_args, **m_options, &block|
+			Loggability[ Observability ].debug "Wrapped method %p: %p" %
+				[ name, context ]
+			Observability.observer.event( context, **options ) do
+				# :TODO: Freeze or dup the arguments to prevent accidental modification?
+				callback.call( *m_args, **m_options, &block ) if callback
+				super( *m_args, **m_options, &block )
+			end
+		end
+	end
+
+	#
+	# DSL Methods
+	#
+
+	### Wrap an instance method in an observer call.
+	def observe_method( method_name, *details, **options, &callback )
+		hooks = Observability.observer_hooks[ self ] or
+			raise "No observer hooks installed for %p?!" % [ self ]
+
+		context = self.instance_method( method_name )
+		context = [ context, *details ]
+		method_body = Observability.make_wrapped_method( method_name, context, options, &callback )
+
+		hooks.define_method( method_name, &method_body )
+	end
+
+
+	### Wrap a class method in an observer call.
+	def observe_class_method( method_name, *details, **options, &callback )
+		self.singleton_class.observe_method( method_name, *details, **options, &callback )
+	end
+
+end # module Observability
+

data/lib/observability/collector.rb

@@ -0,0 +1,61 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'socket'
+require 'pluggability'
+require 'loggability'
+
+
+require 'observability' unless defined?( Observability )
+
+
+class Observability::Collector
+	extend Loggability,
+		Pluggability,
+		Configurability
+
+	# Loggability API -- log to the Observability logger
+	log_to :observability
+
+	# Set the directories to search for concrete subclassse
+	plugin_prefixes 'observability/collector'
+
+	# Configurability -- declare config settings and defaults
+	configurability( 'observability.collector' ) do
+
+		setting :type, default: 'timescale'
+
+	end
+
+
+	# Prevent direct instantiation
+	private_class_method :new
+
+
+	### Let subclasses be inherited
+	def self::inherited( subclass )
+		super
+		subclass.public_class_method( :new )
+	end
+
+
+	### Create an instance of the configured type of collector and return it.
+	def self::configured_type
+		return self.create( self.type )
+	end
+
+
+	### Start a collector of the specified +type+, returning only when it shuts down.
+	def self::start
+		instance = self.configured_type
+		instance.start
+	end
+
+
+	### Start the collector.
+	def start
+		# No-op
+	end
+
+end # class Observability::Collector
+

data/lib/observability/collector/timescale.rb

@@ -0,0 +1,140 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'sequel'
+require 'configurability'
+
+require 'observability/collector' unless defined?( Observability::Collector )
+
+
+class Observability::Collector::Timescale < Observability::Collector
+	extend Configurability,
+		Loggability
+
+	Sequel.extension( :pg_json )
+
+
+	# The maximum size of event messages
+	MAX_EVENT_BYTES = 64 * 1024
+
+	# The number of seconds to wait between IO loops
+	LOOP_TIMER = 0.25
+
+	# The config to pass to JSON.parse
+	JSON_CONFIG = {
+		object_class: Sequel::Postgres::JSONHash,
+		array_class: Sequel::Postgres::JSONArray
+	}.freeze
+
+
+	log_to :observability
+
+	configurability( 'observability.collector.timescale' ) do
+
+		##
+		# The host to bind to
+		setting :host, default: 'localhost'
+
+		##
+		# The port to bind to
+		setting :port, default: 15775
+
+		##
+		# The URL of the timescale DB to store events in
+		setting :db, default: 'postgres:/observability'
+	end
+
+
+	### Create a new UDP collector
+	def initialize
+		super
+
+		@socket     = UDPSocket.new
+		@db         = nil
+		@cursor     = nil
+		@processing = false
+	end
+
+
+	######
+	public
+	######
+
+	### Start receiving events.
+	def start
+		self.log.info "Starting up."
+		@db = Sequel.connect( self.class.db )
+		@db.extension( :pg_json )
+		# @cursor = @db[ :events ].prepare( :insert, :insert_new_event,
+		# 	 time: :$time,
+		# 	 type: :$type,
+		# 	 version: :$version,
+		# 	 data: :$data
+		# )
+
+		@socket.bind( self.class.host, self.class.port )
+
+		self.start_processing
+	end
+
+
+	### Stop receiving events.
+	def stop
+		self.stop_processing
+
+		@cursor = nil
+		@db.disconnct
+	end
+
+
+	### Start consuming incoming events and storing them.
+	def start_processing
+		@processing = true
+		while @processing
+			event = self.read_next_event or next
+			self.log.debug "Read event: %p" % [ event ]
+			self.store_event( event )
+		end
+	end
+
+
+	### Stop consuming events.
+	def stop_processing
+		@processing = false
+	end
+
+
+	### Read the next event from the socket
+	def read_next_event
+		self.log.debug "Reading next event."
+		data = @socket.recv_nonblock( MAX_EVENT_BYTES, exception: false )
+
+		if data == :wait_readable
+			IO.select( [@socket], nil, nil, LOOP_TIMER )
+			return nil
+		elsif data.empty?
+			return nil
+		else
+			self.log.info "Read %d bytes" % [ data.bytesize ]
+			return JSON.parse( data )
+		end
+	end
+
+
+	### Store the specified +event+.
+	def store_event( event )
+		time    = event.delete('@timestamp')
+		type    = event.delete('@type')
+		version = event.delete('@version')
+
+		# @cursor.call( time: time, type: type, version: version, data: event )
+		@db[ :events ].insert(
+			 time: time,
+			 type: type,
+			 version: version,
+			 data: Sequel.pg_json( event )
+		)
+	end
+
+end # class Observability::Collector::UDP
+