Module: StatsD::Instrument

Includes:
StrictMetaprogramming
Defined in:
lib/statsd/instrument.rb,
lib/statsd/instrument/client.rb,
lib/statsd/instrument/strict.rb,
lib/statsd/instrument/helpers.rb,
lib/statsd/instrument/railtie.rb,
lib/statsd/instrument/version.rb,
lib/statsd/instrument/datagram.rb,
lib/statsd/instrument/log_sink.rb,
lib/statsd/instrument/matchers.rb,
lib/statsd/instrument/udp_sink.rb,
lib/statsd/instrument/null_sink.rb,
lib/statsd/instrument/assertions.rb,
lib/statsd/instrument/environment.rb,
lib/statsd/instrument/expectation.rb,
lib/statsd/instrument/capture_sink.rb,
lib/statsd/instrument/batched_udp_sink.rb,
lib/statsd/instrument/datagram_builder.rb,
lib/statsd/instrument/dogstatsd_datagram.rb,
lib/statsd/instrument/statsd_datagram_builder.rb,
lib/statsd/instrument/dogstatsd_datagram_builder.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: BatchedUDPSink, CaptureSink, Client, Datagram, DatagramBuilder, DogStatsDDatagram, DogStatsDDatagramBuilder, Environment, Expectation, LogSink, NullSink, Railtie, StatsDDatagramBuilder, UDPSink

Constant Summary collapse

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

For backwards compatibility

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.



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

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.



62
63
64
65
66
 
# File 'lib/statsd/instrument.rb', line 62

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

.generate_tags(tags, callee, *args) ⇒ Array[String]

Generates the tags for an instrumented method.

Returns:

  • (Array[String]) 


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

def self.generate_tags(tags, callee, *args)
  return if tags.nil?

  tags.respond_to?(:call) ? tags.call(callee, args) : tags
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



204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/statsd/instrument.rb', line 204

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)
      tags = StatsD::Instrument.generate_tags(tags, 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:



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/statsd/instrument.rb', line 168

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)
        tags = StatsD::Instrument.generate_tags(tags, self, *args)
        client.increment(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix)
      end
    end
  end
end

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

  • tag_error_class (defaults to: false) —

    add a error_class tag with the error class when an error is thrown

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



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/statsd/instrument.rb', line 127

def statsd_count_success(method, name, sample_rate: nil,
  tags: nil, no_prefix: false, client: nil, tag_error_class: false)
  add_to_method(method, name, :count_success) do
    define_method(method) do |*args, &block|
      truthiness = result = super(*args, &block)
    rescue => error
      truthiness = false
      raise
    else
      if block_given?
        begin
          truthiness = yield(result)
        rescue => error
          truthiness = false
        end
      end
      result
    ensure
      client ||= StatsD.singleton_client
      suffix = truthiness == false ? "failure" : "success"
      key = StatsD::Instrument.generate_metric_name(name, self, *args)
      tags = StatsD::Instrument.generate_tags(tags, self, *args)
      tags = Helpers.add_tag(tags, :error_class, error.class.name) if tag_error_class && error

      client.increment("#{key}.#{suffix}", sample_rate: sample_rate, tags: tags, no_prefix: no_prefix)
    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



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

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)
      tags = StatsD::Instrument.generate_tags(tags, 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

  • tags (Hash, #call) (defaults to: nil) —

    The tags to be associated with the metric. You can also pass in a callable to dynamically generate the tags key and values



77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/statsd/instrument.rb', line 77

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)
      tags = StatsD::Instrument.generate_tags(tags, 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:



221
222
223
 
# File 'lib/statsd/instrument.rb', line 221

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:



230
231
232
 
# File 'lib/statsd/instrument.rb', line 230

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:



239
240
241
 
# File 'lib/statsd/instrument.rb', line 239

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:



257
258
259
 
# File 'lib/statsd/instrument.rb', line 257

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:



248
249
250
 
# File 'lib/statsd/instrument.rb', line 248

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