Class: Datadog::Statsd

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

Defined Under Namespace

Classes: Batch, Connection, UDPConnection, UDSConnection

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.5.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, sample_rate: 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] (Hash) —

    a customizable set of options

  • [Logger] (Hash) —

    a customizable set of options

  • [Integer] (Hash) —

    a customizable set of options

  • [Float] (Hash) —

    a customizable set of options



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/datadog/statsd.rb', line 225

def initialize(
  host = nil,
  port = nil,
  namespace: nil,
  tags: nil,
  max_buffer_bytes: 8192,
  socket_path: nil,
  logger: nil,
  sample_rate: nil
)
  if socket_path.nil?
    @connection = UDPConnection.new(host, port, logger)
  else
    @connection = UDSConnection.new(socket_path, logger)
  end
  @logger = logger

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

  @sample_rate = sample_rate

  unless tags.nil? or tags.is_a? Array or tags.is_a? Hash
    raise ArgumentError, 'tags must be a Array<String> or a Hash'
  end

  tags = tag_hash_to_array(tags) if tags.is_a? Hash
  @tags = (tags || []).compact.map! {|tag| escape_tag_content(tag)}

  # append the entity id to tags if DD_ENTITY_ID env var is not nil
  @tags << 'dd.internal.entity_id:' + escape_tag_content(ENV.fetch('DD_ENTITY_ID', nil)) unless ENV.fetch('DD_ENTITY_ID', nil).nil?

  @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



206
207
208
 
# File 'lib/datadog/statsd.rb', line 206

def buffer
  @buffer
end

#connection ⇒ Object (readonly)

Connection



215
216
217
 
# File 'lib/datadog/statsd.rb', line 215

def connection
  @connection
end

#max_buffer_bytes ⇒ Object (readonly)

Maximum buffer size in bytes before it is flushed



209
210
211
 
# File 'lib/datadog/statsd.rb', line 209

def max_buffer_bytes
  @max_buffer_bytes
end

#namespace ⇒ Object (readonly)

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



200
201
202
 
# File 'lib/datadog/statsd.rb', line 200

def namespace
  @namespace
end

#sample_rate ⇒ Object (readonly)

Default sample rate



212
213
214
 
# File 'lib/datadog/statsd.rb', line 212

def sample_rate
  @sample_rate
end

#tags ⇒ Object (readonly)

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



203
204
205
 
# File 'lib/datadog/statsd.rb', line 203

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



262
263
264
265
266
267
 
# File 'lib/datadog/statsd.rb', line 262

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


452
453
454
 
# File 'lib/datadog/statsd.rb', line 452

def batch
  @batch.open { yield self }
end

#close ⇒ Object

Close the underlying socket



457
458
459
 
# File 'lib/datadog/statsd.rb', line 457

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



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

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:



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

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



352
353
354
 
# File 'lib/datadog/statsd.rb', line 352

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 newlines (\n)

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

    the additional data about the event

Options Hash (opts):

  • :date_happened (Integer, String, 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



440
441
442
 
# File 'lib/datadog/statsd.rb', line 440

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



322
323
324
325
 
# File 'lib/datadog/statsd.rb', line 322

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



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

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:



277
278
279
280
281
 
# File 'lib/datadog/statsd.rb', line 277

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


418
419
420
 
# File 'lib/datadog/statsd.rb', line 418

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



402
403
404
405
 
# File 'lib/datadog/statsd.rb', line 402

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:



384
385
386
387
388
389
390
391
 
# File 'lib/datadog/statsd.rb', line 384

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



366
367
368
369
 
# File 'lib/datadog/statsd.rb', line 366

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