Module: StatsD

Extended by:
Forwardable
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 module contains low-level metrics for collecting metrics and sending them to the backend.

See Also:

Defined Under Namespace

Modules: Instrument

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.logger ⇒ Logger

The logger to use in case of any errors.

Returns:

  • (Logger)

See Also:



332
333
334
 
# File 'lib/statsd/instrument.rb', line 332

def logger
  @logger
end

.singleton_client ⇒ StatsD::Instrument::Client

The StatsD client that handles method calls on the StatsD singleton

Returns:



343
344
345
 
# File 'lib/statsd/instrument.rb', line 343

def singleton_client
  @singleton_client ||= StatsD::Instrument::Environment.current.client
end

Class Method Details

.distribution(name, value = nil, sample_rate: nil, tags: nil, &block) ⇒ void

Note:

The distribution metric type is not available on all implementations. A NotImplementedError will be raised if you call this method, but the active implementation does not support it.

This method returns an undefined value.

Emits a distribution metric, which builds a histogram of the reported values.

Parameters:

  • value (Numeric) (defaults to: nil) —

    The value to include in the distribution histogram.



371
372
373
374
375
376
377
378
379
 
# File 'lib/statsd/instrument.rb', line 371

def_delegators :singleton_client,
:increment,
:gauge,
:set,
:measure,
:histogram,
:distribution,
:event,
:service_check

.event(title, text, tags: nil, hostname: nil, timestamp: nil, aggregation_key: nil, priority: nil, source_type_name: nil, alert_type: nil) ⇒ void

Note:

Supported by the Datadog implementation only.

This method returns an undefined value.

Emits an event. An event represents any record of activity noteworthy for engineers.

Parameters:

  • title (String) —

    Event title.

  • text (String) —

    Event description. Newlines are allowed.

  • timestamp (Time) (defaults to: nil) —

    The of the event. If not provided, Datadog will interpret it as the current timestamp.

  • hostname (String) (defaults to: nil) —

    A hostname to associate with the event.

  • aggregation_key (String) (defaults to: nil) —

    An aggregation key to group events with the same key.

  • priority (String) (defaults to: nil) —

    Priority of the event. Either "normal" (default) or "low".

  • source_type_name (String) (defaults to: nil) —

    The source type of the event.

  • alert_type (String) (defaults to: nil) —

    Either "error", "warning", "info" (default) or "success".

  • tags (Array, Hash) (defaults to: nil) —

    Tags to associate with the event.



371
372
373
374
375
376
377
378
379
 
# File 'lib/statsd/instrument.rb', line 371

def_delegators :singleton_client,
:increment,
:gauge,
:set,
:measure,
:histogram,
:distribution,
:event,
:service_check

.gauge(name, value, sample_rate: nil, tags: nil) ⇒ void

This method returns an undefined value.

Emits a gauge metric.

You should use a gauge if you are reporting the current value of something that can only have one value at the time. E.g., the speed of your car. A newly reported value will replace the previously reported value.

Parameters:

  • value (Numeric) —

    The gauged value.



371
372
373
374
375
376
377
378
379
 
# File 'lib/statsd/instrument.rb', line 371

def_delegators :singleton_client,
:increment,
:gauge,
:set,
:measure,
:histogram,
:distribution,
:event,
:service_check

.histogram(name, value, sample_rate: nil, tags: nil) ⇒ void

Note:

The histogram metric type is not available on all implementations. A NotImplementedError will be raised if you call this method, but the active implementation does not support it.

This method returns an undefined value.

Emits a histogram metric, which builds a histogram of the reported values.

Parameters:

  • value (Numeric) —

    The value to include in the histogram.



371
372
373
374
375
376
377
378
379
 
# File 'lib/statsd/instrument.rb', line 371

def_delegators :singleton_client,
:increment,
:gauge,
:set,
:measure,
:histogram,
:distribution,
:event,
:service_check

.increment(name, value = 1, sample_rate: nil, tags: nil) ⇒ void

This method returns an undefined value.

Emits a counter metric.

You should use a counter metric to count the frequency of something happening. As a result, the value should generally be set to 1 (the default), unless you reporting about a batch of activity. E.g. increment('messages.processed', messages.size) For values that are not frequencies, you should use another metric type, e.g. #histogram or #distribution.

Parameters:

  • name (String) —

    The name of the metric.

    • We recommend using snake_case.metric_names as naming scheme.
    • A . should be used for namespacing, e.g. foo.bar.baz
    • A metric name should not include the following characters: |, @, and :. The library will convert these characters to _.
  • value (Integer) (defaults to: 1) —

    (default: 1) 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 set to 0.01, you should not 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 compensate for it.

  • sample_rate (Float) (defaults to: nil) —

    (default: #default_sample_rate) The rate at which to sample this metric call. This value should be between 0 and 1. This value can be used to reduce the amount of network I/O (and CPU cycles) is being used for very frequent metrics.

    • A value of 0.1 means that only 1 out of 10 calls will be emitted; the other 9 will be short-circuited.
    • When set to 1, every metric will be emitted.
    • If this parameter is not set, the default sample rate for this client will be used.
  • tags (Hash<Symbol, String>, Array<String>) (defaults to: nil) —

    (default: nil)



371
372
373
374
375
376
377
378
379
 
# File 'lib/statsd/instrument.rb', line 371

def_delegators :singleton_client,
:increment,
:gauge,
:set,
:measure,
:histogram,
:distribution,
:event,
:service_check

.measure(name, value = nil, sample_rate: nil, tags: nil, &block) ⇒ void

This method returns an undefined value.

Emits a timing metric.

Parameters:

  • value (Numeric) (defaults to: nil) —

    The duration to record, in milliseconds.



371
372
373
374
375
376
377
378
379
 
# File 'lib/statsd/instrument.rb', line 371

def_delegators :singleton_client,
:increment,
:gauge,
:set,
:measure,
:histogram,
:distribution,
:event,
:service_check

.service_check(name, status, tags: nil, hostname: nil, timestamp: nil, message: nil) ⇒ void

Note:

Supported by the Datadog implementation only.

This method returns an undefined value.

Emits a service check. Services Checks allow you to characterize the status of a service in order to monitor it within Datadog.

Parameters:

  • name (String) —

    Name of the service

  • status (Symbol) —

    Either :ok, :warning, :critical or :unknown

  • timestamp (Time) (defaults to: nil) —

    The moment when the service was checked. If not provided, Datadog will interpret it as the current timestamp.

  • hostname (String) (defaults to: nil) —

    A hostname to associate with the check.

  • tags (Array, Hash) (defaults to: nil) —

    Tags to associate with the check.

  • message (String) (defaults to: nil) —

    A message describing the current state of the service check.



371
372
373
374
375
376
377
378
379
 
# File 'lib/statsd/instrument.rb', line 371

def_delegators :singleton_client,
:increment,
:gauge,
:set,
:measure,
:histogram,
:distribution,
:event,
:service_check

.set(name, value, sample_rate: nil, tags: nil) ⇒ void

This method returns an undefined value.

Emits a set metric, which counts distinct values.

Parameters:

  • value (Numeric, String) —

    The value to count for distinct occurrences.



371
372
373
374
375
376
377
378
379
 
# File 'lib/statsd/instrument.rb', line 371

def_delegators :singleton_client,
:increment,
:gauge,
:set,
:measure,
:histogram,
:distribution,
:event,
:service_check