statsd-instrument 3.11.2 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51853f9d4b70fc39649e251e7e93ff3d77b2bcca1d776182f82de8219ea86886
-  data.tar.gz: fce22a816682f0bc25510b6a68248a64c93ba983e7640b57ec01dbb0b985c9d2
+  metadata.gz: c7184b3fb0852d7afea02fa71a292812ef26b491eb94ab2427f603b49f01202c
+  data.tar.gz: e40e7aa3d4cb034467b6d59fdfdb3bcbf55a2901e82c48368fd1e904d0aa67c5
 SHA512:
-  metadata.gz: 4a06bd60427001260e206243f4db74ecb3d8225c1c5e3f8f9764239bc40901457cf621d7f5fbd0936d39fa0765145499672a9fb0a9c22025ac8611f7051f7154
-  data.tar.gz: f74279e49141844c564d896e1d04b88b6b9f66585e56401a4ee52f7f4cb8dcc5fbe6a99b8427fbfa45ca1be843fef5a8c9357fb629129372880ac5020aceab31
+  metadata.gz: e1d01801fcbedc88df3e57bf948e6a4b599b52365e80d55e66ced52d4b308427632d5dc8161614705a7524e9a7f1b56e85e717ef9e3f0509969091b801ec30c2
+  data.tar.gz: 97bf3cf218ef6be51d72dc96f067464cc8f21eb0b070be9e48d7097cc4863735f41a58a3ed6967829524b6df64af1d8a1122197fec46944ce8154dcf539a4721

data/CHANGELOG.md

@@ -6,6 +6,14 @@ section below.
 
 ## Unreleased changes
 
+## Version 4.0.1
+
+- Normalize ASCII whitespace in metric names and prefixes, and newlines (`\n` and `\r`) in tags and set values, including aggregated and compiled metrics.
+
+## Version 4.0.0
+
+- Make the internal aggregator interface positional-only and injectable through `Client`, with fixed-arity `increment`, `gauge`, and `aggregate_timing` entrypoints for native aggregation backends. Public Client metric methods retain their keyword API.
+
 ## Version 3.11.2
 
 - Widen the `CompiledMetric` tag-combination cache key from 32 to 57 bits, eliminating

data/README.md

@@ -114,6 +114,11 @@ Please note that since aggregation is an experimental feature, it should be used
 ## StatsD keys
 
 StatsD keys look like 'admin.logins.api.success'. Dots are used as namespace separators.
+Metric names and prefixes normalize `:`, `|`, `@`, and ASCII whitespace (spaces,
+tabs, and line breaks) to `_`, one underscore per character.
+Newlines (`\n`, `\r`) in set values are also replaced with `_`; in array/hash tags,
+newlines are removed alongside `|` and `,`. Other tag/value whitespace is preserved.
+Normalization is silent.
 
 ## Usage
 

data/lib/statsd/instrument/aggregator.rb

@@ -148,7 +148,7 @@ module StatsD
       # @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, sample_rate: CONST_SAMPLE_RATE)
+      def increment(name, value, tags, no_prefix, sample_rate)
         unless thread_healthcheck
           @sink << datagram_builder(no_prefix: no_prefix).c(name, value, sample_rate, tags)
           return
@@ -224,7 +224,7 @@ module StatsD
         end
       end
 
-      def aggregate_timing(name, value, tags: [], no_prefix: false, type: DISTRIBUTION, sample_rate: CONST_SAMPLE_RATE)
+      def aggregate_timing(name, value, tags, no_prefix, type, sample_rate)
         unless thread_healthcheck
           @sink << datagram_builder(no_prefix: no_prefix).timing_value_packed(
             name, type.to_s, [value], sample_rate, tags
@@ -249,7 +249,7 @@ module StatsD
         do_flush(aggregation_state) if aggregation_state
       end
 
-      def gauge(name, value, tags: [], no_prefix: false)
+      def gauge(name, value, tags, no_prefix)
         unless thread_healthcheck
           @sink << datagram_builder(no_prefix: no_prefix).g(name, value, CONST_SAMPLE_RATE, tags)
           return

data/lib/statsd/instrument/client.rb

@@ -19,6 +19,9 @@ module StatsD
     # @see StatsD.singleton_client
     # @see #clone_with_options
     class Client
+      EMPTY_TAGS = [].freeze
+      private_constant :EMPTY_TAGS
+
       class << self
         # Instantiates a StatsD::Instrument::Client using configuration values provided in
         # environment variables.
@@ -31,7 +34,8 @@ module StatsD
           default_tags: env.statsd_default_tags,
           implementation: env.statsd_implementation,
           sink: env.default_sink_for_environment,
-          datagram_builder_class: datagram_builder_class_for_implementation(implementation)
+          datagram_builder_class: datagram_builder_class_for_implementation(implementation),
+          aggregator: nil
         )
           new(
             prefix: prefix,
@@ -42,6 +46,7 @@ module StatsD
             datagram_builder_class: datagram_builder_class,
             enable_aggregation: env.experimental_aggregation_enabled?,
             aggregation_flush_interval: env.aggregation_interval,
+            aggregator: aggregator,
           )
         end
 
@@ -147,6 +152,16 @@ module StatsD
       end
 
       # Instantiates a new client.
+      #
+      # Aggregators use fixed-arity positional +increment+, +gauge+, and
+      # +aggregate_timing+ methods. This keeps the aggregation hot path simple
+      # and avoids keyword argument forwarding. An injected aggregator is also
+      # expected to implement the existing precompiled aggregation methods and
+      # +flush+. Calls without tags receive a shared frozen empty array. Other tag
+      # values are forwarded as-is; custom backends may require arrays.
+      #
+      # @param aggregator [#increment, #gauge, #aggregate_timing, nil]
+      #   Optional external aggregation backend.
       # @see .from_env to instantiate a client using environment variables.
       def initialize(
         prefix: nil,
@@ -157,7 +172,8 @@ module StatsD
         datagram_builder_class: self.class.datagram_builder_class_for_implementation(implementation),
         enable_aggregation: false,
         aggregation_flush_interval: 2.0,
-        aggregation_max_context_size: StatsD::Instrument::Aggregator::DEFAULT_MAX_CONTEXT_SIZE
+        aggregation_max_context_size: StatsD::Instrument::Aggregator::DEFAULT_MAX_CONTEXT_SIZE,
+        aggregator: nil
       )
         @sink = sink
         @datagram_builder_class = datagram_builder_class
@@ -167,10 +183,11 @@ module StatsD
         @default_sample_rate = default_sample_rate
 
         @datagram_builder = { false => nil, true => nil }
-        @enable_aggregation = enable_aggregation
+        @injected_aggregator = aggregator
+        @enable_aggregation = enable_aggregation || !aggregator.nil?
         @aggregation_flush_interval = aggregation_flush_interval
         if @enable_aggregation
-          @aggregator =
+          @aggregator = aggregator ||
             Aggregator.new(
               @sink,
               datagram_builder_class,
@@ -196,8 +213,8 @@ module StatsD
       #
       #   - We recommend using `snake_case.metric_names` as naming scheme.
       #   - A `.` should be used for namespacing, e.g. `foo.bar.baz`
-      #   - A metric name should not include the following characters: `|`, `@`, and `:`.
-      #     The library will convert these characters to `_`.
+      #   - A metric name should not include `|`, `@`, `:`, or ASCII whitespace.
+      #     The library converts each such character to `_`, including in prefixes.
       #
       # @param value [Integer] (default: 1) The value to increment the counter by.
       #
@@ -223,7 +240,7 @@ module StatsD
         return StatsD::Instrument::VOID if sample_rate && !sample?(sample_rate)
 
         if @enable_aggregation
-          @aggregator.increment(name, value, tags: tags, no_prefix: no_prefix, sample_rate: sample_rate)
+          @aggregator.increment(name, value, tags || EMPTY_TAGS, no_prefix, sample_rate)
         else
           emit(datagram_builder(no_prefix: no_prefix).c(name, value, sample_rate, tags))
         end
@@ -357,7 +374,7 @@ module StatsD
         end
 
         if @enable_aggregation
-          @aggregator.aggregate_timing(name, value, tags: tags, no_prefix: no_prefix, type: :ms, sample_rate: sample_rate)
+          @aggregator.aggregate_timing(name, value, tags || EMPTY_TAGS, no_prefix, :ms, sample_rate)
           return StatsD::Instrument::VOID
         end
         emit(datagram_builder(no_prefix: no_prefix).ms(name, value, sample_rate, tags))
@@ -379,7 +396,7 @@ module StatsD
       # @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)
+          @aggregator.gauge(name, value, tags || EMPTY_TAGS, no_prefix)
           return StatsD::Instrument::VOID
         end
 
@@ -431,14 +448,7 @@ module StatsD
         end
 
         if @enable_aggregation
-          @aggregator.aggregate_timing(
-            name,
-            value,
-            tags: tags,
-            no_prefix: no_prefix,
-            type: :d,
-            sample_rate: sample_rate,
-          )
+          @aggregator.aggregate_timing(name, value, tags || EMPTY_TAGS, no_prefix, :d, sample_rate)
           return StatsD::Instrument::VOID
         end
 
@@ -467,7 +477,7 @@ module StatsD
         end
 
         if @enable_aggregation
-          @aggregator.aggregate_timing(name, value, tags: tags, no_prefix: no_prefix, type: :h, sample_rate: sample_rate)
+          @aggregator.aggregate_timing(name, value, tags || EMPTY_TAGS, no_prefix, :h, sample_rate)
           return StatsD::Instrument::VOID
         end
 
@@ -508,10 +518,10 @@ module StatsD
               @aggregator.aggregate_timing(
                 name,
                 latency_in_ms,
-                tags: tags,
-                no_prefix: no_prefix,
-                type: metric_type,
-                sample_rate: sample_rate,
+                tags || EMPTY_TAGS,
+                no_prefix,
+                metric_type,
+                sample_rate,
               )
             else
               emit(datagram_builder(no_prefix: no_prefix).send(metric_type, name, latency_in_ms, sample_rate, tags))
@@ -598,7 +608,8 @@ module StatsD
         prefix: NO_CHANGE,
         default_sample_rate: NO_CHANGE,
         default_tags: NO_CHANGE,
-        datagram_builder_class: NO_CHANGE
+        datagram_builder_class: NO_CHANGE,
+        aggregator: NO_CHANGE
       )
         client = clone_with_options(
           sink: sink,
@@ -606,6 +617,7 @@ module StatsD
           default_sample_rate: default_sample_rate,
           default_tags: default_tags,
           datagram_builder_class: datagram_builder_class,
+          aggregator: aggregator,
         )
 
         yield(client)
@@ -616,7 +628,8 @@ module StatsD
         prefix: NO_CHANGE,
         default_sample_rate: NO_CHANGE,
         default_tags: NO_CHANGE,
-        datagram_builder_class: NO_CHANGE
+        datagram_builder_class: NO_CHANGE,
+        aggregator: NO_CHANGE
       )
         self.class.new(
           sink: sink == NO_CHANGE ? @sink : sink,
@@ -627,6 +640,7 @@ module StatsD
             datagram_builder_class == NO_CHANGE ? @datagram_builder_class : datagram_builder_class,
           enable_aggregation: @enable_aggregation,
           aggregation_flush_interval: @aggregation_flush_interval,
+          aggregator: aggregator == NO_CHANGE ? @injected_aggregator : aggregator,
         )
       end
 

data/lib/statsd/instrument/compiled_metric.rb

@@ -70,7 +70,8 @@ module StatsD
           # Create a new class for this specific metric
           # Using classes instead of instances for better YJIT optimization
           metric_class = tap do
-            @name = DatagramBlueprintBuilder.normalize_name(name).freeze
+            # Own a frozen name without freezing a mutable string from the caller.
+            @name = -DatagramBlueprintBuilder.normalize_name(name)
             @datagram_blueprint = datagram_blueprint
             @tag_combination_cache = {}
             @max_cache_size = max_cache_size
@@ -300,9 +301,10 @@ module StatsD
 
           # Normalizes metric names by replacing special characters
           # @param name [String] The metric name
-          # @return [String] The normalized metric name
+          # @return [String] The original string if clean, otherwise a new string.
+          #   Does not copy or freeze clean input; retaining callers own that step.
           def normalize_name(name)
-            name.tr(":|@", "_")
+            Sanitization.name(name)
           end
 
           private
@@ -314,16 +316,14 @@ module StatsD
           def build_prefix(client_prefix, no_prefix)
             return "" if no_prefix || client_prefix.nil?
 
-            "#{client_prefix}."
+            "#{Sanitization.name(client_prefix.to_s)}."
           end
 
           # Normalizes tag names/values by removing StatsD protocol special characters
           # @param str [Symbol, String, Integer, Float] The string to normalize
           # @return [String] The normalized string
           def normalize_statsd_string(str)
-            str = str.to_s
-            str = str.tr("|,", "") if /[|,]/.match?(str)
-            str
+            Sanitization.tag(str.to_s)
           end
 
           # Compiles all tags (default_tags, static_tags, dynamic_tags) into a single string
@@ -412,10 +412,10 @@ module StatsD
           # Sanitize string and symbol values (other types handled by sprintf %s)
           values = @tag_values.map do |arg|
             if arg.is_a?(String)
-              /[|,]/.match?(arg) ? arg.tr("|,", "") : arg
+              Sanitization::TAG_PATTERN.match?(arg) ? arg.tr(Sanitization::TAG_CHARACTERS, "") : arg
             elsif arg.is_a?(Symbol)
               str = arg.to_s
-              /[|,]/.match?(str) ? str.tr("|,", "") : str
+              Sanitization::TAG_PATTERN.match?(str) ? str.tr(Sanitization::TAG_CHARACTERS, "") : str
             else
               arg
             end

data/lib/statsd/instrument/datagram.rb

@@ -72,9 +72,9 @@ module StatsD
 
       PARSER = %r{
         \A
-        (?<name>[^\:\|\@]+)\:(?<value>(?:[^\:\|\@]+:)*[^\:\|\@]+)\|(?<type>c|ms|g|s|h|d)
-        (?:\|\@(?<sample_rate>\d*(?:\.\d*)?))?
-        (?:\|\#(?<tags>(?:[^\|,]+(?:,[^\|,]+)*)))?
+        (?<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.
         \z
       }x.freeze

data/lib/statsd/instrument/datagram_builder.rb

@@ -20,13 +20,13 @@ module StatsD
         end
 
         def normalize_string(string)
-          string = string.tr("|#", "_") if /[|#]/.match?(string)
+          string = string.tr("|#\r\n", "_") if /[|#\r\n]/.match?(string)
           string
         end
       end
 
       def initialize(prefix: nil, default_tags: nil)
-        @prefix = prefix.nil? ? "" : "#{prefix}.".tr(":|@", "_")
+        @prefix = prefix.nil? ? "" : "#{Sanitization.name(prefix.to_s)}."
         @default_tags = default_tags.nil? || default_tags.empty? ? nil : compile_tags(default_tags, "|#".b)
       end
 
@@ -43,6 +43,8 @@ module StatsD
       end
 
       def s(name, value, sample_rate, tags)
+        value = value.to_s
+        value = value.tr("\r\n", "_") if /[\r\n]/.match?(value)
         generate_generic_datagram(name, value, "s", sample_rate, tags)
       end
 
@@ -76,16 +78,13 @@ module StatsD
 
       # Utility function to remove invalid characters from a StatsD metric name
       def normalize_name(name)
-        # Fast path when no normalization is needed to avoid copying the string
-        return name unless /[:|@]/.match?(name)
-
-        name.tr(":|@", "_")
+        Sanitization.name(name)
       end
 
       def generate_generic_datagram(name, value, type, sample_rate, tags)
         datagram = "".b <<
           @prefix <<
-          (/[:|@]/.match?(name) ? name.tr(":|@", "_") : name) <<
+          (Sanitization::NAME_PATTERN.match?(name) ? name.tr(Sanitization::NAME_CHARACTERS, "_") : name) <<
           ":" << value.to_s <<
           "|" << type
 
@@ -105,7 +104,8 @@ module StatsD
 
       def compile_tags(tags, buffer = "".b)
         if tags.is_a?(String)
-          tags = self.class.normalize_string(tags) if /[|,]/.match?(tags)
+          # String tags are already serialized: commas separate tags here.
+          tags = self.class.normalize_string(tags) if Sanitization::TAG_PATTERN.match?(tags)
           buffer << tags
           return buffer
         end
@@ -118,14 +118,14 @@ module StatsD
               buffer << ","
             end
             key = key.to_s
-            key = key.tr("|,", "") if /[|,]/.match?(key)
+            key = key.tr(Sanitization::TAG_CHARACTERS, "") if Sanitization::TAG_PATTERN.match?(key)
             value = value.to_s
-            value = value.tr("|,", "") if /[|,]/.match?(value)
+            value = value.tr(Sanitization::TAG_CHARACTERS, "") if Sanitization::TAG_PATTERN.match?(value)
             buffer << key << ":" << value
           end
         else
-          if tags.any? { |tag| /[|,]/.match?(tag) }
-            tags = tags.map { |tag| tag.tr("|,", "") }
+          if tags.any? { |tag| Sanitization::TAG_PATTERN.match?(tag) }
+            tags = tags.map { |tag| Sanitization.tag(tag) }
           end
           buffer << tags.join(",")
         end

data/lib/statsd/instrument/dogstatsd_datagram.rb

@@ -62,11 +62,11 @@ module StatsD
 
       SERVICE_CHECK_PARSER = %r{
         \A
-        (?<type>_sc)\|(?<name>[^\|]+)\|(?<value>\d+)
-        (?:\|h:(?<hostname>[^\|]+))?
+        (?<type>_sc)\|(?<name>[^|]+)\|(?<value>\d+)
+        (?:\|h:(?<hostname>[^|]+))?
         (?:\|d:(?<timestamp>\d+))?
-        (?:\|\#(?<tags>(?:[^\|,]+(?:,[^\|,]+)*)))?
-        (?:\|m:(?<message>[^\|]+))?
+        (?:\|\#(?<tags>(?:[^|,]+(?:,[^|,]+)*)))?
+        (?:\|m:(?<message>[^|]+))?
         \n? # In some implementations, the datagram may include a trailing newline.
         \z
       }x.freeze
@@ -74,14 +74,14 @@ module StatsD
       # |k:my-key|p:low|s:source|t:success|
       EVENT_PARSER = %r{
         \A
-        (?<type>_e)\{\d+\,\d+\}:(?<name>[^\|]+)\|(?<value>[^\|]+)
-        (?:\|h:(?<hostname>[^\|]+))?
+        (?<type>_e)\{\d+,\d+\}:(?<name>[^|]+)\|(?<value>[^|]+)
+        (?:\|h:(?<hostname>[^|]+))?
         (?:\|d:(?<timestamp>\d+))?
-        (?:\|k:(?<aggregation_key>[^\|]+))?
-        (?:\|p:(?<priority>[^\|]+))?
-        (?:\|s:(?<source_type_name>[^\|]+))?
-        (?:\|t:(?<alert_type>[^\|]+))?
-        (?:\|\#(?<tags>(?:[^\|,]+(?:,[^\|,]+)*)))?
+        (?:\|k:(?<aggregation_key>[^|]+))?
+        (?:\|p:(?<priority>[^|]+))?
+        (?:\|s:(?<source_type_name>[^|]+))?
+        (?:\|t:(?<alert_type>[^|]+))?
+        (?:\|\#(?<tags>(?:[^|,]+(?:,[^|,]+)*)))?
         \n? # In some implementations, the datagram may include a trailing newline.
         \z
       }x.freeze

data/lib/statsd/instrument/dogstatsd_datagram_builder.rb

@@ -84,7 +84,7 @@ module StatsD
           compile_tags(tags, datagram)
         end
 
-        datagram << "|m:#{normalize_name(message)}" if message
+        datagram << "|m:#{Sanitization.service_check_message(message)}" if message
         datagram
       end
 

data/lib/statsd/instrument/sanitization.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module StatsD
+  module Instrument
+    # Field-specific wire normalization. Clean strings are returned unchanged;
+    # callers retaining a frozen value must take ownership themselves.
+    # @api private
+    module Sanitization
+      # Hot serializers use these same rules inline to avoid per-field Ruby calls.
+      NAME_PATTERN = /[:|@\s]/.freeze
+      NAME_CHARACTERS = ":|@ \t\r\n\f\v"
+      TAG_PATTERN = /[|,\r\n]/.freeze
+      TAG_CHARACTERS = "|,\r\n"
+
+      class << self
+        # Replace each ASCII whitespace or protocol delimiter with one underscore.
+        # @return [String] The original string if clean, otherwise a new string.
+        def name(string)
+          NAME_PATTERN.match?(string) ? string.tr(NAME_CHARACTERS, "_") : string
+        end
+
+        # Tag components allow spaces and colons, but not field/tag separators.
+        def tag(string)
+          TAG_PATTERN.match?(string) ? string.tr(TAG_CHARACTERS, "") : string
+        end
+
+        # Keep message whitespace intact; this is not a metric name.
+        def service_check_message(string)
+          /[:|@\r\n]/.match?(string) ? string.tr(":|@\r\n", "_") : string
+        end
+      end
+    end
+  end
+end

data/lib/statsd/instrument/version.rb

@@ -2,6 +2,6 @@
 
 module StatsD
   module Instrument
-    VERSION = "3.11.2"
+    VERSION = "4.0.1"
   end
 end

data/lib/statsd/instrument.rb

@@ -391,6 +391,7 @@ require "statsd/instrument/client"
 require "statsd/instrument/datagram"
 require "statsd/instrument/aggregator"
 require "statsd/instrument/dogstatsd_datagram"
+require "statsd/instrument/sanitization"
 require "statsd/instrument/datagram_builder"
 require "statsd/instrument/statsd_datagram_builder"
 require "statsd/instrument/dogstatsd_datagram_builder"