statsd-instrument 3.8.0 → 3.9.0

data/lib/statsd/instrument/aggregator.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module StatsD
+  module Instrument
+    class AggregationKey
+      attr_reader :name, :tags, :no_prefix, :type, :hash
+
+      def initialize(name, tags, no_prefix, type)
+        @name = name
+        @tags = tags
+        @no_prefix = no_prefix
+        @type = type
+        @hash = [@name, @tags, @no_prefix, @type].hash
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          @name == other.name &&
+          @tags == other.tags &&
+          @no_prefix == other.no_prefix &&
+          @type == other.type
+      end
+      alias_method :eql?, :==
+    end
+
+    class Aggregator
+      CONST_SAMPLE_RATE = 1.0
+      COUNT = :c
+      DISTRIBUTION = :d
+      MEASURE = :ms
+      HISTOGRAM = :h
+      GAUGE = :g
+
+      class << self
+        def finalize(aggregation_state, sink, datagram_builders, datagram_builder_class, default_tags)
+          proc do
+            aggregation_state.each do |key, agg_value|
+              no_prefix = key.no_prefix
+              datagram_builders[no_prefix] ||= datagram_builder_class.new(
+                prefix: no_prefix ? nil : @metric_prefix,
+                default_tags: default_tags,
+              )
+              case key.type
+              when COUNT
+                sink << datagram_builders[no_prefix].c(
+                  key.name,
+                  agg_value,
+                  CONST_SAMPLE_RATE,
+                  key.tags,
+                )
+              when DISTRIBUTION, MEASURE, HISTOGRAM
+                sink << datagram_builders[no_prefix].timing_value_packed(
+                  key.name,
+                  key.type.to_s,
+                  agg_value,
+                  CONST_SAMPLE_RATE,
+                  key.tags,
+                )
+              when GAUGE
+                sink << datagram_builders[no_prefix].g(
+                  key.name,
+                  agg_value,
+                  CONST_SAMPLE_RATE,
+                  key.tags,
+                )
+              else
+                StatsD.logger.error { "[#{self.class.name}] Unknown aggregation type: #{key.type}" }
+              end
+            end
+            aggregation_state.clear
+          end
+        end
+      end
+
+      # @param sink [#<<] The sink to write the aggregated metrics to.
+      # @param datagram_builder_class [Class] The class to use for building datagrams.
+      # @param prefix [String] The prefix to add to all metrics.
+      # @param default_tags [Array<String>] The tags to add to all metrics.
+      # @param flush_interval [Float] The interval at which to flush the aggregated metrics.
+      # @param max_values [Integer] The maximum number of values to aggregate before flushing.
+      def initialize(sink, datagram_builder_class, prefix, default_tags, flush_interval: 5.0, max_values: 100)
+        @sink = sink
+        @datagram_builder_class = datagram_builder_class
+        @metric_prefix = prefix
+        @default_tags = default_tags
+        @datagram_builders = {
+          true: nil,
+          false: nil,
+        }
+        @max_values = max_values
+
+        # Mutex protects the aggregation_state and flush_thread from concurrent access
+        @mutex = Mutex.new
+        @aggregation_state = {}
+
+        @pid = Process.pid
+        @flush_interval = flush_interval
+        @flush_thread = Thread.new do
+          Thread.current.abort_on_exception = true
+          loop do
+            sleep(@flush_interval)
+            thread_healthcheck
+            flush
+          rescue => e
+            StatsD.logger.error { "[#{self.class.name}] Error in flush thread: #{e}" }
+            raise e
+          end
+        end
+
+        ObjectSpace.define_finalizer(
+          self,
+          self.class.finalize(@aggregation_state, @sink, @datagram_builders, @datagram_builder_class, @default_tags),
+        )
+      end
+
+      # Increment a counter by a given value and save it for later flushing.
+      # @param name [String] The name of the counter.
+      # @param value [Integer] The value to increment the counter by.
+      # @param tags [Hash{String, Symbol => String},Array<String>] The tags to attach to the counter.
+      # @param no_prefix [Boolean] If true, the metric will not be prefixed.
+      # @return [void]
+      def increment(name, value = 1, tags: [], no_prefix: false)
+        unless thread_healthcheck
+          sink << datagram_builder(no_prefix: no_prefix).c(name, value, CONST_SAMPLE_RATE, tags)
+          return
+        end
+
+        tags = tags_sorted(tags)
+        key = packet_key(name, tags, no_prefix, COUNT)
+
+        @mutex.synchronize do
+          @aggregation_state[key] ||= 0
+          @aggregation_state[key] += value
+        end
+      end
+
+      def aggregate_timing(name, value, tags: [], no_prefix: false, type: DISTRIBUTION)
+        unless thread_healthcheck
+          sink << datagram_builder(no_prefix: no_prefix).timing_value_packed(
+            name, type, [value], CONST_SAMPLE_RATE, tags
+          )
+          return
+        end
+
+        tags = tags_sorted(tags)
+        key = packet_key(name, tags, no_prefix, type)
+
+        @mutex.synchronize do
+          values = @aggregation_state[key] ||= []
+          if values.size + 1 >= @max_values
+            do_flush
+          end
+          values << value
+        end
+      end
+
+      def gauge(name, value, tags: [], no_prefix: false)
+        unless thread_healthcheck
+          sink << datagram_builder(no_prefix: no_prefix).g(name, value, CONST_SAMPLE_RATE, tags)
+          return
+        end
+
+        tags = tags_sorted(tags)
+        key = packet_key(name, tags, no_prefix, GAUGE)
+
+        @mutex.synchronize do
+          @aggregation_state[key] = value
+        end
+      end
+
+      def flush
+        @mutex.synchronize { do_flush }
+      end
+
+      private
+
+      EMPTY_ARRAY = [].freeze
+
+      def do_flush
+        @aggregation_state.each do |key, value|
+          case key.type
+          when COUNT
+            @sink << datagram_builder(no_prefix: key.no_prefix).c(
+              key.name,
+              value,
+              CONST_SAMPLE_RATE,
+              key.tags,
+            )
+          when DISTRIBUTION, MEASURE, HISTOGRAM
+            @sink << datagram_builder(no_prefix: key.no_prefix).timing_value_packed(
+              key.name,
+              key.type.to_s,
+              value,
+              CONST_SAMPLE_RATE,
+              key.tags,
+            )
+          when GAUGE
+            @sink << datagram_builder(no_prefix: key.no_prefix).g(
+              key.name,
+              value,
+              CONST_SAMPLE_RATE,
+              key.tags,
+            )
+          else
+            StatsD.logger.error { "[#{self.class.name}] Unknown aggregation type: #{key.type}" }
+          end
+        end
+        @aggregation_state.clear
+      end
+
+      def tags_sorted(tags)
+        return "" if tags.nil? || tags.empty?
+
+        if tags.is_a?(Hash)
+          tags = tags.sort_by { |k, _v| k.to_s }.map! { |k, v| "#{k}:#{v}" }
+        else
+          tags.sort!
+        end
+        datagram_builder(no_prefix: false).normalize_tags(tags)
+      end
+
+      def packet_key(name, tags = "".b, no_prefix = false, type = COUNT)
+        AggregationKey.new(DatagramBuilder.normalize_string(name), tags, no_prefix, type).freeze
+      end
+
+      def datagram_builder(no_prefix:)
+        @datagram_builders[no_prefix] ||= @datagram_builder_class.new(
+          prefix: no_prefix ? nil : @metric_prefix,
+          default_tags: @default_tags,
+        )
+      end
+
+      def thread_healthcheck
+        @mutex.synchronize do
+          unless @flush_thread&.alive?
+            return false unless Thread.main.alive?
+
+            if @pid != Process.pid
+              StatsD.logger.info { "[#{self.class.name}] Restarting the flush thread after fork" }
+              @pid = Process.pid
+              @aggregation_state.clear
+            else
+              StatsD.logger.info { "[#{self.class.name}] Restarting the flush thread" }
+            end
+            @flush_thread = Thread.new do
+              Thread.current.abort_on_exception = true
+              loop do
+                sleep(@flush_interval)
+                thread_healthcheck
+                flush
+              end
+            end
+          end
+          true
+        end
+      end
+    end
+  end
+end

data/lib/statsd/instrument/{batched_udp_sink.rb → batched_sink.rb}

@@ -1,22 +1,30 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 module StatsD
   module Instrument
-    # @note This class is part of the new Client implementation that is intended
-    #   to become the new default in the next major release of this library.
-    class BatchedUDPSink
+    class BatchedSink
+      extend Forwardable
+
+      def_delegator :@sink, :host
+      def_delegator :@sink, :port
+
       DEFAULT_THREAD_PRIORITY = 100
       DEFAULT_BUFFER_CAPACITY = 5_000
       # https://docs.datadoghq.com/developers/dogstatsd/high_throughput/?code-lang=ruby#ensure-proper-packet-sizes
       DEFAULT_MAX_PACKET_SIZE = 1472
       DEFAULT_STATISTICS_INTERVAL = 0 # in seconds, and 0 implies disabled-by-default.
 
-      attr_reader :host, :port
-
       class << self
         def for_addr(addr, **kwargs)
-          host, port_as_string = addr.split(":", 2)
-          new(host, Integer(port_as_string), **kwargs)
+          if addr.include?(":")
+            sink = StatsD::Instrument::Sink.for_addr(addr)
+            new(sink, **kwargs)
+          else
+            connection = UdsConnection.new(addr)
+            new(connection, **kwargs)
+          end
         end
 
         def finalize(dispatcher)
@@ -25,18 +33,15 @@ module StatsD
       end
 
       def initialize(
-        host,
-        port,
+        sink,
         thread_priority: DEFAULT_THREAD_PRIORITY,
         buffer_capacity: DEFAULT_BUFFER_CAPACITY,
         max_packet_size: DEFAULT_MAX_PACKET_SIZE,
         statistics_interval: DEFAULT_STATISTICS_INTERVAL
       )
-        @host = host
-        @port = port
+        @sink = sink
         @dispatcher = Dispatcher.new(
-          host,
-          port,
+          @sink,
           buffer_capacity,
           thread_priority,
           max_packet_size,
@@ -62,6 +67,10 @@ module StatsD
         @dispatcher.flush(blocking: blocking)
       end
 
+      def connection
+        @sink.connection
+      end
+
       class Buffer < SizedQueue
         def push_nonblock(item)
           push(item, true)
@@ -81,7 +90,7 @@ module StatsD
       end
 
       class DispatcherStats
-        def initialize(interval)
+        def initialize(interval, type)
           # The number of times the batched udp sender needed to
           # send a statsd line synchronously, due to the buffer
           # being full.
@@ -98,6 +107,12 @@ module StatsD
           # The average number of statsd lines per batch.
           @avg_batch_length = 0
 
+          @sync_sends_metric = "statsd_instrument.batched_#{type}_sink.synchronous_sends"
+          @batched_sends_metric = "statsd_instrument.batched_#{type}_sink.batched_sends"
+          @avg_buffer_length_metric = "statsd_instrument.batched_#{type}_sink.avg_buffer_length"
+          @avg_batched_packet_size_metric = "statsd_instrument.batched_#{type}_sink.avg_batched_packet_size"
+          @avg_batch_length_metric = "statsd_instrument.batched_#{type}_sink.avg_batch_length"
+
           @mutex = Mutex.new
 
           @interval = interval
@@ -121,11 +136,11 @@ module StatsD
             @since = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           end
 
-          StatsD.increment("statsd_instrument.batched_udp_sink.synchronous_sends", synchronous_sends)
-          StatsD.increment("statsd_instrument.batched_udp_sink.batched_sends", batched_sends)
-          StatsD.gauge("statsd_instrument.batched_udp_sink.avg_buffer_length", avg_buffer_length)
-          StatsD.gauge("statsd_instrument.batched_udp_sink.avg_batched_packet_size", avg_batched_packet_size)
-          StatsD.gauge("statsd_instrument.batched_udp_sink.avg_batch_length", avg_batch_length)
+          StatsD.increment(@sync_sends_metric, synchronous_sends)
+          StatsD.increment(@batched_sends_metric, batched_sends)
+          StatsD.gauge(@avg_buffer_length_metric, avg_buffer_length)
+          StatsD.gauge(@avg_batched_packet_size_metric, avg_batched_packet_size)
+          StatsD.gauge(@avg_batch_length_metric, avg_batch_length)
         end
 
         def increment_synchronous_sends
@@ -143,8 +158,8 @@ module StatsD
       end
 
       class Dispatcher
-        def initialize(host, port, buffer_capacity, thread_priority, max_packet_size, statistics_interval)
-          @udp_sink = UDPSink.new(host, port)
+        def initialize(sink, buffer_capacity, thread_priority, max_packet_size, statistics_interval)
+          @sink = sink
           @interrupted = false
           @thread_priority = thread_priority
           @max_packet_size = max_packet_size
@@ -153,7 +168,8 @@ module StatsD
           @dispatcher_thread = Thread.new { dispatch }
           @pid = Process.pid
           if statistics_interval > 0
-            @statistics = DispatcherStats.new(statistics_interval)
+            type = @sink.connection.type
+            @statistics = DispatcherStats.new(statistics_interval, type)
           end
         end
 
@@ -161,7 +177,7 @@ module StatsD
           if !thread_healthcheck || !@buffer.push_nonblock(datagram)
             # The buffer is full or the thread can't be respawned,
             # we'll send the datagram synchronously
-            @udp_sink << datagram
+            @sink << datagram
 
             @statistics&.increment_synchronous_sends
           end
@@ -206,7 +222,7 @@ module StatsD
             end
 
             packet_size = packet.bytesize
-            @udp_sink << packet
+            @sink << packet
             packet.clear
 
             @statistics&.increment_batched_sends(buffer_len, packet_size, batch_len)

data/lib/statsd/instrument/client.rb

@@ -40,6 +40,8 @@ module StatsD
             implementation: implementation,
             sink: sink,
             datagram_builder_class: datagram_builder_class,
+            enable_aggregation: env.experimental_aggregation_enabled?,
+            aggregation_flush_interval: env.aggregation_interval,
           )
         end
 
@@ -82,7 +84,7 @@ module StatsD
       # Generally, you should use an instance of one of the following classes that
       # ship with this library:
       #
-      # - {StatsD::Instrument::UDPSink} A sink that will actually emit the provided
+      # - {StatsD::Instrument::Sink} A sink that will actually emit the provided
       #   datagrams over UDP.
       # - {StatsD::Instrument::NullSink} A sink that will simply swallow every
       #   datagram. This sink is for use when testing your application.
@@ -152,7 +154,9 @@ module StatsD
         default_tags: nil,
         implementation: "datadog",
         sink: StatsD::Instrument::NullSink.new,
-        datagram_builder_class: self.class.datagram_builder_class_for_implementation(implementation)
+        datagram_builder_class: self.class.datagram_builder_class_for_implementation(implementation),
+        enable_aggregation: false,
+        aggregation_flush_interval: 2.0
       )
         @sink = sink
         @datagram_builder_class = datagram_builder_class
@@ -162,6 +166,18 @@ module StatsD
         @default_sample_rate = default_sample_rate
 
         @datagram_builder = { false => nil, true => nil }
+        @enable_aggregation = enable_aggregation
+        @aggregation_flush_interval = aggregation_flush_interval
+        if @enable_aggregation
+          @aggregator =
+            Aggregator.new(
+              @sink,
+              datagram_builder_class,
+              prefix,
+              default_tags,
+              flush_interval: @aggregation_flush_interval,
+            )
+        end
       end
 
       # @!group Metric Methods
@@ -201,6 +217,12 @@ module StatsD
       # @return [void]
       def increment(name, value = 1, sample_rate: nil, tags: nil, no_prefix: false)
         sample_rate ||= @default_sample_rate
+
+        if @enable_aggregation
+          @aggregator.increment(name, value, tags: tags, no_prefix: no_prefix)
+          return StatsD::Instrument::VOID
+        end
+
         if sample_rate.nil? || sample?(sample_rate)
           emit(datagram_builder(no_prefix: no_prefix).c(name, value, sample_rate, tags))
         end
@@ -219,6 +241,10 @@ module StatsD
           return latency(name, sample_rate: sample_rate, tags: tags, metric_type: :ms, no_prefix: no_prefix, &block)
         end
 
+        if @enable_aggregation
+          @aggregator.aggregate_timing(name, value, tags: tags, no_prefix: no_prefix, type: :ms)
+          return StatsD::Instrument::VOID
+        end
         sample_rate ||= @default_sample_rate
         if sample_rate.nil? || sample?(sample_rate)
           emit(datagram_builder(no_prefix: no_prefix).ms(name, value, sample_rate, tags))
@@ -240,6 +266,11 @@ module StatsD
       # @param tags (see #increment)
       # @return [void]
       def gauge(name, value, sample_rate: nil, tags: nil, no_prefix: false)
+        if @enable_aggregation
+          @aggregator.gauge(name, value, tags: tags, no_prefix: no_prefix)
+          return StatsD::Instrument::VOID
+        end
+
         sample_rate ||= @default_sample_rate
         if sample_rate.nil? || sample?(sample_rate)
           emit(datagram_builder(no_prefix: no_prefix).g(name, value, sample_rate, tags))
@@ -279,6 +310,11 @@ module StatsD
           return latency(name, sample_rate: sample_rate, tags: tags, metric_type: :d, no_prefix: no_prefix, &block)
         end
 
+        if @enable_aggregation
+          @aggregator.aggregate_timing(name, value, tags: tags, no_prefix: no_prefix, type: :d)
+          return StatsD::Instrument::VOID
+        end
+
         sample_rate ||= @default_sample_rate
         if sample_rate.nil? || sample?(sample_rate)
           emit(datagram_builder(no_prefix: no_prefix).d(name, value, sample_rate, tags))
@@ -298,6 +334,10 @@ module StatsD
       # @param tags (see #increment)
       # @return [void]
       def histogram(name, value, sample_rate: nil, tags: nil, no_prefix: false)
+        if @enable_aggregation
+          @aggregator.aggregate_timing(name, value, tags: tags, no_prefix: no_prefix, type: :h)
+        end
+
         sample_rate ||= @default_sample_rate
         if sample_rate.nil? || sample?(sample_rate)
           emit(datagram_builder(no_prefix: no_prefix).h(name, value, sample_rate, tags))
@@ -324,11 +364,15 @@ module StatsD
         ensure
           stop = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
 
-          sample_rate ||= @default_sample_rate
-          if sample_rate.nil? || sample?(sample_rate)
-            metric_type ||= datagram_builder(no_prefix: no_prefix).latency_metric_type
-            latency_in_ms = stop - start
-            emit(datagram_builder(no_prefix: no_prefix).send(metric_type, name, latency_in_ms, sample_rate, tags))
+          metric_type ||= datagram_builder(no_prefix: no_prefix).latency_metric_type
+          latency_in_ms = stop - start
+          if @enable_aggregation
+            @aggregator.aggregate_timing(name, latency_in_ms, tags: tags, no_prefix: no_prefix, type: metric_type)
+          else
+            sample_rate ||= @default_sample_rate
+            if sample_rate.nil? || sample?(sample_rate)
+              emit(datagram_builder(no_prefix: no_prefix).send(metric_type, name, latency_in_ms, sample_rate, tags))
+            end
           end
         end
       end
@@ -386,6 +430,18 @@ module StatsD
         ))
       end
 
+      # Forces the client to flush all metrics that are currently buffered, first flushes the aggregation
+      # if enabled.
+      #
+      # @return [void]
+      def force_flush
+        if @enable_aggregation
+          @aggregator.flush
+        end
+        @sink.flush(blocking: false)
+        StatsD::Instrument::VOID
+      end
+
       NO_CHANGE = Object.new
 
       # Instantiates a new StatsD client that uses the settings of the current client,
@@ -427,6 +483,8 @@ module StatsD
           default_tags: default_tags == NO_CHANGE ? @default_tags : default_tags,
           datagram_builder_class:
             datagram_builder_class == NO_CHANGE ? @datagram_builder_class : datagram_builder_class,
+          enable_aggregation: @enable_aggregation,
+          aggregation_flush_interval: @aggregation_flush_interval,
         )
       end
 

data/lib/statsd/instrument/datagram.rb

@@ -31,7 +31,11 @@ module StatsD
         when :c
           Integer(parsed_datagram[:value])
         when :g, :h, :d, :kv, :ms
-          Float(parsed_datagram[:value])
+          if parsed_datagram[:value].include?(":")
+            parsed_datagram[:value].split(":").map { |v| Float(v) }
+          else
+            Float(parsed_datagram[:value])
+          end
         when :s
           String(parsed_datagram[:value])
         else
@@ -68,7 +72,7 @@ module StatsD
 
       PARSER = %r{
         \A
-        (?<name>[^\:\|\@]+)\:(?<value>[^\:\|\@]+)\|(?<type>c|ms|g|s|h|d)
+        (?<name>[^\:\|\@]+)\:(?<value>(?:[^\:\|\@]+:)*[^\:\|\@]+)\|(?<type>c|ms|g|s|h|d)
         (?:\|\@(?<sample_rate>\d*(?:\.\d*)?))?
         (?:\|\#(?<tags>(?:[^\|,]+(?:,[^\|,]+)*)))?
         \n? # In some implementations, the datagram may include a trailing newline.

data/lib/statsd/instrument/datagram_builder.rb

@@ -5,6 +5,7 @@ module StatsD
     # @note This class is part of the new Client implementation that is intended
     #   to become the new default in the next major release of this library.
     class DatagramBuilder
+      extend Forwardable
       class << self
         def unsupported_datagram_types(*types)
           types.each do |type|
@@ -17,6 +18,11 @@ module StatsD
         def datagram_class
           StatsD::Instrument::Datagram
         end
+
+        def normalize_string(string)
+          string = string.tr("|#", "_") if /[|#]/.match?(string)
+          string
+        end
       end
 
       def initialize(prefix: nil, default_tags: nil)
@@ -48,6 +54,12 @@ module StatsD
         generate_generic_datagram(name, value, "d", sample_rate, tags)
       end
 
+      def timing_value_packed(name, type, values, sample_rate, tags)
+        # here values is an array
+        values = values.join(":")
+        generate_generic_datagram(name, values, type, sample_rate, tags)
+      end
+
       def kv(name, value, sample_rate, tags)
         generate_generic_datagram(name, value, "kv", sample_rate, tags)
       end
@@ -56,6 +68,10 @@ module StatsD
         :ms
       end
 
+      def normalize_tags(tags, buffer = "".b)
+        compile_tags(tags, buffer)
+      end
+
       protected
 
       # Utility function to remove invalid characters from a StatsD metric name
@@ -88,6 +104,11 @@ module StatsD
       end
 
       def compile_tags(tags, buffer = "".b)
+        if tags.is_a?(String)
+          tags = self.class.normalize_string(tags) if /[|,]/.match?(tags)
+          buffer << tags
+          return buffer
+        end
         if tags.is_a?(Hash)
           first = true
           tags.each do |key, value|