promenade 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21a119e5d3d87a758957487577e0167dfff5f3d9bf04938b9c2b257f91d46c7c
-  data.tar.gz: 37698954cc28bdfca381663448821c190bfb5e5d4f67373780668c45e90669e5
+  metadata.gz: 235f95d0b77870a9975ff9870428ed5a995b9174380b981c2df7d8a338519ffb
+  data.tar.gz: 7d6e327e2d602fd2b07342fb45c9be29e36ad266212ad4ed98a72eafee58bc9e
 SHA512:
-  metadata.gz: 9fc56c5ea2851e9dfaeae6e56ef63795cab6e2acbd11eed8ecc0e70b9f8198186f92ca74d37afaa92bba579db826b06820fad7b78ee2dcd756aa019d8dd7967f
-  data.tar.gz: dd5269ee49251537374407c60cf9f31a00d3fcb6ffcfa7c0c0bfa9e8b76d23ca29c868d25ff5732a815e9adef193d73d4da626dd3f223f90d61ae31b640a9340
+  metadata.gz: e8596f53e3110b636696cb38f2d3bfa872715de3e331fdf260da62e30c31949a1753702b935c3343545c7be19da56f0e30a65d89568eefd419b94a5ef80fe2f9
+  data.tar.gz: 7e65f494c50b2bc25b05b169794f73c02c64ad1548c3425399b1d2cb4e7077d930e0e7d9c99ea88088c76e1026bb64cfbda246ab1a6b09c057b4f2b717b130d8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    promenade (0.5.0)
+    promenade (0.6.0)
       actionpack
       activesupport (> 6.0, < 8.0)
       prometheus-client-mmap (~> 0.16.0)
@@ -140,7 +140,7 @@ GEM
     parallel (1.22.1)
     parser (3.1.2.0)
       ast (~> 2.4.1)
-    prometheus-client-mmap (0.16.0)
+    prometheus-client-mmap (0.16.2)
     pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)

data/README.md

@@ -181,6 +181,20 @@ Rails.application.config.middleware.insert_after ActionDispatch::ShowExceptions,
         exception_handler: exception_handler
 ```
 
+#### Customising the histogram buckets
+
+The default buckets cover a range of latencies from 5 ms to 10s see [Promenade::Configuration::DEFAULT_RACK_LATENCY_BUCKETS](https://github.com/errm/promenade/blob/ea7eb54c04257770a601b7e28b3e13db5d2430bb/lib/promenade/configuration.rb#L5). This is intended to capture the typical range of latencies for a web application. However, this might not be suitable for your Service-Level Agreements (SLAs), and other bucket size intervals may be required (see [histogram bins](https://en.wikipedia.org/wiki/Histogram#Number_of_bins_and_width)).
+
+If you would like to customise the histogram buckets, you can do so by configuring Promenade in an initializer:
+
+```ruby
+# config/initializers/promenade.rb
+
+Promenade.configure do |config|
+  config.rack_latency_buckets = [0.25, 0.350, 0.5, 1, 1.5, 2.5, 5, 10, 15, 19]
+end
+```
+
 ### Configuration
 
 If you are using rails it should load a railtie and configure promenade.
@@ -205,6 +219,10 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/errm/p
 
 This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
+## Acknowledgements
+
+The original code for the Rack middleware collector class was copied from [Prometheus Client MMap](https://gitlab.com/gitlab-org/prometheus-client-mmap/-/blob/master/lib/prometheus/client/rack/collector.rb).
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/promenade/client/rack/http_request_duration_collector.rb

@@ -0,0 +1,92 @@
+require "prometheus/client"
+require_relative "middleware_base"
+require_relative "request_labeler"
+require_relative "exception_handler"
+require_relative "queue_time_duration"
+
+module Promenade
+  module Client
+    module Rack
+      class HTTPRequestDurationCollector < MiddlwareBase
+        REQUEST_DURATION_HISTOGRAM_NAME = :http_req_duration_seconds
+
+        REQUESTS_COUNTER_NAME = :http_requests_total
+
+        EXCEPTIONS_COUNTER_NAME = :http_exceptions_total
+
+        private_constant :REQUEST_DURATION_HISTOGRAM_NAME,
+          :REQUESTS_COUNTER_NAME,
+          :EXCEPTIONS_COUNTER_NAME
+
+        def initialize(app,
+                       registry: ::Prometheus::Client.registry,
+                       label_builder: RequestLabeler,
+                       exception_handler: nil)
+
+          @latency_buckets = Promenade.configuration.rack_latency_buckets
+          @_exception_handler = exception_handler
+
+          super(app, registry: registry, label_builder: label_builder)
+        end
+
+        private
+
+          attr_reader :latency_buckets, :queue_time_buckets
+
+          def trace(env)
+            start = current_time
+            begin
+              response = yield
+              record_request_duration(labels(env, response), duration_since(start))
+              response
+            rescue StandardError => e
+              exception_handler.call(e, env, duration_since(start))
+            end
+          end
+
+          def record_request_duration(labels, duration)
+            requests_counter.increment(labels)
+            durations_histogram.observe(labels, duration)
+          end
+
+          def duration_since(start_time)
+            current_time - start_time
+          end
+
+          def current_time
+            Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          end
+
+          def durations_histogram
+            registry.get(REQUEST_DURATION_HISTOGRAM_NAME)
+          end
+
+          def requests_counter
+            registry.get(REQUESTS_COUNTER_NAME)
+          end
+
+          def register_metrics!
+            registry.counter(REQUESTS_COUNTER_NAME,
+              "A counter of the total number of HTTP requests made.")
+            registry.histogram(REQUEST_DURATION_HISTOGRAM_NAME,
+              "A histogram of the response latency.", {}, latency_buckets)
+            registry.counter(EXCEPTIONS_COUNTER_NAME,
+              "A counter of the total number of exceptions raised.")
+          end
+
+          def exception_handler
+            @_exception_handler ||= default_exception_handler
+          end
+
+          def default_exception_handler
+            ExceptionHandler.initialize_singleton(
+              histogram_name: REQUEST_DURATION_HISTOGRAM_NAME,
+              requests_counter_name: REQUESTS_COUNTER_NAME,
+              exceptions_counter_name: EXCEPTIONS_COUNTER_NAME,
+              registry: registry,
+            )
+          end
+      end
+    end
+  end
+end

data/lib/promenade/client/rack/http_request_queue_time_collector.rb

@@ -0,0 +1,55 @@
+require "prometheus/client"
+require_relative "middleware_base"
+require_relative "request_labeler"
+require_relative "queue_time_duration"
+
+module Promenade
+  module Client
+    module Rack
+      class HTTPRequestQueueTimeCollector < MiddlwareBase
+        REQUEST_QUEUE_TIME_HISTOGRAM_NAME = :http_req_queue_time_seconds
+
+        private_constant :REQUEST_QUEUE_TIME_HISTOGRAM_NAME
+
+        def initialize(app,
+                       registry: ::Prometheus::Client.registry,
+                       label_builder: RequestLabeler)
+
+          @queue_time_buckets = Promenade.configuration.queue_time_buckets
+
+          super(app, registry: registry, label_builder: label_builder)
+        end
+
+        private
+
+          attr_reader :queue_time_buckets
+
+          def trace(env)
+            start_timestamp = Time.now.utc
+            response = yield
+            record_request_queue_time(labels: labels(env, response),
+              env: env,
+              request_received_time: start_timestamp)
+            response
+          end
+
+          def record_request_queue_time(labels:, env:, request_received_time:)
+            request_queue_duration = QueueTimeDuration.new(env: env,
+              request_received_time: request_received_time)
+            return unless request_queue_duration.valid_header_present?
+
+            queue_time_histogram.observe(labels, request_queue_duration.queue_time_seconds)
+          end
+
+          def register_metrics!
+            registry.histogram(REQUEST_QUEUE_TIME_HISTOGRAM_NAME,
+              "A histogram of request queue time", {}, queue_time_buckets)
+          end
+
+          def queue_time_histogram
+            registry.get(REQUEST_QUEUE_TIME_HISTOGRAM_NAME)
+          end
+      end
+    end
+  end
+end

data/lib/promenade/client/rack/middleware_base.rb

@@ -0,0 +1,36 @@
+module Promenade
+  module Client
+    module Rack
+      class MiddlwareBase
+        def initialize(app, registry:, label_builder:)
+          @app = app
+          @registry = registry
+          @label_builder = label_builder
+
+          register_metrics!
+        end
+
+        def call(env)
+          trace(env) { app.call(env) }
+        end
+
+        private
+
+          attr_reader :app, :label_builder, :registry
+
+          def trace(env)
+            raise NotImplementedError,
+              "Please define #{__method__} in #{self.class}"
+          end
+
+          def labels(env, response)
+            label_builder.call(env).merge!(code: response.first.to_s)
+          end
+
+          def register_metrics!
+            # :noop:
+          end
+      end
+    end
+  end
+end

data/lib/promenade/client/rack/queue_time_duration.rb

@@ -0,0 +1,50 @@
+module Promenade
+  module Client
+    module Rack
+      class QueueTimeDuration
+        REQUEST_START_HEADER = "HTTP_X_REQUEST_START".freeze
+
+        QUEUE_START_HEADER = "HTTP_X_QUEUE_START".freeze
+
+        HEADER_VALUE_MATCHER = /^(?:t=)(?<timestamp>\d{10}(?:\.\d+))$/.freeze
+
+        def initialize(env:, request_received_time:)
+          @env = env
+          @request_queued_time_ms = extract_request_queued_time_from_env(env)
+          @valid_header_present = @request_queued_time_ms.is_a?(Float)
+          @request_received_time_ms = request_received_time.utc.to_f
+
+          freeze
+        end
+
+        def valid_header_present?
+          @valid_header_present
+        end
+
+        def queue_time_seconds
+          return unless valid_header_present?
+
+          queue_time.round(3)
+        end
+
+        private
+
+          attr_reader :env, :request_queued_time_ms, :request_received_time_ms
+
+          def queue_time
+            request_received_time_ms - request_queued_time_ms
+          end
+
+          def extract_request_queued_time_from_env(env_hash)
+            header_value = env_hash[REQUEST_START_HEADER] || env_hash[QUEUE_START_HEADER]
+            return if header_value.nil?
+
+            header_time_match = header_value.to_s.match(HEADER_VALUE_MATCHER)
+            return unless header_time_match
+
+            header_time_match[:timestamp].to_f
+          end
+      end
+    end
+  end
+end

data/lib/promenade/configuration.rb

@@ -1,11 +1,14 @@
 module Promenade
   class Configuration
-    attr_accessor :rack_latency_buckets
+    attr_accessor :queue_time_buckets, :rack_latency_buckets
 
     DEFAULT_RACK_LATENCY_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10].freeze
 
+    DEFAULT_QUEUE_TIME_BUCKETS = [0.01, 0.5, 1.0, 10.0, 30.0].freeze
+
     def initialize
       @rack_latency_buckets = DEFAULT_RACK_LATENCY_BUCKETS
+      @queue_time_buckets = DEFAULT_QUEUE_TIME_BUCKETS
     end
   end
 end

data/lib/promenade/railtie.rb

@@ -1,13 +1,16 @@
 require "promenade/setup"
 require "promenade/engine"
-require "promenade/client/rack/collector"
+require "promenade/client/rack/http_request_duration_collector"
+require "promenade/client/rack/http_request_queue_time_collector"
 
 module Promenade
   class Railtie < ::Rails::Railtie
     initializer "promenade.configure_rails_initialization" do
       Promenade.setup
       Rails.application.config.middleware.insert_after ActionDispatch::ShowExceptions,
-        Promenade::Client::Rack::Collector
+        Promenade::Client::Rack::HTTPRequestDurationCollector
+      Rails.application.config.middleware.insert 0,
+        Promenade::Client::Rack::HTTPRequestQueueTimeCollector
     end
   end
 end

data/lib/promenade/version.rb

@@ -1,3 +1,3 @@
 module Promenade
-  VERSION = "0.5.0".freeze
+  VERSION = "0.6.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: promenade
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Ed Robinson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-06-23 00:00:00.000000000 Z
+date: 2022-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -271,8 +271,11 @@ files:
 - bin/setup
 - exe/promenade
 - lib/promenade.rb
-- lib/promenade/client/rack/collector.rb
 - lib/promenade/client/rack/exception_handler.rb
+- lib/promenade/client/rack/http_request_duration_collector.rb
+- lib/promenade/client/rack/http_request_queue_time_collector.rb
+- lib/promenade/client/rack/middleware_base.rb
+- lib/promenade/client/rack/queue_time_duration.rb
 - lib/promenade/client/rack/request_labeler.rb
 - lib/promenade/client/rack/singleton_caller.rb
 - lib/promenade/configuration.rb
@@ -312,7 +315,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
+rubygems_version: 3.3.18
 signing_key:
 specification_version: 4
 summary: Promenade makes it simple to instrument Ruby apps for prometheus scraping

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

@@ -1,113 +0,0 @@
-require "prometheus/client"
-require_relative "request_labeler"
-require_relative "exception_handler"
-
-module Promenade
-  module Client
-    module Rack
-      # Original code taken from Prometheus Client MMap
-      # https://gitlab.com/gitlab-org/prometheus-client-mmap/-/blob/master/lib/prometheus/client/rack/collector.rb
-      #
-      # Collector is a Rack middleware that provides a sample implementation of
-      # a HTTP tracer. The default label builder can be modified to export a
-      # different set of labels per recorded metric.
-      class Collector
-        REQUEST_METHOD = "REQUEST_METHOD".freeze
-
-        HTTP_HOST = "HTTP_HOST".freeze
-
-        PATH_INFO = "PATH_INFO".freeze
-
-        HISTOGRAM_NAME = :http_req_duration_seconds
-
-        REQUESTS_COUNTER_NAME = :http_requests_total
-
-        EXCEPTIONS_COUNTER_NAME = :http_exceptions_total
-
-        private_constant *%i(
-          REQUEST_METHOD
-          HTTP_HOST
-          PATH_INFO
-          HISTOGRAM_NAME
-          REQUESTS_COUNTER_NAME
-          EXCEPTIONS_COUNTER_NAME
-        )
-
-        def initialize(app,
-                       registry: ::Prometheus::Client.registry,
-                       label_builder: RequestLabeler,
-                       exception_handler: nil)
-          @app = app
-          @registry = registry
-          @label_builder = label_builder
-          @latency_buckets = Promenade.configuration.rack_latency_buckets
-          @exception_handler = exception_handler || default_exception_handler
-          register_metrics!
-        end
-
-        def call(env)
-          trace(env) { app.call(env) }
-        end
-
-        private
-
-          attr_reader :app,
-            :registry,
-            :label_builder,
-            :latency_buckets,
-            :exception_handler
-
-          def trace(env)
-            start = current_time
-            begin
-              response = yield
-              record(labels(env, response), duration_since(start))
-              response
-            rescue StandardError => e
-              exception_handler.call(e, env, duration_since(start))
-            end
-          end
-
-          def labels(env, response)
-            label_builder.call(env).merge!(code: response.first.to_s)
-          end
-
-          def record(labels, duration)
-            requests_counter.increment(labels)
-            durations_histogram.observe(labels, duration)
-          end
-
-          def duration_since(start_time)
-            current_time - start_time
-          end
-
-          def current_time
-            Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          end
-
-          def durations_histogram
-            registry.get(HISTOGRAM_NAME)
-          end
-
-          def requests_counter
-            registry.get(REQUESTS_COUNTER_NAME)
-          end
-
-          def register_metrics!
-            registry.counter(REQUESTS_COUNTER_NAME, "A counter of the total number of HTTP requests made.")
-            registry.histogram(HISTOGRAM_NAME, "A histogram of the response latency.", {}, latency_buckets)
-            registry.counter(EXCEPTIONS_COUNTER_NAME, "A counter of the total number of exceptions raised.")
-          end
-
-          def default_exception_handler
-            ExceptionHandler.initialize_singleton(
-              histogram_name: HISTOGRAM_NAME,
-              requests_counter_name: REQUESTS_COUNTER_NAME,
-              exceptions_counter_name: EXCEPTIONS_COUNTER_NAME,
-              registry: registry,
-            )
-          end
-      end
-    end
-  end
-end