Class: Statsd

Inherits:
Object
  • Object
show all
Defined in:
lib/statsd.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

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

  • :tcp (Symbol) —

    for TCP, :udp or any other value for UDP



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

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



258
259
260
 
# File 'lib/statsd.rb', line 258

def logger
  @logger
end

Instance Attribute Details

#batch_size ⇒ Object

The default batch size for new batches (default: 10)



248
249
250
 
# File 'lib/statsd.rb', line 248

def batch_size
  @batch_size
end

#delimiter ⇒ Object

The replacement of

on ruby module names when transformed to statsd metric names



254
255
256
 
# File 'lib/statsd.rb', line 254

def delimiter
  @delimiter
end

#host ⇒ Object

StatsD host. Defaults to 127.0.0.1.



239
240
241
 
# File 'lib/statsd.rb', line 239

def host
  @host
end

#namespace ⇒ Object

A namespace to prepend to all statsd calls.



236
237
238
 
# File 'lib/statsd.rb', line 236

def namespace
  @namespace
end

#port ⇒ Object

StatsD port. Defaults to 8125.



242
243
244
 
# File 'lib/statsd.rb', line 242

def port
  @port
end

#postfix ⇒ Object

a postfix to append to all metrics



251
252
253
 
# File 'lib/statsd.rb', line 251

def postfix
  @postfix
end

#prefix ⇒ Object (readonly)

StatsD namespace prefix, generated from #namespace



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

def prefix
  @prefix
end

#stat_delimiter=(value) ⇒ Object (writeonly)

Allows for custom delimiter replacement for

when Ruby modules are transformed to statsd metric name



310
311
312
 
# File 'lib/statsd.rb', line 310

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



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

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



411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
 
# File 'lib/statsd.rb', line 411

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, opts = {}) ⇒ Object

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

Parameters:

  • stat (String) —

    stat name

  • count (Integer) —

    count



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

def count(stat, count, opts={})
  send_stats stat, count, :c, opts
end

#decrement(stat, opts = {}) ⇒ Object

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

Parameters:

  • stat (String) —

    stat name

See Also:



326
327
328
 
# File 'lib/statsd.rb', line 326

def decrement(stat, opts={})
  count stat, -1, opts
end

#gauge(stat, value, opts = {}) ⇒ 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.



348
349
350
 
# File 'lib/statsd.rb', line 348

def gauge(stat, value, opts={})
  send_stats stat, value, :g, opts
end

#increment(stat, opts = {}) ⇒ Object

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

Parameters:

  • stat (String) —

    stat name

See Also:



318
319
320
 
# File 'lib/statsd.rb', line 318

def increment(stat, opts={})
  count stat, 1, opts
end

#set(stat, value, opts = {}) ⇒ 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.



363
364
365
 
# File 'lib/statsd.rb', line 363

def set(stat, value, opts={})
  send_stats stat, value, :s, opts
end

#time(stat, opts = {}) { ... } ⇒ 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

Yields:

  • The operation to be timed

See Also:



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

def time(stat, opts={})
  start = Time.now
  result = yield
ensure
  timing(stat, ((Time.now - start) * 1000).round, opts)
  result
end

#timing(stat, ms, opts = {}) ⇒ 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



374
375
376
 
# File 'lib/statsd.rb', line 374

def timing(stat, ms, opts={})
  send_stats stat, ms, :ms, opts
end