Class: Statsd

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

Overview

Statsd: A Statsd client (github.com/etsy/statsd)

Statsd instances are thread safe for general usage, by utilizing the thread safe nature of UDP sends. The attributes are stateful, and are not mutexed, it is expected that users will not change these at runtime in threaded environments. If users require such use cases, it is recommend that users either mutex around their Statsd object, or create separate objects for each namespace / host+port combination.

Examples:

Set up a global Statsd client for a server on localhost:8125

$statsd = Statsd.new 'localhost', 8125

Set up a global Statsd client for a server on IPv6 port 8125

$statsd = Statsd.new '::1', 8125

Send some stats

$statsd.increment 'garets'
$statsd.timing 'glork', 320
$statsd.gauge 'bork', 100

Use #time to time the execution of a block

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

Create a namespaced statsd client and increment ‘account.activate’

statsd = Statsd.new('localhost').tap{|sd| sd.namespace = 'account'}
statsd.increment 'activate'

Direct Known Subclasses

Batch

Defined Under Namespace

Modules: MonotonicTime Classes: Admin, Batch

Class Attribute Summary collapse

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host = '127.0.0.1', port = 8125, protocol = :udp) ⇒ Statsd

Returns a new instance of Statsd.

Parameters:

  • host (String) (defaults to: '127.0.0.1') —

    your statsd host

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

    your statsd port

  • protocol (Symbol) (defaults to: :udp) —

    :tcp for TCP, :udp or any other value for UDP



294
295
296
297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/statsd.rb', line 294

def initialize(host = '127.0.0.1', port = 8125, protocol = :udp)
  @host = host || '127.0.0.1'
  @port = port || 8125
  self.delimiter = "."
  @prefix = nil
  @batch_size = 10
  @batch_byte_size = nil
  @flush_interval = nil
  @postfix = nil
  @socket = nil
  @protocol = protocol || :udp
  @s_mu = Mutex.new
  connect
end

Class Attribute Details

.logger ⇒ Object

Set to a standard logger instance to enable debug logging.



288
289
290
 
# File 'lib/statsd.rb', line 288

def logger
  @logger
end

Instance Attribute Details

#batch_byte_size ⇒ Object

The default batch size, in bytes, for new batches (default: default nil; use batch_size)



275
276
277
 
# File 'lib/statsd.rb', line 275

def batch_byte_size
  @batch_byte_size
end

#batch_size ⇒ Object

The default batch size for new batches. Set to nil to use batch_byte_size (default: 10)



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

def batch_size
  @batch_size
end

#delimiter ⇒ Object

The replacement of

on ruby module names when transformed to statsd metric names



284
285
286
 
# File 'lib/statsd.rb', line 284

def delimiter
  @delimiter
end

#flush_interval ⇒ Object

The flush interval, in seconds, for new batches (default: nil)



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

def flush_interval
  @flush_interval
end

#host ⇒ Object

StatsD host. Defaults to 127.0.0.1.



263
264
265
 
# File 'lib/statsd.rb', line 263

def host
  @host
end

#namespace ⇒ Object

A namespace to prepend to all statsd calls.



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

def namespace
  @namespace
end

#port ⇒ Object

StatsD port. Defaults to 8125.



266
267
268
 
# File 'lib/statsd.rb', line 266

def port
  @port
end

#postfix ⇒ Object

a postfix to append to all metrics



281
282
283
 
# File 'lib/statsd.rb', line 281

def postfix
  @postfix
end

#prefix ⇒ Object (readonly)

StatsD namespace prefix, generated from #namespace



269
270
271
 
# File 'lib/statsd.rb', line 269

def prefix
  @prefix
end

#stat_delimiter=(value) ⇒ Object (writeonly)

Allows for custom delimiter replacement for

when Ruby modules are transformed to statsd metric name



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

def delimiter=(delimiter)
  @delimiter = delimiter || "."
end

Instance Method Details

#batch {|Batch| ... } ⇒ Object

Creates and yields a Batch that can be used to batch instrument reports into larger packets. Batches are sent either when the packet is “full” (defined by batch_size), or when the block completes, whichever is the sooner.

Examples:

Batch two instument operations:

$statsd.batch do |batch|
  batch.increment 'sys.requests'
  batch.gauge('user.count', User.count)
end

Yields:

  • (Batch) —

    a statsd subclass that collects and batches instruments



442
443
444
 
# File 'lib/statsd.rb', line 442

def batch(&block)
  Batch.new(self).easy(&block)
end

#connect ⇒ Object

Reconnects the socket, useful if the address of the statsd has changed. This method is not thread safe from a perspective of stat submission. It is safe from resource leaks. Users do not normally need to call this, but calling it may be appropriate when reconfiguring a process (e.g. from HUP).



450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
 
# File 'lib/statsd.rb', line 450

def connect
  @s_mu.synchronize do
    begin
      @socket.close if @socket
    rescue
      # Errors are ignored on reconnects.
    end

    case @protocol
    when :tcp
      @socket = TCPSocket.new @host, @port
    else
      @socket = UDPSocket.new Addrinfo.ip(@host).afamily
      @socket.connect host, port
    end
  end
end

#count(stat, count, sample_rate = 1) ⇒ Object

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

Parameters:

  • stat (String) —

    stat name

  • count (Integer) —

    count

  • sample_rate (Numeric) (defaults to: 1) —

    sample rate, 1 for always



369
370
371
 
# File 'lib/statsd.rb', line 369

def count(stat, count, sample_rate=1)
  send_stats stat, count, :c, sample_rate
end

#decrement(stat, sample_rate = 1) ⇒ Object

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

Parameters:

  • stat (String) —

    stat name

  • sample_rate (Numeric) (defaults to: 1) —

    sample rate, 1 for always

See Also:



360
361
362
 
# File 'lib/statsd.rb', line 360

def decrement(stat, sample_rate=1)
  count stat, -1, sample_rate
end

#gauge(stat, value, sample_rate = 1) ⇒ 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.

  • sample_rate (Numeric) (defaults to: 1) —

    sample rate, 1 for always



384
385
386
 
# File 'lib/statsd.rb', line 384

def gauge(stat, value, sample_rate=1)
  send_stats stat, value, :g, sample_rate
end

#increment(stat, sample_rate = 1) ⇒ Object

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

Parameters:

  • stat (String) —

    stat name

  • sample_rate (Numeric) (defaults to: 1) —

    sample rate, 1 for always

See Also:



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

def increment(stat, sample_rate=1)
  count stat, 1, sample_rate
end

#set(stat, value, sample_rate = 1) ⇒ Object

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

This is for recording counts of unique events, which are useful to see on graphs to correlate to other values. For example, a deployment might get recorded as a set, and be drawn as annotations on a CPU history graph.

Examples:

Report a deployment happening:

$statsd.set('deployment', DEPLOYMENT_EVENT_CODE)

Parameters:

  • stat (String) —

    stat name.

  • value (Numeric) —

    event value.

  • sample_rate (Numeric) (defaults to: 1) —

    sample rate, 1 for always



400
401
402
 
# File 'lib/statsd.rb', line 400

def set(stat, value, sample_rate=1)
  send_stats stat, value, :s, sample_rate
end

#time(stat, sample_rate = 1) { ... } ⇒ Object

Reports execution time of the provided block using #timing.

Examples:

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

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

Parameters:

  • stat (String) —

    stat name

  • sample_rate (Numeric) (defaults to: 1) —

    sample rate, 1 for always

Yields:

  • The operation to be timed

See Also:



424
425
426
427
428
429
430
 
# File 'lib/statsd.rb', line 424

def time(stat, sample_rate=1)
  start = MonotonicTime.time_in_ms
  result = yield
ensure
  timing(stat, (MonotonicTime.time_in_ms - start).round, sample_rate)
  result
end

#timing(stat, ms, sample_rate = 1) ⇒ 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

  • sample_rate (Numeric) (defaults to: 1) —

    sample rate, 1 for always



412
413
414
 
# File 'lib/statsd.rb', line 412

def timing(stat, ms, sample_rate=1)
  send_stats stat, ms, :ms, sample_rate
end