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., you 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, Helpers, Matchers, Strict, StrictMetaprogramming Classes: CaptureSink, Client, Datagram, DatagramBuilder, DogStatsDDatagram, DogStatsDDatagramBuilder, Environment, Expectation, LogSink, NullSink, Railtie, StatsDDatagramBuilder, UDPSink

Constant Summary collapse

VOID = 
VoidClass.new.freeze
VERSION = 
"3.0.0"
MetricExpectation =

For backwards compatibility

StatsD::Instrument::Expectation

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.



42
43
44
 
# File 'lib/statsd/instrument.rb', line 42

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.



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

.generate_metric_name(name, callee, *args) ⇒ String

Generates a metric name for an instrumented method.

Returns:

  • (String) 


33
34
35
 
# 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

Instance Method Details

#statsd_count(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil) ⇒ 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



189
190
191
192
193
194
195
196
197
198
 
# File 'lib/statsd/instrument.rb', line 189

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

#statsd_count_if(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil) {|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 considered a success, false otherwise.

See Also:



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/statsd/instrument.rb', line 152

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|
      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
          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
end

#statsd_count_success(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil) {|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 considered a success, false otherwise.

See Also:



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# 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|
      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
        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
end

#statsd_distribution(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil) ⇒ 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



86
87
88
89
90
91
92
93
94
95
96
 
# 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

#statsd_instrumentations ⇒ Object 



20
21
22
23
24
25
26
27
28
 
# 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

#statsd_measure(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil) ⇒ 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



66
67
68
69
70
71
72
73
74
75
76
 
# 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

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



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

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:



214
215
216
 
# File 'lib/statsd/instrument.rb', line 214

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:



223
224
225
 
# File 'lib/statsd/instrument.rb', line 223

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:



241
242
243
 
# File 'lib/statsd/instrument.rb', line 241

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:



232
233
234
 
# File 'lib/statsd/instrument.rb', line 232

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