prometheus-client 0.1.0 → 0.2.0

data/README.md

@@ -1,7 +1,13 @@
 # Prometheus Ruby Client
 
+A suite of instrumentation metric primitives for Ruby that can be exposed
+through a JSON web services interface. Intended to be used together with a
+[Prometheus server][1].
+
 ## Usage
 
+### Library
+
 ```ruby
 require 'prometheus/client'
 
@@ -10,14 +16,40 @@ prometheus = Prometheus::Client.registry
 
 # create a new counter metric
 http_requests = Prometheus::Client::Counter.new
-
 # register the metric
-prometheus.register(:http_requests, 'A counter of the total number of HTTP requests made', http_requests)
+prometheus.register(:http_requests, 'A counter of HTTP requests made', http_requests)
+
+# equivalent helper function
+http_requests = prometheus.counter(:http_requests, 'A counter of HTTP requests made')
 
 # start using the counter
 http_requests.increment
 ```
 
+### Rack middleware
+
+There are two [Rack][2] middlewares available, one to expose a metrics HTTP
+endpoint to be scraped by a prometheus server and one to trace all HTTP
+requests.
+
+```ruby
+# config.ru
+
+require 'rack'
+require 'prometheus/client/rack/collector'
+require 'prometheus/client/rack/exporter'
+
+use Prometheus::Client::Rack::Collector
+use Prometheus::Client::Rack::Exporter
+run lambda { |env| [200, {'Content-Type' => 'text/html'}, ['OK']] }
+```
+
+Start the server and have a look at the metrics endpoint:
+[http://localhost:5000/metrics](http://localhost:5000/metrics).
+
+For further instructions and other scripts to get started, have a look at the
+integrated [example application](examples/rack/README.md).
+
 ## Metrics
 
 The following metric types are currently supported.
@@ -26,21 +58,64 @@ The following metric types are currently supported.
 
 A Counter is a metric that exposes merely a sum or tally of things.
 
+```ruby
+counter = Prometheus::Client::Counter.new
+
+# increment the counter for a given label set
+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')
+# => 5
+```
+
 ### Gauge
 
 A Gauge is a metric that exposes merely an instantaneous value or some
 snapshot thereof.
 
+```ruby
+gauge = Prometheus::Client::Gauge.new
+
+# set a value
+gauge.set({ role: 'base' }, 'up')
+
+# retrieve the current value for a given label set
+gauge.get({ role: 'problematic' })
+# => 'down'
+```
+
+### Summary
+
+The Summary is an accumulator for samples. It captures Numeric data and provides
+an efficient percentile calculation mechanism.
+
+```ruby
+summary = Prometheus::Client::Summary.new
+
+# record a value
+summary.add({ service: 'slow' }, Benchmark.realtime { service.call(arg) })
+
+# retrieve the current quantile values
+summary.get({ service: 'database' })
+# => { 0.5: 1.233122, 0.9: 83.4323, 0.99: 341.3428231 }
+```
+
 ## Todo
 
-  * add histogram support
   * add push support to a vanilla prometheus exporter
-  * add tests for Rack middlewares
   * use a more performant JSON library
+  * add protobuf support
 
 ## Tests
 
-[![Build Status][1]](http://travis-ci.org/prometheus/client_ruby)
+[![Build Status][3]](http://travis-ci.org/prometheus/client_ruby)
 
 Install necessary development gems with `bundle install` and run tests with
 rspec:
@@ -49,4 +124,6 @@ rspec:
 rspec
 ```
 
-[1]: https://secure.travis-ci.org/prometheus/client_ruby.png?branch=master
+[1]: https://github.com/prometheus/prometheus
+[2]: http://rack.github.io/
+[3]: https://secure.travis-ci.org/prometheus/client_ruby.png?branch=master

data/lib/prometheus/client/counter.rb

@@ -3,10 +3,6 @@ require 'prometheus/client/metric'
 module Prometheus
   module Client
     class Counter < Metric
-      def default
-        0
-      end
-
       def type
         :counter
       end
@@ -19,6 +15,13 @@ module Prometheus
       def decrement(labels = {}, by = 1)
         increment(labels, -by)
       end
+
+    private
+
+      def default
+        0
+      end
+
     end
   end
 end

data/lib/prometheus/client/gauge.rb

@@ -6,6 +6,11 @@ module Prometheus
       def type
         :gauge
       end
+
+      # Sets the value for the given label set
+      def set(labels, value)
+        @values[label_set_for(labels)] = value
+      end
     end
   end
 end

data/lib/prometheus/client/metric.rb

@@ -7,12 +7,7 @@ module Prometheus
     class Metric
       def initialize
         @mutex = Mutex.new
-        @values = Hash.new(default)
-      end
-
-      # Default value
-      def default
-        nil
+        @values = Hash.new { |hash, key| hash[key] = default }
       end
 
       # Returns the metric type
@@ -20,23 +15,11 @@ module Prometheus
         raise NotImplementedError
       end
 
-      # Returns all values
-      def value
-        @values.map do |labels, value|
-          { :labels => labels, :value => value }
-        end
-      end
-
       # Returns the value for the given label set
       def get(labels = {})
         @values[label_set_for(labels)]
       end
 
-      # Sets the value for the given label set
-      def set(labels, value)
-        @values[label_set_for(labels)] = value
-      end
-
       # Generates JSON representation
       def to_json(*json)
         {
@@ -45,7 +28,17 @@ module Prometheus
         }.to_json(*json)
       end
 
-    protected
+    private
+
+      def default
+        nil
+      end
+
+      def value
+        @values.map do |labels, value|
+          { :labels => labels, :value => get(labels) }
+        end
+      end
 
       def label_set_for(labels)
         LabelSet.new(labels)

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

@@ -14,11 +14,7 @@ module Prometheus
         end
 
         def call(env) # :nodoc:
-          start = Time.now
-          @app.call(env)
-        ensure
-          @requests.increment
-          @requests_duration.increment({}, ((Time.now - start) * 1_000_000).to_i)
+          trace(env) { @app.call(env) }
         end
 
       protected
@@ -26,6 +22,36 @@ module Prometheus
         def init_metrics
           @requests = @registry.counter(:http_requests_total, 'A counter of the total number of HTTP requests made')
           @requests_duration = @registry.counter(:http_request_durations_total_microseconds, 'The total amount of time Rack has spent answering HTTP requests (microseconds).')
+          @durations = @registry.summary(:http_request_durations_microseconds, 'A histogram of the response latency for requests made (microseconds).')
+        end
+
+        def trace(env, &block)
+          start = Time.now
+          response = yield
+        rescue => exception
+          raise
+        ensure
+          duration = ((Time.now - start) * 1_000_000).to_i
+          record(duration, env, response, exception)
+        end
+
+        def record(duration, env, response, exception)
+          labels = {
+            :method => env['REQUEST_METHOD'].downcase,
+            :path   => env['PATH_INFO'].to_s,
+          }
+
+          if response
+            labels[:code] = response.first.to_s
+          else
+            labels[:exception] = exception.class.name
+          end
+
+          @requests.increment(labels)
+          @requests_duration.increment(labels, duration)
+          @durations.add(labels, duration)
+        rescue => error
+          # TODO: log unexpected exception during request recording
         end
 
       end

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

@@ -6,10 +6,14 @@ module Prometheus
       class Exporter
         attr_reader :app, :registry, :path
 
+        API_VERSION  = '0.0.2'
+        CONTENT_TYPE = 'application/json; schema="prometheus/telemetry"; version=' + API_VERSION
+        HEADERS      = { 'Content-Type' => CONTENT_TYPE }
+
         def initialize(app, options = {})
           @app = app
           @registry = options[:registry] || Client.registry
-          @path = options[:path] || '/metrics.json'
+          @path = options[:path] || '/metrics'
         end
 
         def call(env)
@@ -23,13 +27,7 @@ module Prometheus
       protected
 
         def metrics_response
-          json = @registry.to_json
-          headers = {
-            'Content-Type' => 'application/json',
-            'Content-Length' => json.size.to_s
-          }
-
-          [200, headers, [json]]
+          [200, HEADERS, [@registry.to_json]]
         end
 
       end

data/lib/prometheus/client/registry.rb

@@ -3,6 +3,7 @@ require 'thread'
 
 require 'prometheus/client/container'
 require 'prometheus/client/counter'
+require 'prometheus/client/summary'
 require 'prometheus/client/gauge'
 
 module Prometheus
@@ -36,6 +37,10 @@ module Prometheus
         register(name, docstring, Counter.new, base_labels).metric
       end
 
+      def summary(name, docstring, base_labels = {})
+        register(name, docstring, Summary.new, base_labels).metric
+      end
+
       def gauge(name, docstring, base_labels = {})
         register(name, docstring, Gauge.new, base_labels).metric
       end

data/lib/prometheus/client/summary.rb

@@ -0,0 +1,36 @@
+require 'quantile'
+require 'prometheus/client/metric'
+
+module Prometheus
+  module Client
+    class Summary < Metric
+      def type
+        :histogram
+      end
+
+      # Records a given value.
+      def add(labels, value)
+        label_set = label_set_for(labels)
+        synchronize { @values[label_set].observe(value) }
+      end
+
+      # Returns the value for the given label set
+      def get(labels = {})
+        synchronize do
+          estimator = @values[label_set_for(labels)]
+          estimator.invariants.inject({}) do |memo, invariant|
+            memo[invariant.quantile] = estimator.query(invariant.quantile)
+            memo
+          end
+        end
+      end
+
+    private
+
+      def default
+        Quantile::Estimator.new
+      end
+
+    end
+  end
+end

data/lib/prometheus/client/version.rb

@@ -1,5 +1,5 @@
 module Prometheus
   module Client
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

metadata

@@ -1,15 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: prometheus-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
+  prerelease: 
 platform: ruby
 authors:
 - Tobias Schmidt
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-05 00:00:00.000000000 Z
-dependencies: []
+date: 2013-11-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: quantile
+  requirement: &19137520 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *19137520
 description: 
 email:
 - ts@soundcloud.com
@@ -20,40 +32,40 @@ files:
 - README.md
 - lib/prometheus/client/counter.rb
 - lib/prometheus/client/gauge.rb
-- lib/prometheus/client/histogram/bucket.rb
 - lib/prometheus/client/metric.rb
 - lib/prometheus/client/container.rb
 - lib/prometheus/client/registry.rb
 - lib/prometheus/client/rack/collector.rb
 - lib/prometheus/client/rack/exporter.rb
-- lib/prometheus/client/histogram.rb
 - lib/prometheus/client/version.rb
 - lib/prometheus/client/label_set.rb
+- lib/prometheus/client/summary.rb
 - lib/prometheus/client.rb
 - lib/prometheus.rb
 homepage: https://github.com/prometheus/client_ruby
 licenses:
 - Apache 2.0
-metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.2
+rubygems_version: 1.8.5
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: A suite of instrumentation metric primitives for Ruby that can be exposed
   through a JSON web services interface.
 test_files: []

checksums.yaml

@@ -1,15 +0,0 @@
----
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    OTQ3NjhkOGY4ZjA3Zjg0MDZiNWIyMjc1MDc2YmZmMjI5Y2IxMGIxYg==
-  data.tar.gz: !binary |-
-    ZjBhYjc4OTA2YWIxNzdjYmY5YjNjYTYwM2I2ZDBiMjJiNTc1NTEwOA==
-SHA512:
-  metadata.gz: !binary |-
-    MTFlNDlkZDZhNjA1ZGE4M2EzN2Q2NTQ2M2M3N2E5NGZkOWFmNjg0YzEyZmQy
-    NGRiNDgyNTVhMDU1ODkzMmUzYjBhN2E1MjNkNDc4M2ExMjVjY2ZjMmVkMWU5
-    MDZmMThkMjE4ZGE1MzNiZDcwMWUxMjU3N2EzOGJmNmRiMWJkZTI=
-  data.tar.gz: !binary |-
-    YWE3ZWI4MmU4MjUyOTkyMjk3MWRkMzNkYWIxZTc4MDUxMWQ0OTk0NzIxZTNl
-    OTMzNGIxNTkxOTgyNDc3ODczM2E2ODM0YjM2MTFhYTIzZjdjOTRhMDI0N2Yy
-    ODkzNTQyYTg4MjcwMmM4OTdmNDcyNzgzOTZkYmNlMGFiOTQ4MzM=

data/lib/prometheus/client/histogram.rb

@@ -1,19 +0,0 @@
-require 'prometheus/client/metric'
-
-module Prometheus
-  module Client
-    class Histogram < Metric
-      def type
-        :histogram
-      end
-
-      def add(labels, timing)
-        raise NotImplementedError
-      end
-
-      def measure(labels, &block)
-        raise NotImplementedError
-      end
-    end
-  end
-end

data/lib/prometheus/client/histogram/bucket.rb

@@ -1,19 +0,0 @@
-module Prometheus
-  module Client
-    class Histogram
-      class Bucket
-        attr_reader :observations
-
-        def initialize
-          @observations = 0
-          @timings = []
-        end
-
-        def add(timing)
-          # TODO: mutex
-          @timmings << timing
-        end
-      end
-    end
-  end
-end