Class: StatsD::Instrument::LegacyClient

Inherits:
Object
  • Object
show all
Defined in:
lib/statsd/instrument/legacy_client.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#backend ⇒ Object 



16
17
18
 
# File 'lib/statsd/instrument/legacy_client.rb', line 16

def backend
  @backend ||= StatsD::Instrument::Environment.default_backend
end

#default_sample_rate ⇒ Object

Returns the value of attribute default_sample_rate.



8
9
10
 
# File 'lib/statsd/instrument/legacy_client.rb', line 8

def default_sample_rate
  @default_sample_rate
end

#default_tags ⇒ Object

Returns the value of attribute default_tags.



10
11
12
 
# File 'lib/statsd/instrument/legacy_client.rb', line 10

def default_tags
  @default_tags
end

#prefix ⇒ Object

Returns the value of attribute prefix.



8
9
10
 
# File 'lib/statsd/instrument/legacy_client.rb', line 8

def prefix
  @prefix
end

Class Method Details

.singleton ⇒ Object 



4
5
6
 
# File 'lib/statsd/instrument/legacy_client.rb', line 4

def self.singleton
  @singleton ||= new
end

Instance Method Details

#distribution(name, value, sample_rate: nil, tags: nil) ⇒ void #distribution(key, metric_options = {}) { ... } ⇒ Object

Note:

Supported by the datadog implementation only.

Emits a distribution metric.

Examples:

http_response = StatsD.distribution('HTTP.call.duration') do
  Net::HTTP.get(url)
end

Overloads:

  • #distribution(name, value, sample_rate: nil, tags: nil) ⇒ void

    This method returns an undefined value.

    Emits a distribution metric, given a provided value to record.

    Parameters:

    • value (Numeric) —

      The value to record.

  • #distribution(key, metric_options = {}) { ... } ⇒ Object

    Emits a distribution metric for the duration of the provided block, in milliseconds.

    Yields:

    • StatsD.distribution will yield the block and measure the duration. After the block returns, the duration in millisecond will be emitted as metric.

    Returns:

    • The value that was returned by the block passed through.

Parameters:

  • key (String) —

    The name of the metric.

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

    (default: StatsD.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) 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 (Array<String>, Hash<Symbol, String>) (defaults to: nil) —

    The tags to associate with this measurement. They can be provided as an array of strings, or a hash of key/value pairs. Note: Tags are not supported by all implementations.



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

def distribution(
  key, value_arg = nil, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
  value: value_arg, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
  prefix: self.prefix, no_prefix: false,
  &block
)
  prefix = nil if no_prefix
  if block_given?
    measure_latency(:d, key, sample_rate: sample_rate, tags: tags, prefix: prefix, &block)
  else
    collect_metric(:d, key, value, sample_rate: sample_rate, tags: tags, prefix: prefix)
  end
end

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

Parameters:

  • title (String) —

    Title of the event. A configured prefix may be applied to this title.

  • text (String) —

    Body of the event. Can contain newlines.

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

    The hostname to associate with the event.

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

    The moment the status of the service was checkes. Defaults to now.

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

    A key to aggregate similar events into groups.

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

    The event's priority, either "low" or "normal" (default).

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

    The source type.

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

    The type of alert. Either "info" (default), "warning", "error", or "success".

  • tags (Array<String>, Hash<Symbol, String>) (defaults to: nil) —

    The tags to associate with this measurement. They can be provided as an array of strings, or a hash of key/value pairs. Note: Tags are not supported by all implementations.



234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/statsd/instrument/legacy_client.rb', line 234

def event(
  title, text,
  deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
  sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
  prefix: self.prefix, no_prefix: false,
  hostname: nil, date_happened: nil, timestamp: date_happened,
  aggregation_key: nil, priority: nil, source_type_name: nil, alert_type: nil,
  **_ignored
)
  prefix = nil if no_prefix
  collect_metric(:_e, title, text, sample_rate: sample_rate, tags: tags, prefix: prefix, metadata: {
    hostname: hostname, timestamp: timestamp, aggregation_key: aggregation_key,
    priority: priority, source_type_name: source_type_name, alert_type: alert_type
  })
end

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

This method returns an undefined value.

Emits a gauge metric.

Parameters:

  • key —

    The name of the metric.

  • value (Numeric) —

    The current value to record.

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

    (default: StatsD.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) 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 (Array<String>, Hash<Symbol, String>) (defaults to: nil) —

    The tags to associate with this measurement. They can be provided as an array of strings, or a hash of key/value pairs. Note: Tags are not supported by all implementations.



110
111
112
113
114
115
116
117
 
# File 'lib/statsd/instrument/legacy_client.rb', line 110

def gauge(
  key, value_arg = nil, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
  value: value_arg, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
  prefix: self.prefix, no_prefix: false
)
  prefix = nil if no_prefix
  collect_metric(:g, key, value, sample_rate: sample_rate, tags: tags, prefix: prefix)
end

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

Note:

Supported by the datadog implementation only.

This method returns an undefined value.

Emits a histogram metric.

Parameters:

  • key —

    The name of the metric.

  • value (Numeric) —

    The value to record.

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

    (default: StatsD.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) 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 (Array<String>, Hash<Symbol, String>) (defaults to: nil) —

    The tags to associate with this measurement. They can be provided as an array of strings, or a hash of key/value pairs. Note: Tags are not supported by all implementations.



150
151
152
153
154
155
156
157
 
# File 'lib/statsd/instrument/legacy_client.rb', line 150

def histogram(
  key, value_arg = nil, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
  value: value_arg, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
  prefix: self.prefix, no_prefix: false
)
  prefix = nil if no_prefix
  collect_metric(:h, key, value, sample_rate: sample_rate, tags: tags, prefix: prefix)
end

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

This method returns an undefined value.

Emits a counter metric.

Parameters:

  • key (String) —

    The name of the metric.

  • value (Integer) (defaults to: 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 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 handle it.

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

    (default: StatsD.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) 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 (Array<String>, Hash<Symbol, String>) (defaults to: nil) —

    The tags to associate with this measurement. They can be provided as an array of strings, or a hash of key/value pairs. Note: Tags are not supported by all implementations.



92
93
94
95
96
97
98
99
 
# File 'lib/statsd/instrument/legacy_client.rb', line 92

def increment(
  key, value_arg = 1, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
  value: value_arg, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
  prefix: self.prefix, no_prefix: false
)
  prefix = nil if no_prefix
  collect_metric(:c, key, value, sample_rate: sample_rate, tags: tags, prefix: prefix)
end

#key_value(name, value) ⇒ void

Note:

Supported by the statsite implementation only.

This method returns an undefined value.

Emits a key/value metric.

Parameters:

  • key (String) —

    The name of the metric.

  • value (Numeric) —

    The value to record.



210
211
212
213
214
215
216
 
# File 'lib/statsd/instrument/legacy_client.rb', line 210

def key_value(
  key, value_arg = nil, deprecated_sample_rate_arg = nil,
  value: value_arg, sample_rate: deprecated_sample_rate_arg, no_prefix: false
)
  prefix = nil if no_prefix
  collect_metric(:kv, key, value, sample_rate: sample_rate, prefix: prefix)
end

#measure(key, value, sample_rate: nil, tags: nil) ⇒ void #measure(key, sample_rate: nil, tags: nil) { ... } ⇒ Object

Emits a timing metric

Examples:

Providing a value directly

start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
do_something
stop = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
http_response = StatsD.measure('HTTP.call.duration', stop - start)

Providing a block to measure the duration of its execution

http_response = StatsD.measure('HTTP.call.duration') do
  Net::HTTP.get(url)
end

Overloads:

  • #measure(key, value, sample_rate: nil, tags: nil) ⇒ void

    This method returns an undefined value.

    Emits a timing metric, by providing a duration in milliseconds.

    Parameters:

    • value (Float) —

      The measured duration in milliseconds

  • #measure(key, sample_rate: nil, tags: nil) { ... } ⇒ Object

    Emits a timing metric, after measuring the execution duration of the block passed to this method.

    Yields:

    • StatsD.measure will yield the block and measure the duration. After the block returns, the duration in millisecond will be emitted as metric.

    Returns:

    • The value that was returned by the block passed through.

Parameters:

  • key (String) —

    The name of the metric.

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

    (default: StatsD.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) 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 (Array<String>, Hash<Symbol, String>) (defaults to: nil) —

    The tags to associate with this measurement. They can be provided as an array of strings, or a hash of key/value pairs. Note: Tags are not supported by all implementations.



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/statsd/instrument/legacy_client.rb', line 52

def measure(
  key, value_arg = nil, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
  value: value_arg, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
  prefix: self.prefix, no_prefix: false, as_dist: false,
  &block
)
  # TODO: in the next version, hardcode this to :ms when the as_dist argument is dropped.
  type = as_dist ? :d : :ms
  prefix = nil if no_prefix
  if block_given?
    measure_latency(type, key, sample_rate: sample_rate, tags: tags, prefix: prefix, &block)
  else
    collect_metric(type, key, value, sample_rate: sample_rate, tags: tags, prefix: prefix)
  end
end

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

Parameters:

  • name (String) —

    Name of the service. A configured prefix may be applied to this title.

  • status (Symbol) —

    Current status of the service. Either :ok, :warning, :critical, or :unknown.

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

    The hostname to associate with the event.

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

    The moment the status of the service was checkes. Defaults to now.

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

    A message that describes the current status.

  • tags (Array<String>, Hash<Symbol, String>) (defaults to: nil) —

    The tags to associate with this measurement. They can be provided as an array of strings, or a hash of key/value pairs. Note: Tags are not supported by all implementations.



263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/statsd/instrument/legacy_client.rb', line 263

def service_check(
  name, status,
  deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
  sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
  prefix: self.prefix, no_prefix: false,
  hostname: nil, timestamp: nil, message: nil, **_ignored
)
  prefix = nil if no_prefix
  collect_metric(:_sc, name, status, sample_rate: sample_rate, prefix: prefix, tags: tags, metadata: {
    hostname: hostname, timestamp: timestamp, message: message
  })
end

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

This method returns an undefined value.

Emits a set metric, which counts the number of distinct values that have occurred.

Examples:

Couning the number of unique visitors

StatsD.set('visitors.unique', Current.user.id)

Parameters:

  • key (String) —

    The name of the metric.

  • value (Numeric) —

    The value to record.

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

    (default: StatsD.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) 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 (Array<String>, Hash<Symbol, String>) (defaults to: nil) —

    The tags to associate with this measurement. They can be provided as an array of strings, or a hash of key/value pairs. Note: Tags are not supported by all implementations.



131
132
133
134
135
136
137
138
 
# File 'lib/statsd/instrument/legacy_client.rb', line 131

def set(
  key, value_arg = nil, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
  value: value_arg, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
  prefix: self.prefix, no_prefix: false
)
  prefix = nil if no_prefix
  collect_metric(:s, key, value, sample_rate: sample_rate, tags: tags, prefix: prefix)
end