statsd-instrument 3.10.0 → 3.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4768c067e6be6c254db4557916f0cfecb4b86cb318bc8c220acfaf67e9930029
-  data.tar.gz: 756ea941dc116e8c4ed95f1d6af1060ca1d524271b13cb5a418772fc7952519b
+  metadata.gz: 3da8fd9b1f80c7cf776c41d335ab14858dd625299bbec536c7f8994dfe93baf6
+  data.tar.gz: b1ca1c4049a5f3956ea510074027bb577d26ab8a2033cf96d4af5fcc39fc90c9
 SHA512:
-  metadata.gz: aab58b7242348378b11869da05bcf548c434b63a5f9155a904532b186e5a420e44891c30b1e551d0627359da05fad9c50414876d6eb57baba5883b7990f1d127
-  data.tar.gz: aece18a4af6ef4a14fbb437a91b3dcbd84b7a876a815210d3fb1e207b4851bc8803531589f1b985563da5a31e93e2724d1cc18d2d063742d7dc91ccbeb5abf60
+  metadata.gz: f8774b020de05ec35687a82aca947a19b095ea34867fdcd73518748c9ccddfe28e41cdc41c2dfe1b9c2e4f657b4416218d67fe3b0e259a8bf10a810580f8ea60
+  data.tar.gz: 420ea1eb853426b83d2d5f546dde091d402aaff31ef243b912df3869dd02882e8ef24bde4b124f860beccb0e9528dcfbcd7ab6b25b36b3d2fc3e02798fa209e1

data/CHANGELOG.md

@@ -6,6 +6,15 @@ section below.
 
 ## Unreleased changes
 
+## Version 3.11.1
+
+- Fix `CompiledMetric::Distribution` applying `sample_rate` twice.
+
+## Version 3.11.0
+
+- [#418](https://github.com/Shopify/statsd-instrument/pull/418) - Prevent misuse of `CompiledMetric` definitions by requiring a subclass when defining one.
+- [#417](https://github.com/Shopify/statsd-instrument/pull/417) - Add a `metric_name` method to `CompiledMetric`.
+
 ## Version 3.10.0
 
 - [#416](https://github.com/Shopify/statsd-instrument/pull/416) - Fix missing `metric_prefix` in Aggregator finalizer, causing metrics to lose their prefix when flushed during GC.

data/lib/statsd/instrument/client.rb

@@ -285,6 +285,25 @@ module StatsD
         StatsD::Instrument::VOID
       end
 
+      # Emits a pre-sampled compiled distribution metric.
+      # This method is used when the generated compiled metric method already made
+      # the sampling decision before measuring block latency.
+      #
+      # @param precompiled_datagram [StatsD::Instrument::CompiledMetric::PrecompiledDatagram]
+      #   The precompiled metric datagram
+      # @param value [Numeric] The metric value
+      # @return [void]
+      # @api private
+      def emit_presampled_precompiled_distribution_metric(precompiled_datagram, value)
+        if @enable_aggregation
+          @aggregator.aggregate_precompiled_timing_metric(precompiled_datagram, value)
+          return StatsD::Instrument::VOID
+        end
+
+        emit(precompiled_datagram.to_datagram(value))
+        StatsD::Instrument::VOID
+      end
+
       # Emits a precompiled metric for high-performance use cases.
       # This method is used by {StatsD::Instrument::CompiledMetric::Gauge} to emit metrics
       # with minimal allocations.

data/lib/statsd/instrument/compiled_metric.rb

@@ -18,6 +18,12 @@ module StatsD
     #   # Later, emit with minimal allocations:
     #   CheckoutMetric.increment(shop_id: 123, user_id: 456, value: 1)
     class CompiledMetric
+      # Raised when a CompiledMetric subclass is defined incorrectly.
+      # This includes calling `define` on a base type class directly,
+      # calling `define` more than once, or using a metric before `define`
+      # has been called.
+      class DefinitionError < StandardError; end
+
       # Default maximum number of unique tag combinations to cache before clearing
       # the cache to prevent unbounded memory growth
       DEFAULT_MAX_TAG_COMBINATION_CACHE_SIZE = 5000
@@ -33,6 +39,19 @@ module StatsD
         # @param max_cache_size [Integer] Maximum tag combinations this metric supports, and will be retained in-memory. Cardinality beyond this number will fall back to the slow path and should be avoided.
         # @return [Class] A new CompiledMetric subclass configured for this metric
         def define(name:, static_tags: {}, tags: {}, no_prefix: false, sample_rate: nil, max_cache_size: DEFAULT_MAX_TAG_COMBINATION_CACHE_SIZE)
+          if equal?(CompiledMetric) || superclass.equal?(CompiledMetric)
+            raise DefinitionError,
+              "`define` must be called on a subclass, not on #{self.name} directly. " \
+                "Use `Class.new(#{self.name}) { define(...) }` or " \
+                "`class MyMetric < #{self.name}; define(...); end` instead."
+          end
+
+          if defined?(@datagram_blueprint)
+            raise DefinitionError,
+              "`define` has already been called on #{self.name}. " \
+                "Each CompiledMetric subclass can only be defined once."
+          end
+
           client = StatsD.singleton_client
 
           # Build the datagram blueprint using the builder
@@ -51,7 +70,7 @@ 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)
+            @name = DatagramBlueprintBuilder.normalize_name(name).freeze
             @datagram_blueprint = datagram_blueprint
             @tag_combination_cache = {}
             @max_cache_size = max_cache_size
@@ -101,10 +120,15 @@ module StatsD
           @singleton_client.sink.sample?(sample_rate)
         end
 
+        # @return [String, nil] The normalized metric name for this compiled metric class (`nil` if not yet defined).
+        def metric_name
+          @name
+        end
+
         # @return [Float] The defined sample rate for a metric class.
         # Will raise when `define` has not yet been called on the class.
         def sample_rate
-          raise ArgumentError, "Every CompiledMetric subclass needs to call `define` before accessing its sample_rate." unless defined?(@sample_rate)
+          raise DefinitionError, "Every CompiledMetric subclass needs to call `define` before accessing its sample_rate." unless defined?(@sample_rate)
 
           @sample_rate
         end
@@ -115,7 +139,7 @@ module StatsD
         # Once `define` was called during the class creation, it will override the
         # method implementation to emit the actual metric datagrams.
         def require_define_to_be_called
-          raise ArgumentError, "Every CompiledMetric subclass needs to call `define` before first invocation of #{method_name}."
+          raise DefinitionError, "Every CompiledMetric subclass needs to call `define` before first invocation of #{method_name}."
         end
 
         def generate_block_handler
@@ -153,6 +177,10 @@ module StatsD
           default_val = default_value
           default_val_assignment = default_val.nil? ? "" : " = #{default_val.inspect}"
           allow_block = allow_measuring_latency
+          # Block-enabled compiled metrics run through generate_block_handler first,
+          # which applies sample_rate before emitting. Use the presampled client helper
+          # here so distributions don't make a second sampling decision.
+          client_emit_method = allow_block ? "emit_presampled_precompiled_#{method}_metric" : "emit_precompiled_#{method}_metric"
 
           method_code = <<~RUBY
             def self.#{method}(__value__#{default_val_assignment}, #{tag_names.map { |name| "#{name}:" }.join(", ")})
@@ -194,7 +222,7 @@ module StatsD
 
               __datagram__ ||= PrecompiledDatagram.new([#{tag_names.join(", ")}], @datagram_blueprint, @sample_rate)
 
-              @singleton_client.emit_precompiled_#{method}_metric(__datagram__, __value__)
+              @singleton_client.#{client_emit_method}(__datagram__, __value__)
               __return_value__
             end
           RUBY
@@ -209,12 +237,16 @@ module StatsD
           method = method_name
           default_val = default_value
           allow_block = allow_measuring_latency
+          # Block-enabled compiled metrics run through generate_block_handler first,
+          # which applies sample_rate before emitting. Use the presampled client helper
+          # here so distributions don't make a second sampling decision.
+          client_emit_method = allow_block ? "emit_presampled_precompiled_#{method}_metric" : "emit_precompiled_#{method}_metric"
 
           instance_eval(<<~RUBY, __FILE__, __LINE__ + 1)
             def self.#{method}(__value__ = #{default_val.inspect})
               __return_value__ = StatsD::Instrument::VOID
               #{generate_block_handler if allow_block}
-              @singleton_client.emit_precompiled_#{method}_metric(@static_datagram, __value__)
+              @singleton_client.#{client_emit_method}(@static_datagram, __value__)
               __return_value__
             end
           RUBY

data/lib/statsd/instrument/version.rb

@@ -2,6 +2,6 @@
 
 module StatsD
   module Instrument
-    VERSION = "3.10.0"
+    VERSION = "3.11.1"
   end
 end

data/test/compiled_metric/counter_test.rb

@@ -24,7 +24,7 @@ class CompiledMetricCounterTest < Minitest::Test
   def test_counter_without_define
     metric = Class.new(StatsD::Instrument::CompiledMetric::Counter)
 
-    error = assert_raises(ArgumentError) do
+    error = assert_raises(StatsD::Instrument::CompiledMetric::DefinitionError) do
       metric.increment(5)
     end
     assert_equal("Every CompiledMetric subclass needs to call `define` before first invocation of increment.", error.message)

data/test/compiled_metric/distribution_test.rb

@@ -24,7 +24,7 @@ class CompiledMetricDistributionTest < Minitest::Test
   def test_distribution_without_define
     metric = Class.new(StatsD::Instrument::CompiledMetric::Distribution)
 
-    error = assert_raises(ArgumentError) do
+    error = assert_raises(StatsD::Instrument::CompiledMetric::DefinitionError) do
       metric.distribution(5)
     end
     assert_equal("Every CompiledMetric subclass needs to call `define` before first invocation of distribution.", error.message)
@@ -230,6 +230,43 @@ class CompiledMetricDistributionTest < Minitest::Test
     assert_equal(["env:production", "region:us-east", "service:web"], datagram.tags.sort)
   end
 
+  def test_sampled_distribution_value_uses_one_sampling_decision
+    sample_rate = 0.5
+    @sink.expects(:sample?).with(sample_rate).once.returns(true)
+
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Distribution) do
+      define(
+        name: "foo.bar",
+        tags: { shop_id: Integer },
+        sample_rate: sample_rate,
+      )
+    end
+
+    metric.distribution(5, shop_id: 123)
+
+    assert_equal(1, @sink.datagrams.size)
+    assert_equal("test.foo.bar:5|d|@0.5|#shop_id:123", @sink.datagrams.first.source)
+  end
+
+  def test_sampled_distribution_block_uses_one_sampling_decision
+    sample_rate = 0.5
+    @sink.expects(:sample?).with(sample_rate).once.returns(true)
+    Process.stubs(:clock_gettime).with(Process::CLOCK_MONOTONIC, :float_millisecond).returns(100.0, 125.0)
+
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Distribution) do
+      define(
+        name: "foo.bar",
+        sample_rate: sample_rate,
+      )
+    end
+
+    returned_value = metric.distribution { :result }
+
+    assert_equal(:result, returned_value)
+    assert_equal(1, @sink.datagrams.size)
+    assert_equal("test.foo.bar:25.0|d|@0.5", @sink.datagrams.first.source)
+  end
+
   def test_latency_as_value_when_block_provided
     metric = Class.new(StatsD::Instrument::CompiledMetric::Distribution) do
       define(
@@ -415,18 +452,17 @@ class CompiledMetricDistributionWithAggregationTest < Minitest::Test
   end
 
   def test_sample_rate_with_aggregation
-    # When aggregating with sample_rate, sampling happens before aggregation
-    # This test verifies that with a sample_rate >0, a subset of distributions are aggregated
+    sample_rate = 0.5
+    @sink.expects(:sample?).with(sample_rate).times(5).returns(false, true, false, false, true)
+
     metric = Class.new(StatsD::Instrument::CompiledMetric::Distribution) do
       define(
         name: "foo.bar",
         static_tags: { service: "web" },
-        sample_rate: 0.5,
+        sample_rate: sample_rate,
       )
     end
 
-    metric.stubs(:sample?).returns(false, true, false, false, true)
-
     metric.distribution(1)
     metric.distribution(2)
     metric.distribution(3)

data/test/compiled_metric/gauge_test.rb

@@ -24,7 +24,7 @@ class CompiledMetricGaugeTest < Minitest::Test
   def test_gauge_without_define
     metric = Class.new(StatsD::Instrument::CompiledMetric::Gauge)
 
-    error = assert_raises(ArgumentError) do
+    error = assert_raises(StatsD::Instrument::CompiledMetric::DefinitionError) do
       metric.gauge(5)
     end
     assert_equal("Every CompiledMetric subclass needs to call `define` before first invocation of gauge.", error.message)

data/test/compiled_metric_test.rb

@@ -439,9 +439,78 @@ class CompiledMetricDefinitionTest < Minitest::Test
   def test_sample_rate_without_define
     metric = Class.new(StatsD::Instrument::CompiledMetric::Counter)
 
-    error = assert_raises(ArgumentError) do
+    error = assert_raises(StatsD::Instrument::CompiledMetric::DefinitionError) do
       metric.sample_rate
     end
     assert_equal("Every CompiledMetric subclass needs to call `define` before accessing its sample_rate.", error.message)
   end
+
+  def test_metric_name
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo.bar",
+      )
+    end
+
+    assert_equal("foo.bar", metric.metric_name)
+    assert_predicate(metric.metric_name, :frozen?)
+  end
+
+  def test_metric_name_is_normalized
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+      define(
+        name: "foo:bar|baz@qux",
+      )
+    end
+
+    assert_equal("foo_bar_baz_qux", metric.metric_name)
+    assert_predicate(metric.metric_name, :frozen?)
+  end
+
+  def test_metric_name_without_define
+    metric = Class.new(StatsD::Instrument::CompiledMetric::Counter)
+
+    assert_nil(metric.metric_name)
+  end
+
+  def test_define_directly_on_counter_raises
+    error = assert_raises(StatsD::Instrument::CompiledMetric::DefinitionError) do
+      StatsD::Instrument::CompiledMetric::Counter.define(name: "bad_metric")
+    end
+    assert_includes(error.message, "`define` must be called on a subclass")
+    assert_includes(error.message, "Counter")
+  end
+
+  def test_define_directly_on_gauge_raises
+    error = assert_raises(StatsD::Instrument::CompiledMetric::DefinitionError) do
+      StatsD::Instrument::CompiledMetric::Gauge.define(name: "bad_metric")
+    end
+    assert_includes(error.message, "`define` must be called on a subclass")
+    assert_includes(error.message, "Gauge")
+  end
+
+  def test_define_directly_on_distribution_raises
+    error = assert_raises(StatsD::Instrument::CompiledMetric::DefinitionError) do
+      StatsD::Instrument::CompiledMetric::Distribution.define(name: "bad_metric")
+    end
+    assert_includes(error.message, "`define` must be called on a subclass")
+    assert_includes(error.message, "Distribution")
+  end
+
+  def test_define_directly_on_compiled_metric_raises
+    error = assert_raises(StatsD::Instrument::CompiledMetric::DefinitionError) do
+      StatsD::Instrument::CompiledMetric.define(name: "bad_metric")
+    end
+    assert_includes(error.message, "`define` must be called on a subclass")
+  end
+
+  def test_double_define_raises
+    error = assert_raises(StatsD::Instrument::CompiledMetric::DefinitionError) do
+      Class.new(StatsD::Instrument::CompiledMetric::Counter) do
+        define(name: "first_metric")
+        define(name: "second_metric")
+      end
+    end
+    assert_includes(error.message, "`define` has already been called")
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statsd-instrument
 version: !ruby/object:Gem::Version
-  version: 3.10.0
+  version: 3.11.1
 platform: ruby
 authors:
 - Jesse Storimer
@@ -135,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.14
 specification_version: 4
 summary: A StatsD client for Ruby apps
 test_files: