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



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

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

Class Attribute Details

.loggerObject

Set to a standard logger instance to enable debug logging.



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

def logger
  @logger
end

Instance Attribute Details

#batch_sizeObject

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



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

def batch_size
  @batch_size
end

#hostObject

StatsD host. Defaults to 127.0.0.1.



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

def host
  @host
end

#namespaceObject

A namespace to prepend to all statsd calls.



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

def namespace
  @namespace
end

#portObject

StatsD port. Defaults to 8125.



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

def port
  @port
end

#postfixObject

a postfix to append to all metrics



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

def postfix
  @postfix
end

#prefixObject (readonly)

StatsD namespace prefix, generated from #namespace



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

def prefix
  @prefix
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



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

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.



296
297
298
# File 'lib/statsd.rb', line 296

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.

See Also:



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

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)


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

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.

See Also:



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

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)


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

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! }

Yields:

  • The operation to be timed

See Also:



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

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.



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

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