prometheus-client 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 525f1dcd2ca63486f95a2d2fd44b7f047625edc3
-  data.tar.gz: 0480ce9fd716c715553e8c1a0877345f2124b563
+  metadata.gz: 1ca1c148a74709f3c2fbbba112f651babdf43fbe
+  data.tar.gz: e55c7b9be73218b6a252a5a624fc8a865d00d851
 SHA512:
-  metadata.gz: 362f0157652258f5270dc815434d7ef4768e4842a68a5a344e9dcff41ee494fadcab29d0c15c5764310bfa8d9b1655e27a829a7c62782505ea3c6f611402796e
-  data.tar.gz: 548905e7ec71056de3e6a622073bf0fc342f6dca7a6d9c0c783411c35ab7f306aa87f71aecab7fc128a4dfd232f62dcb72dca0682a3421451d162844dab66960
+  metadata.gz: 337ad7b5c4315463492d5120b4652bd0e4d58c1b2a53fa8be05c5f1d02c7b567133196e31e5b43899001f25fd896c7f60d4cccda717d1d8fede675aaa21276e0
+  data.tar.gz: fcbb6c9963f8f0e5c5c532209fecf8643fad16a8943b74fd601644972ff25bb30f8c0e0be02b307c0247fb7a83549d21a54fe1f75850df795000d7756c9092ab

data/README.md

@@ -73,7 +73,7 @@ require 'prometheus/client'
 require 'prometheus/client/push'
 
 prometheus = Prometheus::Client.registry
-# ... register some metrics, set/add/increment/etc. their values
+# ... register some metrics, set/increment/observe/etc. their values
 
 # push the registry state to the default gateway
 Prometheus::Client::Push.new('my-batch-job').add(prometheus)
@@ -96,19 +96,16 @@ The following metric types are currently supported.
 Counter is a metric that exposes merely a sum or tally of things.
 
 ```ruby
-counter = Prometheus::Client::Counter.new(:foo, '...')
+counter = Prometheus::Client::Counter.new(:service_requests_total, '...')
 
 # increment the counter for a given label set
-counter.increment(service: 'foo')
+counter.increment({ service: 'foo' })
 
 # increment by a given value
 counter.increment({ service: 'bar' }, 5)
 
-# decrement the counter
-counter.decrement(service: 'exceptional')
-
 # get current value for a given label set
-counter.get(service: 'bar')
+counter.get({ service: 'bar' })
 # => 5
 ```
 
@@ -118,30 +115,47 @@ Gauge is a metric that exposes merely an instantaneous value or some snapshot
 thereof.
 
 ```ruby
-gauge = Prometheus::Client::Gauge.new(:bar, '...')
+gauge = Prometheus::Client::Gauge.new(:room_temperature_celsius, '...')
 
 # set a value
-gauge.set({ role: 'base' }, 'up')
+gauge.set({ room: 'kitchen' }, 21.534)
 
 # retrieve the current value for a given label set
-gauge.get({ role: 'problematic' })
-# => 'down'
+gauge.get({ room: 'kitchen' })
+# => 21.534
+```
+
+### Histogram
+
+A histogram samples observations (usually things like request durations or
+response sizes) and counts them in configurable buckets. It also provides a sum
+of all observed values.
+
+```ruby
+histogram = Prometheus::Client::Histogram.new(:service_latency_seconds, '...')
+
+# record a value
+histogram.observe({ service: 'users' }, Benchmark.realtime { service.call(arg) })
+
+# retrieve the current quantile values
+histogram.get({ service: 'users' })
+# => { 0.005 => 3, 0.01 => 15, 0.025 => 18, ..., 2.5 => 42, 5 => 42, 10 = >42 }
 ```
 
 ### Summary
 
-Summary is an accumulator for samples. It captures Numeric data and provides
-an efficient percentile calculation mechanism.
+Summary, similar to histograms, is an accumulator for samples. It captures
+Numeric data and provides an efficient percentile calculation mechanism.
 
 ```ruby
-summary = Prometheus::Client::Summary.new(:baz, '...')
+summary = Prometheus::Client::Summary.new(:service_latency_seconds, '...')
 
 # record a value
-summary.add({ service: 'slow' }, Benchmark.realtime { service.call(arg) })
+summary.observe({ service: 'database' }, Benchmark.realtime { service.call() })
 
 # retrieve the current quantile values
 summary.get({ service: 'database' })
-# => { 0.5: 1.233122, 0.9: 83.4323, 0.99: 341.3428231 }
+# => { 0.5 => 0.1233122, 0.9 => 3.4323, 0.99 => 5.3428231 }
 ```
 
 ## Todo

data/lib/prometheus/client/counter.rb

@@ -11,7 +11,7 @@ module Prometheus
       end
 
       def increment(labels = {}, by = 1)
-        fail ArgumentError, 'increment must be a non-negative number' if by < 0
+        raise ArgumentError, 'increment must be a non-negative number' if by < 0
 
         label_set = label_set_for(labels)
         synchronize { @values[label_set] += by }

data/lib/prometheus/client/formats/text.rb

@@ -5,20 +5,20 @@ module Prometheus
     module Formats
       # Text format is human readable mainly used for manual inspection.
       module Text
-        MEDIA_TYPE   = 'text/plain'
-        VERSION      = '0.0.4'
-        CONTENT_TYPE = "#{MEDIA_TYPE}; version=#{VERSION}"
+        MEDIA_TYPE   = 'text/plain'.freeze
+        VERSION      = '0.0.4'.freeze
+        CONTENT_TYPE = "#{MEDIA_TYPE}; version=#{VERSION}".freeze
 
-        METRIC_LINE = '%s%s %s'
-        TYPE_LINE   = '# TYPE %s %s'
-        HELP_LINE   = '# HELP %s %s'
+        METRIC_LINE = '%s%s %s'.freeze
+        TYPE_LINE   = '# TYPE %s %s'.freeze
+        HELP_LINE   = '# HELP %s %s'.freeze
 
-        LABEL     = '%s="%s"'
-        SEPARATOR = ','
-        DELIMITER = "\n"
+        LABEL     = '%s="%s"'.freeze
+        SEPARATOR = ','.freeze
+        DELIMITER = "\n".freeze
 
-        REGEX   = { doc: /[\n\\]/, label: /[\n\\"]/ }
-        REPLACE = { "\n" => '\n', '\\' => '\\\\', '"' => '\"' }
+        REGEX   = { doc: /[\n\\]/, label: /[\n\\"]/ }.freeze
+        REPLACE = { "\n" => '\n', '\\' => '\\\\', '"' => '\"' }.freeze
 
         def self.marshal(registry)
           lines = []
@@ -36,44 +36,59 @@ module Prometheus
           (lines << nil).join(DELIMITER)
         end
 
-        private
+        class << self
+          private
 
-        def self.representation(metric, label_set, value, &block)
-          set = metric.base_labels.merge(label_set)
+          def representation(metric, label_set, value, &block)
+            set = metric.base_labels.merge(label_set)
 
-          if metric.type == :summary
-            summary(metric.name, set, value, &block)
-          else
-            yield metric(metric.name, labels(set), value)
+            if metric.type == :summary
+              summary(metric.name, set, value, &block)
+            elsif metric.type == :histogram
+              histogram(metric.name, set, value, &block)
+            else
+              yield metric(metric.name, labels(set), value)
+            end
           end
-        end
 
-        def self.summary(name, set, value)
-          value.each do |q, v|
-            yield metric(name, labels(set.merge(quantile: q)), v)
-          end
+          def summary(name, set, value)
+            value.each do |q, v|
+              yield metric(name, labels(set.merge(quantile: q)), v)
+            end
 
-          l = labels(set)
-          yield metric("#{name}_sum", l, value.sum)
-          yield metric("#{name}_count", l, value.total)
-        end
+            l = labels(set)
+            yield metric("#{name}_sum", l, value.sum)
+            yield metric("#{name}_count", l, value.total)
+          end
 
-        def self.metric(name, labels, value)
-          format(METRIC_LINE, name, labels, value)
-        end
+          def histogram(name, set, value)
+            value.each do |q, v|
+              yield metric(name, labels(set.merge(le: q)), v)
+            end
+            yield metric(name, labels(set.merge(le: '+Inf')), value.total)
 
-        def self.labels(set)
-          return if set.empty?
+            l = labels(set)
+            yield metric("#{name}_sum", l, value.sum)
+            yield metric("#{name}_count", l, value.total)
+          end
 
-          strings = set.each_with_object([]) do |(key, value), memo|
-            memo << format(LABEL, key, escape(value, :label))
+          def metric(name, labels, value)
+            format(METRIC_LINE, name, labels, value)
           end
 
-          "{#{strings.join(SEPARATOR)}}"
-        end
+          def labels(set)
+            return if set.empty?
+
+            strings = set.each_with_object([]) do |(key, value), memo|
+              memo << format(LABEL, key, escape(value, :label))
+            end
 
-        def self.escape(string, format = :doc)
-          string.to_s.gsub(REGEX[format], REPLACE)
+            "{#{strings.join(SEPARATOR)}}"
+          end
+
+          def escape(string, format = :doc)
+            string.to_s.gsub(REGEX[format], REPLACE)
+          end
         end
       end
     end

data/lib/prometheus/client/histogram.rb

@@ -0,0 +1,73 @@
+# encoding: UTF-8
+
+require 'prometheus/client/metric'
+
+module Prometheus
+  module Client
+    # A histogram samples observations (usually things like request durations
+    # or response sizes) and counts them in configurable buckets. It also
+    # provides a sum of all observed values.
+    class Histogram < Metric
+      # Value represents the state of a Histogram at a given point.
+      class Value < Hash
+        attr_accessor :sum, :total
+
+        def initialize(buckets)
+          @sum = 0.0
+          @total = 0
+
+          buckets.each do |bucket|
+            self[bucket] = 0
+          end
+        end
+
+        def observe(value)
+          @sum += value
+          @total += 1
+
+          each_key do |bucket|
+            self[bucket] += 1 if value <= bucket
+          end
+        end
+      end
+
+      # DEFAULT_BUCKETS are the default Histogram buckets. The default buckets
+      # are tailored to broadly measure the response time (in seconds) of a
+      # network service. (From DefBuckets client_golang)
+      DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1,
+                         2.5, 5, 10].freeze
+
+      # Offer a way to manually specify buckets
+      def initialize(name, docstring, base_labels = {},
+                     buckets = DEFAULT_BUCKETS)
+        raise ArgumentError, 'Unsorted buckets, typo?' unless sorted? buckets
+
+        @buckets = buckets
+        super(name, docstring, base_labels)
+      end
+
+      def type
+        :histogram
+      end
+
+      def observe(labels, value)
+        if labels[:le]
+          raise ArgumentError, 'Label with name "le" is not permitted'
+        end
+
+        label_set = label_set_for(labels)
+        synchronize { @values[label_set].observe(value) }
+      end
+
+      private
+
+      def default
+        Value.new(@buckets)
+      end
+
+      def sorted?(bucket)
+        bucket.each_cons(2).all? { |i, j| i <= j }
+      end
+    end
+  end
+end

data/lib/prometheus/client/label_set_validator.rb

@@ -6,7 +6,7 @@ module Prometheus
     # Prometheus specification.
     class LabelSetValidator
       # TODO: we might allow setting :instance in the future
-      RESERVED_LABELS = [:job, :instance]
+      RESERVED_LABELS = [:job, :instance].freeze
 
       class LabelSetError < StandardError; end
       class InvalidLabelSetError < LabelSetError; end
@@ -19,7 +19,7 @@ module Prometheus
 
       def valid?(labels)
         unless labels.respond_to?(:all?)
-          fail InvalidLabelSetError, "#{labels} is not a valid label set"
+          raise InvalidLabelSetError, "#{labels} is not a valid label set"
         end
 
         labels.all? do |key, _|
@@ -35,7 +35,7 @@ module Prometheus
         valid?(labels)
 
         unless @validated.empty? || match?(labels, @validated.first.last)
-          fail InvalidLabelSetError, 'labels must have the same signature'
+          raise InvalidLabelSetError, 'labels must have the same signature'
         end
 
         @validated[labels.hash] = labels
@@ -50,19 +50,19 @@ module Prometheus
       def validate_symbol(key)
         return true if key.is_a?(Symbol)
 
-        fail InvalidLabelError, "label #{key} is not a symbol"
+        raise InvalidLabelError, "label #{key} is not a symbol"
       end
 
       def validate_name(key)
         return true unless key.to_s.start_with?('__')
 
-        fail ReservedLabelError, "label #{key} must not start with __"
+        raise ReservedLabelError, "label #{key} must not start with __"
       end
 
       def validate_reserved_key(key)
         return true unless RESERVED_LABELS.include?(key)
 
-        fail ReservedLabelError, "#{key} is reserved"
+        raise ReservedLabelError, "#{key} is reserved"
       end
     end
   end

data/lib/prometheus/client/metric.rb

@@ -25,7 +25,7 @@ module Prometheus
 
       # Returns the metric type
       def type
-        fail NotImplementedError
+        raise NotImplementedError
       end
 
       # Returns the value for the given label set
@@ -53,13 +53,13 @@ module Prometheus
       def validate_name(name)
         return true if name.is_a?(Symbol)
 
-        fail ArgumentError, 'given name must be a symbol'
+        raise ArgumentError, 'given name must be a symbol'
       end
 
       def validate_docstring(docstring)
         return true if docstring.respond_to?(:empty?) && !docstring.empty?
 
-        fail ArgumentError, 'docstring must be given'
+        raise ArgumentError, 'docstring must be given'
       end
 
       def label_set_for(labels)

data/lib/prometheus/client/push.rb

@@ -12,10 +12,10 @@ module Prometheus
     # Push implements a simple way to transmit a given registry to a given
     # Pushgateway.
     class Push
-      DEFAULT_GATEWAY = 'http://localhost:9091'
-      PATH            = '/metrics/jobs/%s'
-      INSTANCE_PATH   = '/metrics/jobs/%s/instances/%s'
-      HEADER          = { 'Content-Type' => Formats::Text::CONTENT_TYPE }
+      DEFAULT_GATEWAY = 'http://localhost:9091'.freeze
+      PATH            = '/metrics/jobs/%s'.freeze
+      INSTANCE_PATH   = '/metrics/jobs/%s/instances/%s'.freeze
+      HEADER          = { 'Content-Type' => Formats::Text::CONTENT_TYPE }.freeze
 
       attr_reader :job, :instance, :gateway, :path
 
@@ -44,7 +44,7 @@ module Prometheus
         if uri.scheme == 'http'
           uri
         else
-          fail ArgumentError, 'only HTTP gateway URLs are supported currently.'
+          raise ArgumentError, 'only HTTP gateway URLs are supported currently.'
         end
       rescue URI::InvalidURIError => e
         raise ArgumentError, "#{url} is not a valid URL: #{e}"

data/lib/prometheus/client/rack/collector.rb

@@ -37,19 +37,19 @@ module Prometheus
         def init_request_metrics
           @requests = @registry.counter(
             :http_requests_total,
-            'A counter of the total number of HTTP requests made.')
-          @requests_duration = @registry.counter(
-            :http_request_duration_total_seconds,
-            'The total amount of time spent answering HTTP requests.')
+            'A counter of the total number of HTTP requests made.',
+          )
           @durations = @registry.summary(
             :http_request_duration_seconds,
-            'A histogram of the response latency.')
+            'A histogram of the response latency.',
+          )
         end
 
         def init_exception_metrics
           @exceptions = @registry.counter(
             :http_exceptions_total,
-            'A counter of the total number of exceptions raised.')
+            'A counter of the total number of exceptions raised.',
+          )
         end
 
         def trace(env)
@@ -71,8 +71,7 @@ module Prometheus
 
         def record(labels, duration)
           @requests.increment(labels)
-          @requests_duration.increment(labels, duration)
-          @durations.add(labels, duration)
+          @durations.observe(labels, duration)
         rescue
           # TODO: log unexpected exception during request recording
           nil

data/lib/prometheus/client/rack/exporter.rb

@@ -11,7 +11,7 @@ module Prometheus
       class Exporter
         attr_reader :app, :registry, :path
 
-        FORMATS  = [Formats::Text]
+        FORMATS  = [Formats::Text].freeze
         FALLBACK = Formats::Text
 
         def initialize(app, options = {})

data/lib/prometheus/client/registry.rb

@@ -5,6 +5,7 @@ require 'thread'
 require 'prometheus/client/counter'
 require 'prometheus/client/summary'
 require 'prometheus/client/gauge'
+require 'prometheus/client/histogram'
 
 module Prometheus
   module Client
@@ -22,7 +23,7 @@ module Prometheus
 
         @mutex.synchronize do
           if exist?(name.to_sym)
-            fail AlreadyRegisteredError, "#{name} has already been registered"
+            raise AlreadyRegisteredError, "#{name} has already been registered"
           else
             @metrics[name.to_sym] = metric
           end
@@ -43,6 +44,11 @@ module Prometheus
         register(Gauge.new(name, docstring, base_labels))
       end
 
+      def histogram(name, docstring, base_labels = {},
+                    buckets = Histogram::DEFAULT_BUCKETS)
+        register(Histogram.new(name, docstring, base_labels, buckets))
+      end
+
       def exist?(name)
         @metrics.key?(name)
       end

data/lib/prometheus/client/summary.rb

@@ -8,6 +8,8 @@ module Prometheus
     # Summary is an accumulator for samples. It captures Numeric data and
     # provides an efficient quantile calculation mechanism.
     class Summary < Metric
+      extend Gem::Deprecate
+
       # Value represents the state of a Summary at a given point.
       class Value < Hash
         attr_accessor :sum, :total
@@ -27,10 +29,12 @@ module Prometheus
       end
 
       # Records a given value.
-      def add(labels, value)
+      def observe(labels, value)
         label_set = label_set_for(labels)
         synchronize { @values[label_set].observe(value) }
       end
+      alias add observe
+      deprecate :add, :observe, 2016, 10
 
       # Returns the value for the given label set
       def get(labels = {})

data/lib/prometheus/client/version.rb

@@ -2,6 +2,6 @@
 
 module Prometheus
   module Client
-    VERSION = '0.5.0'
+    VERSION = '0.6.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prometheus-client
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Tobias Schmidt
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-12 00:00:00.000000000 Z
+date: 2016-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: quantile
@@ -37,6 +37,7 @@ files:
 - lib/prometheus/client/counter.rb
 - lib/prometheus/client/formats/text.rb
 - lib/prometheus/client/gauge.rb
+- lib/prometheus/client/histogram.rb
 - lib/prometheus/client/label_set_validator.rb
 - lib/prometheus/client/metric.rb
 - lib/prometheus/client/push.rb