instrument.rb in statsd-instrument-2.3.0.beta4

- old
+ new

@@ -70,11 +70,11 @@
         yield
         Time.now - start
       end
     end
 
-    # Adds execution duration instrumentation to a method.
+    # Adds execution duration instrumentation to a method as a timing.
     #
     # @param method [Symbol] The name of the method to instrument.
     # @param name [String, #call] The name of the metric to use. You can also pass in a
     #    callable to dynamically generate a metric name
     # @param metric_options (see StatsD#measure)
@@ -85,10 +85,26 @@
           StatsD.measure(StatsD::Instrument.generate_metric_name(name, self, *args), *metric_options) { super(*args, &block) }
         end
       end
     end
 
+    # Adds execution duration instrumentation to a method as a distribution.
+    #
+    # @param method [Symbol] The name of the method to instrument.
+    # @param name [String, #call] The name of the metric to use. You can also pass in a
+    #    callable to dynamically generate a metric name
+    # @param metric_options (see StatsD#measure)
+    # @return [void]
+    # @note Supported by the datadog implementation only (in beta)
+    def statsd_distribution(method, name, *metric_options)
+      add_to_method(method, name, :distribution) do
+        define_method(method) do |*args, &block|
+          StatsD.distribution(StatsD::Instrument.generate_metric_name(name, self, *args), *metric_options) { super(*args, &block) }
+        end
+      end
+    end
+
     # Adds success and failure counter instrumentation to a method.
     #
     # A method call will be considered successful if it does not raise an exception, and the result is true-y.
     # For successful calls, the metric <tt>[name].success</tt> will be incremented; for failed calls, the metric
     # name is <tt>[name].failure</tt>.
@@ -204,10 +220,19 @@
     # @see #statsd_measure
     def statsd_remove_measure(method, name)
       remove_from_method(method, name, :measure)
     end
 
+    # Removes StatsD distribution instrumentation from a method
+    # @param method (see #statsd_remove_count)
+    # @param name (see #statsd_remove_count)
+    # @return [void]
+    # @see #statsd_measure
+    def statsd_remove_distribution(method, name)
+      remove_from_method(method, name, :distribution)
+    end
+
     private
 
     def statsd_instrumentation_for(method, name, action)
       unless statsd_instrumentations.key?([method, name, action])
         mod = Module.new do
@@ -280,21 +305,17 @@
   #   @example
   #      http_response = StatsD.measure('HTTP.call.duration') do
   #        HTTP.get(url)
   #      end
   def measure(key, value = nil, *metric_options, &block)
-    if value.is_a?(Hash) && metric_options.empty?
-      metric_options = [value]
-      value = value.fetch(:value, nil)
-    end
+    value, metric_options = parse_options(value, metric_options)
     type = (!metric_options.empty? && metric_options.first[:as_dist] ? :d : :ms)
 
     result = nil
     value  = 1000 * StatsD::Instrument.duration { result = block.call } if block_given?
-    metric = collect_metric(hash_argument(metric_options).merge(type: type, name: key, value: value))
-    result = metric unless block_given?
-    result
+    metric = collect_metric(type, key, value, metric_options)
+    (result || metric)
   end
 
   # Emits a counter metric.
   # @param key [String] The name of the metric.
   # @param value [Integer] The value to increment the counter by.
@@ -305,120 +326,98 @@
   #   should know how to handle it.
   #
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   def increment(key, value = 1, *metric_options)
-    if value.is_a?(Hash) && metric_options.empty?
-      metric_options = [value]
-      value = value.fetch(:value, 1)
-    end
-
-    collect_metric(hash_argument(metric_options).merge(type: :c, name: key, value: value))
+    collect_metric(:c, key, value, metric_options)
   end
 
   # Emits a gauge metric.
   # @param key [String] The name of the metric.
   # @param value [Numeric] The current value to record.
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   def gauge(key, value, *metric_options)
-    if value.is_a?(Hash) && metric_options.empty?
-      metric_options = [value]
-      value = value.fetch(:value, nil)
-    end
-
-    collect_metric(hash_argument(metric_options).merge(type: :g, name: key, value: value))
+    collect_metric(:g, key, value, metric_options)
   end
 
   # Emits a histogram metric.
   # @param key [String] The name of the metric.
   # @param value [Numeric] The value to record.
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   # @note Supported by the datadog implementation only.
   def histogram(key, value, *metric_options)
-    if value.is_a?(Hash) && metric_options.empty?
-      metric_options = [value]
-      value = value.fetch(:value, nil)
-    end
-
-    collect_metric(hash_argument(metric_options).merge(type: :h, name: key, value: value))
+    collect_metric(:h, key, value, metric_options)
   end
 
   # Emits a distribution metric.
   # @param key [String] The name of the metric.
   # @param value [Numeric] The value to record.
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   # @note Supported by the datadog implementation only (in beta)
-  def distribution(key, value, *metric_options)
-    if value.is_a?(Hash) && metric_options.empty?
-      metric_options = [value]
-      value = value.fetch(:value, nil)
-    end
-
-    collect_metric(hash_argument(metric_options).merge(type: :d, name: key, value: value))
+  #
+  # @overload distribution(key, metric_options = {}, &block)
+  #   Emits a distribution metric, after measuring the execution duration of the
+  #   block passed to this method.
+  #   @param key [String] The name of the metric.
+  #   @param metric_options [Hash] Options for the metric
+  #   @yield The method will yield the block that was passed to this method to measure its duration.
+  #   @return The value that was returns by the block passed to this method.
+  #   @note Supported by the datadog implementation only.
+  #
+  #   @example
+  #      http_response = StatsD.distribution('HTTP.call.duration') do
+  #        HTTP.get(url)
+  #      end
+  def distribution(key, value=nil, *metric_options, &block)
+    value, metric_options = parse_options(value, metric_options)
+    result = nil
+    value  = 1000 * StatsD::Instrument.duration { result = block.call } if block_given?
+    metric = collect_metric(:d, key, value, metric_options)
+    (result || metric)
   end
 
   # Emits a key/value metric.
   # @param key [String] The name of the metric.
   # @param value [Numeric] The value to record.
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   # @note Supported by the statsite implementation only.
   def key_value(key, value, *metric_options)
-    if value.is_a?(Hash) && metric_options.empty?
-      metric_options = [value]
-      value = value.fetch(:value, nil)
-    end
-
-    collect_metric(hash_argument(metric_options).merge(type: :kv, name: key, value: value))
+    collect_metric(:kv, key, value, metric_options)
   end
 
   # Emits a set metric.
   # @param key [String] The name of the metric.
   # @param value [Numeric] The value to record.
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   # @note Supported by the datadog implementation only.
   def set(key, value, *metric_options)
-    if value.is_a?(Hash) && metric_options.empty?
-      metric_options = [value]
-      value = value.fetch(:value, nil)
-    end
-
-    collect_metric(hash_argument(metric_options).merge(type: :s, name: key, value: value))
+    collect_metric(:s, key, value, metric_options)
   end
 
   # Emits an event metric.
   # @param title [String] Title of the event.
   # @param text [String] Body of the event.
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   # @note Supported by the datadog implementation only.
   def event(title, text, *metric_options)
-    if text.is_a?(Hash) && metric_options.empty?
-      metric_options = [text]
-      text = text.fetch(:text, nil)
-    end
-
-    collect_metric(hash_argument(metric_options).merge(type: :_e, name: title, value: text))
+    collect_metric(:_e, title, text, metric_options)
   end
 
   # Emits a service check metric.
   # @param title [String] Title of the event.
   # @param text [String] Body of the event.
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   # @note Supported by the datadog implementation only.
   def service_check(name, status, *metric_options)
-    if status.is_a?(Hash) && metric_options.empty?
-      metric_options = [status]
-      status = status.fetch(:status, nil)
-    end
-
-    collect_metric(hash_argument(metric_options).merge(type: :_sc, name: name, value: status))
+    collect_metric(:_sc, name, status, metric_options)
   end
 
   private
 
   # Converts old-style ordered arguments in an argument hash for backwards compatibility.
@@ -435,13 +434,24 @@
     end
 
     return hash
   end
 
+  def parse_options(value, metric_options)
+    if value.is_a?(Hash) && metric_options.empty?
+      metric_options = [value]
+      value = value.fetch(:value, nil)
+    end
+    [value, metric_options]
+  end
+
   # Instantiates a metric, and sends it to the backend for further processing.
   # @param options (see StatsD::Instrument::Metric#initialize)
   # @return [StatsD::Instrument::Metric] The meric that was sent to the backend.
-  def collect_metric(options)
+  def collect_metric(type, name, value, metric_options)
+    value, metric_options = parse_options(value, metric_options)
+
+    options = hash_argument(metric_options).merge(type: type, name: name, value: value)
     backend.collect_metric(metric = StatsD::Instrument::Metric.new(options))
     metric
   end
 end
 