Module: StatsD::Instrument

Includes:
StrictMetaprogramming
Defined in:
lib/statsd/instrument.rb,
lib/statsd/instrument/strict.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, Strict, StrictMetaprogramming Classes: Backend, Metric, MetricExpectation, Railtie

Constant Summary collapse

VERSION = 
"2.5.1"

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.current_timestamp ⇒ Object

Deprecated.

Use Process.clock_gettime(Process::CLOCK_MONOTONIC) instead.

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.



70
71
72
 
# File 'lib/statsd/instrument.rb', line 70

def self.current_timestamp
  Process.clock_gettime(Process::CLOCK_MONOTONIC)
end

.duration ⇒ Object

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.

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.



81
82
83
84
85
 
# File 'lib/statsd/instrument.rb', line 81

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 



61
62
63
 
# File 'lib/statsd/instrument.rb', line 61

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, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: nil, no_prefix: false) ⇒ 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



227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/statsd/instrument.rb', line 227

def statsd_count(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
  sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: nil, no_prefix: false)

  add_to_method(method, name, :count) do
    define_method(method) do |*args, &block|
      key = StatsD::Instrument.generate_metric_name(name, self, *args)
      prefix ||= StatsD.prefix
      StatsD.increment(key, sample_rate: sample_rate, tags: tags, prefix: prefix, no_prefix: no_prefix)
      super(*args, &block)
    end
  end
end

#statsd_count_if(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: nil, no_prefix: false) {|result| ... } ⇒ void

This method returns an undefined value.

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.

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:



188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/statsd/instrument.rb', line 188

def statsd_count_if(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
  sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: nil, no_prefix: false)

  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
        if block_given?
          begin
            truthiness = yield(result)
          rescue
            truthiness = false
          end
        end
        result
      ensure
        if truthiness
          key = StatsD::Instrument.generate_metric_name(name, self, *args)
          prefix ||= StatsD.prefix
          StatsD.increment(key, sample_rate: sample_rate, tags: tags, prefix: prefix, no_prefix: no_prefix)
        end
      end
    end
  end
end

#statsd_count_success(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: nil, no_prefix: false) {|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:



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/statsd/instrument.rb', line 147

def statsd_count_success(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
  sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: nil, no_prefix: false)

  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
        if block_given?
          begin
            truthiness = yield(result)
          rescue
            truthiness = false
          end
        end
        result
      ensure
        suffix = truthiness == false ? 'failure' : 'success'
        key = "#{StatsD::Instrument.generate_metric_name(name, self, *args)}.#{suffix}"
        prefix ||= StatsD.prefix
        StatsD.increment(key, sample_rate: sample_rate, tags: tags, prefix: prefix, no_prefix: no_prefix)
      end
    end
  end
end

#statsd_distribution(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: nil, no_prefix: false) ⇒ void

Note:

Supported by the datadog implementation only (in beta)

This method returns an undefined value.

Adds execution duration instrumentation to a method as a distribution.

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



118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/statsd/instrument.rb', line 118

def statsd_distribution(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
  sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: nil, no_prefix: false)

  add_to_method(method, name, :distribution) do
    define_method(method) do |*args, &block|
      key = StatsD::Instrument.generate_metric_name(name, self, *args)
      prefix ||= StatsD.prefix
      StatsD.distribution(key, sample_rate: sample_rate, tags: tags, prefix: prefix, no_prefix: no_prefix) do
        super(*args, &block)
      end
    end
  end
end

#statsd_instrumentations ⇒ Object 



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

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, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil, as_dist: false, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: nil, no_prefix: false) ⇒ void

This method returns an undefined value.

Adds execution duration instrumentation to a method as a timing.

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



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

def statsd_measure(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil, as_dist: false,
  sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: nil, no_prefix: false)

  add_to_method(method, name, :measure) do
    define_method(method) do |*args, &block|
      key = StatsD::Instrument.generate_metric_name(name, self, *args)
      prefix ||= StatsD.prefix
      StatsD.measure(
        key, sample_rate: sample_rate, tags: tags, prefix: prefix, no_prefix: no_prefix, as_dist: as_dist
      ) do
        super(*args, &block)
      end
    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:



245
246
247
 
# File 'lib/statsd/instrument.rb', line 245

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:



254
255
256
 
# File 'lib/statsd/instrument.rb', line 254

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:



263
264
265
 
# File 'lib/statsd/instrument.rb', line 263

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

#statsd_remove_distribution(method, name) ⇒ void

This method returns an undefined value.

Removes StatsD distribution 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:



281
282
283
 
# File 'lib/statsd/instrument.rb', line 281

def statsd_remove_distribution(method, name)
  remove_from_method(method, name, :distribution)
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:



272
273
274
 
# File 'lib/statsd/instrument.rb', line 272

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