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 using a thread local UDPSocket and carrying no state. 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) ⇒ 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



241
242
243
244
245
246
247
# File 'lib/statsd.rb', line 241

def initialize(host = '127.0.0.1', port = 8125)
  self.host, self.port = host, port
  self.delimiter = "."
  @prefix = nil
  @batch_size = 10
  @postfix = nil
end

Class Attribute Details

.loggerObject

Set to a standard logger instance to enable debug logging.



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

def logger
  @logger
end

Instance Attribute Details

#batch_sizeObject

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



226
227
228
# File 'lib/statsd.rb', line 226

def batch_size
  @batch_size
end

#delimiterObject

The replacement of

on ruby module names when transformed to statsd metric names



232
233
234
# File 'lib/statsd.rb', line 232

def delimiter
  @delimiter
end

#hostObject

StatsD host. Defaults to 127.0.0.1.



217
218
219
# File 'lib/statsd.rb', line 217

def host
  @host
end

#namespaceObject

A namespace to prepend to all statsd calls.



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

def namespace
  @namespace
end

#portObject

StatsD port. Defaults to 8125.



220
221
222
# File 'lib/statsd.rb', line 220

def port
  @port
end

#postfixObject

a postfix to append to all metrics



229
230
231
# File 'lib/statsd.rb', line 229

def postfix
  @postfix
end

#prefixObject (readonly)

StatsD namespace prefix, generated from #namespace



223
224
225
# File 'lib/statsd.rb', line 223

def prefix
  @prefix
end

#stat_delimiter=(value) ⇒ Object (writeonly)

Allows for custom delimiter replacement for

when Ruby modules are transformed to statsd metric name



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

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



379
380
381
# File 'lib/statsd.rb', line 379

def batch(&block)
  Batch.new(self).easy &block
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



307
308
309
# File 'lib/statsd.rb', line 307

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:



298
299
300
# File 'lib/statsd.rb', line 298

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



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

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:



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

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



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

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:



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

def time(stat, sample_rate=1)
  start = Time.now
  result = yield
  timing(stat, ((Time.now - start) * 1000).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



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

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