prometheus-client 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a751a9f1859db76b453a64f74ae033ad6e197ccdd5e868fa72a267f074ea6cb
-  data.tar.gz: 5f68748f976f3c1ce975f950d352c4d015fa021bd1fc93e3dd337cff19bd8d7f
+  metadata.gz: 26ff1f489c371d04487bbd7fe478ac70f43ed79f7c462d18b46d9475136f63f4
+  data.tar.gz: ddc03d2b15acfa3bf44ebc4661dd7653c2fd45a951d8ef2e2b015469a73d89c1
 SHA512:
-  metadata.gz: beb6e41e1a0fb2a269977646022a1ff055c17087a9736732f53df8ee6dedf3e14257c32584f756980148aeea0cc00635fc5d40c2730ef90b1a39dc5755c9798e
-  data.tar.gz: 34c04abc96d1059ff55a4284e33d5a621ec9f76a12325c41ec92ef7650d3deb5ed91bc19eb55124cae54ed904c48779196fc34577a72ed28e24778b07f88c99a
+  metadata.gz: 54dc0dedfb667d7bf49c909fdf043209b5508473876b6d5df019db192dd5d788397424972e5ba8c6eab6e4162940bff1d43313dc8ea12379d84018b910840044
+  data.tar.gz: 98d74089ed076100bc845721c318944bd620b19a9228405b0160d81c248ea6023eab79c60019eea661c92ace20e7f59cc05b237f6bbbe43fd27500427242dd5a

data/README.md

@@ -158,6 +158,11 @@ histogram.get(labels: { service: 'users' })
 # => { 0.005 => 3, 0.01 => 15, 0.025 => 18, ..., 2.5 => 42, 5 => 42, 10 = >42 }
 ```
 
+Histograms provide default buckets of `[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]`
+
+You can specify your own buckets, either explicitly, or using the `Histogram.linear_buckets`
+or `Histogram.exponential_buckets` methods to define regularly spaced buckets.
+
 ### Summary
 
 Summary, similar to histograms, is an accumulator for samples. It captures
@@ -320,9 +325,9 @@ When instantiating metrics, there is an optional `store_settings` attribute. Thi
 to set up store-specific settings for each metric. For most stores, this is not used, but
 for multi-process stores, this is used to specify how to aggregate the values of each
 metric across multiple processes. For the most part, this is used for Gauges, to specify
-whether you want to report the `SUM`, `MAX` or `MIN` value observed across all processes.
-For almost all other cases, you'd leave the default (`SUM`). More on this on the 
-*Aggregation* section below.
+whether you want to report the `SUM`, `MAX`, `MIN`, or `MOST_RECENT` value observed across
+all processes. For almost all other cases, you'd leave the default (`SUM`). More on this
+on the *Aggregation* section below.
 
 Custom stores may also accept extra parameters besides `:aggregation`. See the
 documentation of each store for more details.
@@ -355,8 +360,11 @@ use case, you may need to control how this works. When using this store,
 each Metric allows you to specify an `:aggregation` setting, defining how
 to aggregate the multiple possible values we can get for each labelset. By default,
 Counters, Histograms and Summaries are `SUM`med, and Gauges report all their values (one
-for each process), tagged with a `pid` label. You can also select `SUM`, `MAX` or `MIN`
-for your gauges, depending on your use case.
+for each process), tagged with a `pid` label. You can also select `SUM`, `MAX`, `MIN`, or
+`MOST_RECENT` for your gauges, depending on your use case.
+
+Please note that that the `MOST_RECENT` aggregation only works for gauges, and it does not
+allow the use of `increment` / `decrement`, you can only use `set`. 
 
 **Memory Usage**: When scraped by Prometheus, this store will read all these files, get all
 the values and aggregate them. We have notice this can have a noticeable effect on memory
@@ -368,6 +376,19 @@ you store your metric files (specified when initializing the `DirectFileStore`)
 when your app starts. Otherwise, each app run will continue exporting the metrics from the 
 previous run.  
 
+If you have this issue, one way to do this is to run code similar to this as part of you
+initialization:
+
+```ruby
+Dir["#{app_path}/tmp/prometheus/*.bin"].each do |file_path|
+  File.unlink(file_path)
+end
+```
+
+If you are running in pre-fork servers (such as Unicorn or Puma with multiple processes),
+make sure you do this **before** the server forks. Otherwise, each child process may delete
+files created by other processes on *this* run, instead of deleting old files.
+
 **Large numbers of files**: Because there is an individual file per metric and per process 
 (which is done to optimize for observation performance), you may end up with a large number 
 of files. We don't currently have a solution for this problem, but we're working on it.

data/lib/prometheus/client/data_stores/direct_file_store.rb

@@ -29,7 +29,7 @@ module Prometheus
 
       class DirectFileStore
         class InvalidStoreSettingsError < StandardError; end
-        AGGREGATION_MODES = [MAX = :max, MIN = :min, SUM = :sum, ALL = :all]
+        AGGREGATION_MODES = [MAX = :max, MIN = :min, SUM = :sum, ALL = :all, MOST_RECENT = :most_recent]
         DEFAULT_METRIC_SETTINGS = { aggregation: SUM }
         DEFAULT_GAUGE_SETTINGS = { aggregation: ALL }
 
@@ -45,7 +45,7 @@ module Prometheus
           end
 
           settings = default_settings.merge(metric_settings)
-          validate_metric_settings(settings)
+          validate_metric_settings(metric_type, settings)
 
           MetricStore.new(metric_name: metric_name,
                           store_settings: @store_settings,
@@ -54,7 +54,7 @@ module Prometheus
 
         private
 
-        def validate_metric_settings(metric_settings)
+        def validate_metric_settings(metric_type, metric_settings)
           unless metric_settings.has_key?(:aggregation) &&
             AGGREGATION_MODES.include?(metric_settings[:aggregation])
             raise InvalidStoreSettingsError,
@@ -65,6 +65,11 @@ module Prometheus
             raise InvalidStoreSettingsError,
                   "Only :aggregation setting can be specified"
           end
+
+          if metric_settings[:aggregation] == MOST_RECENT && metric_type != :gauge
+            raise InvalidStoreSettingsError,
+                  "Only :gauge metrics support :most_recent aggregation"
+          end
         end
 
         class MetricStore
@@ -74,6 +79,7 @@ module Prometheus
             @metric_name = metric_name
             @store_settings = store_settings
             @values_aggregation_mode = metric_settings[:aggregation]
+            @store_opened_by_pid = nil
 
             @lock = Monitor.new
           end
@@ -100,6 +106,12 @@ module Prometheus
           end
 
           def increment(labels:, by: 1)
+            if @values_aggregation_mode == DirectFileStore::MOST_RECENT
+              raise InvalidStoreSettingsError,
+                    "The :most_recent aggregation does not support the use of increment"\
+                      "/decrement"
+            end
+
             key = store_key(labels)
             in_process_sync do
               value = internal_store.read_value(key)
@@ -121,7 +133,7 @@ module Prometheus
             stores_for_metric.each do |file_path|
               begin
                 store = FileMappedDict.new(file_path, true)
-                store.all_values.each do |(labelset_qs, v)|
+                store.all_values.each do |(labelset_qs, v, ts)|
                   # Labels come as a query string, and CGI::parse returns arrays for each key
                   # "foo=bar&x=y" => { "foo" => ["bar"], "x" => ["y"] }
                   # Turn the keys back into symbols, and remove the arrays
@@ -129,7 +141,7 @@ module Prometheus
                     [k.to_sym, vs.first]
                   end.to_h
 
-                  stores_data[label_set] << v
+                  stores_data[label_set] << [v, ts]
                 end
               ensure
                 store.close if store
@@ -181,30 +193,41 @@ module Prometheus
           end
 
           def aggregate_values(values)
-            if @values_aggregation_mode == SUM
-              values.inject { |sum, element| sum + element }
-            elsif @values_aggregation_mode == MAX
-              values.max
-            elsif @values_aggregation_mode == MIN
-              values.min
-            elsif @values_aggregation_mode == ALL
-              values.first
+            # Each entry in the `values` array is a tuple of `value` and `timestamp`,
+            # so for all aggregations except `MOST_RECENT`, we need to only take the
+            # first value in each entry and ignore the second.
+            if @values_aggregation_mode == MOST_RECENT
+              latest_tuple = values.max { |a,b| a[1] <=> b[1] }
+              latest_tuple.first # return the value without the timestamp
             else
-              raise InvalidStoreSettingsError,
-                    "Invalid Aggregation Mode: #{ @values_aggregation_mode }"
+              values = values.map(&:first) # Discard timestamps
+
+              if @values_aggregation_mode == SUM
+                values.inject { |sum, element| sum + element }
+              elsif @values_aggregation_mode == MAX
+                values.max
+              elsif @values_aggregation_mode == MIN
+                values.min
+              elsif @values_aggregation_mode == ALL
+                values.first
+              else
+                raise InvalidStoreSettingsError,
+                      "Invalid Aggregation Mode: #{ @values_aggregation_mode }"
+              end
             end
           end
         end
 
         private_constant :MetricStore
 
-        # A dict of doubles, backed by an file we access directly a a byte array.
+        # A dict of doubles, backed by an file we access directly as a byte array.
         #
         # The file starts with a 4 byte int, indicating how much of it is used.
         # Then 4 bytes of padding.
         # There's then a number of entries, consisting of a 4 byte int which is the
         # size of the next field, a utf-8 encoded string key, padding to an 8 byte
-        # alignment, and then a 8 byte float which is the value.
+        # alignment, and then a 8 byte float which is the value, and then a 8 byte
+        # float which is the unix timestamp when the value was set.
         class FileMappedDict
           INITIAL_FILE_SIZE = 1024*1024
 
@@ -235,8 +258,8 @@ module Prometheus
             with_file_lock do
               @positions.map do |key, pos|
                 @f.seek(pos)
-                value = @f.read(8).unpack('d')[0]
-                [key, value]
+                value, timestamp = @f.read(16).unpack('dd')
+                [key, value, timestamp]
               end
             end
           end
@@ -256,9 +279,10 @@ module Prometheus
               init_value(key)
             end
 
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
             pos = @positions[key]
             @f.seek(pos)
-            @f.write([value].pack('d'))
+            @f.write([value, now].pack('dd'))
             @f.flush
           end
 
@@ -299,7 +323,7 @@ module Prometheus
           def init_value(key)
             # Pad to be 8-byte aligned.
             padded = key + (' ' * (8 - (key.length + 4) % 8))
-            value = [padded.length, padded, 0.0].pack("lA#{padded.length}d")
+            value = [padded.length, padded, 0.0, 0.0].pack("lA#{padded.length}dd")
             while @used + value.length > @capacity
               @capacity *= 2
               resize_file(@capacity)
@@ -310,7 +334,7 @@ module Prometheus
             @f.seek(0)
             @f.write([@used].pack('l'))
             @f.flush
-            @positions[key] = @used - 8
+            @positions[key] = @used - 16
           end
 
           # Read position of all keys. No locking is performed.
@@ -320,7 +344,7 @@ module Prometheus
               padded_len = @f.read(4).unpack('l')[0]
               key = @f.read(padded_len).unpack("A#{padded_len}")[0].strip
               @positions[key] = @f.pos
-              @f.seek(8, :CUR)
+              @f.seek(16, :CUR)
             end
           end
         end

data/lib/prometheus/client/histogram.rb

@@ -33,6 +33,14 @@ module Prometheus
               store_settings: store_settings)
       end
 
+      def self.linear_buckets(start:, width:, count:)
+        count.times.map { |idx| start.to_f + idx * width }
+      end
+
+      def self.exponential_buckets(start:, factor: 2, count:)
+        count.times.map { |idx| start.to_f * factor ** idx }
+      end
+
       def with_labels(labels)
         self.class.new(name,
                        docstring: docstring,
@@ -81,15 +89,15 @@ module Prometheus
 
       # Returns all label sets with their values expressed as hashes with their buckets
       def values
-        v = @store.all_values
+        values = @store.all_values
 
-        result = v.each_with_object({}) do |(label_set, v), acc|
+        result = values.each_with_object({}) do |(label_set, v), acc|
           actual_label_set = label_set.reject{|l| l == :le }
           acc[actual_label_set] ||= @buckets.map{|b| [b.to_s, 0.0]}.to_h
           acc[actual_label_set][label_set[:le].to_s] = v
         end
 
-        result.each do |(label_set, v)|
+        result.each do |(_label_set, v)|
           accumulate_buckets(v)
         end
       end

data/lib/prometheus/client/metric.rb

@@ -29,16 +29,17 @@ module Prometheus
         @docstring = docstring
         @preset_labels = stringify_values(preset_labels)
 
+        @all_labels_preset = false
+        if preset_labels.keys.length == labels.length
+          @validator.validate_labelset!(preset_labels)
+          @all_labels_preset = true
+        end
+
         @store = Prometheus::Client.config.data_store.for_metric(
           name,
           metric_type: type,
           metric_settings: store_settings
         )
-
-        if preset_labels.keys.length == labels.length
-          @validator.validate_labelset!(preset_labels)
-          @all_labels_preset = true
-        end
       end
 
       # Returns the value for the given label set

data/lib/prometheus/client/push.rb

@@ -66,9 +66,9 @@ module Prometheus
 
       def build_path(job, instance)
         if instance
-          format(INSTANCE_PATH, URI.escape(job), URI.escape(instance))
+          format(INSTANCE_PATH, CGI::escape(job), CGI::escape(instance))
         else
-          format(PATH, URI.escape(job))
+          format(PATH, CGI::escape(job))
         end
       end
 

data/lib/prometheus/client/summary.rb

@@ -36,9 +36,9 @@ module Prometheus
 
       # Returns all label sets with their values expressed as hashes with their sum/count
       def values
-        v = @store.all_values
+        values = @store.all_values
 
-        v.each_with_object({}) do |(label_set, v), acc|
+        values.each_with_object({}) do |(label_set, v), acc|
           actual_label_set = label_set.reject{|l| l == :quantile }
           acc[actual_label_set] ||= { "count" => 0.0, "sum" => 0.0 }
           acc[actual_label_set][label_set[:quantile]] = v

data/lib/prometheus/client/version.rb

@@ -2,6 +2,6 @@
 
 module Prometheus
   module Client
-    VERSION = '2.0.0'
+    VERSION = '2.1.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prometheus-client
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Ben Kochie
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-28 00:00:00.000000000 Z
+date: 2020-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
@@ -88,8 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: A suite of instrumentation metric primitivesthat can be exposed through a