dogstatsd-ruby 4.5.0 → 4.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fde2be6b614574c2555c8cbbd2ca16ef33bcd09837502f482f5f6baf582fd67b
-  data.tar.gz: cc1523c5aa78643d93fc891116c46bb5322dda297f1676cd73d201c9beee2a26
+  metadata.gz: 7d521571f811d6206670773db4ac3808c02513d8761445ecf917f831578e2614
+  data.tar.gz: 97d68494f8520a777569dc8f7b3c04070152aa0924edabc67ffa0ae1f16cb615
 SHA512:
-  metadata.gz: 9c96177f1ea0ab2288712cf9829cb8408687e12ce0f22f06ddbb1433447a3a4eaf05fe13f0fda8746b9f0e8fad71ea3b0b50ba7d8a028e464db334349951c64b
-  data.tar.gz: 11e23d434a7e88925e049484dfbb252d5c78ce12a4a07fd3c09edca57835db30224cba202f86f57352357acdf2073b8c8e93f20bd403975242b201321bef8ecc
+  metadata.gz: f43fb9314373873b5d436824a3cae0a5dc0ef4fcc2a458b8a98b98dbd8b12cb28d3b32293436451829a53da8cb70f17c6104aa64403cfb6000822e59a74ca29a
+  data.tar.gz: a796456e38da22047d952b7a1bebaf1f923a0847c29a9e7548020c8b658144e729133e7e90a16453d0f48a815353734523870e2e391371d8699f1d6574bd8379

data/README.md

@@ -1,86 +1,35 @@
+# dogstatsd-ruby
 
-dogstatsd-ruby
-==============
-
-A client for DogStatsD, an extension of the StatsD metric server for Datadog.
+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).
 
 [![Build Status](https://secure.travis-ci.org/DataDog/dogstatsd-ruby.svg)](http://travis-ci.org/DataDog/dogstatsd-ruby)
 
-Quick Start Guide
------------------
-
-First install the library:
-
-    gem install dogstatsd-ruby
-
-Then start instrumenting your code:
-
-``` ruby
-# Load the dogstats module.
-require 'datadog/statsd'
-
-# Create a stats 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
+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/).
 
-# Increment a counter.
-statsd.increment('page.views')
-statsd.increment('messages.count', by: 2, tags: ['kind:incoming'])
+## Installation
 
-# 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'])
-
-# Tag a metric by passing in a Hash
-statsd.histogram('query.time', 10, :tags => {version: 1})
+First install the library:
 
-# Auto-close socket after end of block
-Datadog::Statsd.open('localhost', 8125) do |s|
-  s.increment('page.views')
-end
+```
+gem install dogstatsd-ruby
 ```
 
-You can also post events to your stream. You can tag them, set priority and even aggregate them with other events.
+## Configuration
 
-Aggregation in the stream is made on hostname/event_type/source_type/aggregation_key.
+To instantiate a DogStatsd client:
 
-``` ruby
-# Post a simple message
-statsd.event('There might be a storm tomorrow', 'A friend warned me earlier.')
+```ruby
+# Import the library
+require 'datadog/statsd'
 
-# Cry for help
-statsd.event(
-  'SO MUCH SNOW',
-  "Started yesterday and it won't stop !!",
-  alert_type: 'error',
-  tags: ['urgent', 'endoftheworld']
-)
+# Create a DogStatsD client instance.
+statsd = Datadog::Statsd.new('localhost', 8125)
 ```
 
+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=go#client-instantiation-parameters).
 
+### Origin detection over UDP
 
-Origin detection over UDP
--------------
 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.
 
 To enable origin detection over UDP, add the following lines to your application manifest
@@ -93,27 +42,31 @@ env:
 ```
 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

@@ -20,6 +20,56 @@ require 'socket'
 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)
+        @disabled = disabled
+        @tags = tags
+        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
+      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
+
     class Connection
       DEFAULT_HOST = '127.0.0.1'
       DEFAULT_PORT = 8125
@@ -33,6 +83,10 @@ module Datadog
       # DogStatsd unix socket path. Not used by default.
       attr_reader :socket_path
 
+      def initialize(telemetry)
+        @telemetry = telemetry
+      end
+
       # Close the underlying socket
       def close
         @socket && @socket.close
@@ -40,7 +94,12 @@ module Datadog
 
       def write(message)
         @logger.debug { "Statsd: #{message}" } if @logger
-        send_message(message)
+        payload = message + @telemetry.flush()
+        send_message(payload)
+
+        @telemetry.reset
+        @telemetry.bytes_sent += payload.length
+        @telemetry.packets_sent += 1
       rescue StandardError => boom
         # Try once to reconnect if the socket has been closed
         retries ||= 1
@@ -57,6 +116,8 @@ module Datadog
           end
         end
 
+        @telemetry.bytes_dropped += payload.length
+        @telemetry.packets_dropped += 1
         @logger.error { "Statsd: #{boom.class} #{boom}" } if @logger
         nil
       end
@@ -69,7 +130,8 @@ module Datadog
     end
 
     class UDPConnection < Connection
-      def initialize(host, port, logger)
+      def initialize(host, port, logger, telemetry)
+        super(telemetry)
         @host = host || ENV.fetch('DD_AGENT_HOST', nil) || DEFAULT_HOST
         @port = port || ENV.fetch('DD_DOGSTATSD_PORT', nil) || DEFAULT_PORT
         @logger = logger
@@ -91,7 +153,8 @@ module Datadog
     class UDSConnection < Connection
       class BadSocketError < StandardError; end
 
-      def initialize(socket_path, logger)
+      def initialize(socket_path, logger, telemetry)
+        super(telemetry)
         @socket_path = socket_path
         @logger = logger
       end
@@ -186,7 +249,8 @@ module Datadog
     CRITICAL  = 2
     UNKNOWN   = 3
 
-    MAX_EVENT_SIZE = 8 * 1024
+    DEFAULT_BUFFER_SIZE = 8 * 1_024
+    MAX_EVENT_SIZE = 8 * 1_024
 
     COUNTER_TYPE = 'c'.freeze
     GAUGE_TYPE = 'g'.freeze
@@ -194,7 +258,7 @@ module Datadog
     DISTRIBUTION_TYPE = 'd'.freeze
     TIMING_TYPE = 'ms'.freeze
     SET_TYPE = 's'.freeze
-    VERSION = "4.5.0".freeze
+    VERSION = "4.6.0".freeze
 
     # A namespace to prepend to all statsd calls. Defaults to no namespace.
     attr_reader :namespace
@@ -227,23 +291,12 @@ module Datadog
       port = nil,
       namespace: nil,
       tags: nil,
-      max_buffer_bytes: 8192,
+      max_buffer_bytes: DEFAULT_BUFFER_SIZE,
       socket_path: nil,
       logger: nil,
-      sample_rate: nil
+      sample_rate: nil,
+      disable_telemetry: false
     )
-      if socket_path.nil?
-        @connection = UDPConnection.new(host, port, logger)
-      else
-        @connection = UDSConnection.new(socket_path, logger)
-      end
-      @logger = logger
-
-      @namespace = namespace
-      @prefix = @namespace ? "#{@namespace}.".freeze : nil
-
-      @sample_rate = sample_rate
-
       unless tags.nil? or tags.is_a? Array or tags.is_a? Hash
         raise ArgumentError, 'tags must be a Array<String> or a Hash'
       end
@@ -254,7 +307,25 @@ module Datadog
       # append the entity id to tags if DD_ENTITY_ID env var is not nil
       @tags << 'dd.internal.entity_id:' + escape_tag_content(ENV.fetch('DD_ENTITY_ID', nil)) unless ENV.fetch('DD_ENTITY_ID', nil).nil?
 
-      @batch = Batch.new @connection, max_buffer_bytes
+      # 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)
+
+      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
+
+      @sample_rate = sample_rate
+
+      # 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
@@ -338,9 +409,6 @@ module Datadog
     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.
@@ -416,6 +484,7 @@ module Datadog
     # @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)
+      @telemetry.service_checks += 1
       send_stat format_service_check(name, status, opts)
     end
 
@@ -438,6 +507,7 @@ module Datadog
     # @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)
+      @telemetry.events += 1
       send_stat format_event(title, text, opts)
     end
 
@@ -563,6 +633,7 @@ module Datadog
     end
 
     def send_stats(stat, delta, type, opts=EMPTY_OPTIONS)
+      @telemetry.metrics += 1
       sample_rate = opts[:sample_rate] || @sample_rate || 1
       if sample_rate == 1 or rand <= sample_rate
         full_stat = ''.dup
@@ -590,17 +661,12 @@ module Datadog
           full_stat << '#'.freeze
           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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dogstatsd-ruby
 version: !ruby/object:Gem::Version
-  version: 4.5.0
+  version: 4.6.0
 platform: ruby
 authors:
 - Rein Henrichs
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-08-22 00:00:00.000000000 Z
+date: 2020-01-20 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby DogStastd client
 email: code@datadoghq.com
@@ -21,10 +21,14 @@ files:
 - LICENSE.txt
 - README.md
 - lib/datadog/statsd.rb
-homepage: http://github.com/datadog/dogstatsd-ruby
+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.6.0/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/dogstatsd-ruby/4.6.0
+  source_code_uri: https://github.com/DataDog/dogstatsd-ruby/tree/v4.6.0
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -41,7 +45,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 2.7.10
 signing_key: 
 specification_version: 4
 summary: A Ruby DogStatsd client