Class: Datadog::Statsd

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

Defined Under Namespace

Classes: Batch, Connection

Constant Summary collapse

OPTS_KEYS =

Create a dictionary to assign a key to every parameter’s name, except for tags (treated differently) Goal: Simple and fast to add some other parameters

{
  :date_happened     => :d,
  :hostname          => :h,
  :aggregation_key   => :k,
  :priority          => :p,
  :source_type_name  => :s,
  :alert_type        => :t,
}
SC_OPT_KEYS =

Service check options

{
  :timestamp  => 'd:'.freeze,
  :hostname   => 'h:'.freeze,
  :tags       => '#'.freeze,
  :message    => 'm:'.freeze,
}
OK = 
0
WARNING = 
1
CRITICAL = 
2
UNKNOWN = 
3
MAX_EVENT_SIZE = 
8 * 1024
COUNTER_TYPE = 
'c'.freeze
GAUGE_TYPE = 
'g'.freeze
HISTOGRAM_TYPE = 
'h'.freeze
DISTRIBUTION_TYPE = 
'd'.freeze
TIMING_TYPE = 
'ms'.freeze
SET_TYPE = 
's'.freeze
VERSION = 
"4.0.0".freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host = nil, port = nil, namespace: nil, tags: nil, max_buffer_bytes: 8192, socket_path: nil, logger: nil) ⇒ Statsd

Returns a new instance of Statsd.

Parameters:

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

    your statsd host

  • port (Integer) (defaults to: nil) —

    your statsd port

  • [String] (Hash) —

    a customizable set of options

  • [Array<String>] (Hash) —

    a customizable set of options

  • [Loger] (Hash) —

    a customizable set of options

  • [Integer] (Hash) —

    a customizable set of options

Raises:

  • (ArgumentError) 


207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/datadog/statsd.rb', line 207

def initialize(
  host = nil,
  port = nil,
  namespace: nil,
  tags: nil,
  max_buffer_bytes: 8192,
  socket_path: nil,
  logger: nil
)
  @connection = Connection.new(host, port, socket_path, logger)
  @logger = logger

  @namespace = namespace
  @prefix = @namespace ? "#{@namespace}.".freeze : nil

  raise ArgumentError, 'tags must be a Array<String>' unless tags.nil? or tags.is_a? Array
  @tags = (tags || []).compact.map! {|tag| escape_tag_content(tag)}

  @batch = Batch.new @connection, max_buffer_bytes
end

Instance Attribute Details

#buffer ⇒ Object (readonly)

Buffer containing the statsd message before they are sent in batch



192
193
194
 
# File 'lib/datadog/statsd.rb', line 192

def buffer
  @buffer
end

#connection ⇒ Object (readonly)

Connection



198
199
200
 
# File 'lib/datadog/statsd.rb', line 198

def connection
  @connection
end

#max_buffer_bytes ⇒ Object (readonly)

Maximum buffer size in bytes before it is flushed



195
196
197
 
# File 'lib/datadog/statsd.rb', line 195

def max_buffer_bytes
  @max_buffer_bytes
end

#namespace ⇒ Object (readonly)

A namespace to prepend to all statsd calls. Defaults to no namespace.



186
187
188
 
# File 'lib/datadog/statsd.rb', line 186

def namespace
  @namespace
end

#tags ⇒ Object (readonly)

Global tags to be added to every statsd call. Defaults to no tags.



189
190
191
 
# File 'lib/datadog/statsd.rb', line 189

def tags
  @tags
end

Class Method Details

.open(*args) ⇒ Object

yield a new instance to a block and close it when done for short-term use-cases that don’t want to close the socket manually



230
231
232
233
234
235
 
# File 'lib/datadog/statsd.rb', line 230

def self.open(*args)
  instance = new(*args)
  yield instance
ensure
  instance.close
end

Instance Method Details

#batch ⇒ Object

Send several metrics in the same UDP Packet They will be buffered and flushed when the block finishes

Examples:

Send several metrics in one packet:

$statsd.batch do |s|
   s.gauge('users.online',156)
   s.increment('page.views')
 end


420
421
422
 
# File 'lib/datadog/statsd.rb', line 420

def batch
  @batch.open { yield self }
end

#close ⇒ Object

Close the underlying socket



425
426
427
 
# File 'lib/datadog/statsd.rb', line 425

def close
  @connection.close
end

#count(stat, count, opts = EMPTY_OPTIONS) ⇒ Object

Sends an arbitrary count for the given stat to the statsd server.

Parameters:

  • stat (String) —

    stat name

  • count (Integer) —

    count

  • opts (Hash) (defaults to: EMPTY_OPTIONS) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags



272
273
274
275
 
# File 'lib/datadog/statsd.rb', line 272

def count(stat, count, opts=EMPTY_OPTIONS)
  opts = {:sample_rate => opts} if opts.is_a? Numeric
  send_stats stat, count, COUNTER_TYPE, opts
end

#decrement(stat, opts = EMPTY_OPTIONS) ⇒ Object

Sends a decrement (count = -1) for the given stat to the statsd server.

Parameters:

  • stat (String) —

    stat name

  • opts (Hash) (defaults to: EMPTY_OPTIONS) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags

  • :by (Numeric) —

    decrement value, default 1

See Also:



259
260
261
262
263
 
# File 'lib/datadog/statsd.rb', line 259

def decrement(stat, opts=EMPTY_OPTIONS)
  opts = {:sample_rate => opts} if opts.is_a? Numeric
  decr_value = - opts.fetch(:by, 1)
  count stat, decr_value, opts
end

#distribution(stat, value, opts = EMPTY_OPTIONS) ⇒ Object

Sends a value to be tracked as a distribution to the statsd server. Note: Distributions are a beta feature of Datadog and not generally available. Distributions must be specifically enabled for your organization.

Examples:

Report the current user count:

$statsd.distribution('user.count', User.count)

Parameters:

  • stat (String) —

    stat name.

  • value (Numeric) —

    distribution value.

  • opts (Hash) (defaults to: EMPTY_OPTIONS) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags



320
321
322
 
# File 'lib/datadog/statsd.rb', line 320

def distribution(stat, value, opts=EMPTY_OPTIONS)
  send_stats stat, value, DISTRIBUTION_TYPE, opts
end

#event(title, text, opts = EMPTY_OPTIONS) ⇒ Object

This end point allows you to post events to the stream. You can tag them, set priority and even aggregate them with other events.

Aggregation in the stream is made on hostname/event_type/source_type/aggregation_key. If there’s no event type, for example, then that won’t matter; it will be grouped with other events that don’t have an event type.

Examples:

Report an awful event:

$statsd.event('Something terrible happened', 'The end is near if we do nothing', :alert_type=>'warning', :tags=>['end_of_times','urgent'])

Parameters:

  • title (String) —

    Event title

  • text (String) —

    Event text. Supports n

  • opts (Hash) (defaults to: EMPTY_OPTIONS) —

    the additional data about the event

Options Hash (opts):

  • :date_happened (Integer, nil) — default: nil —

    Assign a timestamp to the event. Default is now when none

  • :hostname (String, nil) — default: nil —

    Assign a hostname to the event.

  • :aggregation_key (String, nil) — default: nil —

    Assign an aggregation key to the event, to group it with some others

  • :priority (String, nil) — default: 'normal' —

    Can be “normal” or “low”

  • :source_type_name (String, nil) — default: nil —

    Assign a source type to the event

  • :alert_type (String, nil) — default: 'info' —

    Can be “error”, “warning”, “info” or “success”.

  • :tags (Array<String>) —

    tags to be added to every metric



408
409
410
 
# File 'lib/datadog/statsd.rb', line 408

def event(title, text, opts=EMPTY_OPTIONS)
  send_stat format_event(title, text, opts)
end

#gauge(stat, value, opts = EMPTY_OPTIONS) ⇒ Object

Sends an arbitary gauge value for the given stat to the statsd server.

This is useful for recording things like available disk space, memory usage, and the like, which have different semantics than counters.

Examples:

Report the current user count:

$statsd.gauge('user.count', User.count)

Parameters:

  • stat (String) —

    stat name.

  • value (Numeric) —

    gauge value.

  • opts (Hash) (defaults to: EMPTY_OPTIONS) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags



290
291
292
293
 
# File 'lib/datadog/statsd.rb', line 290

def gauge(stat, value, opts=EMPTY_OPTIONS)
  opts = {:sample_rate => opts} if opts.is_a? Numeric
  send_stats stat, value, GAUGE_TYPE, opts
end

#histogram(stat, value, opts = EMPTY_OPTIONS) ⇒ Object

Sends a value to be tracked as a histogram to the statsd server.

Examples:

Report the current user count:

$statsd.histogram('user.count', User.count)

Parameters:

  • stat (String) —

    stat name.

  • value (Numeric) —

    histogram value.

  • opts (Hash) (defaults to: EMPTY_OPTIONS) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags



304
305
306
 
# File 'lib/datadog/statsd.rb', line 304

def histogram(stat, value, opts=EMPTY_OPTIONS)
  send_stats stat, value, HISTOGRAM_TYPE, opts
end

#increment(stat, opts = EMPTY_OPTIONS) ⇒ Object

Sends an increment (count = 1) for the given stat to the statsd server.

Parameters:

  • stat (String) —

    stat name

  • opts (Hash) (defaults to: EMPTY_OPTIONS) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags

  • :by (Numeric) —

    increment value, default 1

See Also:



245
246
247
248
249
 
# File 'lib/datadog/statsd.rb', line 245

def increment(stat, opts=EMPTY_OPTIONS)
  opts = {:sample_rate => opts} if opts.is_a? Numeric
  incr_value = opts.fetch(:by, 1)
  count stat, incr_value, opts
end

#service_check(name, status, opts = EMPTY_OPTIONS) ⇒ Object

Examples:

Report a critical service check status

$statsd.service_check('my.service.check', Statsd::CRITICAL, :tags=>['urgent'])


386
387
388
 
# File 'lib/datadog/statsd.rb', line 386

def service_check(name, status, opts=EMPTY_OPTIONS)
  send_stat format_service_check(name, status, opts)
end

#set(stat, value, opts = EMPTY_OPTIONS) ⇒ Object

Sends a value to be tracked as a set to the statsd server.

Examples:

Record a unique visitory by id:

$statsd.set('visitors.uniques', User.id)

Parameters:

  • stat (String) —

    stat name.

  • value (Numeric) —

    set value.

  • opts (Hash) (defaults to: EMPTY_OPTIONS) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags



370
371
372
373
 
# File 'lib/datadog/statsd.rb', line 370

def set(stat, value, opts=EMPTY_OPTIONS)
  opts = {:sample_rate => opts} if opts.is_a? Numeric
  send_stats stat, value, SET_TYPE, opts
end

#time(stat, opts = EMPTY_OPTIONS) { ... } ⇒ Object

Reports execution time of the provided block using #timing.

If the block fails, the stat is still reported, then the error is reraised

Examples:

Report the time (in ms) taken to activate an account

$statsd.time('account.activate') { @account.activate! }

Parameters:

  • stat (String) —

    stat name

  • opts (Hash) (defaults to: EMPTY_OPTIONS) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags

Yields:

  • The operation to be timed

See Also:



352
353
354
355
356
357
358
359
 
# File 'lib/datadog/statsd.rb', line 352

def time(stat, opts=EMPTY_OPTIONS)
  opts = {:sample_rate => opts} if opts.is_a? Numeric
  start = (PROCESS_TIME_SUPPORTED ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : Time.now.to_f)
  return yield
ensure
  finished = (PROCESS_TIME_SUPPORTED ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : Time.now.to_f)
  timing(stat, ((finished - start) * 1000).round, opts)
end

#timing(stat, ms, opts = EMPTY_OPTIONS) ⇒ Object

Sends a timing (in ms) for the given stat to the statsd server. The sample_rate determines what percentage of the time this report is sent. The statsd server then uses the sample_rate to correctly track the average timing for the stat.

Parameters:

  • stat (String) —

    stat name

  • ms (Integer) —

    timing in milliseconds

  • opts (Hash) (defaults to: EMPTY_OPTIONS) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags



334
335
336
337
 
# File 'lib/datadog/statsd.rb', line 334

def timing(stat, ms, opts=EMPTY_OPTIONS)
  opts = {:sample_rate => opts} if opts.is_a? Numeric
  send_stats stat, ms, TIMING_TYPE, opts
end