Class: Datadog::Statsd

Inherits:
Object
  • Object
show all
Defined in:
lib/datadog/statsd.rb,
lib/datadog/statsd/timer.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/connection_cfg.rb,
lib/datadog/statsd/message_buffer.rb,
lib/datadog/statsd/udp_connection.rb,
lib/datadog/statsd/uds_connection.rb,
lib/datadog/statsd/origin_detection.rb,
lib/datadog/statsd/single_thread_sender.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/field_serializer.rb,
lib/datadog/statsd/serialization/service_check_serializer.rb

Defined Under Namespace

Modules: Serialization Classes: Connection, ConnectionCfg, Error, Forwarder, MessageBuffer, Sender, SingleThreadSender, Telemetry, Timer, 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
UDP_DEFAULT_SENDER_QUEUE_SIZE = 
2048
UDS_DEFAULT_SENDER_QUEUE_SIZE = 
512
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 = 
'5.7.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, buffer_flush_interval: nil, sender_queue_size: nil, logger: nil, single_thread: false, delay_serialization: false, telemetry_enable: true, telemetry_flush_interval: DEFAULT_TELEMETRY_FLUSH_INTERVAL, origin_detection: true, container_id: nil, cardinality: nil) ⇒ 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

  • [Numeric] (Hash) —

    a customizable set of options

  • [Float] (Hash) —

    a customizable set of options

  • [Boolean] (Hash) —

    a customizable set of options



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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/datadog/statsd.rb', line 89

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,
  buffer_flush_interval: nil,

  sender_queue_size: nil,

  logger: nil,

  single_thread: false,
  delay_serialization: false,

  telemetry_enable: true,
  telemetry_flush_interval: DEFAULT_TELEMETRY_FLUSH_INTERVAL,

  origin_detection: true,
  container_id: nil,
  cardinality: nil
)
  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

  origin_detection_enabled = origin_detection_enabled?(origin_detection)
  container_id = get_container_id(container_id, origin_detection_enabled)

  external_data = sanitize(ENV['DD_EXTERNAL_ENV']) if origin_detection_enabled

  @serializer = Serialization::Serializer.new(prefix: @prefix,
                                              container_id: container_id,
                                              external_data: external_data,
                                              global_tags: tags,
                                              )

  @cardinality = cardinality || ENV['DD_CARDINALITY'] || ENV['DATADOG_CARDINALITY']

  @sample_rate = sample_rate
  @delay_serialization = delay_serialization

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

    global_tags: tags,
    logger: logger,

    single_thread: single_thread,

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

    sender_queue_size: sender_queue_size,

    telemetry_flush_interval: telemetry_enable ? telemetry_flush_interval : nil,
    container_id: container_id,
    external_data: external_data,
    cardinality: @cardinality,

    serializer: serializer
  )
end

Instance Attribute Details

#namespace ⇒ Object (readonly)

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



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

def namespace
  @namespace
end

#sample_rate ⇒ Object (readonly)

Default sample rate



71
72
73
 
# File 'lib/datadog/statsd.rb', line 71

def sample_rate
  @sample_rate
end

Class Method Details

.open(*args, **kwargs) ⇒ 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 TODO: replace with … once we are on ruby 2.7



171
172
173
174
175
176
177
 
# File 'lib/datadog/statsd.rb', line 171

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

  yield instance
ensure
  instance.close if instance
end

Instance Method Details

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

Send several metrics in the same packet. They will be buffered and flushed when the block finishes.

This method exists for compatibility with v4.x versions, it is not needed anymore since the batching is now automatically done internally. It also means that an automatic flush could occur if the buffer is filled during the execution of the batch block.

This method is DEPRECATED and will be removed in future v6.x API.

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:



410
411
412
413
 
# File 'lib/datadog/statsd.rb', line 410

def batch
  yield self
  flush(sync: true)
end

#close(flush: true) ⇒ Object

Close the underlying socket

Parameters:

  • flush (Boolean, true) (defaults to: true) —

    Should we flush the metrics before closing



418
419
420
421
 
# File 'lib/datadog/statsd.rb', line 418

def close(flush: true)
  flush(sync: true) if flush
  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

  • :pre_sampled (Boolean) —

    If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn’t perform sampling.

  • :tags (Array<String>) —

    An array of tags

  • :cardinality (String) —

    The tag cardinality to use



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

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

  • :pre_sampled (Boolean) —

    If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn’t perform sampling.

  • :tags (Array<String>) —

    An array of tags

  • :by (Numeric) —

    decrement value, default 1

  • :cardinality (String) —

    The tag cardinality to use

See Also:



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

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

  • :pre_sampled (Boolean) —

    If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn’t perform sampling.

  • :tags (Array<String>) —

    An array of tags

  • :cardinality (String) —

    The tag cardinality to use



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

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

#distribution_time(stat, opts = EMPTY_OPTIONS) ⇒ Object

Reports execution time of the provided block as a distribution.

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.distribution_time('account.activate') { @account.activate! }

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

  • :cardinality (String) —

    The tag cardinality to use



288
289
290
291
292
293
294
 
# File 'lib/datadog/statsd.rb', line 288

def distribution_time(stat, opts = EMPTY_OPTIONS)
  opts = { sample_rate: opts } if opts.is_a?(Numeric)
  start = now
  yield
ensure
  distribution(stat, ((now - start) * 1000).round, 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”.

  • :truncate_if_too_long (Boolean, false) — default: false —

    Truncate the event if it is too long

  • :tags (Array<String>) —

    tags to be added to every metric

  • :cardinality (String) —

    The tag cardinality to use



389
390
391
392
393
 
# File 'lib/datadog/statsd.rb', line 389

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



428
429
430
 
# File 'lib/datadog/statsd.rb', line 428

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 arbitrary 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

  • :pre_sampled (Boolean) —

    If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn’t perform sampling.

  • :tags (Array<String>) —

    An array of tags

  • :cardinality (String) —

    The tag cardinality to use



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

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

  • :pre_sampled (Boolean) —

    If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn’t perform sampling.

  • :tags (Array<String>) —

    An array of tags

  • :cardinality (String) —

    The tag cardinality to use



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

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

#host ⇒ Object 



436
437
438
 
# File 'lib/datadog/statsd.rb', line 436

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

  • :pre_sampled (Boolean) —

    If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn’t perform sampling.

  • :tags (Array<String>) —

    An array of tags

  • :by (Numeric) —

    increment value, default 1

  • :cardinality (String) —

    The tag cardinality to use

See Also:



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

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

#port ⇒ Object 



440
441
442
 
# File 'lib/datadog/statsd.rb', line 440

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'])


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

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

  • :pre_sampled (Boolean) —

    If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn’t perform sampling.

  • :tags (Array<String>) —

    An array of tags

  • :cardinality (String) —

    The tag cardinality to use



347
348
349
350
 
# File 'lib/datadog/statsd.rb', line 347

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_path ⇒ Object 



444
445
446
 
# File 'lib/datadog/statsd.rb', line 444

def socket_path
  forwarder.socket_path
end

#sync_with_outbound_io ⇒ Object 



423
424
425
 
# File 'lib/datadog/statsd.rb', line 423

def sync_with_outbound_io
  forwarder.sync_with_outbound_io
end

#tags ⇒ Object

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



66
67
68
 
# File 'lib/datadog/statsd.rb', line 66

def tags
  serializer.global_tags
end

#telemetry ⇒ Object 



432
433
434
 
# File 'lib/datadog/statsd.rb', line 432

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

  • :pre_sampled (Boolean) —

    If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn’t perform sampling.

  • :tags (Array<String>) —

    An array of tags

  • :cardinality (String) —

    The tag cardinality to use

Yields:

  • The operation to be timed

See Also:



328
329
330
331
332
333
334
 
# File 'lib/datadog/statsd.rb', line 328

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

  • :pre_sampled (Boolean) —

    If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn’t perform sampling.

  • :tags (Array<String>) —

    An array of tags

  • :cardinality (String) —

    The tag cardinality to use



308
309
310
311
 
# File 'lib/datadog/statsd.rb', line 308

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_type ⇒ Object 



448
449
450
 
# File 'lib/datadog/statsd.rb', line 448

def transport_type
  forwarder.transport_type
end