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:9125

$statsd = Statsd.new 'localhost', 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: 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



116
117
118
119
120
121
 
# File 'lib/statsd.rb', line 116

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

.logger ⇒ Object

Set to a standard logger instance to enable debug logging.



111
112
113
 
# File 'lib/statsd.rb', line 111

def logger
  @logger
end

Instance Attribute Details

#batch_size ⇒ Object

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



104
105
106
 
# File 'lib/statsd.rb', line 104

def batch_size
  @batch_size
end

#host ⇒ Object

StatsD host. Defaults to 127.0.0.1.



95
96
97
 
# File 'lib/statsd.rb', line 95

def host
  @host
end

#namespace ⇒ Object

A namespace to prepend to all statsd calls.



92
93
94
 
# File 'lib/statsd.rb', line 92

def namespace
  @namespace
end

#port ⇒ Object

StatsD port. Defaults to 8125.



98
99
100
 
# File 'lib/statsd.rb', line 98

def port
  @port
end

#postfix ⇒ Object

a postfix to append to all metrics



107
108
109
 
# File 'lib/statsd.rb', line 107

def postfix
  @postfix
end

#prefix ⇒ Object (readonly)

StatsD namespace prefix, generated from #namespace



101
102
103
 
# File 'lib/statsd.rb', line 101

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



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

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



175
176
177
 
# File 'lib/statsd.rb', line 175

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:



166
167
168
 
# File 'lib/statsd.rb', line 166

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



190
191
192
 
# File 'lib/statsd.rb', line 190

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:



157
158
159
 
# File 'lib/statsd.rb', line 157

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



206
207
208
 
# File 'lib/statsd.rb', line 206

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:



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

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



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

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