puma_metrics_engine 1.0.0

checksums.yaml

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 BigBinary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+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

@@ -0,0 +1,121 @@
+# PumaMetricsEngine
+
+A Rails engine gem that provides a `/matrix` endpoint for Puma metrics and queue time statistics.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "puma_metrics_engine", path: "../puma_metrics_engine"  # For local development
+# Or from a gem server:
+# gem "puma_metrics_engine"
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Usage
+
+Mount the engine in your routes:
+
+```ruby
+# 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.)
+
+## Example Response
+
+```json
+{
+  "timestamp": "2024-01-15T10:30:00Z",
+  "queue_time_ms": {
+    "avg": 12.5,
+    "p50": 10.0,
+    "p95": 25.0,
+    "p99": 50.0,
+    "max": 100.0,
+    "min": 1.0,
+    "sample_count": 1000
+  },
+  "queue_time_windows": {
+    "10s": { "avg": 12.3, "sample_count": 50 },
+    "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
+  }
+}
+```
+
+## Dependencies
+
+- **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 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).
+

data/app/controllers/puma_metrics_engine/matrix_controller.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module PumaMetricsEngine
+  class MatrixController < ActionController::Base
+    skip_before_action :verify_authenticity_token
+
+    TTL_SECONDS = 300 # 5 minutes
+    REQUESTS_KEY = "puma:request_timestamps"
+    QUEUE_TIMES_KEY = "puma:queue_times"
+    MAX_SAMPLES = 1000
+
+    def show
+      puma_stats = fetch_puma_stats
+      queue_time_stats = calculate_aggregate_queue_times
+      queue_time_windows = calculate_queue_time_windows
+      requests_per_minute = calculate_requests_per_minute
+
+      render json: {
+        timestamp: Time.current,
+        queue_time_ms: queue_time_stats,
+        queue_time_windows: queue_time_windows,
+        requests_per_minute: requests_per_minute,
+        puma: puma_stats
+      }
+    end
+
+    private
+
+      def calculate_aggregate_queue_times
+        # Fetch all queue times from Redis (already sorted by timestamp)
+        # This includes queue times from ALL requests across all workers and dynos (aggregated in shared Redis)
+        times = redis.zrange(QUEUE_TIMES_KEY, 0, -1).map(&:to_f)
+
+        return { error: "No queue time data available", sample_count: 0 } if times.empty?
+
+        sorted = times.sort
+        {
+          avg: times.sum / times.size.to_f,
+          p50: percentile(sorted, 50),
+          p95: percentile(sorted, 95),
+          p99: percentile(sorted, 99),
+          max: times.max,
+          min: times.min,
+          sample_count: times.size
+        }.transform_values { |v| v.is_a?(Numeric) ? v.round(2) : v }
+      rescue Redis::BaseError => e
+        {
+          error: "Failed to fetch queue time data: #{e.message}",
+          sample_count: 0
+        }
+      end
+
+      def calculate_queue_time_windows
+        current_time = Time.now.to_f
+        windows = {
+          "10s" => current_time - 10,
+          "20s" => current_time - 20,
+          "30s" => current_time - 30
+        }
+
+        result = {}
+        windows.each do |window_name, start_time|
+          # Get queue times within the time window using Redis sorted set range query
+          queue_times = redis.zrangebyscore(QUEUE_TIMES_KEY, start_time, current_time)
+          times = queue_times.map(&:to_f)
+
+          if times.empty?
+            result[window_name] = {
+              avg: 0,
+              sample_count: 0
+            }
+          else
+            result[window_name] = {
+              avg: (times.sum / times.size.to_f).round(2),
+              sample_count: times.size
+            }
+          end
+        end
+
+        result
+      rescue Redis::BaseError => e
+        {
+          error: "Failed to calculate queue time windows: #{e.message}",
+          "10s" => { avg: 0, sample_count: 0 },
+          "20s" => { avg: 0, sample_count: 0 },
+          "30s" => { avg: 0, sample_count: 0 }
+        }
+      end
+
+      def calculate_requests_per_minute
+        current_time = Time.now.to_f
+        one_minute_ago = current_time - 60
+
+        # Count requests in the last minute using Redis sorted set range query
+        # This counts ALL requests across all workers and dynos (aggregated in shared Redis)
+        request_count = redis.zcount(REQUESTS_KEY, one_minute_ago, current_time)
+
+        {
+          count: request_count,
+          window_seconds: 60
+        }
+      rescue Redis::BaseError => e
+        {
+          error: "Failed to calculate requests per minute: #{e.message}",
+          count: 0,
+          window_seconds: 60
+        }
+      end
+
+      def redis
+        @redis ||= Redis.new(url: ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" })
+      end
+
+      def percentile(sorted_array, percentile)
+        return 0 if sorted_array.empty?
+
+        index = (percentile / 100.0 * sorted_array.size).ceil - 1
+        sorted_array[[index, 0].max]
+      end
+
+      def fetch_puma_stats
+        return { error: "Puma stats not available" } unless defined?(Puma)
+
+        begin
+          if Puma.respond_to?(:stats)
+            stats = JSON.parse(Puma.stats, symbolize_names: true)
+            format_puma_stats(stats)
+          else
+            get_basic_stats
+          end
+        rescue StandardError => e
+          { error: "Failed to fetch Puma stats: #{e.message}" }
+        end
+      end
+
+      def format_puma_stats(stats)
+        formatted = {
+          workers: stats[:workers] || 0,
+          phase: stats[:phase] || 0,
+          booted_workers: stats[:booted_workers] || 0,
+          old_workers: stats[:old_workers] || 0,
+          backlog: stats[:backlog] || 0,
+          running: stats[:running] || 0,
+          pool_capacity: stats[:pool_capacity] || 0,
+          max_threads: stats[:max_threads] || 0
+        }
+
+        # Include worker status if available
+        if stats[:worker_status].present?
+          formatted[:worker_status] = stats[:worker_status].map do |worker|
+            {
+              pid: worker[:pid],
+              index: worker[:index],
+              phase: worker[:phase],
+              booted: worker[:booted],
+              last_status: worker[:last_status]
+            }
+          end
+        end
+
+        formatted
+      end
+
+      def get_basic_stats
+        {
+          threads: Thread.list.count,
+          process_id: Process.pid,
+          rails_env: Rails.env,
+          note: "Running in single-threaded mode"
+        }
+      end
+  end
+end
+

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+PumaMetricsEngine::Engine.routes.draw do
+  get "matrix", to: "matrix#show"
+end
+

data/lib/puma_metrics_engine/engine.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module PumaMetricsEngine
+  class Engine < ::Rails::Engine
+    isolate_namespace PumaMetricsEngine
+  end
+end
+

data/lib/puma_metrics_engine/version.rb

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

data/lib/puma_metrics_engine.rb

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

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: puma_metrics_engine
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Neeto
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-11-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A Rails engine that exposes Puma server metrics, queue time statistics,
+  and request rate information via a /matrix endpoint
+email:
+- engineering@bigbinary.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- 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/version.rb
+homepage: https://github.com/bigbinary/puma_metrics_engine
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bigbinary/puma_metrics_engine
+  source_code_uri: https://github.com/bigbinary/puma_metrics_engine
+  changelog_uri: https://github.com/bigbinary/puma_metrics_engine/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Rails engine that provides a /matrix endpoint for Puma metrics and queue
+  time statistics
+test_files: []