statsd-instrument 3.9.9 → 3.10.0

data/test/compiled_metric_test.rb

@@ -0,0 +1,447 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class CompiledMetricDefinitionTest < Minitest::Test
+  def setup
+    super
+    @old_client = StatsD.singleton_client
+    @sink = StatsD::Instrument::CaptureSink.new(parent: StatsD::Instrument::NullSink.new)
+    StatsD.singleton_client = StatsD::Instrument::Client.new(
+      sink: @sink,
+      prefix: "test",
+      default_tags: [],
+      enable_aggregation: false,
+    )
+  end
+
+  def teardown
+    super
+    @sink.clear
+    StatsD.singleton_client = @old_client
+  end
+
+  def test_sanitizes_tag_names
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        static_tags: { "tag|with|pipes" => "value", "tag,with,commas" => "value2" },
+      )
+    end
+
+    metric.increment(1)
+
+    datagram = @sink.datagrams.first
+    # Pipes and commas should be removed from tag names
+    assert(datagram.tags[0], "tag_with_pipes:value")
+    assert(datagram.tags[1], "tag_with_commas:value2")
+  end
+
+  def test_sanitizes_tag_values_in_static_tags
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        static_tags: { service: "web|api" },
+      )
+    end
+
+    metric.increment(1)
+
+    datagram = @sink.datagrams.first
+    # Pipes should be removed from tag values
+    assert_equal(["service:webapi"], datagram.tags)
+  end
+
+  def test_sanitizes_dynamic_string_tag_values
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        tags: { endpoint: String },
+      )
+    end
+
+    metric.increment(1, endpoint: "/api|v1,endpoint")
+
+    datagram = @sink.datagrams.first
+    # Pipes and commas should be removed
+    assert_equal(["endpoint:/apiv1endpoint"], datagram.tags)
+  end
+
+  def test_normalizes_metric_name
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo:bar|baz@qux",
+      )
+    end
+    metric.increment(1)
+
+    datagram = @sink.datagrams.first
+    # Special characters should be converted to underscores
+    assert_equal("test.foo_bar_baz_qux", datagram.name)
+  end
+
+  def test_raises_on_unsupported_tag_type
+    assert_raises(ArgumentError) do
+      Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+        define(
+          name: "foo.bar",
+          tags: { invalid: Array },
+        )
+      end
+    end
+  end
+
+  def test_sample_rate_parameter
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        static_tags: { service: "web" },
+
+        sample_rate: 0.5,
+      )
+    end
+
+    metric.increment(1)
+
+    assert_equal(1, @sink.datagrams.size)
+    assert_equal(0.5, @sink.datagrams.first.sample_rate)
+  end
+
+  def test_default_sample_rate_from_client
+    # Create a client with default sample rate
+    client = StatsD::Instrument::Client.new(
+      sink: @sink,
+      prefix: "test",
+      default_tags: [],
+      enable_aggregation: false,
+      default_sample_rate: 0.6,
+    )
+    StatsD.singleton_client = client
+
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+      )
+    end
+    metric.increment(1)
+    assert_equal(1, @sink.datagrams.size)
+    assert_equal(0.6, @sink.datagrams.first.sample_rate)
+  end
+
+  def test_sample_rate_default_to_1
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        static_tags: { service: "web" },
+      )
+    end
+
+    metric.increment(5)
+
+    assert_equal(1, @sink.datagrams.size)
+    assert_equal(1.0, @sink.datagrams.first.sample_rate)
+  end
+
+  def test_sample_rate_omitted_when_1
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        sample_rate: 1.0,
+      )
+    end
+
+    # With sample rate = 1.0, it should be omitted from the datagram
+    metric.increment(3)
+
+    assert_equal(1, @sink.datagrams.size)
+    datagram = @sink.datagrams.first
+    # Sample rate defaults to 1.0 when not present in datagram
+    assert_equal(1.0, datagram.sample_rate)
+    # Verify the source doesn't contain |@1.0
+    refute_includes(datagram.source, "|@")
+  end
+
+  def test_normalizes_symbol_tag_values
+    # Test with tag value that's a symbol (should hit the else clause)
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        tags: { status: String },
+      )
+    end
+
+    # Pass a symbol as a tag value (not a common case but should be handled)
+    # This will be converted to string
+    metric.increment(1, status: :active)
+
+    datagram = @sink.datagrams.first
+    assert_equal(["status:active"], datagram.tags)
+  end
+
+  def test_supports_boolean_dynamic_tags
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        tags: { enabled: :Boolean },
+      )
+    end
+
+    metric.increment(1, enabled: true)
+    assert_equal(["enabled:true"], @sink.datagrams.first.tags)
+
+    @sink.clear
+
+    metric.increment(1, enabled: false)
+    assert_equal(["enabled:false"], @sink.datagrams.first.tags)
+  end
+
+  def test_supports_symbol_dynamic_tags
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        tags: { status: Symbol },
+      )
+    end
+
+    metric.increment(1, status: :active)
+    assert_equal(["status:active"], @sink.datagrams.first.tags)
+
+    @sink.clear
+
+    metric.increment(1, status: :inactive)
+    assert_equal(["status:inactive"], @sink.datagrams.first.tags)
+  end
+
+  def test_sanitizes_symbol_dynamic_tag_values
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        tags: { status: Symbol },
+      )
+    end
+
+    metric.increment(1, status: :"active|with,special")
+    assert_equal(["status:activewithspecial"], @sink.datagrams.first.tags)
+  end
+
+  def test_handles_nil_tag_values
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        tags: { shop_id: Integer, name: String, rate: Float },
+      )
+    end
+
+    metric.increment(1, shop_id: nil, name: nil, rate: nil)
+
+    assert_equal(1, @sink.datagrams.size)
+    assert_equal(["name:", "rate:", "shop_id:"], @sink.datagrams.first.tags.sort)
+  end
+
+  def test_emits_metric_when_cache_exceeded
+    # Create a metric with a very small cache size
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        tags: { shop_id: Integer },
+
+        max_cache_size: 2,
+      )
+    end
+
+    # Clear any existing datagrams
+    @sink.clear
+
+    # Fill the cache (2 entries)
+    metric.increment(1, shop_id: 1)
+    metric.increment(1, shop_id: 2)
+
+    # Third entry brings us to max_cache_size. it should trigger cache exceeded (cache.size = 3 >= 2)
+    metric.increment(1, shop_id: 3)
+
+    # Find the cache exceeded metric (includes prefix)
+    cache_exceeded_metric = @sink.datagrams.find do |datagram|
+      datagram.name == "test.statsd_instrument.compiled_metric.cache_exceeded_total"
+    end
+
+    assert_equal(4, @sink.datagrams.size)
+    refute_nil(cache_exceeded_metric, "Expected cache exceeded metric to be emitted")
+    assert_equal(1, cache_exceeded_metric.value)
+    assert_includes(cache_exceeded_metric.tags, "metric_name:foo.bar")
+    assert_includes(cache_exceeded_metric.tags, "max_size:2")
+  end
+
+  def test_emits_metric_on_hash_collision
+    # Create a metric with a single tag
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        tags: { shop_id: Integer },
+      )
+    end
+
+    # First call with shop_id=1 to populate cache
+    metric.increment(1, shop_id: 1)
+
+    cache = metric.instance_variable_get(:@tag_combination_cache)
+
+    # Compute cache keys using the rotate-left + XOR formula (32-bit bounded)
+    # For single tag, it's the hash value masked to 32 bits
+    cache_key_for_1 = 1.hash & 0xFFFFFFFF
+    cache_key_for_2 = 2.hash & 0xFFFFFFFF
+
+    # Store the cached datagram under the collision key
+    cached_datagram = cache[cache_key_for_1]
+    cache[cache_key_for_2] = cached_datagram
+
+    # Clear datagrams before the collision test
+    @sink.clear
+
+    # Now increment with the collision shop_id - this should detect the collision
+    # because the tag_values won't match
+    metric.increment(1, shop_id: 2)
+
+    # Find the hash collision metric (includes prefix)
+    hash_collision_metric = @sink.datagrams.find do |datagram|
+      datagram.name == "test.statsd_instrument.compiled_metric.hash_collision_detected"
+    end
+
+    refute_nil(hash_collision_metric, "Expected hash collision metric to be emitted")
+    assert_equal(1, hash_collision_metric.value)
+    # The metric name uses the normalized name (only : | @ are replaced, not .)
+    assert_includes(hash_collision_metric.tags, "metric_name:foo.bar")
+  end
+
+  def test_handles_default_tags_as_array
+    StatsD.singleton_client = StatsD::Instrument::Client.new(
+      sink: @sink,
+      prefix: "test",
+      default_tags: ["env:production", "region:us-east"],
+      enable_aggregation: false,
+    )
+
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        static_tags: { service: "web" },
+      )
+    end
+
+    metric.increment(1)
+
+    datagram = @sink.datagrams.first
+    assert_equal(["env:production", "region:us-east", "service:web"], datagram.tags.sort)
+  end
+
+  def test_handles_default_tags_as_hash
+    StatsD.singleton_client = StatsD::Instrument::Client.new(
+      sink: @sink,
+      prefix: "test",
+      default_tags: { env: "production", region: "us-east" },
+      enable_aggregation: false,
+    )
+
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        static_tags: { service: "web" },
+      )
+    end
+
+    metric.increment(1)
+
+    datagram = @sink.datagrams.first
+    assert_equal(["env:production", "region:us-east", "service:web"], datagram.tags.sort)
+  end
+
+  def test_handles_default_tags_as_string
+    StatsD.singleton_client = StatsD::Instrument::Client.new(
+      sink: @sink,
+      prefix: "test",
+      default_tags: "env:production",
+      enable_aggregation: false,
+    )
+
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        static_tags: { service: "web" },
+      )
+    end
+
+    metric.increment(1)
+
+    datagram = @sink.datagrams.first
+    assert_equal(["env:production", "service:web"], datagram.tags.sort)
+  end
+
+  def test_allows_value_as_tag_name
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        tags: { value: String, status: String },
+      )
+    end
+
+    metric.increment(1, value: "product", status: "active")
+
+    datagram = @sink.datagrams.first
+    assert_equal(["status:active", "value:product"], datagram.tags.sort)
+  end
+
+  def test_cache_key_is_order_dependent
+    # Verify that swapped tag values produce different cache entries
+    # This tests the fix for XOR-based cache keys which are commutative
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        tags: { tag_a: :Boolean, tag_b: :Boolean },
+      )
+    end
+
+    # Emit with (true, false)
+    metric.increment(1, tag_a: true, tag_b: false)
+
+    # Emit with (false, true) - swapped values
+    metric.increment(1, tag_a: false, tag_b: true)
+
+    # Both should be cached separately
+    cache = metric.instance_variable_get(:@tag_combination_cache)
+    assert_equal(2, cache.size, "Swapped tag values should produce different cache entries")
+
+    # Verify the datagrams have different tags
+    assert_equal(2, @sink.datagrams.size)
+    assert_equal(["tag_a:true", "tag_b:false"], @sink.datagrams[0].tags)
+    assert_equal(["tag_a:false", "tag_b:true"], @sink.datagrams[1].tags)
+  end
+
+  def test_sample_rate
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+        sample_rate: 0.1337,
+      )
+    end
+
+    assert_equal(0.1337, metric.sample_rate)
+  end
+
+  def test_sample_rate_with_define_without_sample_rate
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar.withouth_sample_rate",
+      )
+    end
+
+    assert_equal(StatsD.singleton_client.default_sample_rate, metric.sample_rate)
+  end
+
+  def test_sample_rate_without_define
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter)
+
+    error = assert_raises(ArgumentError) do
+      metric.sample_rate
+    end
+    assert_equal("Every CompiledMetric subclass needs to call `define` before accessing its sample_rate.", error.message)
+  end
+end

data/test/dispatcher_stats_test.rb

@@ -48,21 +48,21 @@ class DispatcherStatsTest < Minitest::Test
     end
     assert_equal(batches.length, stats.instance_variable_get(:@batched_sends))
     assert_equal(
-      batches.map { |b|
+      batches.map do |b|
         b[:buffer_len]
-      }.sum / batches.length,
+      end.sum / batches.length,
       stats.instance_variable_get(:@avg_buffer_length),
     )
     assert_equal(
-      batches.map { |b|
+      batches.map do |b|
         b[:packet_size]
-      }.sum / batches.length,
+      end.sum / batches.length,
       stats.instance_variable_get(:@avg_batched_packet_size),
     )
     assert_equal(
-      batches.map { |b|
+      batches.map do |b|
         b[:batch_len]
-      }.sum / batches.length,
+      end.sum / batches.length,
       stats.instance_variable_get(:@avg_batch_length),
     )
   end

data/test/integration_test.rb

@@ -103,4 +103,56 @@ class IntegrationTest < Minitest::Test
     assert_match(/counter:\d+|c/, packets.find { |packet| packet.start_with?("counter:") })
     assert_match(/test_distribution:\d+:3|d/, packets.find { |packet| packet.start_with?("test_distribution:") })
   end
+
+  def test_signal_trap_with_aggregation_fallback
+    skip("#{RUBY_ENGINE} not supported for this test. Reason: signal handling") if RUBY_ENGINE != "ruby"
+
+    client = StatsD::Instrument::Environment.new(
+      "STATSD_ADDR" => "#{@server.addr[2]}:#{@server.addr[1]}",
+      "STATSD_IMPLEMENTATION" => "dogstatsd",
+      "STATSD_ENV" => "production",
+      "STATSD_ENABLE_AGGREGATION" => "true",
+      "STATSD_AGGREGATION_INTERVAL" => "5.0",
+    ).client
+
+    signal_received = false
+
+    old_trap = Signal.trap("USR1") do
+      signal_received = true
+      # These should fall back to direct writes
+      client.increment("trap_metric", 5)
+      client.gauge("trap_gauge", 42)
+      client.distribution("trap_distribution", 100)
+    end
+
+    Process.kill("USR1", Process.pid)
+
+    sleep(0.1)
+
+    assert(signal_received, "Signal should have been received")
+
+    packets = []
+    while IO.select([@server], nil, nil, 0.1)
+      packet = @server.recvfrom(300).first
+      packets.concat(packet.split("\n"))
+    end
+
+    # When aggregation is disabled due to trap context, metrics might be batched
+    assert(packets.size >= 3, "Expected at least 3 metrics, got #{packets.size}: #{packets.inspect}")
+
+    assert(
+      packets.any? { |p| p == "trap_metric:5|c" },
+      "Expected counter metric, got: #{packets.inspect}",
+    )
+    assert(
+      packets.any? { |p| p == "trap_gauge:42|g" },
+      "Expected gauge metric, got: #{packets.inspect}",
+    )
+    assert(
+      packets.any? { |p| p == "trap_distribution:100|d" },
+      "Expected distribution metric, got: #{packets.inspect}",
+    )
+  ensure
+    Signal.trap("USR1", old_trap || "DEFAULT")
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statsd-instrument
 version: !ruby/object:Gem::Version
-  version: 3.9.9
+  version: 3.10.0
 platform: ruby
 authors:
 - Jesse Storimer
@@ -9,7 +9,7 @@ authors:
 - Willem van Bergen
 bindir: bin
 cert_chain: []
-date: 2025-01-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: A StatsD client for Ruby apps. Provides metaprogramming methods to inject
   StatsD instrumentation into your code.
@@ -49,6 +49,7 @@ files:
 - lib/statsd/instrument/batched_sink.rb
 - lib/statsd/instrument/capture_sink.rb
 - lib/statsd/instrument/client.rb
+- lib/statsd/instrument/compiled_metric.rb
 - lib/statsd/instrument/connection_behavior.rb
 - lib/statsd/instrument/datagram.rb
 - lib/statsd/instrument/datagram_builder.rb
@@ -86,6 +87,10 @@ files:
 - test/capture_sink_test.rb
 - test/changelog_test.rb
 - test/client_test.rb
+- test/compiled_metric/counter_test.rb
+- test/compiled_metric/distribution_test.rb
+- test/compiled_metric/gauge_test.rb
+- test/compiled_metric_test.rb
 - test/datagram_builder_test.rb
 - test/datagram_test.rb
 - test/dispatcher_stats_test.rb
@@ -130,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.8
 specification_version: 4
 summary: A StatsD client for Ruby apps
 test_files:
@@ -142,6 +147,10 @@ test_files:
 - test/capture_sink_test.rb
 - test/changelog_test.rb
 - test/client_test.rb
+- test/compiled_metric/counter_test.rb
+- test/compiled_metric/distribution_test.rb
+- test/compiled_metric/gauge_test.rb
+- test/compiled_metric_test.rb
 - test/datagram_builder_test.rb
 - test/datagram_test.rb
 - test/dispatcher_stats_test.rb