Class: Datadog::Statsd

Inherits:
Object
  • Object
show all
Defined in:
lib/datadog/statsd.rb,
lib/datadog/statsd/sender.rb,
lib/datadog/statsd/version.rb,
lib/datadog/statsd/forwarder.rb,
lib/datadog/statsd/telemetry.rb,
lib/datadog/statsd/connection.rb,
lib/datadog/statsd/serialization.rb,
lib/datadog/statsd/message_buffer.rb,
lib/datadog/statsd/udp_connection.rb,
lib/datadog/statsd/uds_connection.rb,
lib/datadog/statsd/serialization/serializer.rb,
lib/datadog/statsd/serialization/tag_serializer.rb,
lib/datadog/statsd/serialization/stat_serializer.rb,
lib/datadog/statsd/serialization/event_serializer.rb,
lib/datadog/statsd/serialization/service_check_serializer.rb

Defined Under Namespace

Modules: Serialization Classes: Connection, Error, Forwarder, MessageBuffer, Sender, Telemetry, UDPConnection, UDSConnection

Constant Summary collapse

OK =
0
WARNING =
1
CRITICAL =
2
UNKNOWN =
3
UDP_DEFAULT_BUFFER_SIZE =
1_432
UDS_DEFAULT_BUFFER_SIZE =
8_192
DEFAULT_BUFFER_POOL_SIZE =
Float::INFINITY
MAX_EVENT_SIZE =
8 * 1_024
DEFAULT_TELEMETRY_FLUSH_INTERVAL =

minimum flush interval for the telemetry in seconds

10
COUNTER_TYPE =
'c'
GAUGE_TYPE =
'g'
HISTOGRAM_TYPE =
'h'
DISTRIBUTION_TYPE =
'd'
TIMING_TYPE =
'ms'
SET_TYPE =
's'
VERSION =
'4.8.1'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host = nil, port = nil, socket_path: nil, namespace: nil, tags: nil, sample_rate: nil, buffer_max_payload_size: nil, buffer_max_pool_size: nil, buffer_overflowing_stategy: :drop, logger: nil, telemetry_enable: true, telemetry_flush_interval: DEFAULT_TELEMETRY_FLUSH_INTERVAL) ⇒ Statsd

Returns a new instance of Statsd.

Parameters:

  • host (String) (defaults to: nil)

    your statsd host

  • port (Integer) (defaults to: nil)

    your statsd port

  • [String] (Hash)

    a customizable set of options

  • [Array<String>|Hash] (Hash)

    a customizable set of options

  • [Logger] (Hash)

    a customizable set of options

  • [Integer] (Hash)

    a customizable set of options

  • [Float] (Hash)

    a customizable set of options


73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
# File 'lib/datadog/statsd.rb', line 73

def initialize(
  host = nil,
  port = nil,
  socket_path: nil,

  namespace: nil,
  tags: nil,
  sample_rate: nil,

  buffer_max_payload_size: nil,
  buffer_max_pool_size: nil,
  buffer_overflowing_stategy: :drop,

  logger: nil,

  telemetry_enable: true,
  telemetry_flush_interval: DEFAULT_TELEMETRY_FLUSH_INTERVAL
)
  unless tags.nil? || tags.is_a?(Array) || tags.is_a?(Hash)
    raise ArgumentError, 'tags must be an array of string tags or a Hash'
  end

  @namespace = namespace
  @prefix = @namespace ? "#{@namespace}.".freeze : nil
  @serializer = Serialization::Serializer.new(prefix: @prefix, global_tags: tags)
  @sample_rate = sample_rate

  @forwarder = Forwarder.new(
    host: host,
    port: port,
    socket_path: socket_path,

    global_tags: tags,
    logger: logger,

    buffer_max_payload_size: buffer_max_payload_size,
    buffer_max_pool_size: buffer_max_pool_size,
    buffer_overflowing_stategy: buffer_overflowing_stategy,

    telemetry_flush_interval: telemetry_enable ? telemetry_flush_interval : nil,
  )
end

Instance Attribute Details

#namespaceObject (readonly)

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


54
55
56
# File 'lib/datadog/statsd.rb', line 54

def namespace
  @namespace
end

#sample_rateObject (readonly)

Default sample rate


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

def sample_rate
  @sample_rate
end

Class Method Details

.open(*args) ⇒ Object

yield a new instance to a block and close it when done for short-term use-cases that don't want to close the socket manually


118
119
120
121
122
123
124
# File 'lib/datadog/statsd.rb', line 118

def self.open(*args)
  instance = new(*args)

  yield instance
ensure
  instance.close
end

Instance Method Details

#closeObject

Close the underlying socket


302
303
304
# File 'lib/datadog/statsd.rb', line 302

def close
  forwarder.close
end

#count(stat, count, opts = EMPTY_OPTIONS) ⇒ 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: EMPTY_OPTIONS)

    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


161
162
163
164
# File 'lib/datadog/statsd.rb', line 161

def count(stat, count, opts = EMPTY_OPTIONS)
  opts = { sample_rate: opts } if opts.is_a?(Numeric)
  send_stats(stat, count, COUNTER_TYPE, opts)
end

#decrement(stat, opts = EMPTY_OPTIONS) ⇒ Object

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

Parameters:

  • stat (String)

    stat name

  • opts (Hash) (defaults to: EMPTY_OPTIONS)

    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

  • :by (Numeric)

    decrement value, default 1

See Also:


148
149
150
151
152
# File 'lib/datadog/statsd.rb', line 148

def decrement(stat, opts = EMPTY_OPTIONS)
  opts = { sample_rate: opts } if opts.is_a?(Numeric)
  decr_value = - opts.fetch(:by, 1)
  count(stat, decr_value, opts)
end

#distribution(stat, value, opts = EMPTY_OPTIONS) ⇒ Object

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

Examples:

Report the current user count:

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

Parameters:

  • stat (String)

    stat name.

  • value (Numeric)

    distribution value.

  • opts (Hash) (defaults to: EMPTY_OPTIONS)

    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


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

def distribution(stat, value, opts = EMPTY_OPTIONS)
  send_stats(stat, value, DISTRIBUTION_TYPE, opts)
end

#event(title, text, opts = EMPTY_OPTIONS) ⇒ 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 newlines (\n)

  • opts (Hash) (defaults to: EMPTY_OPTIONS)

    the additional data about the event

Options Hash (opts):

  • :date_happened (Integer, String, 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


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

def event(title, text, opts = EMPTY_OPTIONS)
  telemetry.sent(events: 1) if telemetry

  forwarder.send_message(serializer.to_event(title, text, opts))
end

#flush(flush_telemetry: false, sync: false) ⇒ Object

Flush the buffer into the connection


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

def flush(flush_telemetry: false, sync: false)
  forwarder.flush(flush_telemetry: flush_telemetry, sync: sync)
end

#gauge(stat, value, opts = EMPTY_OPTIONS) ⇒ 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: EMPTY_OPTIONS)

    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


179
180
181
182
# File 'lib/datadog/statsd.rb', line 179

def gauge(stat, value, opts = EMPTY_OPTIONS)
  opts = { sample_rate: opts } if opts.is_a?(Numeric)
  send_stats(stat, value, GAUGE_TYPE, opts)
end

#histogram(stat, value, opts = EMPTY_OPTIONS) ⇒ 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: EMPTY_OPTIONS)

    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


193
194
195
# File 'lib/datadog/statsd.rb', line 193

def histogram(stat, value, opts = EMPTY_OPTIONS)
  send_stats(stat, value, HISTOGRAM_TYPE, opts)
end

#hostObject


319
320
321
# File 'lib/datadog/statsd.rb', line 319

def host
  forwarder.host
end

#increment(stat, opts = EMPTY_OPTIONS) ⇒ Object

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

Parameters:

  • stat (String)

    stat name

  • opts (Hash) (defaults to: EMPTY_OPTIONS)

    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

  • :by (Numeric)

    increment value, default 1

See Also:


134
135
136
137
138
# File 'lib/datadog/statsd.rb', line 134

def increment(stat, opts = EMPTY_OPTIONS)
  opts = { sample_rate: opts } if opts.is_a?(Numeric)
  incr_value = opts.fetch(:by, 1)
  count(stat, incr_value, opts)
end

#portObject


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

def port
  forwarder.port
end

#service_check(name, status, opts = EMPTY_OPTIONS) ⇒ Object

Examples:

Report a critical service check status

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

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

def service_check(name, status, opts = EMPTY_OPTIONS)
  telemetry.sent(service_checks: 1) if telemetry

  forwarder.send_message(serializer.to_service_check(name, status, opts))
end

#set(stat, value, opts = EMPTY_OPTIONS) ⇒ 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: EMPTY_OPTIONS)

    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


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

def set(stat, value, opts = EMPTY_OPTIONS)
  opts = { sample_rate: opts } if opts.is_a?(Numeric)
  send_stats(stat, value, SET_TYPE, opts)
end

#socket_pathObject


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

def socket_path
  forwarder.socket_path
end

#sync_with_outbound_ioObject


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

def sync_with_outbound_io
  forwarder.sync_with_outbound_io
end

#tagsObject

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


57
58
59
# File 'lib/datadog/statsd.rb', line 57

def tags
  serializer.global_tags
end

#telemetryObject


315
316
317
# File 'lib/datadog/statsd.rb', line 315

def telemetry
  forwarder.telemetry
end

#time(stat, opts = EMPTY_OPTIONS) { ... } ⇒ 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: EMPTY_OPTIONS)

    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:


238
239
240
241
242
243
244
# File 'lib/datadog/statsd.rb', line 238

def time(stat, opts = EMPTY_OPTIONS)
  opts = { sample_rate: opts } if opts.is_a?(Numeric)
  start = now
  yield
ensure
  timing(stat, ((now - start) * 1000).round, opts)
end

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

    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


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

def timing(stat, ms, opts = EMPTY_OPTIONS)
  opts = { sample_rate: opts } if opts.is_a?(Numeric)
  send_stats(stat, ms, TIMING_TYPE, opts)
end

#transport_typeObject


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

def transport_type
  forwarder.transport_type
end