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



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

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.



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

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)



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

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)



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

def batch_size
  @batch_size
end

#delimiter ⇒ Object

The replacement of

on ruby module names when transformed to statsd metric names



286
287
288
 
# File 'lib/statsd.rb', line 286

def delimiter
  @delimiter
end

#flush_interval ⇒ Object

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



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

def flush_interval
  @flush_interval
end

#host ⇒ Object

StatsD host. Defaults to 127.0.0.1.



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

def host
  @host
end

#namespace ⇒ Object

A namespace to prepend to all statsd calls.



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

def namespace
  @namespace
end

#port ⇒ Object

StatsD port. Defaults to 8125.



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

def port
  @port
end

#postfix ⇒ Object

a postfix to append to all metrics



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

def postfix
  @postfix
end

#prefix ⇒ Object (readonly)

StatsD namespace prefix, generated from #namespace



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

def prefix
  @prefix
end

#stat_delimiter=(value) ⇒ Object (writeonly)

Allows for custom delimiter replacement for

when Ruby modules are transformed to statsd metric name



344
345
346
 
# File 'lib/statsd.rb', line 344

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



444
445
446
 
# File 'lib/statsd.rb', line 444

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



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

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



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

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:



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

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



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

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:



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

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



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

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:



426
427
428
429
430
431
432
 
# File 'lib/statsd.rb', line 426

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



414
415
416
 
# File 'lib/statsd.rb', line 414

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