observability 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb2bcfb9c815937bbc46798e8645ccc77e0a7e87dfa5024d327c9e9d4db5a1ff
-  data.tar.gz: c561389042c72073f21a5e18c06252a36177cd19022e6330c2633f8368953a8f
+  metadata.gz: ca1dcfc173024a7ef76eb412bc386cae1e45ccc1844cd79bae98cea45377b110
+  data.tar.gz: b3c53287536774ec9d33c3acc63fe10856921cdccdb2485850191924e2ed707c
 SHA512:
-  metadata.gz: 4295af2f27a6d6eed728608896ae92fd79736d159c9b2f4c0595b5918708e6b6f63cde95d9824450daa741db481b0ecc7331c842fd43006eb03e704a35b9e603
-  data.tar.gz: e98b10c101567afa169e55d4b75dffa400d06491ff0320e3c9f01c72d73349ca413655697bb4e69b6493bfa676b2682ff1a48a035f3474de9552e349f9734fbf
+  metadata.gz: 81a5b9df54dd9cc7d350a61f186741e0dd74f7651d8c21a527592dcfe10d1463a4c86b332de3351e5bfab44030a431169e2b4c587a1a86de764073f9e517468c
+  data.tar.gz: 52002d309d9ee18d8ca6a26d7f02023bfdbd10e5b9ebf6a1959b678a7f4f17878a2f3567ec046a34bd47b0d02221a0cb77e0232ab62b394e7dbd171541dc2629

data/History.md

@@ -2,6 +2,20 @@
 
 ---
 
+## v0.3.0 [2020-02-21] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Add `requires` to instrumentation, add a PG instrument
+- Add an event ID for cross-application context
+- Update for Ruby 2.7.
+
+Bugfixes:
+
+- Add a provisional fix for observing arity-0 methods
+- Guard against blockless observe calls
+
+
 ## v0.2.0 [2019-10-16] Michael Granger <ged@faeriemud.org>
 
 Improvements:

data/README.md

@@ -19,7 +19,7 @@ Observability is a toolkit for instrumenting code to make it more observable.
 It follows the principle of Observability-Oriented Design as expressed by Charity
 Majors (@mipsytipsy).
 
-Its goals are [stolen from https://charity.wtf/2019/02/05/logs-vs-structured-events/]:
+Its goals are stolen from https://charity.wtf/2019/02/05/logs-vs-structured-events/:
 
 * Emit a rich record from the perspective of a single action as the code is
   executing.
@@ -35,6 +35,8 @@ Its goals are [stolen from https://charity.wtf/2019/02/05/logs-vs-structured-eve
   system quality, system behavior, outliers, error conditions, etc. You will be
   absolutely amazed how useful it is … and appalled by what you turn up. 🙂
 
+[![builds.sr.ht status](https://builds.sr.ht/~ged/Observability.svg)](https://builds.sr.ht/~ged/Observability?)
+
 
 ## Prerequisites
 
@@ -52,13 +54,6 @@ You can check out the current development source with Mercurial via its
 [project page][sourcehut]. Or if you prefer Git, via
 [its Github mirror][github].
 
-After checking out the source, run:
-
-    $ rake newb
-
-This task will install any missing dependencies, run the tests/specs,
-and generate the API documentation.
-
 
 ## Author
 
@@ -67,7 +62,7 @@ and generate the API documentation.
 
 ## License
 
-Copyright (c) 2019, Michael Granger
+Copyright (c) 2019-2020, Michael Granger
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/lib/observability.rb

@@ -13,11 +13,14 @@ module Observability
 
 
 	# Package version
-	VERSION = '0.2.0'
+	VERSION = '0.3.0'
 
 	# Version control revision
 	REVISION = %q$Revision$
 
+	# The default port to use for network communications
+	DEFAULT_PORT = 15775
+
 
 	# Loggability -- Create a logger
 	log_as :observability
@@ -93,13 +96,27 @@ module Observability
 	### 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 )
+
+		# Supering into arity-zero methods with (empty) *args and **options raises an
+		# ArgumentError for some reason.
+		if context.first.arity.zero?
+			return Proc.new do |*m_args, **m_options, &block|
+				Loggability[ Observability ].debug "Wrapped zero-arity method %p: %p" %
+					[ name, context ]
+				Observability.observer.event( context, **options ) do
+					callback.call( *m_args, **m_options, &block ) if callback
+					super( *m_args, &block )
+				end
+			end
+		else
+			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
 	end

data/lib/observability/collector/rabbitmq.rb

@@ -36,7 +36,7 @@ class Observability::Collector::RabbitMQ < Observability::Collector
 
 		##
 		# The port to bind to
-		setting :port, default: 15775
+		setting :port, default: Observability::DEFAULT_PORT
 
 		##
 		# The broker_uri to use when connecting to RabbitMQ

data/lib/observability/collector/timescale.rb

@@ -37,7 +37,7 @@ class Observability::Collector::Timescale < Observability::Collector
 
 		##
 		# The port to bind to
-		setting :port, default: 15775
+		setting :port, default: Observability::DEFAULT_PORT
 
 		##
 		# The URL of the timescale DB to store events in
@@ -106,7 +106,6 @@ class Observability::Collector::Timescale < Observability::Collector
 
 	### 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
@@ -123,6 +122,8 @@ class Observability::Collector::Timescale < Observability::Collector
 
 	### Store the specified +event+.
 	def store_event( event )
+		self.log.debug "Storing event: %p" % [ event ]
+
 		time    = event.delete('@timestamp')
 		type    = event.delete('@type')
 		version = event.delete('@version')

data/lib/observability/event.rb

@@ -3,6 +3,7 @@
 
 require 'time'
 require 'forwardable'
+require 'uuid'
 require 'loggability'
 require 'concurrent'
 
@@ -22,8 +23,23 @@ class Observability::Event
 	log_to :observability
 
 
+	### Return a generator that can return a unique ID string for identifying Events
+	### across application boundaries.
+	def self::id_generator
+		return @id_generator ||= UUID.new
+	end
+
+
+	### Generate a new Event ID.
+	def self::generate_id
+		return self.id_generator.generate
+	end
+
+
 	### Create a new event
-	def initialize( type, **fields )
+	def initialize( type, parent=nil, **fields )
+		@id        = self.class.generate_id
+		@parent_id = parent&.id
 		@type      = type.freeze
 		@timestamp = Time.now
 		@start     = Concurrent.monotonic_time
@@ -35,6 +51,14 @@ class Observability::Event
 	public
 	######
 
+	##
+	# The ID of the event, used to pass context through application boundaries
+	attr_reader :id
+
+	##
+	# The ID of the containing context event, if there is one
+	attr_reader :parent_id
+
 	##
 	# The type of the event, which should be a string of the form: 'foo.bar.baz'
 	attr_reader :type
@@ -71,6 +95,8 @@ class Observability::Event
 		unless @fields.frozen?
 			self.log.debug "Resolving event %#x" % [ self.object_id ]
 			data = self.fields.merge(
+				:@id => self.id,
+				:@parent_id => self.parent_id,
 				:@type => self.type,
 				:@timestamp => self.timestamp,
 				:@version => FORMAT_VERSION

data/lib/observability/instrumentation.rb

@@ -45,6 +45,7 @@ module Observability::Instrumentation
 			mod.extend( Loggability )
 			mod.log_to( :observability )
 			mod.instance_variable_set( :@depends_on, Set.new )
+			mod.instance_variable_set( :@requires, Set.new )
 			mod.instance_variable_set( :@installation_callbacks, Set.new )
 			mod.singleton_class.attr_reader( :installation_callbacks )
 		else
@@ -81,11 +82,18 @@ module Observability::Instrumentation
 	### If they are not present when the instrumentation loads, it will be skipped
 	### entirely.
 	def depends_on( *modules )
-		@depends_on.merge( modules.flatten(1) )
+		@depends_on.merge( modules.flatten )
 		return @depends_on
 	end
 
 
+	### Specified +files+ to require if this instrumentation is loaded.
+	def requires( *files )
+		@requires.merge( files.flatten )
+		return @requires
+	end
+
+
 	### Register a +callback+ that will be called when instrumentation is installed,
 	### if and only if all of the given +modules+ are present (may be empty).
 	def when_installed( *modules, &callback )
@@ -101,6 +109,9 @@ module Observability::Instrumentation
 
 	### Call installation callbacks which meet their prerequistes.
 	def install
+		self.requires.each do |file|
+			require( file )
+		end
 		self.installation_callbacks.each do |callback, dependencies|
 			missing = dependencies.
 				reject {|mod| Observability::Instrumentation.check_for_module(mod) }
@@ -112,6 +123,8 @@ module Observability::Instrumentation
 				self.log.info "Skipping %p: missing %s" % [ callback, missing.join(', ') ]
 			end
 		end
+	rescue LoadError => err
+		raise "%p while loading instrumentation"
 	end
 
 end # module Observability::Instrumentation

data/lib/observability/instrumentation/cztop.rb

@@ -0,0 +1,39 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'observability/instrumentation' unless defined?( Observability::Instrumentation )
+
+
+# Instrumentation for the CZTop library
+# Refs:
+# - https://gitlab.com/paddor/cztop
+module Observability::Instrumentation::CZTop
+	extend Observability::Instrumentation
+
+	depends_on 'CZTop'
+
+
+	when_installed( 'CZTop::Socket' ) do
+		CZTop::Socket.extend( Observability )
+		CZTop::Socket.observe_method( :CURVE_server! )
+		CZTop::Socket.observe_method( :CURVE_client! )
+		CZTop::Socket.observe_method( :connect )
+		CZTop::Socket.observe_method( :disconnect )
+		CZTop::Socket.observe_method( :close )
+		CZTop::Socket.observe_method( :bind )
+		CZTop::Socket.observe_method( :unbind )
+		CZTop::Socket.observe_method( :signal )
+		CZTop::Socket.observe_method( :wait )
+	end
+
+
+	when_installed( 'CZTop::Message' ) do
+		CZTop::Message.extend( Observability )
+		CZTop::Message.observe_class_method( :receive_from )
+		CZTop::Message.observe_method( :send_to )
+		CZTop::Message.observe_method( :<< )
+		CZTop::Message.observe_method( :routing_id= )
+	end
+
+end # module Observability::Instrumentation::CZTop
+

data/lib/observability/instrumentation/pg.rb

@@ -0,0 +1,70 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'observability/instrumentation' unless defined?( Observability::Instrumentation )
+
+
+# Instrumentation for the 'pg' PostgreSQL driver
+# Refs:
+# - https://github.com/ged/ruby-pg
+module Observability::Instrumentation::PG
+	extend Observability::Instrumentation
+
+	depends_on 'PG'
+
+	requires 'pg_query'
+
+	when_installed( 'PG::Connection' ) do
+		PG::Connection.extend( Observability )
+		PG::Connection.observe_class_method( :connect_start )
+		PG::Connection.observe_class_method( :ping, timed: true )
+		PG::Connection.observe_method( :connect_poll )
+		PG::Connection.observe_method( :reset )
+		PG::Connection.observe_method( :reset_start )
+		PG::Connection.observe_method( :reset_poll )
+		PG::Connection.observe_method( :sync_exec )
+		PG::Connection.observe_method( :finish )
+
+		PG::Connection.observe_method( :exec, timed: true, &self.method(:observe_exec) )
+		PG::Connection.observe_method( :exec_params, timed: true, &self.method(:observe_exec) )
+
+		PG::Connection.observe_method( :sync_exec, timed: true, &self.method(:observe_exec) )
+		PG::Connection.observe_method( :sync_exec_params, timed: true, &self.method(:observe_exec) )
+
+		PG::Connection.observe_method( :prepare, timed: true, &self.method(:observe_prepare) )
+		PG::Connection.observe_method( :exec_prepared, timed: true, &self.method(:observe_exec_prepared) )
+
+		PG::Connection.observe_method( :sync_prepare, timed: true, &self.method(:observe_prepare) )
+		PG::Connection.observe_method( :sync_exec_prepared, timed: true, &self.method(:observe_exec_prepared) )
+	end
+
+
+	###############
+	module_function
+	###############
+
+	### Observer callback for the *exec methods.
+	def observe_exec( sql, * )
+		nsql = PgQuery.normalize( sql )
+		Observability.observer.add( query: nsql )
+	rescue => err
+		Loggability[ Observability ].warn "Couldn't normalize query: %p" % [ sql ]
+	end
+
+
+	### Observer callback for *prepare methods.
+	def observe_prepare( name, query, * )
+		nsql = PgQuery.normalize( query )
+		Observability.observer.add( statement_name: name, query: nsql )
+	rescue => err
+		Loggability[ Observability ].warn "Couldn't normalize query: %p" % [ sql ]
+	end
+
+
+	### Observer callback for *exec_prepared methods.
+	def observe_exec_prepared( name, query, * )
+		Observability.observer.add( statement_name: name )
+	end
+
+end # module Observability::Instrumentation::PG
+

data/lib/observability/instrumentation/sequel.rb

@@ -32,6 +32,5 @@ module Observability::Instrumentation::Sequel
 		end
 	end
 
-
 end # module Observability::Instrumentation::Sequel
 

data/lib/observability/observer.rb

@@ -54,7 +54,8 @@ class Observability::Observer
 		type = self.type_from_object( type )
 		fields = self.fields_from_options( options )
 
-		event = Observability::Event.new( type, **fields )
+		parent = @event_stack.value.last
+		event = Observability::Event.new( type, parent, **fields )
 		@event_stack.value.push( event )
 
 		new_context = @context_stack.value.last&.dup || {}

data/lib/observability/observer_hooks.rb

@@ -11,10 +11,13 @@ module Observability::ObserverHooks
 	### 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 )
+		if block
+			marker = Observability.observer.event( [block, detail], **options )
+			Observability.observer.finish_after_block( marker, &block )
+		else
+			Loggability[ Observability ].warn "No block given for %p -> %p with options: %p" %
+				[ self, detail, options ]
+		end
 	end
 
 

data/lib/observability/sender/udp.rb

@@ -28,7 +28,7 @@ class Observability::Sender::UDP < Observability::Sender
 
 		##
 		# The port to send events to
-		setting :port, default: 15775
+		setting :port, default: Observability::DEFAULT_PORT
 
 	end
 

data/lib/observability/sender/udp_multicast.rb

@@ -35,7 +35,7 @@ class Observability::Sender::UdpMulticast < Observability::Sender
 
 		##
 		# The port to bind to
-		setting :port, default: 15775
+		setting :port, default: Observability::DEFAULT_PORT
 
 	end
 

data/spec/observability/event_spec.rb

@@ -35,6 +35,26 @@ describe Observability::Event do
 	end
 
 
+	it "can be created with a parent event" do
+		parent_event = described_class.new( 'acme.server.request', score: 100, time: 48 )
+		child_event = described_class.new( 'acme.user.created', parent_event )
+
+		expect( child_event.parent_id ).to eq( parent_event.id )
+	end
+
+
+	it "is created with a unique ID" do
+		event1 = described_class.new( 'acme.server.request' )
+		event2 = described_class.new( 'acme.server.request' )
+
+		expect( event1.id ).to be_a( String )
+		expect( event1.id.length ).to be > 16
+		expect( event2.id ).to be_a( String )
+		expect( event2.id.length ).to be == event1.id.length
+		expect( event2.id ).to_not eq( event1.id )
+	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) )
@@ -99,7 +119,7 @@ describe Observability::Event do
 
 		sleep 0.25
 
-		expect( event.resolve[:duration] ).to be_within( 0.01 ).of( 0.25 )
+		expect( event.resolve[:duration] ).to be_a( Float ).and( be > 0.25 )
 	end
 
 end

data/spec/observability/sender/udp_spec.rb

@@ -34,7 +34,7 @@ describe Observability::Sender::UDP do
 			block.call( *args )
 		end
 		expect( udp_socket ).to receive( :connect ).with( 'localhost', 8787 )
-		expect( udp_socket ).to receive( :sendmsg_nonblock ) do |msg, flags, **opts|
+		expect( udp_socket ).to receive( :sendmsg_nonblock ) do |msg, flags, opts={}|
 			expect( msg ).to match( /\{.*"@type":"acme\.engine\.startup".*\}/ )
 			expect( flags ).to eq( 0 )
 			expect( opts ).to include( exception: false )
@@ -55,7 +55,7 @@ describe Observability::Sender::UDP do
 			block.call( *args )
 		end
 		expect( udp_socket ).to receive( :connect ).with( 'localhost', 8787 )
-		expect( udp_socket ).to receive( :sendmsg_nonblock ) do |msg, flags, **opts|
+		expect( udp_socket ).to receive( :sendmsg_nonblock ) do |msg, flags, opts={}|
 			if !blocked_once
 				blocked_once = true
 				:wait_writable

data/spec/spec_helper.rb

@@ -147,6 +147,8 @@ RSpec.configure do |config|
 	config.mock_with( :rspec ) do |mock|
 		mock.syntax = :expect
 	end
+	config.warnings = true
+	config.profile_examples = 5
 
 	config.include( Loggability::SpecHelpers )
 	config.include( Observability::SpecHelpers )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: observability
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Michael Granger
@@ -34,7 +34,7 @@ cert_chain:
   jBZSA+N+xUTgUWpXjjwsLZjzJkhWATJWq+krNXcqpwXo6HsjmdUxoFMt63RBb+sI
   XrxOxp8o0uOkU7FdLSGsyqJ2LzsR4obN
   -----END CERTIFICATE-----
-date: 2019-10-17 00:00:00.000000000 Z
+date: 2020-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -70,42 +70,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.11'
+        version: '0.15'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.11'
+        version: '0.15'
 - !ruby/object:Gem::Dependency
   name: configurability
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.3'
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.3'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: pluggability
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: msgpack
   requirement: !ruby/object:Gem::Requirement
@@ -120,6 +120,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: uuid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.26'
 - !ruby/object:Gem::Dependency
   name: timecop
   requirement: !ruby/object:Gem::Requirement
@@ -140,14 +182,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -182,7 +224,8 @@ description: |-
   Majors (@mipsytipsy).
 email:
 - ged@faeriemud.org
-executables: []
+executables:
+- observability-collector
 extensions: []
 extra_rdoc_files: []
 files:
@@ -198,7 +241,9 @@ files:
 - lib/observability/event.rb
 - lib/observability/instrumentation.rb
 - lib/observability/instrumentation/bunny.rb
+- lib/observability/instrumentation/cztop.rb
 - lib/observability/instrumentation/grape.rb
+- lib/observability/instrumentation/pg.rb
 - lib/observability/instrumentation/rack.rb
 - lib/observability/instrumentation/sequel.rb
 - lib/observability/observer.rb
@@ -237,7 +282,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Observability is a toolkit for instrumenting code to make it more observable.