puma_metrics_engine 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 711453f75e30a751aaedaa85d58133fb0c0b5e5d4819339503f10af88bdbd964
-  data.tar.gz: 291c8e013fd863f42b6adb83b95b6c38904de5402442902c3fe65c53f8fd231f
+  metadata.gz: 248a19d8e7fb9d4392b1f4c4bf3cfa13d8e4872426d843f171732264783eaf94
+  data.tar.gz: b09efaf7ede10a759b435b8be828f0dbebde7f54ece70efddb050180e474ac4a
 SHA512:
-  metadata.gz: aaa668f89f9931652c7682ba0c45390bc4a37dde9fe8e9d692549a8ee246cbfb92128cdbfcfffd5b22015b0f19e599b9dafe59abf89103ee9e07ab94bf353f26
-  data.tar.gz: afe36aab4715936a485b54279c803ed4dc6d8fe8027bdbff9bb487e5bac547bae3db37c1784c37080ae93a19478bf92f4251f836b934e395f40773b124db4ff7
+  metadata.gz: 4bbfb1639f3157a75afc8bbc538eecfd52492c05240be8d96576884ea2448cd6d8598b16e0a87c8fd2a93153b0b051e186842083e18bb874b8c5bb14bb17813c
+  data.tar.gz: 006066e431c7c1d7fed9cfb6c19b17715e2e7437a09ef23b8962838e33e063299a62ce7b47d6c6d535ebe535032ed8abd840f3851cf7e0505fab11bc023a041e

data/LICENSE.txt

@@ -19,4 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-

data/README.md

@@ -1,22 +1,16 @@
 # PumaMetricsEngine
 
-A Rails engine gem that provides a `/matrix` endpoint for Puma metrics and queue time statistics.
+A Rails engine that provides a `/matrix` endpoint for Puma metrics and queue time statistics.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add to your Gemfile:
 
 ```ruby
-gem "puma_metrics_engine", path: "../puma_metrics_engine"  # For local development
-# Or from a gem server:
-# gem "puma_metrics_engine"
+gem "puma_metrics_engine"
 ```
 
-And then execute:
-
-```bash
-$ bundle install
-```
+Then run `bundle install`.
 
 ## Usage
 
@@ -26,19 +20,12 @@ Mount the engine in your routes:
 # config/routes.rb
 Rails.application.routes.draw do
   mount PumaMetricsEngine::Engine, at: "/"
-  # ... other routes
 end
 ```
 
-The engine automatically provides a `/matrix` endpoint that returns JSON with:
-
-- `timestamp`: Current timestamp
-- `queue_time_ms`: Aggregate queue time statistics (avg, p50, p95, p99, max, min, sample_count)
-- `queue_time_windows`: Queue time averages for 10s, 20s, and 30s windows
-- `requests_per_minute`: Request count in the last minute
-- `puma`: Puma server statistics (workers, threads, backlog, etc.)
+Access metrics at `/matrix` endpoint.
 
-## Example Response
+## Response Format
 
 ```json
 {
@@ -57,65 +44,19 @@ The engine automatically provides a `/matrix` endpoint that returns JSON with:
     "20s": { "avg": 12.5, "sample_count": 100 },
     "30s": { "avg": 12.4, "sample_count": 150 }
   },
-  "requests_per_minute": {
-    "count": 120,
-    "window_seconds": 60
-  },
-  "puma": {
-    "workers": 2,
-    "phase": 0,
-    "booted_workers": 2,
-    "backlog": 0,
-    "running": 10,
-    "pool_capacity": 20,
-    "max_threads": 10
-  }
+  "requests_per_minute": { "count": 120, "window_seconds": 60 },
+  "puma": { "workers": 2, "backlog": 0, "running": 10, ... }
 }
 ```
 
-## Dependencies
+## Requirements
 
 - **Rails** >= 7.0
-- **Redis** >= 5.0 (for storing queue time and request data)
-- **Puma** (optional, for Puma-specific stats)
-
-## Configuration
-
-The engine uses the following Redis keys (shared with ApplicationController if tracking is enabled):
-- `puma:request_timestamps` - Request timestamps
-- `puma:queue_times` - Queue time data
-
-The engine reads from the same Redis keys that `ApplicationController` writes to (if you have queue time tracking enabled in your ApplicationController).
+- **Redis** >= 5.0
+- **X-Request-Start header**: Set by your load balancer (nginx, HAProxy, etc.) for queue time tracking
 
 Redis connection uses `ENV["REDIS_URL"]` or defaults to `redis://localhost:6379/1`.
 
-## Notes
-
-- The endpoint skips CSRF token verification
-- The engine is isolated in the `PumaMetricsEngine` namespace
-- No database migrations required
-
-## Development
-
-After checking out the repo, run `bundle install` to install dependencies.
-
-To build the gem:
-
-```bash
-gem build puma_metrics_engine.gemspec
-```
-
-To install the gem locally:
-
-```bash
-gem install ./puma_metrics_engine-1.0.0.gem
-```
-
-## Contributing
-
-Bug reports and pull requests are welcome.
-
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
+MIT

data/app/controllers/puma_metrics_engine/matrix_controller.rb

@@ -171,4 +171,3 @@ module PumaMetricsEngine
       end
   end
 end
-

data/config/routes.rb

@@ -3,4 +3,3 @@
 PumaMetricsEngine::Engine.routes.draw do
   get "matrix", to: "matrix#show"
 end
-

data/lib/puma_metrics_engine/engine.rb

@@ -3,6 +3,7 @@
 module PumaMetricsEngine
   class Engine < ::Rails::Engine
     isolate_namespace PumaMetricsEngine
+
+    config.app_middleware.use PumaMetricsEngine::QueueTimeTracker
   end
 end
-

data/lib/puma_metrics_engine/queue_time_tracker.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module PumaMetricsEngine
+  class QueueTimeTracker
+    TTL_SECONDS = 300 # 5 minutes
+    REQUESTS_KEY = "puma:request_timestamps"
+    QUEUE_TIMES_KEY = "puma:queue_times"
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      request_start_time = extract_request_start_time(env)
+      process_start_time = Time.now.to_f
+
+      status, headers, response = @app.call(env)
+
+      # Calculate queue time if we have request start time
+      begin
+        if request_start_time
+          queue_time_ms = ((process_start_time - request_start_time) * 1000).round(2)
+          
+          # Only store if queue time is reasonable (positive and less than 1 hour)
+          # Negative values indicate clock skew, very large values are likely errors
+          if queue_time_ms >= 0 && queue_time_ms < 3_600_000
+            timestamp = process_start_time
+            # Store in Redis asynchronously to avoid blocking the request
+            store_metrics_async(timestamp, queue_time_ms)
+          else
+            # Still track request timestamp even if queue time is invalid
+            store_request_timestamp_async(process_start_time)
+          end
+        else
+          # Still track request timestamp even without queue time
+          store_request_timestamp_async(process_start_time)
+        end
+      rescue StandardError => e
+        # Don't let tracking errors break the request
+        Rails.logger.error("QueueTimeTracker error: #{e.message}") if defined?(Rails)
+      end
+
+      [status, headers, response]
+    end
+
+    private
+
+      def extract_request_start_time(env)
+        # Try X-Request-Start header (common in nginx, HAProxy, etc.)
+        # Format: "t=1234567890.123" or "1234567890.123" or Unix timestamp in microseconds
+        header_value = env["HTTP_X_REQUEST_START"] || env["X-Request-Start"]
+
+        return nil unless header_value
+
+        # Handle different formats
+        # Format 1: "t=1234567890.123"
+        if header_value =~ /t=([\d.]+)/
+          timestamp_str = $1
+        # Format 2: "1234567890.123" (direct timestamp)
+        elsif header_value =~ /^[\d.]+$/
+          timestamp_str = header_value
+        else
+          return nil
+        end
+
+        timestamp = timestamp_str.to_f
+
+        # If timestamp is in microseconds (common with nginx), convert to seconds
+        # Timestamps > year 2100 are likely in microseconds
+        if timestamp > 4_102_444_800 # Year 2100 in seconds
+          timestamp = timestamp / 1_000_000.0
+        end
+
+        timestamp
+      rescue StandardError
+        nil
+      end
+
+      def store_metrics_async(timestamp, queue_time_ms)
+        # Use a thread pool or async job, but for simplicity, we'll do it synchronously
+        # In production, you might want to use a background job
+        Thread.new do
+          begin
+            redis_client = redis
+            # Store queue time with timestamp as score
+            redis_client.zadd(QUEUE_TIMES_KEY, timestamp, queue_time_ms)
+            # Store request timestamp
+            redis_client.zadd(REQUESTS_KEY, timestamp, timestamp)
+            # Cleanup old data (older than TTL)
+            cleanup_old_data(redis_client)
+          rescue StandardError => e
+            Rails.logger.error("Failed to store queue time metrics: #{e.message}") if defined?(Rails)
+          end
+        end
+      end
+
+      def store_request_timestamp_async(timestamp)
+        Thread.new do
+          begin
+            redis_client = redis
+            redis_client.zadd(REQUESTS_KEY, timestamp, timestamp)
+            cleanup_old_data(redis_client)
+          rescue StandardError => e
+            Rails.logger.error("Failed to store request timestamp: #{e.message}") if defined?(Rails)
+          end
+        end
+      end
+
+      def cleanup_old_data(redis_client)
+        # Only cleanup occasionally to avoid overhead (10% chance)
+        return unless rand < 0.1
+
+        cutoff_time = Time.now.to_f - TTL_SECONDS
+        # Remove old entries from both sorted sets
+        redis_client.zremrangebyscore(QUEUE_TIMES_KEY, "-inf", cutoff_time)
+        redis_client.zremrangebyscore(REQUESTS_KEY, "-inf", cutoff_time)
+      end
+
+      def redis
+        @redis ||= Redis.new(url: ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" })
+      end
+  end
+end
+

data/lib/puma_metrics_engine/version.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
 module PumaMetricsEngine
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end
-

data/lib/puma_metrics_engine.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 require "puma_metrics_engine/version"
+require "puma_metrics_engine/queue_time_tracker"
 require "puma_metrics_engine/engine"
-

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: puma_metrics_engine
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Neeto
@@ -66,6 +66,76 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-mocks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: fakeredis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
 description: A Rails engine that exposes Puma server metrics, queue time statistics,
   and request rate information via a /matrix endpoint
 email:
@@ -80,6 +150,7 @@ files:
 - config/routes.rb
 - lib/puma_metrics_engine.rb
 - lib/puma_metrics_engine/engine.rb
+- lib/puma_metrics_engine/queue_time_tracker.rb
 - lib/puma_metrics_engine/version.rb
 homepage: https://github.com/bigbinary/puma_metrics_engine
 licenses:
@@ -103,7 +174,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
+rubygems_version: 3.5.10
 signing_key:
 specification_version: 4
 summary: Rails engine that provides a /matrix endpoint for Puma metrics and queue