puma_metrics_engine 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 711453f75e30a751aaedaa85d58133fb0c0b5e5d4819339503f10af88bdbd964
-  data.tar.gz: 291c8e013fd863f42b6adb83b95b6c38904de5402442902c3fe65c53f8fd231f
+  metadata.gz: 1ab335fa7843d45934fd97c5442b9bfd3a87006066b6f14ef99123a9316ab165
+  data.tar.gz: 7bd9134d5a436aecebd2a3f2a4073a5b51c46f3fb3d4a8b2391464e108326503
 SHA512:
-  metadata.gz: aaa668f89f9931652c7682ba0c45390bc4a37dde9fe8e9d692549a8ee246cbfb92128cdbfcfffd5b22015b0f19e599b9dafe59abf89103ee9e07ab94bf353f26
-  data.tar.gz: afe36aab4715936a485b54279c803ed4dc6d8fe8027bdbff9bb487e5bac547bae3db37c1784c37080ae93a19478bf92f4251f836b934e395f40773b124db4ff7
+  metadata.gz: c9f71532254eed460c8169a894c41e0ac03c7a089c37a133fc097d7632a0ab2bd2e282bbe84b7cd3ea667ea1adfa9f5a9cb3afc4aaaeb8d470107e5f403ab016
+  data.tar.gz: b704e4c376bdbdad8324b004c71ed20d176dbdda1febaaa63c6c411da33beee40cdb98460671dd8c558feb085a491602f2babc220d3ede42f2d77e90594b00d7

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,18 @@ 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:
+Access metrics at `/matrix` endpoint.
 
-- `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.)
+For debugging production issues, use `/debug` endpoint to check:
+- Middleware registration status
+- Redis connectivity
+- Header presence
+- Current data in Redis
 
-## Example Response
+## Response Format
 
 ```json
 {
@@ -57,65 +50,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/debug_controller.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module PumaMetricsEngine
+  class DebugController < ActionController::Base
+    skip_before_action :verify_authenticity_token
+
+    def show
+      render json: {
+        timestamp: Time.current,
+        middleware: middleware_status,
+        redis: redis_status,
+        headers: sample_headers,
+        data: redis_data_summary,
+        environment: environment_info
+      }
+    end
+
+    private
+
+      def middleware_status
+        middleware_stack = Rails.application.middleware.to_a.map(&:klass).map(&:name)
+        is_registered = middleware_stack.include?("PumaMetricsEngine::QueueTimeTracker")
+
+        {
+          registered: is_registered,
+          middleware_stack: middleware_stack,
+          note: is_registered ? "Middleware is registered" : "Middleware NOT found in stack"
+        }
+      rescue StandardError => e
+        { error: e.message }
+      end
+
+      def redis_status
+        client = redis
+        client.ping
+        {
+          connected: true,
+          url: ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" },
+          keys: {
+            queue_times: client.exists?(MatrixController::QUEUE_TIMES_KEY),
+            request_timestamps: client.exists?(MatrixController::REQUESTS_KEY)
+          }
+        }
+      rescue StandardError => e
+        {
+          connected: false,
+          error: e.message,
+          url: ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" }
+        }
+      end
+
+      def redis_data_summary
+        client = redis
+        {
+          queue_times_count: client.zcard(MatrixController::QUEUE_TIMES_KEY),
+          request_timestamps_count: client.zcard(MatrixController::REQUESTS_KEY),
+          recent_queue_times: client.zrange(MatrixController::QUEUE_TIMES_KEY, -10, -1),
+          recent_timestamps: client.zrange(MatrixController::REQUESTS_KEY, -10, -1)
+        }
+      rescue StandardError => e
+        { error: e.message }
+      end
+
+      def sample_headers
+        # Show what headers we're looking for
+        {
+          x_request_start: request.headers["X-Request-Start"],
+          http_x_request_start: request.headers["HTTP_X_REQUEST_START"],
+          all_x_headers: request.headers.select { |k, _| k.to_s.upcase.include?("X-REQUEST") },
+          note: "Check if X-Request-Start header is being sent by your load balancer"
+        }
+      end
+
+      def environment_info
+        {
+          rails_env: Rails.env,
+          redis_url_set: ENV.key?("REDIS_URL"),
+          puma_defined: defined?(Puma)
+        }
+      end
+
+      def redis
+        @redis ||= Redis.new(url: ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" })
+      end
+  end
+end
+

data/app/controllers/puma_metrics_engine/matrix_controller.rb

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

data/config/routes.rb

@@ -2,5 +2,5 @@
 
 PumaMetricsEngine::Engine.routes.draw do
   get "matrix", to: "matrix#show"
+  get "debug", to: "debug#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,135 @@
+# 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
+
+      # Log header presence for debugging
+      if defined?(Rails)
+        header_value = env["HTTP_X_REQUEST_START"] || env["X-Request-Start"]
+        Rails.logger.debug("[QueueTimeTracker] X-Request-Start header: #{header_value.inspect}") if header_value
+        Rails.logger.debug("[QueueTimeTracker] No X-Request-Start header found") unless header_value
+      end
+
+      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)
+            Rails.logger.debug("[QueueTimeTracker] Stored queue time: #{queue_time_ms}ms") if defined?(Rails)
+          else
+            # Still track request timestamp even if queue time is invalid
+            Rails.logger.warn("[QueueTimeTracker] Invalid queue time: #{queue_time_ms}ms (rejected)") if defined?(Rails)
+            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)
+        Rails.logger.error("[QueueTimeTracker] Backtrace: #{e.backtrace.first(5).join("\n")}") 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("[QueueTimeTracker] Failed to store metrics: #{e.message}") if defined?(Rails)
+            Rails.logger.error("[QueueTimeTracker] Redis error backtrace: #{e.backtrace.first(3).join("\n")}") 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("[QueueTimeTracker] 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.2.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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puma_metrics_engine
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Neeto
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-28 00:00:00.000000000 Z
+date: 2025-11-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -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:
@@ -76,10 +146,12 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- app/controllers/puma_metrics_engine/debug_controller.rb
 - app/controllers/puma_metrics_engine/matrix_controller.rb
 - 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 +175,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