prometheus-client-mmap 0.7.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 10577a7fe85f4340b412160d874b2249fb9af895
+  data.tar.gz: c04685b407830ad5d30ed1b2f74980078beca53c
+SHA512:
+  metadata.gz: 114932d1e37c16c689b1dbdf9e9c22c4c0b17e7d3fe554418b37ca2795fc4553e4f821457791d75896fc07832a2a8057d103b93cc23dab23740d1ec1bd20a946
+  data.tar.gz: ba68e2b1367ee698ed3a4895537be822557d12c90402ad3f46bfad847f334f5b511d25eba8808b89ecd994c3bcfce95a246eaf97b46c80dcd1e7cbd8563d9f0b

data/README.md

@@ -0,0 +1,183 @@
+# Prometheus Ruby Client
+
+A suite of instrumentation metric primitives for Ruby that can be exposed
+through a HTTP interface. Intended to be used together with a
+[Prometheus server][1].
+
+[![Gem Version][4]](http://badge.fury.io/rb/prometheus-client)
+[![Build Status][3]](http://travis-ci.org/prometheus/client_ruby)
+[![Dependency Status][5]](https://gemnasium.com/prometheus/client_ruby)
+[![Code Climate][6]](https://codeclimate.com/github/prometheus/client_ruby)
+[![Coverage Status][7]](https://coveralls.io/r/prometheus/client_ruby)
+
+## Usage
+
+### Overview
+
+```ruby
+require 'prometheus/client'
+
+# returns a default registry
+prometheus = Prometheus::Client.registry
+
+# create a new counter metric
+http_requests = Prometheus::Client::Counter.new(:http_requests, 'A counter of HTTP requests made')
+# register the metric
+prometheus.register(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 ([Exporter][9]) and one to trace all HTTP
+requests ([Collector][10]).
+
+It's highly recommended to enable gzip compression for the metrics endpoint,
+for example by including the `Rack::Deflater` middleware.
+
+```ruby
+# config.ru
+
+require 'rack'
+require 'prometheus/client/rack/collector'
+require 'prometheus/client/rack/exporter'
+
+use Rack::Deflater, if: ->(env, status, headers, body) { body.any? && body[0].length > 512 }
+use Prometheus::Client::Rack::Collector
+use Prometheus::Client::Rack::Exporter
+
+run ->(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).
+
+### Pushgateway
+
+The Ruby client can also be used to push its collected metrics to a
+[Pushgateway][8]. This comes in handy with batch jobs or in other scenarios
+where it's not possible or feasible to let a Prometheus server scrape a Ruby
+process.
+
+```ruby
+require 'prometheus/client'
+require 'prometheus/client/push'
+
+prometheus = Prometheus::Client.registry
+# ... 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)
+
+# optional: specify the instance name (instead of IP) and gateway
+Prometheus::Client::Push.new(
+  'my-job', 'instance-name', 'http://example.domain:1234').add(prometheus)
+
+# If you want to replace any previously pushed metrics for a given instance,
+# use the #replace method.
+Prometheus::Client::Push.new('my-batch-job', 'instance').replace(prometheus)
+
+# If you want to delete all previously pushed metrics for a given instance,
+# use the #delete method.
+Prometheus::Client::Push.new('my-batch-job', 'instance').delete
+```
+
+## Metrics
+
+The following metric types are currently supported.
+
+### Counter
+
+Counter is a metric that exposes merely a sum or tally of things.
+
+```ruby
+counter = Prometheus::Client::Counter.new(:service_requests_total, '...')
+
+# increment the counter for a given label set
+counter.increment({ service: 'foo' })
+
+# increment by a given value
+counter.increment({ service: 'bar' }, 5)
+
+# get current value for a given label set
+counter.get({ service: 'bar' })
+# => 5
+```
+
+### Gauge
+
+Gauge is a metric that exposes merely an instantaneous value or some snapshot
+thereof.
+
+```ruby
+gauge = Prometheus::Client::Gauge.new(:room_temperature_celsius, '...')
+
+# set a value
+gauge.set({ room: 'kitchen' }, 21.534)
+
+# retrieve the current value for a given label set
+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 bucket values
+histogram.get({ service: 'users' })
+# => { 0.005 => 3, 0.01 => 15, 0.025 => 18, ..., 2.5 => 42, 5 => 42, 10 = >42 }
+```
+
+### Summary
+
+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(:service_latency_seconds, '...')
+
+# record a value
+summary.observe({ service: 'database' }, Benchmark.realtime { service.call() })
+
+# retrieve the current quantile values
+summary.get({ service: 'database' })
+# => { 0.5 => 0.1233122, 0.9 => 3.4323, 0.99 => 5.3428231 }
+```
+
+## Tests
+
+Install necessary development gems with `bundle install` and run tests with
+rspec:
+
+```bash
+rake
+```
+
+[1]: https://github.com/prometheus/prometheus
+[2]: http://rack.github.io/
+[3]: https://secure.travis-ci.org/prometheus/client_ruby.png?branch=master
+[4]: https://badge.fury.io/rb/prometheus-client.svg
+[5]: https://gemnasium.com/prometheus/client_ruby.svg
+[6]: https://codeclimate.com/github/prometheus/client_ruby.png
+[7]: https://coveralls.io/repos/prometheus/client_ruby/badge.png?branch=master
+[8]: https://github.com/prometheus/pushgateway
+[9]: lib/prometheus/client/rack/exporter.rb
+[10]: lib/prometheus/client/rack/collector.rb

data/lib/prometheus.rb

@@ -0,0 +1,5 @@
+# encoding: UTF-8
+
+# Prometheus is a generic time-series collection and computation server.
+module Prometheus
+end

data/lib/prometheus/client.rb

@@ -0,0 +1,13 @@
+# encoding: UTF-8
+
+require 'prometheus/client/registry'
+
+module Prometheus
+  # Client is a ruby implementation for a Prometheus compatible client.
+  module Client
+    # Returns a default registry object
+    def self.registry
+      @registry ||= Registry.new
+    end
+  end
+end

data/lib/prometheus/client/counter.rb

@@ -0,0 +1,28 @@
+# encoding: UTF-8
+
+require 'prometheus/client/metric'
+require 'prometheus/client/valuetype'
+
+module Prometheus
+  module Client
+    # Counter is a metric that exposes merely a sum or tally of things.
+    class Counter < Metric
+      def type
+        :counter
+      end
+
+      def increment(labels = {}, by = 1)
+        raise ArgumentError, 'increment must be a non-negative number' if by < 0
+
+        label_set = label_set_for(labels)
+        synchronize { @values[label_set].increment(by) }
+      end
+
+      private
+
+      def default(labels)
+        ValueClass.new(type, @name, @name, labels)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,200 @@
+# encoding: UTF-8
+
+require 'prometheus/client/valuetype'
+
+module Prometheus
+  module Client
+    module Formats
+      # Text format is human readable mainly used for manual inspection.
+      module Text
+        MEDIA_TYPE   = 'text/plain'.freeze
+        VERSION      = '0.0.4'.freeze
+        CONTENT_TYPE = "#{MEDIA_TYPE}; version=#{VERSION}".freeze
+
+        METRIC_LINE = '%s%s %s'.freeze
+        TYPE_LINE   = '# TYPE %s %s'.freeze
+        HELP_LINE   = '# HELP %s %s'.freeze
+
+        LABEL     = '%s="%s"'.freeze
+        SEPARATOR = ','.freeze
+        DELIMITER = "\n".freeze
+
+        REGEX   = { doc: /[\n\\]/, label: /[\n\\"]/ }.freeze
+        REPLACE = { "\n" => '\n', '\\' => '\\\\', '"' => '\"' }.freeze
+
+        def self.marshal(registry)
+          lines = []
+
+          registry.metrics.each do |metric|
+            lines << format(TYPE_LINE, metric.name, metric.type)
+            lines << format(HELP_LINE, metric.name, escape(metric.docstring))
+
+            metric.values.each do |label_set, value|
+              representation(metric, label_set, value) { |l| lines << l }
+            end
+          end
+
+          # there must be a trailing delimiter
+          (lines << nil).join(DELIMITER)
+        end
+
+        def self.marshal_multiprocess(path=ENV['prometheus_multiproc_dir'])
+          metrics = {}
+          Dir.glob(File.join(path, "*.db")).each do |f|
+            parts = File.basename(f).split("_")
+            type = parts[0].to_sym
+            d = MmapedDict.new(f)
+            d.all_values.each do |key, value|
+              metric_name, name, labelnames, labelvalues = JSON.parse(key)
+              metric = metrics.fetch(metric_name, {
+                metric_name: metric_name,
+                help: 'Multiprocess metric',
+                type: type,
+                samples: [],
+              })
+              if type == :gauge
+                pid = parts[2][0..-3]
+                metric[:multiprocess_mode] = parts[1]
+                metric[:samples] += [[name, labelnames.zip(labelvalues) + [['pid', pid]], value]]
+              else
+                # The duplicates and labels are fixed in the next for.
+                metric[:samples] += [[name, labelnames.zip(labelvalues), value]]
+              end
+              metrics[metric_name] = metric
+            end
+            d.close
+          end
+
+          metrics.each_value do |metric|
+            samples = {}
+            buckets = {}
+            metric[:samples].each do |name, labels, value|
+              case metric[:type]
+              when :gauge
+                without_pid = labels.select{ |l| l[0] != 'pid' }
+                case metric[:multiprocess_mode]
+                when 'min'
+                  s = samples.fetch([name, without_pid], value)
+                  samples[[name, without_pid]] = [s, value].min
+                when 'max'
+                  s = samples.fetch([name, without_pid], value)
+                  samples[[name, without_pid]] = [s, value].max
+                when 'livesum'
+                  s = samples.fetch([name, without_pid], 0.0)
+                  samples[[name, without_pid]] = s + value
+                else # all/liveall
+                  samples[[name, labels]] = value
+                end
+              when :histogram
+                bucket = labels.select{|l| l[0] == 'le' }.map {|k, v| v.to_f}.first
+                if bucket
+                  without_le = labels.select{ |l| l[0] != 'le' }
+                  b = buckets.fetch(without_le, {})
+                  v = b.fetch(bucket, 0.0) + value
+                  if !buckets.has_key?(without_le)
+                    buckets[without_le] = {}
+                  end
+                  buckets[without_le][bucket] = v
+                else
+                  s = samples.fetch([name, labels], 0.0)
+                  samples[[name, labels]] = s + value
+                end
+              else
+                # Counter and Summary.
+                s = samples.fetch([name, without_pid], 0.0)
+                samples[[name, without_pid]] = s + value
+              end
+
+              if metric[:type] == :histogram
+                buckets.each do |labels, values|
+                  acc = 0.0
+                  values.sort.each do |bucket, value|
+                    acc += value
+                    # TODO: handle Infinity
+                    samples[[metric[:metric_name] + '_bucket', labels + [['le', bucket.to_s]]]] = acc
+                  end
+                  samples[[metric[:metric_name] + '_count', labels]] = acc
+                end
+              end
+
+              metric[:samples] = samples.map do |name_labels, value|
+                name, labels = name_labels
+                [name, labels.to_h, value]
+              end
+            end
+          end
+
+          output = ''
+          metrics.each do |name, metric|
+            output += "# HELP #{name} #{metric[:help]}\n"
+            output += "# TYPE #{name} #{metric[:type].to_s}\n"
+            metric[:samples].each do |metric_name, labels, value|
+              if !labels.empty?
+                labelstr = '{' + labels.sort.map { |k, v| "#{k}='#{v}'" }.join(',') + '}'
+              else
+                labelstr = ''
+              end
+              output += "#{metric_name}#{labelstr} #{value}\n"
+            end
+          end
+          output
+        end
+
+        class << self
+          private
+
+          def representation(metric, label_set, value, &block)
+            set = metric.base_labels.merge(label_set)
+
+            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.get)
+            end
+          end
+
+          def summary(name, set, value)
+            value.each do |q, v|
+              yield metric(name, labels(set.merge(quantile: q)), v.get)
+            end
+
+            l = labels(set)
+            yield metric("#{name}_sum", l, value.sum.get)
+            yield metric("#{name}_count", l, value.total.get)
+          end
+
+          def histogram(name, set, value)
+            value.each do |q, v|
+              yield metric(name, labels(set.merge(le: q)), v.get)
+            end
+            yield metric(name, labels(set.merge(le: '+Inf')), value.total.get)
+
+            l = labels(set)
+            yield metric("#{name}_sum", l, value.sum.get)
+            yield metric("#{name}_count", l, value.total.get)
+          end
+
+          def metric(name, labels, value)
+            format(METRIC_LINE, name, labels, value)
+          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
+
+            "{#{strings.join(SEPARATOR)}}"
+          end
+
+          def escape(string, format = :doc)
+            string.to_s.gsub(REGEX[format], REPLACE)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/prometheus/client/gauge.rb

@@ -0,0 +1,32 @@
+# encoding: UTF-8
+
+require 'prometheus/client/metric'
+
+module Prometheus
+  module Client
+    # A Gauge is a metric that exposes merely an instantaneous value or some
+    # snapshot thereof.
+    class Gauge < Metric
+      def initialize(name, docstring, base_labels = {}, multiprocess_mode=:all)
+        super(name, docstring, base_labels)
+        if ValueClass.multiprocess and ![:min, :max, :livesum, :liveall, :all].include?(multiprocess_mode)
+          raise ArgumentError, 'Invalid multiprocess mode: ' + multiprocess_mode
+        end
+        @multiprocess_mode = multiprocess_mode
+      end
+
+      def type
+        :gauge
+      end
+
+      def default(labels)
+        ValueClass.new(type, @name, @name, labels, @multiprocess_mode)
+      end
+
+      # Sets the value for the given label set
+      def set(labels, value)
+        @values[label_set_for(labels)].set(value)
+      end
+    end
+  end
+end