module StatsD::Instrument
The StatsD::Instrument module provides metaprogramming methods to instrument your methods with StatsD metrics. E.g., yopu can create counters on how often a method is called, how often it is successful, the duration of the methods call, etc.
Constants
- VERSION
Public Class Methods
@private
# File lib/statsd/instrument.rb, line 61 def self.duration start = Process.clock_gettime(Process::CLOCK_MONOTONIC) yield Process.clock_gettime(Process::CLOCK_MONOTONIC) - start end
@private
# File lib/statsd/instrument.rb, line 55 def self.generate_metric_name(metric_name, callee, *args) metric_name.respond_to?(:call) ? metric_name.call(callee, args).gsub('::', '.') : metric_name.gsub('::', '.') end
Public Instance Methods
Adds counter instrumentation to a method.
The metric will be incremented for every call of the instrumented method, no matter whether what the method returns, or whether it raises an exception.
@param method (see statsd_measure) @param name (see statsd_measure) @param metric_options (see statsd_measure) @return [void]
# File lib/statsd/instrument.rb, line 164 def statsd_count(method, name, *metric_options) add_to_method(method, name, :count) do define_method(method) do |*args, &block| StatsD.increment(StatsD::Instrument.generate_metric_name(name, self, *args), 1, *metric_options) super(*args, &block) end end end
Adds success and failure counter instrumentation to a method.
A method call will be considered successful if it does not raise an exception, and the result is true-y. Only for successful calls, the metric will be icnremented
@param method (see statsd_measure) @param name (see statsd_measure) @param metric_options (see statsd_measure) @yield (see statsd_count_success) @yieldparam result (see statsd_count_success) @yieldreturn (see statsd_count_success) @return [void] @see statsd_count_success
# File lib/statsd/instrument.rb, line 137 def statsd_count_if(method, name, *metric_options) add_to_method(method, name, :count_if) do define_method(method) do |*args, &block| begin truthiness = result = super(*args, &block) rescue truthiness = false raise else truthiness = (yield(result) rescue false) if block_given? result ensure StatsD.increment(StatsD::Instrument.generate_metric_name(name, self, *args), *metric_options) if truthiness end end end end
Adds success and failure counter instrumentation to a method.
A method call will be considered successful if it does not raise an
exception, and the result is true-y. For successful calls, the metric
[name].success
will be incremented; for failed calls, the
metric name is [name].failure
.
@param method (see statsd_measure) @param name (see statsd_measure) @param metric_options (see statsd_measure) @yield You can pass a block to this method if you want to define yourself what is a successful call
based on the return value of the method.
@yieldparam result The return value of the instrumented method. @yieldreturn [Boolean] Return true iff the return value is consisered a success, false otherwise. @return [void] @see statsd_count_if
# File lib/statsd/instrument.rb, line 105 def statsd_count_success(method, name, *metric_options) add_to_method(method, name, :count_success) do define_method(method) do |*args, &block| begin truthiness = result = super(*args, &block) rescue truthiness = false raise else truthiness = (yield(result) rescue false) if block_given? result ensure suffix = truthiness == false ? 'failure' : 'success' StatsD.increment("#{StatsD::Instrument.generate_metric_name(name, self, *args)}.#{suffix}", 1, *metric_options) end end end end
@private
# File lib/statsd/instrument.rb, line 44 def statsd_instrumentations if defined?(@statsd_instrumentations) @statsd_instrumentations elsif respond_to?(:superclass) && superclass.respond_to?(:statsd_instrumentations) superclass.statsd_instrumentations else @statsd_instrumentations = {} end end
Adds execution duration instrumentation to a method.
@param method [Symbol] The name of the method to instrument. @param name [String, call] The name of the metric to use. You can also pass in a
callable to dynamically generate a metric name
@param metric_options (see StatsD#measure) @return [void]
# File lib/statsd/instrument.rb, line 82 def statsd_measure(method, name, *metric_options) add_to_method(method, name, :measure) do define_method(method) do |*args, &block| StatsD.measure(StatsD::Instrument.generate_metric_name(name, self, *args), nil, *metric_options) { super(*args, &block) } end end end
Removes StatsD counter instrumentation from a method @param method [Symbol] The method to remove instrumentation from. @param name [String] The name of the metric that was used. @return [void] @see statsd_count
# File lib/statsd/instrument.rb, line 178 def statsd_remove_count(method, name) remove_from_method(method, name, :count) end
Removes StatsD conditional counter instrumentation from a method @param method (see statsd_remove_count) @param name (see statsd_remove_count) @return [void] @see statsd_count_if
# File lib/statsd/instrument.rb, line 187 def statsd_remove_count_if(method, name) remove_from_method(method, name, :count_if) end
Removes StatsD success counter instrumentation from a method @param method (see statsd_remove_count) @param name (see statsd_remove_count) @return [void] @see statsd_count_success
# File lib/statsd/instrument.rb, line 196 def statsd_remove_count_success(method, name) remove_from_method(method, name, :count_success) end
Removes StatsD measure instrumentation from a method @param method (see statsd_remove_count) @param name (see statsd_remove_count) @return [void] @see statsd_measure
# File lib/statsd/instrument.rb, line 205 def statsd_remove_measure(method, name) remove_from_method(method, name, :measure) end
Private Instance Methods
# File lib/statsd/instrument.rb, line 223 def add_to_method(method, name, action, &block) instrumentation_module = statsd_instrumentation_for(method, name, action) raise ArgumentError, "already instrumented #{method} for #{self.name}" if instrumentation_module.method_defined?(method) raise ArgumentError, "could not find method #{method} for #{self.name}" unless method_defined?(method) || private_method_defined?(method) method_scope = method_visibility(method) instrumentation_module.module_eval(&block) instrumentation_module.send(method_scope, method) prepend(instrumentation_module) unless self < instrumentation_module end
# File lib/statsd/instrument.rb, line 240 def method_visibility(method) case when private_method_defined?(method) :private when protected_method_defined?(method) :protected else :public end end
# File lib/statsd/instrument.rb, line 236 def remove_from_method(method, name, action) statsd_instrumentation_for(method, name, action).send(:remove_method, method) end
# File lib/statsd/instrument.rb, line 211 def statsd_instrumentation_for(method, name, action) unless statsd_instrumentations.key?([method, name, action]) mod = Module.new do define_singleton_method(:inspect) do "StatsD_Instrument_#{method}_for_#{action}_with_#{name}" end end @statsd_instrumentations = statsd_instrumentations.merge([method, name, action] => mod) end @statsd_instrumentations[[method, name, action]] end