Class: Dogstatsd

Inherits:
Object
  • Object
show all
Defined in:
lib/dogstatsd.rb

Overview

Dogstatsd: A Dogstatsd client (www.datadoghq.com)

Examples:

Set up a global Dogstatsd client for a server on localhost:8125

require 'dogstatsd'
$statsd = Dogstatsd.new 'localhost', 8125

Send some stats

$statsd.increment 'page.views'
$statsd.timing 'page.load', 320
$statsd.gauge 'users.online', 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 = Dogstatsd.new 'localhost', 8125, :namespace => 'account'
statsd.increment 'activate'

Create a statsd client with global tags

statsd = Dogstatsd.new 'localhost', 8125, :tags => 'tag1:true'

Constant Summary collapse

VERSION = 
'2.0.0'
DEFAULT_HOST = 
'127.0.0.1'
DEFAULT_PORT = 
8125
OPTS_KEYS =

Create a dictionary to assign a key to every parameter’s name, except for tags (treated differently) Goal: Simple and fast to add some other parameters

[
      ['date_happened', 'd'],
      ['hostname', 'h'],
      ['aggregation_key', 'k'],
      ['priority', 'p'],
      ['source_type_name', 's'],
      ['alert_type', 't']
]
SC_OPT_KEYS =

Service check options

[
      ['timestamp', 'd:'],
      ['hostname', 'h:'],
      ['tags', '#'],
      ['message', 'm:']
]
OK = 
0
WARNING = 
1
CRITICAL = 
2
UNKNOWN = 
3

Class Attribute Summary collapse

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host = DEFAULT_HOST, port = DEFAULT_PORT, opts = {}, max_buffer_size = 50) ⇒ Dogstatsd

Returns a new instance of Dogstatsd.

Parameters:

  • host (String) (defaults to: DEFAULT_HOST) —

    your statsd host

  • port (Integer) (defaults to: DEFAULT_PORT) —

    your statsd port

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • :namespace (String) —

    set a namespace to be prepended to every metric name

  • :tags (Array<String>) —

    tags to be added to every metric



76
77
78
79
80
81
82
83
84
85
 
# File 'lib/dogstatsd.rb', line 76

def initialize(host = DEFAULT_HOST, port = DEFAULT_PORT, opts = {}, max_buffer_size=50)
  self.host, self.port = host, port
  @prefix = nil
  @socket = UDPSocket.new
  self.namespace = opts[:namespace]
  self.tags = opts[:tags]
  @buffer = Array.new
  self.max_buffer_size = max_buffer_size
  alias :send_stat :send_to_socket
end

Class Attribute Details

.logger ⇒ Object

Set to a standard logger instance to enable debug logging.



69
70
71
 
# File 'lib/dogstatsd.rb', line 69

def logger
  @logger
end

Instance Attribute Details

#buffer ⇒ Object (readonly)

Buffer containing the statsd message before they are sent in batch



62
63
64
 
# File 'lib/dogstatsd.rb', line 62

def buffer
  @buffer
end

#host ⇒ Object

StatsD host. Defaults to 127.0.0.1.



53
54
55
 
# File 'lib/dogstatsd.rb', line 53

def host
  @host
end

#max_buffer_size ⇒ Object

Maximum number of metrics in the buffer before it is flushed



65
66
67
 
# File 'lib/dogstatsd.rb', line 65

def max_buffer_size
  @max_buffer_size
end

#namespace ⇒ Object

A namespace to prepend to all statsd calls. Defaults to no namespace.



50
51
52
 
# File 'lib/dogstatsd.rb', line 50

def namespace
  @namespace
end

#port ⇒ Object

StatsD port. Defaults to 8125.



56
57
58
 
# File 'lib/dogstatsd.rb', line 56

def port
  @port
end

#tags ⇒ Object

Global tags to be added to every statsd call. Defaults to no tags.



59
60
61
 
# File 'lib/dogstatsd.rb', line 59

def tags
  @tags
end

Instance Method Details

#batch {|_self| ... } ⇒ Object

Send several metrics in the same UDP Packet They will be buffered and flushed when the block finishes

Examples:

Send several metrics in one packet:

$statsd.batch do |s|
   s.gauge('users.online',156)
   s.increment('page.views')
 end

Yields:

  • (_self)

Yield Parameters:

  • _self (Dogstatsd) —

    the object that the method was called on



292
293
294
295
296
297
 
# File 'lib/dogstatsd.rb', line 292

def batch()
  alias :send_stat :send_to_buffer
  yield self
  flush_buffer
  alias :send_stat :send_to_socket
end

#count(stat, count, opts = {}) ⇒ Object

Sends an arbitrary count for the given stat to the statsd server.

Parameters:

  • stat (String) —

    stat name

  • count (Integer) —

    count

  • opts (Hash) (defaults to: {}) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags



133
134
135
 
# File 'lib/dogstatsd.rb', line 133

def count(stat, count, opts={})
  send_stats stat, count, :c, opts
end

#decrement(stat, opts = {}) ⇒ Object

Sends a decrement (count = -1) for the given stat to the statsd server.

Parameters:

  • stat (String) —

    stat name

  • opts (Hash) (defaults to: {}) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags

See Also:



122
123
124
 
# File 'lib/dogstatsd.rb', line 122

def decrement(stat, opts={})
  count stat, -1, opts
end

#event(title, text, opts = {}) ⇒ Object

This end point allows you to post events to the stream. You can tag them, set priority and even aggregate them with other events.

Aggregation in the stream is made on hostname/event_type/source_type/aggregation_key. If there’s no event type, for example, then that won’t matter; it will be grouped with other events that don’t have an event type.

Examples:

Report an awful event:

$statsd.event('Something terrible happened', 'The end is near if we do nothing', :alert_type=>'warning', :tags=>['end_of_times','urgent'])

Parameters:

  • title (String) —

    Event title

  • text (String) —

    Event text. Supports n

  • opts (Hash) (defaults to: {}) —

    the additional data about the event

Options Hash (opts):

  • :date_happened (Integer, nil) — default: nil —

    Assign a timestamp to the event. Default is now when none

  • :hostname (String, nil) — default: nil —

    Assign a hostname to the event.

  • :aggregation_key (String, nil) — default: nil —

    Assign an aggregation key to the event, to group it with some others

  • :priority (String, nil) — default: 'normal' —

    Can be “normal” or “low”

  • :source_type_name (String, nil) — default: nil —

    Assign a source type to the event

  • :alert_type (String, nil) — default: 'info' —

    Can be “error”, “warning”, “info” or “success”.

  • :tags (Array<String>) —

    tags to be added to every metric



277
278
279
280
281
282
 
# File 'lib/dogstatsd.rb', line 277

def event(title, text, opts={})
  event_string = format_event(title, text, opts)
  raise "Event #{title} payload is too big (more that 8KB), event discarded" if event_string.length > 8 * 1024

  send_to_socket event_string
end

#format_event(title, text, opts = {}) ⇒ Object 



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
 
# File 'lib/dogstatsd.rb', line 299

def format_event(title, text, opts={})
  escape_event_content title
  escape_event_content text
  event_string_data = "_e{#{title.length},#{text.length}}:#{title}|#{text}"

  # We construct the string to be sent by adding '|key:value' parts to it when needed
  # All pipes ('|') in the metadata are removed. Title and Text can keep theirs
  OPTS_KEYS.each do |name_key|
    if name_key[0] != 'tags' && opts[name_key[0].to_sym]
      value = opts[name_key[0].to_sym]
      rm_pipes value
      event_string_data << "|#{name_key[1]}:#{value}"
    end
  end
  full_tags = tags + (opts[:tags] || [])
  # Tags are joined and added as last part to the string to be sent
  unless full_tags.empty?
    full_tags.each do |tag|
      rm_pipes tag
    end
    event_string_data << "|##{full_tags.join(',')}"
  end

  raise "Event #{title} payload is too big (more that 8KB), event discarded" if event_string_data.length > 8 * 1024
  return event_string_data
end

#format_service_check(name, status, opts = {}) ⇒ Object 



232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/dogstatsd.rb', line 232

def format_service_check(name, status, opts={})
  sc_string = "_sc|#{name}|#{status}"

  SC_OPT_KEYS.each do |name_key|
    if opts[name_key[0].to_sym]
      if name_key[0] == 'tags'
        tags = opts[:tags]
        tags.each do |tag|
          rm_pipes tag
        end
        tags = "#{tags.join(",")}" unless tags.empty?
        sc_string << "|##{tags}"
      elsif name_key[0] == 'message'
        message = opts[:message]
        rm_pipes message
        escape_service_check_message message
        sc_string << "|m:#{message}"
      else
        value = opts[name_key[0].to_sym]
        rm_pipes value
        sc_string << "|#{name_key[1]}#{value}"
      end
    end
  end
  return sc_string
end

#gauge(stat, value, opts = {}) ⇒ 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.

  • opts (Hash) (defaults to: {}) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags



150
151
152
 
# File 'lib/dogstatsd.rb', line 150

def gauge(stat, value, opts={})
  send_stats stat, value, :g, opts
end

#histogram(stat, value, opts = {}) ⇒ Object

Sends a value to be tracked as a histogram to the statsd server.

Examples:

Report the current user count:

$statsd.histogram('user.count', User.count)

Parameters:

  • stat (String) —

    stat name.

  • value (Numeric) —

    histogram value.

  • opts (Hash) (defaults to: {}) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags



163
164
165
 
# File 'lib/dogstatsd.rb', line 163

def histogram(stat, value, opts={})
  send_stats stat, value, :h, opts
end

#increment(stat, opts = {}) ⇒ Object

Sends an increment (count = 1) for the given stat to the statsd server.

Parameters:

  • stat (String) —

    stat name

  • opts (Hash) (defaults to: {}) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags

See Also:



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

def increment(stat, opts={})
  count stat, 1, opts
end

#service_check(name, status, opts = {}) ⇒ Object

Examples:

Report a critical service check status

$statsd.service_check('my.service.check', Dogstatsd::CRITICAL, :tags=>['urgent'])


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

def service_check(name, status, opts={})
  service_check_string = format_service_check(name, status, opts)
  send_to_socket service_check_string
end

#set(stat, value, opts = {}) ⇒ Object

Sends a value to be tracked as a set to the statsd server.

Examples:

Record a unique visitory by id:

$statsd.set('visitors.uniques', User.id)

Parameters:

  • stat (String) —

    stat name.

  • value (Numeric) —

    set value.

  • opts (Hash) (defaults to: {}) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags



212
213
214
 
# File 'lib/dogstatsd.rb', line 212

def set(stat, value, opts={})
  send_stats stat, value, :s, opts
end

#time(stat, opts = {}) { ... } ⇒ Object

Reports execution time of the provided block using #timing.

If the block fails, the stat is still reported, then the error is reraised

Examples:

Report the time (in ms) taken to activate an account

$statsd.time('account.activate') { @account.activate! }

Parameters:

  • stat (String) —

    stat name

  • opts (Hash) (defaults to: {}) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags

Yields:

  • The operation to be timed

See Also:



194
195
196
197
198
199
200
201
202
 
# File 'lib/dogstatsd.rb', line 194

def time(stat, opts={})
  start = Time.now
  result = yield
  time_since(stat, start, opts)
  result
rescue
  time_since(stat, start, opts)
  raise
end

#timing(stat, ms, opts = {}) ⇒ 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

  • opts (Hash) (defaults to: {}) —

    the options to create the metric with

Options Hash (opts):

  • :sample_rate (Numeric) —

    sample rate, 1 for always

  • :tags (Array<String>) —

    An array of tags



177
178
179
 
# File 'lib/dogstatsd.rb', line 177

def timing(stat, ms, opts={})
  send_stats stat, ms, :ms, opts
end