prometheus-client 2.1.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26ff1f489c371d04487bbd7fe478ac70f43ed79f7c462d18b46d9475136f63f4
-  data.tar.gz: ddc03d2b15acfa3bf44ebc4661dd7653c2fd45a951d8ef2e2b015469a73d89c1
+  metadata.gz: b7017e1e3c284f9558d758e91d4855ad97b5df63fdef115cee035aa0948aed30
+  data.tar.gz: 52a7abaadf1addf7bf9303d73a31a14338429882b488eb80c2144a6817cfdb7d
 SHA512:
-  metadata.gz: 54dc0dedfb667d7bf49c909fdf043209b5508473876b6d5df019db192dd5d788397424972e5ba8c6eab6e4162940bff1d43313dc8ea12379d84018b910840044
-  data.tar.gz: 98d74089ed076100bc845721c318944bd620b19a9228405b0160d81c248ea6023eab79c60019eea661c92ace20e7f59cc05b237f6bbbe43fd27500427242dd5a
+  metadata.gz: 1e3b2ff9368dacbdc175ea8cb709e1ad7be73b0d8e644468f65bf36f44b517798a28d7f5dab73b538519fc1a918f977e083e101986a761fdf2fe42ab719fcc1d
+  data.tar.gz: 7fb5a1887a88f7687f2af5ef4839e26030da25cc0c51a03445bbb43706caf8d2231c65108cf3265cc024bc286d5dc8a38ec5d29145b39b2f0cbd0277f29f1972

data/README.md

@@ -5,8 +5,7 @@ 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)
-[![Coverage Status][7]](https://coveralls.io/r/prometheus/client_ruby)
+[![Build Status][3]](https://circleci.com/gh/prometheus/client_ruby/tree/master.svg?style=svg)
 
 ## Usage
 
@@ -71,7 +70,7 @@ integrated [example application](examples/rack/README.md).
 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. TLS and basic access authentication are supported.
+process. TLS and HTTP basic authentication are supported.
 
 ```ruby
 require 'prometheus/client'
@@ -81,18 +80,59 @@ registry = 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(registry)
+Prometheus::Client::Push.new(job: 'my-batch-job').add(registry)
+
+# optional: specify a grouping key that uniquely identifies a job instance, and gateway.
+#
+# Note: the labels you use in the grouping key must not conflict with labels set on the
+# metrics being pushed. If they do, an error will be raised.
+Prometheus::Client::Push.new(
+  job: 'my-batch-job',
+  gateway: 'https://example.domain:1234',
+  grouping_key: { instance: 'some-instance', extra_key: 'foobar' }
+).add(registry)
+
+# If you want to replace any previously pushed metrics for a given grouping key,
+# use the #replace method.
+#
+# Unlike #add, this will completely replace the metrics under the specified grouping key
+# (i.e. anything currently present in the pushgateway for the specified grouping key, but
+# not present in the registry for that grouping key will be removed).
+#
+# See https://github.com/prometheus/pushgateway#put-method for a full explanation.
+Prometheus::Client::Push.new(job: 'my-batch-job').replace(registry)
+
+# If you want to delete all previously pushed metrics for a given grouping key,
+# use the #delete method.
+Prometheus::Client::Push.new(job: 'my-batch-job').delete
+```
 
-# optional: specify the instance name (instead of IP) and gateway.
-Prometheus::Client::Push.new('my-batch-job', 'foobar', 'https://example.domain:1234').add(registry)
+#### Basic authentication
 
-# If you want to replace any previously pushed metrics for a given instance,
-# use the #replace method.
-Prometheus::Client::Push.new('my-batch-job').replace(registry)
+By design, `Prometheus::Client::Push` doesn't read credentials for HTTP basic
+authentication when they are passed in via the gateway URL using the
+`http://user:password@example.com:9091` syntax, and will in fact raise an error if they're
+supplied that way.
 
-# If you want to delete all previously pushed metrics for a given instance,
-# use the #delete method.
-Prometheus::Client::Push.new('my-batch-job').delete
+The reason for this is that when using that syntax, the username and password
+have to follow the usual rules for URL encoding of characters [per RFC
+3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1).
+
+Rather than place the burden of correctly performing that encoding on users of this gem,
+we decided to have a separate method for supplying HTTP basic authentication credentials,
+with no requirement to URL encode the characters in them.
+
+Instead of passing credentials like this:
+
+```ruby
+push = Prometheus::Client::Push.new(job: "my-job", gateway: "http://user:password@localhost:9091")
+```
+
+please pass them like this:
+
+```ruby
+push = Prometheus::Client::Push.new(job: "my-job", gateway: "http://localhost:9091")
+push.basic_auth("user", "password")
 ```
 
 ## Metrics
@@ -389,6 +429,17 @@ If you are running in pre-fork servers (such as Unicorn or Puma with multiple pr
 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.
 
+**Declare metrics before fork**: As well as deleting files before your process forks, you
+should make sure to declare your metrics before forking too. Because the metric registry
+is held in memory, any metrics declared after forking will only be present in child
+processes where the code declaring them ran, and as a result may not be consistently
+exported when scraped (i.e. they will only appear when a child process that declared them
+is scraped).
+
+If you're absolutely sure that every child process will run the metric declaration code,
+then you won't run into this issue, but the simplest approach is to declare the metrics
+before forking.
+
 **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/histogram.rb

@@ -6,7 +6,7 @@ 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.
+    # provides a total count and sum of all observed values.
     class Histogram < Metric
       # DEFAULT_BUCKETS are the default Histogram buckets. The default buckets
       # are tailored to broadly measure the response time (in seconds) of a
@@ -42,18 +42,30 @@ module Prometheus
       end
 
       def with_labels(labels)
-        self.class.new(name,
-                       docstring: docstring,
-                       labels: @labels,
-                       preset_labels: preset_labels.merge(labels),
-                       buckets: @buckets,
-                       store_settings: @store_settings)
+        new_metric = self.class.new(name,
+                                    docstring: docstring,
+                                    labels: @labels,
+                                    preset_labels: preset_labels.merge(labels),
+                                    buckets: @buckets,
+                                    store_settings: @store_settings)
+
+        # The new metric needs to use the same store as the "main" declared one, otherwise
+        # any observations on that copy with the pre-set labels won't actually be exported.
+        new_metric.replace_internal_store(@store)
+
+        new_metric
       end
 
       def type
         :histogram
       end
 
+      # Records a given value. The recorded value is usually positive
+      # or zero. A negative value is accepted but prevents current
+      # versions of Prometheus from properly detecting counter resets
+      # in the sum of observations. See
+      # https://prometheus.io/docs/practices/histograms/#count-and-sum-of-observations
+      # for details.
       def observe(value, labels: {})
         bucket = buckets.find {|upper_limit| upper_limit >= value  }
         bucket = "+Inf" if bucket.nil?

data/lib/prometheus/client/label_set_validator.rb

@@ -7,6 +7,7 @@ module Prometheus
     class LabelSetValidator
       # TODO: we might allow setting :instance in the future
       BASE_RESERVED_LABELS = [:job, :instance, :pid].freeze
+      LABEL_NAME_REGEX = /\A[a-zA-Z_][a-zA-Z0-9_]*\Z/
 
       class LabelSetError < StandardError; end
       class InvalidLabelSetError < LabelSetError; end
@@ -59,9 +60,15 @@ module Prometheus
       end
 
       def validate_name(key)
-        return true unless key.to_s.start_with?('__')
+        if key.to_s.start_with?('__')
+          raise ReservedLabelError, "label #{key} must not start with __"
+        end
+
+        unless key.to_s =~ LABEL_NAME_REGEX
+          raise InvalidLabelError, "label name must match /#{LABEL_NAME_REGEX}/"
+        end
 
-        raise ReservedLabelError, "label #{key} must not start with __"
+        true
       end
 
       def validate_reserved_key(key)

data/lib/prometheus/client/metric.rb

@@ -7,7 +7,7 @@ module Prometheus
   module Client
     # Metric
     class Metric
-      attr_reader :name, :docstring, :preset_labels
+      attr_reader :name, :docstring, :labels, :preset_labels
 
       def initialize(name,
                      docstring:,
@@ -40,8 +40,17 @@ module Prometheus
           metric_type: type,
           metric_settings: store_settings
         )
+
+        # WARNING: Our internal store can be replaced later by `with_labels`
+        # Everything we do after this point needs to still work if @store gets replaced
+        init_label_set({}) if labels.empty?
+      end
+
+      protected def replace_internal_store(new_store)
+        @store = new_store
       end
 
+
       # Returns the value for the given label set
       def get(labels: {})
         label_set = label_set_for(labels)
@@ -49,11 +58,17 @@ module Prometheus
       end
 
       def with_labels(labels)
-        self.class.new(name,
-                       docstring: docstring,
-                       labels: @labels,
-                       preset_labels: preset_labels.merge(labels),
-                       store_settings: @store_settings)
+        new_metric = self.class.new(name,
+                                     docstring: docstring,
+                                     labels: @labels,
+                                     preset_labels: preset_labels.merge(labels),
+                                     store_settings: @store_settings)
+
+        # The new metric needs to use the same store as the "main" declared one, otherwise
+        # any observations on that copy with the pre-set labels won't actually be exported.
+        new_metric.replace_internal_store(@store)
+
+        new_metric
       end
 
       def init_label_set(labels)

data/lib/prometheus/client/push.rb

@@ -1,11 +1,15 @@
 # encoding: UTF-8
 
+require 'base64'
 require 'thread'
 require 'net/http'
 require 'uri'
+require 'erb'
+require 'set'
 
 require 'prometheus/client'
 require 'prometheus/client/formats/text'
+require 'prometheus/client/label_set_validator'
 
 module Prometheus
   # Client is a ruby implementation for a Prometheus compatible client.
@@ -13,23 +17,41 @@ module Prometheus
     # Push implements a simple way to transmit a given registry to a given
     # Pushgateway.
     class Push
+      class HttpError < StandardError; end
+      class HttpRedirectError < HttpError; end
+      class HttpClientError < HttpError; end
+      class HttpServerError < HttpError; end
+
       DEFAULT_GATEWAY = 'http://localhost:9091'.freeze
       PATH            = '/metrics/job/%s'.freeze
-      INSTANCE_PATH   = '/metrics/job/%s/instance/%s'.freeze
       SUPPORTED_SCHEMES = %w(http https).freeze
 
-      attr_reader :job, :instance, :gateway, :path
+      attr_reader :job, :gateway, :path
+
+      def initialize(job:, gateway: DEFAULT_GATEWAY, grouping_key: {}, **kwargs)
+        raise ArgumentError, "job cannot be nil" if job.nil?
+        raise ArgumentError, "job cannot be empty" if job.empty?
+        @validator = LabelSetValidator.new(expected_labels: grouping_key.keys)
+        @validator.validate_symbols!(grouping_key)
 
-      def initialize(job, instance = nil, gateway = nil)
         @mutex = Mutex.new
         @job = job
-        @instance = instance
         @gateway = gateway || DEFAULT_GATEWAY
-        @path = build_path(job, instance)
+        @grouping_key = grouping_key
+        @path = build_path(job, grouping_key)
+
         @uri = parse("#{@gateway}#{@path}")
+        validate_no_basic_auth!(@uri)
 
         @http = Net::HTTP.new(@uri.host, @uri.port)
         @http.use_ssl = (@uri.scheme == 'https')
+        @http.open_timeout = kwargs[:open_timeout] if kwargs[:open_timeout]
+        @http.read_timeout = kwargs[:read_timeout] if kwargs[:read_timeout]
+      end
+
+      def basic_auth(user, password)
+        @user = user
+        @password = password
       end
 
       def add(registry)
@@ -64,26 +86,118 @@ module Prometheus
         raise ArgumentError, "#{url} is not a valid URL: #{e}"
       end
 
-      def build_path(job, instance)
-        if instance
-          format(INSTANCE_PATH, CGI::escape(job), CGI::escape(instance))
-        else
-          format(PATH, CGI::escape(job))
+      def build_path(job, grouping_key)
+        path = format(PATH, ERB::Util::url_encode(job))
+
+        grouping_key.each do |label, value|
+          if value.include?('/')
+            encoded_value = Base64.urlsafe_encode64(value)
+            path += "/#{label}@base64/#{encoded_value}"
+          # While it's valid for the urlsafe_encode64 function to return an
+          # empty string when the input string is empty, it doesn't work for
+          # our specific use case as we're putting the result into a URL path
+          # segment. A double slash (`//`) can be normalised away by HTTP
+          # libraries, proxies, and web servers.
+          #
+          # For empty strings, we use a single padding character (`=`) as the
+          # value.
+          #
+          # See the pushgateway docs for more details:
+          #
+          # https://github.com/prometheus/pushgateway/blob/6393a901f56d4dda62cd0f6ab1f1f07c495b6354/README.md#url
+          elsif value.empty?
+            path += "/#{label}@base64/="
+          else
+            path += "/#{label}/#{ERB::Util::url_encode(value)}"
+          end
         end
+
+        path
       end
 
       def request(req_class, registry = nil)
+        validate_no_label_clashes!(registry) if registry
+
         req = req_class.new(@uri)
         req.content_type = Formats::Text::CONTENT_TYPE
-        req.basic_auth(@uri.user, @uri.password) if @uri.user
+        req.basic_auth(@user, @password) if @user
         req.body = Formats::Text.marshal(registry) if registry
 
-        @http.request(req)
+        response = @http.request(req)
+        validate_response!(response)
+
+        response
       end
 
       def synchronize
         @mutex.synchronize { yield }
       end
+
+      def validate_no_basic_auth!(uri)
+        if uri.user || uri.password
+          raise ArgumentError, <<~EOF
+            Setting Basic Auth credentials in the gateway URL is not supported, please call the `basic_auth` method.
+
+            Received username `#{uri.user}` in gateway URL. Instead of passing
+            Basic Auth credentials like this:
+
+            ```
+            push = Prometheus::Client::Push.new(job: "my-job", gateway: "http://user:password@localhost:9091")
+            ```
+
+            please pass them like this:
+
+            ```
+            push = Prometheus::Client::Push.new(job: "my-job", gateway: "http://localhost:9091")
+            push.basic_auth("user", "password")
+            ```
+
+            While URLs do support passing Basic Auth credentials using the
+            `http://user:password@example.com/` syntax, the username and
+            password in that syntax have to follow the usual rules for URL
+            encoding of characters per RFC 3986
+            (https://datatracker.ietf.org/doc/html/rfc3986#section-2.1).
+
+            Rather than place the burden of correctly performing that encoding
+            on users of this gem, we decided to have a separate method for
+            supplying Basic Auth credentials, with no requirement to URL encode
+            the characters in them.
+          EOF
+        end
+      end
+
+      def validate_no_label_clashes!(registry)
+        # There's nothing to check if we don't have a grouping key
+        return if @grouping_key.empty?
+
+        # We could be doing a lot of comparisons, so let's do them against a
+        # set rather than an array
+        grouping_key_labels = @grouping_key.keys.to_set
+
+        registry.metrics.each do |metric|
+          metric.labels.each do |label|
+            if grouping_key_labels.include?(label)
+              raise LabelSetValidator::InvalidLabelSetError,
+                "label :#{label} from grouping key collides with label of the " \
+                "same name from metric :#{metric.name} and would overwrite it"
+            end
+          end
+        end
+      end
+
+      def validate_response!(response)
+        status = Integer(response.code)
+        if status >= 300
+          message = "status: #{response.code}, message: #{response.message}, body: #{response.body}"
+          if status <= 399
+            raise HttpRedirectError, message
+          elsif status <= 499
+            raise HttpClientError, message
+          else
+            raise HttpServerError, message
+          end
+        end
+      end
     end
   end
 end

data/lib/prometheus/client/registry.rb

@@ -22,7 +22,7 @@ module Prometheus
         name = metric.name
 
         @mutex.synchronize do
-          if exist?(name.to_sym)
+          if @metrics.key?(name.to_sym)
             raise AlreadyRegisteredError, "#{name} has already been registered"
           end
           @metrics[name.to_sym] = metric
@@ -73,15 +73,15 @@ module Prometheus
       end
 
       def exist?(name)
-        @metrics.key?(name)
+        @mutex.synchronize { @metrics.key?(name) }
       end
 
       def get(name)
-        @metrics[name.to_sym]
+        @mutex.synchronize { @metrics[name.to_sym] }
       end
 
       def metrics
-        @metrics.values
+        @mutex.synchronize { @metrics.values }
       end
     end
   end

data/lib/prometheus/client/summary.rb

@@ -11,7 +11,12 @@ module Prometheus
         :summary
       end
 
-      # Records a given value.
+      # Records a given value. The recorded value is usually positive
+      # or zero. A negative value is accepted but prevents current
+      # versions of Prometheus from properly detecting counter resets
+      # in the sum of observations. See
+      # https://prometheus.io/docs/practices/histograms/#count-and-sum-of-observations
+      # for details.
       def observe(value, labels: {})
         base_label_set = label_set_for(labels)
 

data/lib/prometheus/client/version.rb

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

data/lib/prometheus/middleware/collector.rb

@@ -67,15 +67,17 @@ module Prometheus
       end
 
       def record(env, code, duration)
+        path = generate_path(env)
+
         counter_labels = {
           code:   code,
           method: env['REQUEST_METHOD'].downcase,
-          path:   strip_ids_from_path(env['PATH_INFO']),
+          path:   strip_ids_from_path(path),
         }
 
         duration_labels = {
           method: env['REQUEST_METHOD'].downcase,
-          path:   strip_ids_from_path(env['PATH_INFO']),
+          path:   strip_ids_from_path(path),
         }
 
         @requests.increment(labels: counter_labels)
@@ -85,10 +87,58 @@ module Prometheus
         nil
       end
 
+      # While `PATH_INFO` is framework agnostic, and works for any Rack app, some Ruby web
+      # frameworks pass a more useful piece of information into the request env - the
+      # route that the request matched.
+      #
+      # This means that rather than using our generic `:id` and `:uuid` replacements in
+      # the `path` label for any path segments that look like dynamic IDs, we can put the
+      # actual route that matched in there, with correctly named parameters. For example,
+      # if a Sinatra app defined a route like:
+      #
+      # get "/foo/:bar" do
+      #   ...
+      # end
+      #
+      # instead of containing `/foo/:id`, the `path` label would contain `/foo/:bar`.
+      #
+      # Sadly, Rails is a notable exception, and (as far as I can tell at the time of
+      # writing) doesn't provide this info in the request env.
+      def generate_path(env)
+        if env['sinatra.route']
+          route = env['sinatra.route'].partition(' ').last
+        elsif env['grape.routing_args']
+          # We are deep in the weeds of an object that Grape passes into the request env,
+          # but don't document any explicit guarantees about. Let's have a fallback in
+          # case they change it down the line.
+          #
+          # This code would be neater with the safe navigation operator (`&.`) here rather
+          # than the much more verbose `respond_to?` calls, but unlike Rails' `try`
+          # method, it still raises an error if the object is non-nil, but doesn't respond
+          # to the method being called on it.
+          route = nil
+
+          route_info = env.dig('grape.routing_args', :route_info)
+          if route_info.respond_to?(:pattern)
+            pattern = route_info.pattern
+            if pattern.respond_to?(:origin)
+              route = pattern.origin
+            end
+          end
+
+          # Fall back to PATH_INFO if Grape change the structure of `grape.routing_args`
+          route ||= env['PATH_INFO']
+        else
+          route = env['PATH_INFO']
+        end
+
+        [env['SCRIPT_NAME'], route].join
+      end
+
       def strip_ids_from_path(path)
         path
-          .gsub(%r{/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(/|$)}, '/:uuid\\1')
-          .gsub(%r{/\d+(/|$)}, '/:id\\1')
+          .gsub(%r{/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?=/|$)}, '/:uuid\\1')
+          .gsub(%r{/\d+(?=/|$)}, '/:id\\1')
       end
     end
   end

data/lib/prometheus/middleware/exporter.rb

@@ -21,11 +21,12 @@ module Prometheus
         @app = app
         @registry = options[:registry] || Client.registry
         @path = options[:path] || '/metrics'
+        @port = options[:port]
         @acceptable = build_dictionary(FORMATS, FALLBACK)
       end
 
       def call(env)
-        if env['PATH_INFO'] == @path
+        if metrics_port?(env['SERVER_PORT']) && env['PATH_INFO'] == @path
           format = negotiate(env, @acceptable)
           format ? respond_with(format) : not_acceptable(FORMATS)
         else
@@ -86,6 +87,10 @@ module Prometheus
           memo[format::MEDIA_TYPE] = format
         end
       end
+
+      def metrics_port?(request_port)
+        @port.nil? || @port.to_s == request_port
+      end
     end
   end
 end

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: prometheus-client
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Ben Kochie
 - Chris Sinjakli
 - Daniel Magliola
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-06-29 00:00:00.000000000 Z
+date: 2022-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
@@ -40,10 +40,10 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
+description:
 email:
 - superq@gmail.com
-- chris@gocardless.com
+- chris@sinjakli.co.uk
 - dmagliola@crystalgears.com
 executables: []
 extensions: []
@@ -73,7 +73,7 @@ homepage: https://github.com/prometheus/client_ruby
 licenses:
 - Apache 2.0
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -88,8 +88,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.2.32
+signing_key:
 specification_version: 4
 summary: A suite of instrumentation metric primitivesthat can be exposed through a
   web services interface.