Module: StatsD::Instrument

Defined in:
lib/statsd/instrument.rb,
lib/statsd/instrument/version.rb

Overview

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.

Defined Under Namespace

Modules: Assertions, Backends, Environment, Helpers, Matchers Classes: Backend, Metric, MetricExpectation, Railtie

Constant Summary collapse

VERSION = 
"2.1.1"

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.duration ⇒ Object 



51
52
53
54
55
 
# File 'lib/statsd/instrument.rb', line 51

def self.duration
  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  yield
  Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
end

.generate_metric_name(metric_name, callee, *args) ⇒ Object 



45
46
47
 
# File 'lib/statsd/instrument.rb', line 45

def self.generate_metric_name(metric_name, callee, *args)
  metric_name.respond_to?(:call) ? metric_name.call(callee, args).gsub('::', '.') : metric_name.gsub('::', '.')
end

Instance Method Details

#statsd_count(method, name, *metric_options) ⇒ void

This method returns an undefined value.

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.

Parameters:

  • method (Symbol) —

    The name of the method to instrument.

  • name (String, #call) —

    The name of the metric to use. You can also pass in a callable to dynamically generate a metric name



154
155
156
157
158
159
160
161
 
# File 'lib/statsd/instrument.rb', line 154

def statsd_count(method, name, *metric_options)
  add_to_method(method, name, :count) do |old_method, new_method, metric_name|
    define_method(new_method) do |*args, &block|
      StatsD.increment(StatsD::Instrument.generate_metric_name(metric_name, self, *args), 1, *metric_options)
      send(old_method, *args, &block)
    end
  end
end

#statsd_count_if(method, name, *metric_options) {|result| ... } ⇒ void

This method returns an undefined value.

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

Parameters:

  • method (Symbol) —

    The name of the method to instrument.

  • name (String, #call) —

    The name of the metric to use. You can also pass in a callable to dynamically generate a metric name

Yields:

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

Yield Parameters:

  • result —

    The return value of the instrumented method.

Yield Returns:

  • (Boolean) —

    Return true iff the return value is consisered a success, false otherwise.

See Also:



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/statsd/instrument.rb', line 127

def statsd_count_if(method, name, *metric_options)
  add_to_method(method, name, :count_if) do |old_method, new_method, metric_name|
    define_method(new_method) do |*args, &block|
      begin
        truthiness = result = send(old_method, *args, &block)
      rescue
        truthiness = false
        raise
      else
        truthiness = (yield(result) rescue false) if block_given?
        result
      ensure
        StatsD.increment(StatsD::Instrument.generate_metric_name(metric_name, self, *args), *metric_options) if truthiness
      end
    end
  end
end

#statsd_count_success(method, name, *metric_options) {|result| ... } ⇒ void

This method returns an undefined value.

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.

Parameters:

  • method (Symbol) —

    The name of the method to instrument.

  • name (String, #call) —

    The name of the metric to use. You can also pass in a callable to dynamically generate a metric name

Yields:

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

Yield Parameters:

  • result —

    The return value of the instrumented method.

Yield Returns:

  • (Boolean) —

    Return true iff the return value is consisered a success, false otherwise.

See Also:



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/statsd/instrument.rb', line 95

def statsd_count_success(method, name, *metric_options)
  add_to_method(method, name, :count_success) do |old_method, new_method, metric_name|
    define_method(new_method) do |*args, &block|
      begin
        truthiness = result = send(old_method, *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(metric_name, self, *args)}.#{suffix}", 1, *metric_options)
      end
    end
  end
end

#statsd_measure(method, name, *metric_options) ⇒ void

This method returns an undefined value.

Adds execution duration instrumentation to a method.

Parameters:

  • method (Symbol) —

    The name of the method to instrument.

  • name (String, #call) —

    The name of the metric to use. You can also pass in a callable to dynamically generate a metric name



72
73
74
75
76
77
78
 
# File 'lib/statsd/instrument.rb', line 72

def statsd_measure(method, name, *metric_options)
  add_to_method(method, name, :measure) do |old_method, new_method, metric_name, *args|
    define_method(new_method) do |*args, &block|
      StatsD.measure(StatsD::Instrument.generate_metric_name(metric_name, self, *args), nil, *metric_options) { send(old_method, *args, &block) }
    end
  end
end

#statsd_remove_count(method, name) ⇒ void

This method returns an undefined value.

Removes StatsD counter instrumentation from a method

Parameters:

  • method (Symbol) —

    The method to remove instrumentation from.

  • name (String) —

    The name of the metric that was used.

See Also:



168
169
170
 
# File 'lib/statsd/instrument.rb', line 168

def statsd_remove_count(method, name)
  remove_from_method(method, name, :count)
end

#statsd_remove_count_if(method, name) ⇒ void

This method returns an undefined value.

Removes StatsD conditional counter instrumentation from a method

Parameters:

  • method (Symbol) —

    The method to remove instrumentation from.

  • name (String) —

    The name of the metric that was used.

See Also:



177
178
179
 
# File 'lib/statsd/instrument.rb', line 177

def statsd_remove_count_if(method, name)
  remove_from_method(method, name, :count_if)
end

#statsd_remove_count_success(method, name) ⇒ void

This method returns an undefined value.

Removes StatsD success counter instrumentation from a method

Parameters:

  • method (Symbol) —

    The method to remove instrumentation from.

  • name (String) —

    The name of the metric that was used.

See Also:



186
187
188
 
# File 'lib/statsd/instrument.rb', line 186

def statsd_remove_count_success(method, name)
  remove_from_method(method, name, :count_success)
end

#statsd_remove_measure(method, name) ⇒ void

This method returns an undefined value.

Removes StatsD measure instrumentation from a method

Parameters:

  • method (Symbol) —

    The method to remove instrumentation from.

  • name (String) —

    The name of the metric that was used.

See Also:



195
196
197
 
# File 'lib/statsd/instrument.rb', line 195

def statsd_remove_measure(method, name)
  remove_from_method(method, name, :measure)
end