module StatsD::Instrument
The StatsD::Instrument
module provides metaprogramming methods to instrument your methods with StatsD
metrics. E.g., you can create counters on how often a method is called, how often it is successful, the duration of the methods call, etc.
Constants
- MetricExpectation
@private
- UNSPECIFIED
- VERSION
- VOID
- VoidClass
Public Class Methods
Even though this method is considered private, and is no longer used internally, applications in the wild rely on it. As a result, we cannot remove this method until the next major version.
@deprecated Use Process.clock_gettime(Process::CLOCK_MONOTONIC) instead.
# File lib/statsd/instrument.rb, line 42 def self.current_timestamp Process.clock_gettime(Process::CLOCK_MONOTONIC) end
Even though this method is considered private, and is no longer used internally, applications in the wild rely on it. As a result, we cannot remove this method until the next major version.
@deprecated You can implement similar functionality yourself using
`Process.clock_gettime(Process::CLOCK_MONOTONIC)`. Think about what will happen if an exception happens during the block execution though.
# File lib/statsd/instrument.rb, line 53 def self.duration start = Process.clock_gettime(Process::CLOCK_MONOTONIC) yield Process.clock_gettime(Process::CLOCK_MONOTONIC) - start end
Generates a metric name for an instrumented method. @private @return [String]
# File lib/statsd/instrument.rb, line 33 def self.generate_metric_name(name, callee, *args) name.respond_to?(:call) ? name.call(callee, args).gsub("::", ".") : 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 185 def statsd_count(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil) add_to_method(method, name, :count) do define_method(method) do |*args, &block| client ||= StatsD.singleton_client key = StatsD::Instrument.generate_metric_name(name, self, *args) client.increment(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix) super(*args, &block) end end end
Adds success 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 incremented.
@param method (see statsd_measure
) @param name (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 150 def statsd_count_if(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil) add_to_method(method, name, :count_if) do define_method(method) do |*args, &block| truthiness = result = super(*args, &block) rescue truthiness = false raise else if block_given? begin truthiness = yield(result) rescue truthiness = false end end result ensure if truthiness client ||= StatsD.singleton_client key = StatsD::Instrument.generate_metric_name(name, self, *args) client.increment(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix) 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 considered a success, false otherwise. @return [void] @see statsd_count_if
# File lib/statsd/instrument.rb, line 113 def statsd_count_success(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil) add_to_method(method, name, :count_success) do define_method(method) do |*args, &block| truthiness = result = super(*args, &block) rescue truthiness = false raise else if block_given? begin truthiness = yield(result) rescue truthiness = false end end result ensure client ||= StatsD.singleton_client suffix = truthiness == false ? "failure" : "success" key = StatsD::Instrument.generate_metric_name(name, self, *args) client.increment("#{key}.#{suffix}", sample_rate: sample_rate, tags: tags, no_prefix: no_prefix) end end end
Adds execution duration instrumentation to a method as a distribution.
@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] @note Supported by the datadog implementation only (in beta)
# File lib/statsd/instrument.rb, line 86 def statsd_distribution(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil) add_to_method(method, name, :distribution) do define_method(method) do |*args, &block| client ||= StatsD.singleton_client key = StatsD::Instrument.generate_metric_name(name, self, *args) client.distribution(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix) do super(*args, &block) end end end end
@private
# File lib/statsd/instrument.rb, line 20 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 as a timing.
@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 66 def statsd_measure(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil) add_to_method(method, name, :measure) do define_method(method) do |*args, &block| client ||= StatsD.singleton_client key = StatsD::Instrument.generate_metric_name(name, self, *args) client.measure(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix) do super(*args, &block) end 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 201 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 210 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 219 def statsd_remove_count_success(method, name) remove_from_method(method, name, :count_success) end
Removes StatsD
distribution 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 237 def statsd_remove_distribution(method, name) remove_from_method(method, name, :distribution) 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 228 def statsd_remove_measure(method, name) remove_from_method(method, name, :measure) end
Private Instance Methods
# File lib/statsd/instrument.rb, line 259 def add_to_method(method, name, action, &block) instrumentation_module = statsd_instrumentation_for(method, name, action) if instrumentation_module.method_defined?(method) raise ArgumentError, "Already instrumented #{method} for #{self.name}" end unless method_defined?(method) || private_method_defined?(method) raise ArgumentError, "could not find method #{method} for #{self.name}" end method_scope = method_visibility(method) instrumentation_module.module_eval(&block) instrumentation_module.send(method_scope, method) if instrumentation_module.respond_to?(:ruby2_keywords, true) instrumentation_module.send(:ruby2_keywords, method) end prepend(instrumentation_module) unless self < instrumentation_module end
# File lib/statsd/instrument.rb, line 284 def method_visibility(method) if private_method_defined?(method) :private elsif protected_method_defined?(method) :protected else :public end end
# File lib/statsd/instrument.rb, line 280 def remove_from_method(method, name, action) statsd_instrumentation_for(method, name, action).send(:remove_method, method) end
# File lib/statsd/instrument.rb, line 247 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