Module: Observability::Instrumentation

Extended by:
Loggability
Included in:
Bunny, CZTop, Grape, PG, Rack, Sequel
Defined in:
lib/observability/instrumentation.rb

Overview

Utilities for loading and installing pre-packaged instrumentation for common libraries.

Defined Under Namespace

Modules: Bunny, CZTop, Grape, PG, Rack, Sequel

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#modules ⇒ Object (readonly)

:singleton-method: The Set of Instrumentation modules that are laoded



23
24
25
 
# File 'lib/observability/instrumentation.rb', line 23

def modules
  @modules
end

Class Method Details

.check_for_module(mod) ⇒ Object

Returns true if mod is defined and is a Module.



75
76
77
78
 
# File 'lib/observability/instrumentation.rb', line 75

def self::check_for_module( mod )
	self.log.debug "Checking for presence of `%s` module..." % [ mod ]
	Object.const_defined?( mod ) && Object.const_get( mod ).is_a?( Module )
end

.dependencies_met?(*module_names) ⇒ Boolean

Returns true if each of the given module_names are defined and are Module objects.

Returns:

  • (Boolean) 


67
68
69
70
71
 
# File 'lib/observability/instrumentation.rb', line 67

def self::dependencies_met?( *module_names )
	return module_names.flatten.all? do |mod|
		self.check_for_module( mod )
	end
end

.extended(mod) ⇒ Object

Extension callback – declare some instance variables in the extending mod.



40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/observability/instrumentation.rb', line 40

def self::extended( mod )
	super

	if self.modules.add?( mod )
		self.log.info "Loaded %p" % [ mod ]
		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
		self.log.warn "Already loaded %p" % [ mod ]
	end
end

.install ⇒ Object

Install loaded instrumentation if the requisite modules are present.



58
59
60
61
62
 
# File 'lib/observability/instrumentation.rb', line 58

def self::install
	self.modules.each do |mod|
		mod.install if mod.available?
	end
end

.load(*libraries) ⇒ Object

Load instrumentation for the specified libraries.



28
29
30
31
32
33
34
35
 
# File 'lib/observability/instrumentation.rb', line 28

def self::load( *libraries )
	libraries.flatten.each do |library|
		libfile = "observability/instrumentation/%s" % [ library ]
		require( libfile )
	end

	return self
end

Instance Method Details

#available? ⇒ Boolean

Returns true if all of the modules registered with #depends_on are defined.

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/observability/instrumentation.rb', line 105

def available?
	return Observability::Instrumentation.dependencies_met?( self.depends_on.to_a )
end

#depends_on(*modules) ⇒ Object

Declare modules that must be available for instrumentation to be loaded. If they are not present when the instrumentation loads, it will be skipped entirely.



84
85
86
87
 
# File 'lib/observability/instrumentation.rb', line 84

def depends_on( *modules )
	@depends_on.merge( modules.flatten )
	return @depends_on
end

#install ⇒ Object

Call installation callbacks which meet their prerequistes.



111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/observability/instrumentation.rb', line 111

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) }

		if missing.empty?
			self.log.debug "Instrumenting %s: %p" % [ dependencies.join(', '), callback ]
			callback.call
		else
			self.log.info "Skipping %p: missing %s" % [ callback, missing.join(', ') ]
		end
	end
rescue LoadError => err
	raise "%p while loading instrumentation"
end

#requires(*files) ⇒ Object

Specified files to require if this instrumentation is loaded.



91
92
93
94
 
# File 'lib/observability/instrumentation.rb', line 91

def requires( *files )
	@requires.merge( files.flatten )
	return @requires
end

#when_installed(*modules, &callback) ⇒ Object

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).



99
100
101
 
# File 'lib/observability/instrumentation.rb', line 99

def when_installed( *modules, &callback )
	self.installation_callbacks.add( [callback, modules] )
end