module StatsD

The StatsD module contains low-level metrics for collecting metrics and sending them to the backend.

@!attribute backend

The backend that is being used to emit the metrics.
@return [StatsD::Instrument::Backend] the currently active backend. If there is no active backend
  yet, it will call {StatsD::Instrument::Environment#default_backend} to obtain a
  default backend for the environment.
@see StatsD::Instrument::Environment#default_backend

@!attribute prefix

The prefix to apply to metric names. This can be useful to group all the metrics
for an application in a shared StatsD server.

When using a prefix a dot will be included automatically to separate the prefix
from the metric name.

@return [String, nil] The prefix, or <tt>nil</tt> when no prefix is used
@see StatsD::Instrument::Metric#name

@!attribute #default_sample_rate

The sample rate to use if the sample rate is unspecified for a metric call.
@return [Float] Default is 1.0.

@!attribute logger

The logger to use in case of any errors. The logger is also used as default logger
for the LoggerBackend (although this can be overwritten).

@see StatsD::Instrument::Backends::LoggerBackend
@return [Logger]

@see StatsD::Instrument StatsD::Instrument contains module to instrument

existing methods with StatsD metrics.

Attributes

backend[W]

default_sample_rate[RW]

logger[RW]

prefix[RW]

Public Instance Methods

backend() click to toggle source

# File lib/statsd/instrument.rb, line 255
def backend
  @backend ||= StatsD::Instrument::Environment.default_backend
end

gauge(key, value, *metric_options) click to toggle source

Emits a gauge metric. @param key [String] The name of the metric. @param value [Numeric] The current value to record. @param metric_options [Hash] (default: {}) Metric options @return (see collect_metric)

# File lib/statsd/instrument.rb, line 318
def gauge(key, value, *metric_options)
  if value.is_a?(Hash) && metric_options.empty?
    metric_options = [value]
    value = value.fetch(:value, nil)
  end

  collect_metric(hash_argument(metric_options).merge(type: :g, name: key, value: value))
end

histogram(key, value, *metric_options) click to toggle source

Emits a histogram metric. @param key [String] The name of the metric. @param value [Numeric] The value to record. @param metric_options [Hash] (default: {}) Metric options @return (see collect_metric) @note Supported by the datadog implementation only.

# File lib/statsd/instrument.rb, line 333
def histogram(key, value, *metric_options)
  if value.is_a?(Hash) && metric_options.empty?
    metric_options = [value]
    value = value.fetch(:value, nil)
  end

  collect_metric(hash_argument(metric_options).merge(type: :h, name: key, value: value))
end

increment(key, value = 1, *metric_options) click to toggle source

Emits a counter metric. @param key [String] The name of the metric. @param value [Integer] The value to increment the counter by.

You should not compensate for the sample rate using the counter increment. E.g., if
your sample rate is 0.01, you should <b>not</b> use 100 as increment to compensate for it.
The sample rate is part of the packet that is being sent to the server, and the server
should know how to handle it.

@param metric_options [Hash] (default: {}) Metric options @return (see collect_metric)

# File lib/statsd/instrument.rb, line 304
def increment(key, value = 1, *metric_options)
  if value.is_a?(Hash) && metric_options.empty?
    metric_options = [value]
    value = value.fetch(:value, 1)
  end

  collect_metric(hash_argument(metric_options).merge(type: :c, name: key, value: value))
end

key_value(key, value, *metric_options) click to toggle source

Emits a key/value metric. @param key [String] The name of the metric. @param value [Numeric] The value to record. @param metric_options [Hash] (default: {}) Metric options @return (see collect_metric) @note Supported by the statsite implementation only.

# File lib/statsd/instrument.rb, line 348
def key_value(key, value, *metric_options)
  if value.is_a?(Hash) && metric_options.empty?
    metric_options = [value]
    value = value.fetch(:value, nil)
  end

  collect_metric(hash_argument(metric_options).merge(type: :kv, name: key, value: value))
end

measure(key, value = nil, *metric_options, &block) click to toggle source

Emits a duration metric.

@overload measure(key, value, metric_options = {})

Emits a measure metric, by providing a duration in milliseconds.
@param key [String] The name of the metric.
@param value [Float] The measured duration in milliseconds
@param metric_options [Hash] Options for the metric
@return [StatsD::Instrument::Metric] The metric that was sent to the backend.

@overload measure(key, metric_options = {}, &block)

Emits a measure metric, after measuring the execution duration of the
block passed to this method.
@param key [String] The name of the metric.
@param metric_options [Hash] Options for the metric
@yield The method will yield the block that was passed to this emthod to measure its duration.
@return The value that was returns by the block passed to this method.

@example
   http_response = StatsD.measure('HTTP.call.duration') do
     HTTP.get(url)
   end

# File lib/statsd/instrument.rb, line 280
def measure(key, value = nil, *metric_options, &block)
  if value.is_a?(Hash) && metric_options.empty?
    metric_options = [value]
    value = value.fetch(:value, nil)
  end

  result = nil
  value  = 1000 * StatsD::Instrument.duration { result = block.call } if block_given?
  metric = collect_metric(hash_argument(metric_options).merge(type: :ms, name: key, value: value))
  result = metric unless block_given?
  result
end

set(key, value, *metric_options) click to toggle source

Emits a set metric. @param key [String] The name of the metric. @param value [Numeric] The value to record. @param metric_options [Hash] (default: {}) Metric options @return (see collect_metric) @note Supported by the datadog implementation only.

# File lib/statsd/instrument.rb, line 363
def set(key, value, *metric_options)
  if value.is_a?(Hash) && metric_options.empty?
    metric_options = [value]
    value = value.fetch(:value, nil)
  end

  collect_metric(hash_argument(metric_options).merge(type: :s, name: key, value: value))
end

Private Instance Methods

collect_metric(options) click to toggle source

Instantiates a metric, and sends it to the backend for further processing. @param options (see StatsD::Instrument::Metric#initialize) @return [StatsD::Instrument::Metric] The meric that was sent to the backend.

# File lib/statsd/instrument.rb, line 393
def collect_metric(options)
  backend.collect_metric(metric = StatsD::Instrument::Metric.new(options))
  metric
end

hash_argument(args) click to toggle source

Converts old-style ordered arguments in an argument hash for backwards compatibility. @param args [Array] The list of non-required arguments. @return [Hash] The hash of optional arguments.

# File lib/statsd/instrument.rb, line 377
def hash_argument(args)
  return {} if args.length == 0
  return args.first if args.length == 1 && args.first.is_a?(Hash)

  order = [:sample_rate, :tags]
  hash = {}
  args.each_with_index do |value, index|
    hash[order[index]] = value
  end

  return hash
end