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


283
284
285
286
287
288
289
290
291
292
293
294
295
# File 'lib/statsd.rb', line 283

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
  @postfix = nil
  @socket = nil
  @protocol = protocol || :udp
  @s_mu = Mutex.new
  connect
end

Class Attribute Details

.loggerObject

Set to a standard logger instance to enable debug logging.


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

def logger
  @logger
end

Instance Attribute Details

#batch_byte_sizeObject

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


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

def batch_byte_size
  @batch_byte_size
end

#batch_sizeObject

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


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

def batch_size
  @batch_size
end

#delimiterObject

The replacement of

on ruby module names when transformed to statsd metric names


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

def delimiter
  @delimiter
end

#hostObject

StatsD host. Defaults to 127.0.0.1.


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

def host
  @host
end

#namespaceObject

A namespace to prepend to all statsd calls.


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

def namespace
  @namespace
end

#portObject

StatsD port. Defaults to 8125.


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

def port
  @port
end

#postfixObject

a postfix to append to all metrics


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

def postfix
  @postfix
end

#prefixObject (readonly)

StatsD namespace prefix, generated from #namespace


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

def prefix
  @prefix
end

#stat_delimiter=(value) ⇒ Object (writeonly)

Allows for custom delimiter replacement for

when Ruby modules are transformed to statsd metric name


330
331
332
# File 'lib/statsd.rb', line 330

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


430
431
432
# File 'lib/statsd.rb', line 430

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

#connectObject

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


438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
# File 'lib/statsd.rb', line 438

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


357
358
359
# File 'lib/statsd.rb', line 357

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:


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

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


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

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:


339
340
341
# File 'lib/statsd.rb', line 339

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


388
389
390
# File 'lib/statsd.rb', line 388

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:


412
413
414
415
416
417
418
# File 'lib/statsd.rb', line 412

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


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

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