dogstatsd-ruby 4.0.0 → 4.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d2b1b9e7ec2a48c5305f6acda103d0b7a09787801dd899a38fb665f5389e4f3
-  data.tar.gz: 3d974fffb4ace3bc248e69dcdaabb4c556e6783a25d65af98cb65bdccafc52ee
+  metadata.gz: 57d7660dad73ad8c0c5f37f6d6130474d255beaa467aca03f532e552d0b608e0
+  data.tar.gz: 30c8686d3045e4cfb2ca18c57390f78dbcccba1ff941deb170d89497953d5e84
 SHA512:
-  metadata.gz: 16c82cb62bfd324d5e1dc1c6293fa121b92bd0c88d00474210c5da67f2cb07ae350cc0b717b15739c7a6f09e9021323ba348cec70ec2d0ac66a362f15f81007b
-  data.tar.gz: 6e82cef56d746ecf7b10890d397e313c143611b18b4ae65db67eb2f252cb27acacb45de03f6447b7b4ebb1666209806d6b048fb2857c5c8790f1f6729f4ae806
+  metadata.gz: 99214bb827186d3b01568cc59064f7d2a8d043a4a739c7f90a2b013feeeead11ed363937c37d2c29846d101ed886c318a6369c2d5a57292b0c058db81c708813
+  data.tar.gz: c82e6c5e9668804688fd308e091398e05ada88dac8ea78a678ee2da671eaf297ffd95997efaf376506632f65e88b4096a6a9b2590667f772f19c6b020e238827

data/README.md

@@ -1,95 +1,77 @@
+# dogstatsd-ruby
 
-dogstatsd-ruby
-==============
+A client for DogStatsD, an extension of the StatsD metric server for Datadog. Full API documentation is available in [DogStatsD-ruby rubydoc](https://www.rubydoc.info/github/DataDog/dogstatsd-ruby/master/Datadog/Statsd).
 
-A client for DogStatsD, an extension of the StatsD metric server for Datadog.
+[![Build Status](https://secure.travis-ci.org/DataDog/dogstatsd-ruby.svg)](http://travis-ci.org/DataDog/dogstatsd-ruby)
 
-[![Build Status](https://secure.travis-ci.org/DataDog/dogstatsd-ruby.png)](http://travis-ci.org/DataDog/dogstatsd-ruby)
+See [CHANGELOG.md](CHANGELOG.md) for changes. To suggest a feature, report a bug, or general discussion, [open an issue](http://github.com/DataDog/dogstatsd-ruby/issues/).
 
-Quick Start Guide
------------------
+## Installation
 
 First install the library:
 
-    gem install dogstatsd-ruby
+```
+gem install dogstatsd-ruby
+```
+
+## Configuration
 
-Then start instrumenting your code:
+To instantiate a DogStatsd client:
 
-``` ruby
-# Load the dogstats module.
+```ruby
+# Import the library
 require 'datadog/statsd'
 
-# Create a stats instance.
+# Create a DogStatsD client instance.
 statsd = Datadog::Statsd.new('localhost', 8125)
-
-# you could also create a statsd class if you need a drop in replacement
-# class Statsd < Datadog::Statsd
-# end
-
-# Increment a counter.
-statsd.increment('page.views')
-
-# Record a gauge 50% of the time.
-statsd.gauge('users.online', 123, :sample_rate=>0.5)
-
-# Sample a histogram
-statsd.histogram('file.upload.size', 1234)
-
-# Time a block of code
-statsd.time('page.render') do
-  render_page('home.html')
-end
-
-# Send several metrics at the same time
-# All metrics will be buffered and sent in one packet when the block completes
-statsd.batch do |s|
-  s.increment('page.views')
-  s.gauge('users.online', 123)
-end
-
-# Tag a metric.
-statsd.histogram('query.time', 10, :tags => ["version:1"])
-
-# Auto-close socket after end of block
-Datadog::Statsd.open('localhost', 8125) do |s|
-  s.increment('page.views')
-end
+```
+Or if you want to connect over Unix Domain Socket:
+```ruby
+# Connection over Unix Domain Socket
+statsd = Datadog::Statsd.new(socket_path: '/path/to/socket/file')
 ```
 
-You can also post events to your stream. You can tag them, set priority and even aggregate them with other events.
+Find a list of all the available options for your DogStatsD Client in the [DogStatsD-ruby rubydoc](https://www.rubydoc.info/github/DataDog/dogstatsd-ruby/master/Datadog/Statsd) or in the [Datadog public DogStatsD documentation](https://docs.datadoghq.com/developers/dogstatsd/?tab=ruby#client-instantiation-parameters).
 
-Aggregation in the stream is made on hostname/event_type/source_type/aggregation_key.
+### Origin detection over UDP
 
-``` ruby
-# Post a simple message
-statsd.event("There might be a storm tomorrow", "A friend warned me earlier.")
+Origin detection is a method to detect which pod DogStatsD packets are coming from in order to add the pod's tags to the tag list.
 
-# Cry for help
-statsd.event("SO MUCH SNOW", "Started yesterday and it won't stop !!", :alert_type => "error", :tags => ["urgent", "endoftheworld"])
+To enable origin detection over UDP, add the following lines to your application manifest
+```yaml
+env:
+  - name: DD_ENTITY_ID
+    valueFrom:
+      fieldRef:
+        fieldPath: metadata.uid
 ```
+The DogStatsD client attaches an internal tag, `entity_id`. The value of this tag is the content of the `DD_ENTITY_ID` environment variable, which is the pod’s UID.
 
+## Usage
 
+In order to use DogStatsD metrics, events, and Service Checks the Agent must be [running and available](https://docs.datadoghq.com/developers/dogstatsd/?tab=ruby).
 
-Documentation
--------------
+### Metrics
 
-Full API documentation is available
-[here](http://www.rubydoc.info/github/DataDog/dogstatsd-ruby/master/frames).
+After the client is created, you can start sending custom metrics to Datadog. See the dedicated [Metric Submission: DogStatsD documentation](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby) to see how to submit all supported metric types to Datadog with working code examples:
 
+* [Submit a COUNT metric](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#count).
+* [Submit a GAUGE metric](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#gauge).
+* [Submit a SET metric](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#set)
+* [Submit a HISTOGRAM metric](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#histogram)
+* [Submit a DISTRIBUTION metric](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#distribution)
 
-Feedback
---------
+Some options are suppported when submitting metrics, like [applying a Sample Rate to your metrics](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#metric-submission-options) or [tagging your metrics with your custom tags](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#metric-tagging). Find all the available functions to report metrics in the [DogStatsD-ruby rubydoc](https://www.rubydoc.info/github/DataDog/dogstatsd-ruby/master/Datadog/Statsd).
 
-To suggest a feature, report a bug, or general discussion, head over
-[here](http://github.com/DataDog/dogstatsd-ruby/issues/).
+### Events
 
+After the client is created, you can start sending events to your Datadog Event Stream. See the dedicated [Event Submission: DogStatsD documentation](https://docs.datadoghq.com/developers/events/dogstatsd/?tab=ruby) to see how to submit an event to Datadog your Event Stream.
 
-[Change Log](CHANGELOG.md)
-----------------------------
+### Service Checks
 
+After the client is created, you can start sending Service Checks to Datadog. See the dedicated [Service Check Submission: DogStatsD documentation](https://docs.datadoghq.com/developers/service_checks/dogstatsd_service_checks_submission/?tab=ruby) to see how to submit a Service Check to Datadog.
 
-Credits
--------
+## Credits
 
 dogstatsd-ruby is forked from Rien Henrichs [original Statsd
 client](https://github.com/reinh/statsd).

data/lib/datadog/statsd.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 require 'socket'
 
+require_relative 'statsd/telemetry'
+require_relative 'statsd/udp_connection'
+require_relative 'statsd/uds_connection'
+require_relative 'statsd/batch'
+
 # = Datadog::Statsd: A DogStatsd client (https://www.datadoghq.com)
 #
 # @example Set up a global Statsd client for a server on localhost:8125
@@ -19,168 +24,42 @@ require 'socket'
 #   statsd = Datadog::Statsd.new 'localhost', 8125, tags: 'tag1:true'
 module Datadog
   class Statsd
-
-    class Connection
-      DEFAULT_HOST = '127.0.0.1'
-      DEFAULT_PORT = 8125
-
-      # StatsD host. Defaults to 127.0.0.1.
-      attr_reader :host
-
-      # StatsD port. Defaults to 8125.
-      attr_reader :port
-
-      # DogStatsd unix socket path. Not used by default.
-      attr_reader :socket_path
-
-      def initialize(host, port, socket_path, logger)
-        @host = host || DEFAULT_HOST
-        @port = port || DEFAULT_PORT
-        @socket_path = socket_path
-        @logger = logger
-      end
-
-      def write(message)
-        @logger.debug { "Statsd: #{message}" } if @logger
-        if @socket_path.nil?
-          socket.send(message, 0)
-        else
-          socket.sendmsg_nonblock(message)
-        end
-      rescue StandardError => boom
-        # Give up on this socket if it looks like it is bad
-        bad_socket = !@socket_path.nil? && (
-          boom.is_a?(Errno::ECONNREFUSED) ||
-          boom.is_a?(Errno::ECONNRESET) ||
-          boom.is_a?(Errno::ENOENT)
-        )
-        if bad_socket
-          @socket = nil
-          return
-        end
-
-        # Try once to reconnect if the socket has been closed
-        retries ||= 1
-        if retries <= 1 && boom.is_a?(IOError) && boom.message =~ /closed stream/i
-          retries += 1
-          begin
-            @socket = connect
-            retry
-          rescue StandardError => e
-            boom = e
-          end
-        end
-
-        @logger.error { "Statsd: #{boom.class} #{boom}" } if @logger
-        nil
-      end
-
-      # Close the underlying socket
-      def close
-        @socket && @socket.close
-      end
-
-      private
-
-      def socket
-        @socket ||= connect
-      end
-
-      def connect
-        if @socket_path.nil?
-          socket = UDPSocket.new
-          socket.connect(@host, @port)
-        else
-          socket = Socket.new(Socket::AF_UNIX, Socket::SOCK_DGRAM)
-          socket.connect(Socket.pack_sockaddr_un(@socket_path))
-        end
-        socket
-      end
-    end
-
-    class Batch
-      def initialize(connection, max_buffer_bytes)
-        @connection = connection
-        @max_buffer_bytes = max_buffer_bytes
-        @depth = 0
-        reset
-      end
-
-      def open
-        @depth += 1
-        yield
-      ensure
-        @depth -= 1
-        flush if !open?
-      end
-
-      def open?
-        @depth > 0
-      end
-
-      def add(message)
-        message_bytes = message.bytesize
-
-        unless @buffer_bytes == 0
-          if @buffer_bytes + 1 + message_bytes >= @max_buffer_bytes
-            flush
-          else
-            @buffer << NEW_LINE
-            @buffer_bytes += 1
-          end
-        end
-
-        @buffer << message
-        @buffer_bytes += message_bytes
-      end
-
-      def flush
-        return if @buffer_bytes == 0
-        @connection.write @buffer
-        reset
-      end
-
-      private
-
-      def reset
-        @buffer = String.new
-        @buffer_bytes = 0
-      end
-    end
-
     # 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
     OPTS_KEYS = {
-      :date_happened     => :d,
-      :hostname          => :h,
-      :aggregation_key   => :k,
-      :priority          => :p,
-      :source_type_name  => :s,
-      :alert_type        => :t,
-    }
+      date_happened:    :d,
+      hostname:         :h,
+      aggregation_key:  :k,
+      priority:         :p,
+      source_type_name: :s,
+      alert_type:       :t,
+    }.freeze
 
     # Service check options
     SC_OPT_KEYS = {
-      :timestamp  => 'd:'.freeze,
-      :hostname   => 'h:'.freeze,
-      :tags       => '#'.freeze,
-      :message    => 'm:'.freeze,
-    }
-
-    OK        = 0
-    WARNING   = 1
-    CRITICAL  = 2
-    UNKNOWN   = 3
-
-    MAX_EVENT_SIZE = 8 * 1024
-
-    COUNTER_TYPE = 'c'.freeze
-    GAUGE_TYPE = 'g'.freeze
-    HISTOGRAM_TYPE = 'h'.freeze
-    DISTRIBUTION_TYPE = 'd'.freeze
-    TIMING_TYPE = 'ms'.freeze
-    SET_TYPE = 's'.freeze
-    VERSION = "4.0.0".freeze
+      timestamp: 'd:',
+      hostname:  'h:',
+      tags:      '#',
+      message:   'm:',
+    }.freeze
+
+    OK       = 0
+    WARNING  = 1
+    CRITICAL = 2
+    UNKNOWN  = 3
+
+    DEFAULT_BUFFER_SIZE = 8 * 1_024
+    MAX_EVENT_SIZE = 8 * 1_024
+    # minimum flush interval for the telemetry in seconds
+    DEFAULT_TELEMETRY_FLUSH_INTERVAL = 10
+
+    COUNTER_TYPE = 'c'
+    GAUGE_TYPE = 'g'
+    HISTOGRAM_TYPE = 'h'
+    DISTRIBUTION_TYPE = 'd'
+    TIMING_TYPE = 'ms'
+    SET_TYPE = 's'
+    VERSION = '4.7.0'
 
     # A namespace to prepend to all statsd calls. Defaults to no namespace.
     attr_reader :namespace
@@ -194,41 +73,73 @@ module Datadog
     # Maximum buffer size in bytes before it is flushed
     attr_reader :max_buffer_bytes
 
+    # Default sample rate
+    attr_reader :sample_rate
+
     # Connection
     attr_reader :connection
 
     # @param [String] host your statsd host
     # @param [Integer] port your statsd port
     # @option [String] namespace set a namespace to be prepended to every metric name
-    # @option [Array<String>] tags tags to be added to every metric
-    # @option [Loger] logger for debugging
+    # @option [Array<String>|Hash] tags tags to be added to every metric
+    # @option [Logger] logger for debugging
     # @option [Integer] max_buffer_bytes max bytes to buffer when using #batch
     # @option [String] socket_path unix socket path
+    # @option [Float] default sample rate if not overridden
     def initialize(
       host = nil,
       port = nil,
       namespace: nil,
       tags: nil,
-      max_buffer_bytes: 8192,
+      max_buffer_bytes: DEFAULT_BUFFER_SIZE,
       socket_path: nil,
-      logger: nil
+      logger: nil,
+      sample_rate: nil,
+      disable_telemetry: false,
+      telemetry_flush_interval: DEFAULT_TELEMETRY_FLUSH_INTERVAL
     )
-      @connection = Connection.new(host, port, socket_path, logger)
+      unless tags.nil? || tags.is_a?(Array) || tags.is_a?(Hash)
+        raise ArgumentError, 'tags must be a Array<String> or a Hash'
+      end
+
+      tags = tag_hash_to_array(tags) if tags.is_a?(Hash)
+      @tags = (tags || []).compact.map! do |tag|
+        escape_tag_content(tag)
+      end
+
+      # append the entity id to tags if DD_ENTITY_ID env var is not nil
+      unless ENV.fetch('DD_ENTITY_ID', nil).nil?
+        dd_entity = escape_tag_content(ENV.fetch('DD_ENTITY_ID', nil))
+        @tags << 'dd.internal.entity_id:' + dd_entity
+      end
+
+      # init telemetry
+      transport_type = socket_path.nil? ? 'udp': 'uds'
+      telemetry_tags = (["client:ruby", "client_version:#{VERSION}", "client_transport:#{transport_type}"] + @tags).join(COMMA).freeze
+      @telemetry = Telemetry.new(disable_telemetry, telemetry_tags, telemetry_flush_interval)
+
+      if socket_path.nil?
+        @connection = UDPConnection.new(host, port, logger, @telemetry)
+      else
+        @connection = UDSConnection.new(socket_path, logger, @telemetry)
+      end
       @logger = logger
 
       @namespace = namespace
       @prefix = @namespace ? "#{@namespace}.".freeze : nil
 
-      raise ArgumentError, 'tags must be a Array<String>' unless tags.nil? or tags.is_a? Array
-      @tags = (tags || []).compact.map! {|tag| escape_tag_content(tag)}
+      @sample_rate = sample_rate
 
-      @batch = Batch.new @connection, max_buffer_bytes
+      # we reduce max_buffer_bytes by a the rough estimate of the telemetry payload
+      @batch = Batch.new(@connection, (max_buffer_bytes - @telemetry.estimate_max_size))
     end
 
     # 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
     def self.open(*args)
       instance = new(*args)
+
       yield instance
     ensure
       instance.close
@@ -242,10 +153,10 @@ module Datadog
     # @option opts [Array<String>] :tags An array of tags
     # @option opts [Numeric] :by increment value, default 1
     # @see #count
-    def increment(stat, opts=EMPTY_OPTIONS)
-      opts = {:sample_rate => opts} if opts.is_a? Numeric
+    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
+      count(stat, incr_value, opts)
     end
 
     # Sends a decrement (count = -1) for the given stat to the statsd server.
@@ -256,10 +167,10 @@ module Datadog
     # @option opts [Array<String>] :tags An array of tags
     # @option opts [Numeric] :by decrement value, default 1
     # @see #count
-    def decrement(stat, opts=EMPTY_OPTIONS)
-      opts = {:sample_rate => opts} if opts.is_a? Numeric
+    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
+      count(stat, decr_value, opts)
     end
 
     # Sends an arbitrary count for the given stat to the statsd server.
@@ -269,9 +180,9 @@ module Datadog
     # @param [Hash] opts the options to create the metric with
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
     # @option opts [Array<String>] :tags An array of tags
-    def count(stat, count, opts=EMPTY_OPTIONS)
-      opts = {:sample_rate => opts} if opts.is_a? Numeric
-      send_stats stat, count, COUNTER_TYPE, opts
+    def count(stat, count, opts = EMPTY_OPTIONS)
+      opts = { sample_rate: opts } if opts.is_a?(Numeric)
+      send_stats(stat, count, COUNTER_TYPE, opts)
     end
 
     # Sends an arbitary gauge value for the given stat to the statsd server.
@@ -287,9 +198,9 @@ module Datadog
     # @option opts [Array<String>] :tags An array of tags
     # @example Report the current user count:
     #   $statsd.gauge('user.count', User.count)
-    def gauge(stat, value, opts=EMPTY_OPTIONS)
-      opts = {:sample_rate => opts} if opts.is_a? Numeric
-      send_stats stat, value, GAUGE_TYPE, opts
+    def gauge(stat, value, opts = EMPTY_OPTIONS)
+      opts = { sample_rate: opts } if opts.is_a?(Numeric)
+      send_stats(stat, value, GAUGE_TYPE, opts)
     end
 
     # Sends a value to be tracked as a histogram to the statsd server.
@@ -301,14 +212,11 @@ module Datadog
     # @option opts [Array<String>] :tags An array of tags
     # @example Report the current user count:
     #   $statsd.histogram('user.count', User.count)
-    def histogram(stat, value, opts=EMPTY_OPTIONS)
-      send_stats stat, value, HISTOGRAM_TYPE, opts
+    def histogram(stat, value, opts = EMPTY_OPTIONS)
+      send_stats(stat, value, HISTOGRAM_TYPE, opts)
     end
 
     # Sends a value to be tracked as a distribution to the statsd server.
-    # Note: Distributions are a beta feature of Datadog and not generally
-    # available. Distributions must be specifically enabled for your
-    # organization.
     #
     # @param [String] stat stat name.
     # @param [Numeric] value distribution value.
@@ -317,8 +225,8 @@ module Datadog
     # @option opts [Array<String>] :tags An array of tags
     # @example Report the current user count:
     #   $statsd.distribution('user.count', User.count)
-    def distribution(stat, value, opts=EMPTY_OPTIONS)
-      send_stats stat, value, DISTRIBUTION_TYPE, opts
+    def distribution(stat, value, opts = EMPTY_OPTIONS)
+      send_stats(stat, value, DISTRIBUTION_TYPE, opts)
     end
 
     # Sends a timing (in ms) for the given stat to the statsd server. The
@@ -331,9 +239,9 @@ module Datadog
     # @param [Hash] opts the options to create the metric with
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
     # @option opts [Array<String>] :tags An array of tags
-    def timing(stat, ms, opts=EMPTY_OPTIONS)
-      opts = {:sample_rate => opts} if opts.is_a? Numeric
-      send_stats stat, ms, TIMING_TYPE, opts
+    def timing(stat, ms, opts = EMPTY_OPTIONS)
+      opts = { sample_rate: opts } if opts.is_a?(Numeric)
+      send_stats(stat, ms, TIMING_TYPE, opts)
     end
 
     # Reports execution time of the provided block using {#timing}.
@@ -349,12 +257,21 @@ module Datadog
     # @see #timing
     # @example Report the time (in ms) taken to activate an account
     #   $statsd.time('account.activate') { @account.activate! }
-    def time(stat, opts=EMPTY_OPTIONS)
-      opts = {:sample_rate => opts} if opts.is_a? Numeric
-      start = (PROCESS_TIME_SUPPORTED ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : Time.now.to_f)
-      return yield
+    def time(stat, opts = EMPTY_OPTIONS)
+      opts = { sample_rate: opts } if opts.is_a?(Numeric)
+      start = if PROCESS_TIME_SUPPORTED
+                Process.clock_gettime(Process::CLOCK_MONOTONIC) # uncovered
+              else
+                Time.now.to_f # uncovered
+              end
+      yield
     ensure
-      finished = (PROCESS_TIME_SUPPORTED ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : Time.now.to_f)
+      finished =  if PROCESS_TIME_SUPPORTED
+                    Process.clock_gettime(Process::CLOCK_MONOTONIC) # uncovered
+                  else
+                    Time.now.to_f # uncovered
+                  end
+
       timing(stat, ((finished - start) * 1000).round, opts)
     end
 
@@ -367,9 +284,9 @@ module Datadog
     # @option opts [Array<String>] :tags An array of tags
     # @example Record a unique visitory by id:
     #   $statsd.set('visitors.uniques', User.id)
-    def set(stat, value, opts=EMPTY_OPTIONS)
-      opts = {:sample_rate => opts} if opts.is_a? Numeric
-      send_stats stat, value, SET_TYPE, opts
+    def set(stat, value, opts = EMPTY_OPTIONS)
+      opts = { sample_rate: opts } if opts.is_a?(Numeric)
+      send_stats(stat, value, SET_TYPE, opts)
     end
 
     # This method allows you to send custom service check statuses.
@@ -377,14 +294,15 @@ module Datadog
     # @param [String] name Service check name
     # @param [String] status Service check status.
     # @param [Hash] opts the additional data about the service check
-      # @option opts [Integer, nil] :timestamp (nil) Assign a timestamp to the event. Default is now when none
-      # @option opts [String, nil] :hostname (nil) Assign a hostname to the event.
+      # @option opts [Integer, String, nil] :timestamp (nil) Assign a timestamp to the service check. Default is now when none
+      # @option opts [String, nil] :hostname (nil) Assign a hostname to the service check.
       # @option opts [Array<String>, nil] :tags (nil) An array of tags
       # @option opts [String, nil] :message (nil) A message to associate with this service check status
     # @example Report a critical service check status
     #   $statsd.service_check('my.service.check', Statsd::CRITICAL, :tags=>['urgent'])
-    def service_check(name, status, opts=EMPTY_OPTIONS)
-      send_stat format_service_check(name, status, opts)
+    def service_check(name, status, opts = EMPTY_OPTIONS)
+      @telemetry.service_checks += 1
+      send_stat(format_service_check(name, status, opts))
     end
 
     # This end point allows you to post events to the stream. You can tag them, set priority and even aggregate them with other events.
@@ -394,9 +312,9 @@ module Datadog
     # it will be grouped with other events that don't have an event type.
     #
     # @param [String] title Event title
-    # @param [String] text Event text. Supports \n
+    # @param [String] text Event text. Supports newlines (+\n+)
     # @param [Hash] opts the additional data about the event
-    # @option opts [Integer, nil] :date_happened (nil) Assign a timestamp to the event. Default is now when none
+    # @option opts [Integer, String, nil] :date_happened (nil) Assign a timestamp to the event. Default is now when none
     # @option opts [String, nil] :hostname (nil) Assign a hostname to the event.
     # @option opts [String, nil] :aggregation_key (nil) Assign an aggregation key to the event, to group it with some others
     # @option opts [String, nil] :priority ('normal') Can be "normal" or "low"
@@ -405,8 +323,9 @@ module Datadog
     # @option opts [Array<String>] :tags tags to be added to every metric
     # @example 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'])
-    def event(title, text, opts=EMPTY_OPTIONS)
-      send_stat format_event(title, text, opts)
+    def event(title, text, opts = EMPTY_OPTIONS)
+      @telemetry.events += 1
+      send_stat(format_event(title, text, opts))
     end
 
     # Send several metrics in the same UDP Packet
@@ -418,7 +337,9 @@ module Datadog
     #      s.increment('page.views')
     #    end
     def batch
-      @batch.open { yield self }
+      @batch.open do
+        yield self
+      end
     end
 
     # Close the underlying socket
@@ -428,20 +349,20 @@ module Datadog
 
     private
 
-    NEW_LINE = "\n".freeze
-    ESC_NEW_LINE = "\\n".freeze
-    COMMA = ",".freeze
-    PIPE = "|".freeze
-    DOT = ".".freeze
-    DOUBLE_COLON = "::".freeze
-    UNDERSCORE = "_".freeze
-    PROCESS_TIME_SUPPORTED = (RUBY_VERSION >= "2.1.0")
+    NEW_LINE = "\n"
+    ESC_NEW_LINE = '\n'
+    COMMA = ','
+    PIPE = '|'
+    DOT = '.'
+    DOUBLE_COLON = '::'
+    UNDERSCORE = '_'
+    PROCESS_TIME_SUPPORTED = (RUBY_VERSION >= '2.1.0')
     EMPTY_OPTIONS = {}.freeze
 
     private_constant :NEW_LINE, :ESC_NEW_LINE, :COMMA, :PIPE, :DOT,
       :DOUBLE_COLON, :UNDERSCORE, :EMPTY_OPTIONS
 
-    def format_service_check(name, status, opts=EMPTY_OPTIONS)
+    def format_service_check(name, status, opts = EMPTY_OPTIONS)
       sc_string = "_sc|#{name}|#{status}".dup
 
       SC_OPT_KEYS.each do |key, shorthand_key|
@@ -456,23 +377,34 @@ module Datadog
           escaped_message = escape_service_check_message(message)
           sc_string << "|m:#{escaped_message}"
         else
-          value = remove_pipes(opts[key])
+          if key == :timestamp && opts[key].is_a?(Integer)
+            value = opts[key]
+          else
+            value = remove_pipes(opts[key])
+          end
           sc_string << "|#{shorthand_key}#{value}"
         end
       end
       sc_string
     end
 
-    def format_event(title, text, opts=EMPTY_OPTIONS)
+    def format_event(title, text, opts = EMPTY_OPTIONS)
       escaped_title = escape_event_content(title)
       escaped_text = escape_event_content(text)
-      event_string_data = "_e{#{escaped_title.length},#{escaped_text.length}}:#{escaped_title}|#{escaped_text}".dup
+      event_string_data = "_e{#{escaped_title.bytesize},#{escaped_text.bytesize}}:#{escaped_title}|#{escaped_text}".dup
 
       # 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 |key, shorthand_key|
         if key != :tags && opts[key]
-          value = remove_pipes(opts[key])
+          # :date_happened is the only key where the value is an Integer
+          # To not break backwards compatibility, we still accept a String
+          if key == :date_happened && opts[key].is_a?(Integer)
+              value = opts[key]
+          # All other keys only have String values
+          else
+              value = remove_pipes(opts[key])
+          end
           event_string_data << "|#{shorthand_key}:#{value}"
         end
       end
@@ -482,13 +414,18 @@ module Datadog
         event_string_data << "|##{tags_string}"
       end
 
-      raise "Event #{title} payload is too big (more that 8KB), event discarded" if event_string_data.length > MAX_EVENT_SIZE
+      if event_string_data.bytesize > MAX_EVENT_SIZE
+        raise "Event #{title} payload is too big (more that 8KB), event discarded"
+      end
       event_string_data
     end
 
     def tags_as_string(opts)
       if tag_arr = opts[:tags]
-        tag_arr = tag_arr.map { |tag| escape_tag_content(tag) }
+        tag_arr = tag_hash_to_array(tag_arr) if tag_arr.is_a?(Hash)
+        tag_arr = tag_arr.map do |tag|
+          escape_tag_content(tag)
+        end
         tag_arr = tags + tag_arr # @tags are normalized when set, so not need to normalize them again
       else
         tag_arr = tags
@@ -496,63 +433,65 @@ module Datadog
       tag_arr.join(COMMA) unless tag_arr.empty?
     end
 
-    def escape_event_content(msg)
-      msg.gsub NEW_LINE, ESC_NEW_LINE
+    def tag_hash_to_array(tag_hash)
+      tag_hash.to_a.map do |pair|
+        pair.compact.join(':')
+      end
+    end
+
+    def escape_event_content(message)
+      message.gsub(NEW_LINE, ESC_NEW_LINE)
     end
 
     def escape_tag_content(tag)
       tag = remove_pipes(tag.to_s)
-      tag.delete! COMMA
+      tag.delete!(COMMA)
       tag
     end
 
-    def remove_pipes(msg)
-      msg.delete PIPE
+    def remove_pipes(message)
+      message.delete(PIPE)
     end
 
-    def escape_service_check_message(msg)
-      escape_event_content(msg).gsub('m:'.freeze, 'm\:'.freeze)
+    def escape_service_check_message(message)
+      escape_event_content(message).gsub('m:', 'm\:')
     end
 
-    def send_stats(stat, delta, type, opts=EMPTY_OPTIONS)
-      sample_rate = opts[:sample_rate] || 1
-      if sample_rate == 1 or rand < sample_rate
+    def send_stats(stat, delta, type, opts = EMPTY_OPTIONS)
+      @telemetry.metrics += 1
+      sample_rate = opts[:sample_rate] || @sample_rate || 1
+      if sample_rate == 1 || rand <= sample_rate
         full_stat = ''.dup
         full_stat << @prefix if @prefix
 
         stat = stat.is_a?(String) ? stat.dup : stat.to_s
         # Replace Ruby module scoping with '.' and reserved chars (: | @) with underscores.
         stat.gsub!(DOUBLE_COLON, DOT)
-        stat.tr!(':|@'.freeze, UNDERSCORE)
+        stat.tr!(':|@', UNDERSCORE)
         full_stat << stat
 
-        full_stat << ':'.freeze
+        full_stat << ':'
         full_stat << delta.to_s
         full_stat << PIPE
         full_stat << type
 
         unless sample_rate == 1
           full_stat << PIPE
-          full_stat << '@'.freeze
+          full_stat << '@'
           full_stat << sample_rate.to_s
         end
 
         if tags_string = tags_as_string(opts)
           full_stat << PIPE
-          full_stat << '#'.freeze
+          full_stat << '#'
           full_stat << tags_string
         end
-
         send_stat(full_stat)
       end
     end
 
     def send_stat(message)
-      if @batch.open?
-        @batch.add message
-      else
-        @connection.write(message)
-      end
+      @batch.open? ? @batch.add(message) : @connection.write(message)
     end
   end
 end

data/lib/datadog/statsd/batch.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Datadog
+  class Statsd
+    class Batch
+      def initialize(connection, max_buffer_bytes)
+        @connection = connection
+        @max_buffer_bytes = max_buffer_bytes
+        @depth = 0
+        reset
+      end
+
+      def open
+        @depth += 1
+
+        yield
+      ensure
+        @depth -= 1
+        flush if !open?
+      end
+
+      def open?
+        @depth > 0
+      end
+
+      def add(message)
+        message_bytes = message.bytesize
+
+        unless @buffer_bytes == 0
+          if @buffer_bytes + 1 + message_bytes >= @max_buffer_bytes
+            flush
+          else
+            @buffer << NEW_LINE
+            @buffer_bytes += 1
+          end
+        end
+
+        @buffer << message
+        @buffer_bytes += message_bytes
+      end
+
+      def flush
+        return if @buffer_bytes == 0
+        @connection.write(@buffer)
+        reset
+      end
+
+      private
+
+      def reset
+        @buffer = String.new
+        @buffer_bytes = 0
+      end
+    end
+  end
+end

data/lib/datadog/statsd/connection.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Datadog
+  class Statsd
+    class Connection
+      def initialize(telemetry)
+        @telemetry = telemetry
+      end
+
+      # Close the underlying socket
+      def close
+        @socket && @socket.close
+      end
+
+      def write(payload)
+        logger.debug { "Statsd: #{payload}" } if logger
+        flush_telemetry = @telemetry.flush?
+        if flush_telemetry
+          payload += @telemetry.flush()
+        end
+
+        send_message(payload)
+
+        if flush_telemetry
+          @telemetry.reset
+        end
+
+        telemetry.bytes_sent += payload.length
+        telemetry.packets_sent += 1
+      rescue StandardError => boom
+        # Try once to reconnect if the socket has been closed
+        retries ||= 1
+        if retries <= 1 &&
+          (boom.is_a?(Errno::ENOTCONN) or
+           boom.is_a?(Errno::ECONNREFUSED) or
+           boom.is_a?(IOError) && boom.message =~ /closed stream/i)
+          retries += 1
+          begin
+            @socket = connect
+            retry
+          rescue StandardError => e
+            boom = e
+          end
+        end
+
+        telemetry.bytes_dropped += payload.length
+        telemetry.packets_dropped += 1
+        logger.error { "Statsd: #{boom.class} #{boom}" } if logger
+        nil
+      end
+
+      private
+
+      attr_reader :telemetry
+      attr_reader :logger
+
+      def socket
+        @socket ||= connect
+      end
+    end
+  end
+end

data/lib/datadog/statsd/telemetry.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+require 'time'
+
+module Datadog
+  class Statsd
+    class Telemetry
+      attr_accessor :metrics
+      attr_accessor :events
+      attr_accessor :service_checks
+      attr_accessor :bytes_sent
+      attr_accessor :bytes_dropped
+      attr_accessor :packets_sent
+      attr_accessor :packets_dropped
+      attr_reader   :estimate_max_size
+
+      def initialize(disabled, tags, flush_interval)
+        @disabled = disabled
+        @tags = tags
+        @flush_interval = flush_interval
+        reset
+
+        # estimate_max_size is an estimation or the maximum size of the
+        # telemetry payload. Since we don't want our packet to go over
+        # 'max_buffer_bytes', we have to adjust with the size of the telemetry
+        # (and any tags used). The telemetry payload size will change depending
+        # on the actual value of metrics: metrics received, packet dropped,
+        # etc. This is why we add a 63bytes margin: 9 bytes for each of the 7
+        # telemetry metrics.
+        @estimate_max_size = @disabled ? 0 : flush().length + 9 * 7
+      end
+
+      def reset
+        @metrics = 0
+        @events = 0
+        @service_checks = 0
+        @bytes_sent = 0
+        @bytes_dropped = 0
+        @packets_sent = 0
+        @packets_dropped = 0
+        @next_flush_time = Time.now.to_i + @flush_interval
+      end
+
+      def flush?
+        if @next_flush_time < Time.now.to_i
+          return true
+        end
+        return false
+      end
+
+      def flush
+        return '' if @disabled
+
+        # using shorthand syntax to reduce the garbage collection
+        return %Q(
+datadog.dogstatsd.client.metrics:#{@metrics}|#{COUNTER_TYPE}|##{@tags}
+datadog.dogstatsd.client.events:#{@events}|#{COUNTER_TYPE}|##{@tags}
+datadog.dogstatsd.client.service_checks:#{@service_checks}|#{COUNTER_TYPE}|##{@tags}
+datadog.dogstatsd.client.bytes_sent:#{@bytes_sent}|#{COUNTER_TYPE}|##{@tags}
+datadog.dogstatsd.client.bytes_dropped:#{@bytes_dropped}|#{COUNTER_TYPE}|##{@tags}
+datadog.dogstatsd.client.packets_sent:#{@packets_sent}|#{COUNTER_TYPE}|##{@tags}
+datadog.dogstatsd.client.packets_dropped:#{@packets_dropped}|#{COUNTER_TYPE}|##{@tags})
+      end
+    end
+  end
+end

data/lib/datadog/statsd/udp_connection.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'connection'
+
+module Datadog
+  class Statsd
+    class UDPConnection < Connection
+      DEFAULT_HOST = '127.0.0.1'
+      DEFAULT_PORT = 8125
+
+      # StatsD host. Defaults to 127.0.0.1.
+      attr_reader :host
+
+      # StatsD port. Defaults to 8125.
+      attr_reader :port
+
+      def initialize(host, port, logger, telemetry)
+        super(telemetry)
+        @host = host || ENV.fetch('DD_AGENT_HOST', DEFAULT_HOST)
+        @port = port || ENV.fetch('DD_DOGSTATSD_PORT', DEFAULT_PORT)
+        @logger = logger
+      end
+
+      private
+
+      def connect
+        UDPSocket.new.tap do |socket|
+          socket.connect(host, port)
+        end
+      end
+
+      def send_message(message)
+        socket.send(message, 0)
+      end
+    end
+  end
+end

data/lib/datadog/statsd/uds_connection.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'connection'
+
+module Datadog
+  class Statsd
+    class UDSConnection < Connection
+      class BadSocketError < StandardError; end
+
+      # DogStatsd unix socket path
+      attr_reader :socket_path
+
+      def initialize(socket_path, logger, telemetry)
+        super(telemetry)
+        @socket_path = socket_path
+        @logger = logger
+      end
+
+      private
+
+      def connect
+        socket = Socket.new(Socket::AF_UNIX, Socket::SOCK_DGRAM)
+        socket.connect(Socket.pack_sockaddr_un(@socket_path))
+        socket
+      end
+
+      def send_message(message)
+        socket.sendmsg_nonblock(message)
+      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ENOENT => e
+        @socket = nil
+        raise BadSocketError, "#{e.class}: #{e}"
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dogstatsd-ruby
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.7.0
 platform: ruby
 authors:
 - Rein Henrichs
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-20 00:00:00.000000000 Z
+date: 2020-02-14 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby DogStastd client
 email: code@datadoghq.com
@@ -21,10 +21,19 @@ files:
 - LICENSE.txt
 - README.md
 - lib/datadog/statsd.rb
-homepage: http://github.com/datadog/dogstatsd-ruby
+- lib/datadog/statsd/batch.rb
+- lib/datadog/statsd/connection.rb
+- lib/datadog/statsd/telemetry.rb
+- lib/datadog/statsd/udp_connection.rb
+- lib/datadog/statsd/uds_connection.rb
+homepage: https://github.com/DataDog/dogstatsd-ruby
 licenses:
 - MIT
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/DataDog/dogstatsd-ruby/issues
+  changelog_uri: https://github.com/DataDog/dogstatsd-ruby/blob/v4.7.0/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/dogstatsd-ruby/4.7.0
+  source_code_uri: https://github.com/DataDog/dogstatsd-ruby/tree/v4.7.0
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -41,7 +50,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 2.7.10
 signing_key: 
 specification_version: 4
 summary: A Ruby DogStatsd client