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.4"

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.duration ⇒ Object 



61
62
63
64
65
 
# 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

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



55
56
57
 
# 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

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



164
165
166
167
168
169
170
171
 
# 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

#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:



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# 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

#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:



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# 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

#statsd_instrumentations ⇒ Object 



44
45
46
47
48
49
50
51
52
 
# 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

#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



82
83
84
85
86
87
88
 
# 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

#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:



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

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:



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

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:



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

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:



205
206
207
 
# File 'lib/statsd/instrument.rb', line 205

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