Module: StatsD::Instrument

Includes:
StrictMetaprogramming
Defined in:
lib/statsd/instrument.rb,
lib/statsd/instrument/sink.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/null_sink.rb,
lib/statsd/instrument/aggregator.rb,
lib/statsd/instrument/assertions.rb,
lib/statsd/instrument/environment.rb,
lib/statsd/instrument/expectation.rb,
lib/statsd/instrument/batched_sink.rb,
lib/statsd/instrument/capture_sink.rb,
lib/statsd/instrument/udp_connection.rb,
lib/statsd/instrument/uds_connection.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: AggregationKey, Aggregator, BatchedSink, CaptureSink, Client, Datagram, DatagramBuilder, DogStatsDDatagram, DogStatsDDatagramBuilder, Environment, Expectation, LogSink, NullSink, Railtie, Sink, StatsDDatagramBuilder, UdpConnection, UdsConnection

Constant Summary collapse

VOID = 
VoidClass.new.freeze
VERSION = 
"3.9.7"
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.



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

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



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

def 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) 


34
35
36
 
# File 'lib/statsd/instrument.rb', line 34

def 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]) 


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

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

  • sample_rate (defaults to: nil)
  • tags (defaults to: nil)
  • no_prefix (defaults to: false)
  • client (defaults to: nil)
  • 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



209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/statsd/instrument.rb', line 209

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



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

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



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
155
156
 
# File 'lib/statsd/instrument.rb', line 129

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)
      generated_tags = StatsD::Instrument.generate_tags(tags, self, *args)
      generated_tags = Helpers.add_tag(generated_tags, :error_class, error.class.name) if tag_error_class && error

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



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

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



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

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



226
227
228
 
# File 'lib/statsd/instrument.rb', line 226

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:



235
236
237
 
# File 'lib/statsd/instrument.rb', line 235

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:



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

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:



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

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:



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

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