perfm 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e1cff83c55f6245ed510d9f41fe5c169a662173e243ba0e8fb58c10d3274933
+  data.tar.gz: 3084b6db3933db8c23045b49374ac1474ad070b586a716452c095075be135a71
+SHA512:
+  metadata.gz: a511d3fbefdb4554f5f87fa27f09e3f1c64d590dcac763e9cc0ca8b9e53c867ccf80337ff465edd0bcd2b6a63f88b27277d26121cc0dd87abec6411bab1e7e3e
+  data.tar.gz: cb3838701d25771a72c52866b6aaa7bddf215452f1980495c36854655da73ec254088a2e6d38d660e9b59242f5b6cd8f7db3001e74d7d89a2cf68eb76cee50f2

data/LICENSE

@@ -0,0 +1,21 @@
+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,208 @@
+Perfm
+==============
+Perfm aims to be a performance monitoring tool for Ruby on Rails applications. Currently, it has support for GVL instrumentation and provides analytics to help optimize Puma thread concurrency settings based on the collected GVL data.
+
+Requirements
+-----------------
+- Ruby: MRI 3.2+
+
+This is because the GVL instrumentation API was [added](https://bugs.ruby-lang.org/issues/18339) in 3.2.0. Perfm makes use of the [gvl_timing](https://github.com/jhawthorn/gvl_timing) gem to capture per-thread timings for each GVL state.
+
+Installation
+-----------------
+Add perfm to your Gemfile.
+```ruby
+gem 'perfm'
+```
+
+To set up GVL instrumentation run the following command:
+
+```bash
+bin/rails generate perfm:install
+```
+
+This will create a migration file with a table to store the GVL metrics. Run the migration and configure the gem as described below.
+
+Configuration
+-----------------
+Configure Perfm in an initializer:
+
+```ruby
+Perfm.configure do |config|
+  config.enabled = true
+  config.monitor_gvl = true
+  config.storage = :local
+end
+
+Perfm.setup!
+
+```
+
+When `monitor_gvl` is enabled, perfm adds a Rack middleware to log GVL metrics for each request. The metrics are stored in the database.
+
+We just need around `20000` datapoints(i.e requests) to get an idea of the app's workload. So the `monitor_gvl` config can be disabled after that. You can control the value via an ENV variable if you prefer.
+
+## Analysis
+
+```ruby
+gvl_metrics_analyzer = Perfm::GvlMetricsAnalyzer.new(
+  start_time: 5.days.ago,
+  end_time: Time.current
+)
+
+gvl_metrics_analyzer.analyze
+
+# Write to file
+File.write(
+ "tmp/perfm/gvl_analysis_#{Time.current.strftime('%Y%m%d_%H%M%S')}.json",
+  JSON.pretty_generate(gvl_metrics_analyzer.analyze)
+)
+```
+
+This will print the following metrics:
+
+- `total_io_percentage`: Percentage of time spent doing I/O operations
+- `total_io_and_stall_percentage`: Percentage of time spent in I/O operations(idle time) and GVL stalls combined
+- `average_response_time_ms`: Average response time in milliseconds per request
+- `average_stall_ms`: Average GVL stall time in milliseconds per request
+- `request_count`: Total number of requests analyzed
+- `time_range`: Details about the analysis period including:
+  - `start_time`
+  - `end_time`
+  - `duration_seconds`
+
+After analysis, you can drop the table to save space. The following command generates a migration to drop the table.
+
+```bash
+bin/rails generate perfm:uninstall
+```
+
+## Beta Features
+
+The following features are currently in beta and may have limited functionality or be subject to change.
+
+### Perfm queue latency monitor
+
+
+The queue latency monitor tracks Sidekiq queue times and raises alerts when the queue latency exceed their thresholds. To enable this feature, set `config.monitor_sidekiq_queues = true` in your Perfm configuration.
+
+ruby
+
+```ruby
+Perfm.configure do |config|
+  # Other configurations...
+  config.monitor_sidekiq_queues = true
+end
+```
+
+When enabled, Perfm will monitor your Sidekiq queues and raise a `Perfm::Errors::LatencyExceededError` when the queue latency exceeds the threshold.
+
+#### Queue Naming Convention
+
+Perfm expects queues that need latency monitoring to follow this naming pattern:
+
+-   `within_X_seconds` (e.g., within_5_seconds)
+-   `within_X_minutes` (e.g., within_2_minutes)
+-   `within_X_hours` (e.g., within_1_hours)
+
+### Heap analyzer
+
+### Generate and Store Heap Dumps via ActiveStorage
+
+Perfm has a heap dump generator which can be used to generate heap dumps from running Puma worker processes and storing them via ActiveStorage. This can be useful for debugging memory leaks. We can generate three dumps separate by a time period of lets say 15 minutes and analyze it via heapy or sheap.
+
+_Note: The process of heap dump generation can increase the memory usage._
+
+#### Puma configuration changes:
+
+Add the following to your `config/puma.rb`:
+
+```ruby
+on_worker_boot do
+  Perfm::PidStore.instance.add_worker_pid(Process.pid)
+end
+
+on_worker_shutdown do
+  Perfm::PidStore.instance.clear
+end
+```
+
+We need to keep track of pid of each worker process so that we inject code to generate heap dump in each worker process using [rbtrace](https://github.com/tmm1/rbtrace)
+
+#### Route setup
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  namespace :perfm do
+    namespace :admin do
+      resources :heap_dumps, only: :create
+    end
+  end
+end
+```
+
+#### Controller to generate heap dumps
+
+As we need to invoke rbtrace from the same process, we'll use a controller itself to invoke the `HeapDumper`.
+```ruby
+class Perfm::Admin::HeapDumpsController < ActionController::Base
+  skip_forgery_protection
+  before_action :authenticate_admin
+
+  def create
+    blob = Perfm::HeapDumper.generate
+
+    render json: {
+      status: "success",
+      message: "Heap dump generated successfully",
+      blob_id: blob.id,
+      filename: blob.filename.to_s
+    }
+  rescue Perfm::HeapDumper::Error => e
+    render json: { status: "error", message: e.message }, status: :unprocessable_entity
+  end
+
+  private
+
+  def authenticate_admin
+    return if Rails.env.development?
+
+    unless valid_token?(request.headers["X-Perfm-Token"])
+      head :unauthorized
+    end
+  end
+
+  def valid_token?(token)
+    return false if token.blank? || Perfm.configuration.admin_token.blank?
+
+    ActiveSupport::SecurityUtils.secure_compare(
+      token,
+      Perfm.configuration.admin_token
+    )
+  end
+end
+```
+
+#### Usage
+
+```bash
+curl -X POST https://your-app.com/perfm/admin/heap_dumps -H "X-Perfm-Token: your-secure-token"
+```
+
+The generated heap dump will be stored via ActiveStorage and the response includes the blob ID and filename for later reference.
+
+#### Configuration
+
+Configure the admin token in your Perfm initializer:
+
+```ruby
+# config/initializers/perfm.rb
+Perfm.configure do |config|
+  config.admin_token = ENV["PERFM_ADMIN_TOKEN"]
+end
+```
+
+The generated heap dumps can be downloaded and analyzed using [heapy](https://github.com/zombocom/heapy)
+
+We're planning to add a heap analyzer within perfm itself to make the process seamless.

data/Rakefile

@@ -0,0 +1,16 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+require 'bundler/gem_tasks'
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load 'rails/tasks/engine.rake'
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+task default: :test

data/app/models/perfm/application_record.rb

@@ -0,0 +1,5 @@
+module Perfm
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/perfm/gvl_metric.rb

@@ -0,0 +1,14 @@
+module Perfm
+  class GvlMetric < ApplicationRecord
+    self.table_name = "perfm_gvl_metrics"
+
+    scope :within_time_range, ->(start_time, end_time) { 
+      where(created_at: start_time..end_time) 
+    }
+
+    def action_path
+      return "rack middleware" if controller.blank?
+      "#{controller}##{action}"
+    end
+  end
+end

data/lib/generators/perfm/install/install_generator.rb

@@ -0,0 +1,23 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+module Perfm
+  class InstallGenerator < Rails::Generators::Base
+    include ActiveRecord::Generators::Migration
+    source_root File.expand_path("templates", __dir__)
+    
+    def create_migration_file
+      migration_template(
+        'create_perfm_gvl_metrics.rb.erb',
+        File.join(db_migrate_path, "create_perfm_gvl_metrics.rb")
+      )
+    end
+    
+    private
+    
+    def migration_version
+      "[#{ActiveRecord::VERSION::STRING.to_f}]"
+    end
+  end
+end

data/lib/generators/perfm/install/templates/create_perfm_gvl_metrics.rb.erb

@@ -0,0 +1,19 @@
+class CreatePerfmGvlMetrics < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :perfm_gvl_metrics do |t|
+      t.float :gc_ms
+      t.float :run_ms
+      t.float :idle_ms
+      t.float :stall_ms
+      t.float :io_percent
+      t.string :method
+      t.string :controller
+      t.string :action
+      t.integer :puma_max_threads
+
+      t.index [:controller, :action]
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/perfm/uninstall/templates/drop_perfm_gvl_metrics.rb.erb

@@ -0,0 +1,22 @@
+class DropPerfmGvlMetrics < ActiveRecord::Migration<%= migration_version %>
+  def up
+    drop_table :perfm_gvl_metrics
+  end
+
+  def down
+    create_table :perfm_gvl_metrics do |t|
+      t.float :gc_ms
+      t.float :run_ms
+      t.float :idle_ms
+      t.float :stall_ms
+      t.float :io_percent
+      t.string :method
+      t.string :controller
+      t.string :action
+
+      t.index [:controller, :action]
+
+      t.timestamps
+    end
+  end
+end 

data/lib/generators/perfm/uninstall/uninstall_generator.rb

@@ -0,0 +1,23 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+module Perfm
+  class UninstallGenerator < Rails::Generators::Base
+    include ActiveRecord::Generators::Migration
+    source_root File.expand_path("templates", __dir__)
+    
+    def create_migration_file
+      migration_template(
+        'drop_perfm_gvl_metrics.rb.erb',
+        File.join(db_migrate_path, "drop_perfm_gvl_metrics.rb")
+      )
+    end
+    
+    private
+    
+    def migration_version
+      "[#{ActiveRecord::VERSION::STRING.to_f}]"
+    end
+  end
+end 

data/lib/perfm/agent.rb

@@ -0,0 +1,14 @@
+module Perfm
+  class Agent
+    attr_reader :config, :queue
+
+    def initialize(config, storage)
+      @config = config
+      @queue = Queue.new(storage)
+    end
+
+    def push_metrics(data)
+      queue.push_metrics(data)
+    end
+  end
+end

data/lib/perfm/client.rb

@@ -0,0 +1,78 @@
+require "net/http"
+require "json"
+
+module Perfm
+  class Client
+    HTTPS = "https".freeze
+    DEFAULT_TIMEOUT = 10
+
+    def initialize(config)
+      @api_url = config.api_url
+      @api_key = config.api_key
+      @timeout = DEFAULT_TIMEOUT
+      @mutex = Mutex.new
+      @connections = []
+      @headers = {
+        "Content-Type" => "application/json",
+        "Authorization" => "Bearer #{@api_key}",
+        "X-Perfm-Version" => Perfm::VERSION,
+      }
+    end
+
+    def post(path, data)
+      uri = URI(@api_url + path)
+      request = Net::HTTP::Post.new(uri.path, @headers)
+      request.body = data.to_json
+      transmit(request)
+    end
+
+    private
+
+    def transmit(request)
+      http = take_connection
+      response = http.request(request)
+      handle_response(response)
+    rescue => e
+      puts "HTTP Error: #{e.message}"
+    ensure
+      release_connection(http) if http
+    end
+
+    def take_connection
+      @mutex.synchronize do
+        if conn = @connections.pop
+          conn.start unless conn.started?
+          conn
+        else
+          create_connection
+        end
+      end
+    end
+
+    def release_connection(conn)
+      @mutex.synchronize { @connections << conn }
+    end
+
+    def create_connection
+      uri = URI(@api_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == HTTPS
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http
+    end
+
+    def handle_response(response)
+      case response
+      when Net::HTTPSuccess
+        true
+      when Net::HTTPUnauthorized
+        puts "Invalid API key"
+        false
+      else
+        puts "Unexpected response: #{response.code}"
+        false
+      end
+    end
+  end
+end

data/lib/perfm/configuration.rb

@@ -0,0 +1,27 @@
+module Perfm
+  class Configuration < Anyway::Config
+    config_name :perfm
+    
+    attr_config(
+      enabled: true,
+      monitor_sidekiq: false,
+      monitor_gvl: false,
+      monitor_sidekiq_queues: false,
+      storage: :api,
+      api_url: nil,
+      api_key: nil,
+    )
+
+    def monitor_sidekiq?
+      enabled? && monitor_sidekiq
+    end
+
+    def monitor_gvl?
+      enabled? && monitor_gvl
+    end
+
+    def enabled?
+      enabled
+    end
+  end
+end

data/lib/perfm/engine.rb

@@ -0,0 +1,11 @@
+module Perfm
+  class Engine < ::Rails::Engine
+    isolate_namespace Perfm
+    
+    initializer "perfm.gvl_instrumentation" do |app|
+      if Perfm.configuration.monitor_gvl?
+        app.config.middleware.insert(0, Perfm::Middleware::GvlInstrumentation)
+      end
+    end
+  end
+end

data/lib/perfm/errors/latency_exceeded_error.rb

@@ -0,0 +1,17 @@
+module Perfm
+  module Errors
+    class LatencyExceededError < StandardError
+      attr_reader :queue, :latency, :expected_latency
+
+      def initialize(queue:, latency:, expected_latency:)
+        @queue = queue
+        @latency = latency 
+        @expected_latency = expected_latency
+
+        message = "Queue latency exceeded SLA: #{latency.round(2)}s " \
+                 "(limit: #{expected_latency}s) for queue #{queue}"
+        super(message)
+      end
+    end
+  end
+end

data/lib/perfm/gvl_metrics_analyzer.rb

@@ -0,0 +1,169 @@
+module Perfm
+  class GvlMetricsAnalyzer
+    class Error < StandardError; end
+
+    def initialize(start_time:, end_time:, puma_max_threads: nil)
+      @start_time = start_time
+      @end_time = end_time
+      @puma_max_threads = puma_max_threads
+    end
+
+    def analyze
+      return empty_results if metrics.empty?
+      
+      {
+        summary: calculate_summary(metrics),
+        percentiles: calculate_percentiles(metrics),
+        action_breakdowns: calculate_action_breakdowns(metrics)
+      }
+    end
+
+    private
+
+      def metrics
+        @_metrics ||= begin
+          base_scope = GvlMetric.within_time_range(@start_time, @end_time)
+          return base_scope unless @puma_max_threads
+
+          base_scope.where(puma_max_threads: @puma_max_threads)
+        end
+      end
+
+
+      def empty_results
+        {
+          total_io_percentage: 0.0,
+          total_stall_percentage: 0.0,
+          average_response_time_ms: 0.0,
+          average_stall_ms: 0.0,
+          average_gc_ms: 0.0,
+          request_count: 0,
+          time_range: {
+            start_time: @start_time,
+            end_time: @end_time,
+            duration_seconds: (@end_time - @start_time).to_i
+          }
+        }
+      end
+
+      def calculate_io_percentage(run_ms, idle_ms)
+        total_time = run_ms + idle_ms
+        return 0.0 if total_time == 0
+        ((idle_ms / total_time) * 100.0).round(2)
+      end
+
+      def calculate_avg_response_time(run_ms, idle_ms, stall_ms, count)
+        return 0.0 if count == 0
+        ((stall_ms + run_ms + idle_ms) / count).round(2)
+      end
+
+      def calculate_summary(metrics)
+        total_run_ms = metrics.sum(:run_ms)
+        total_idle_ms = metrics.sum(:idle_ms)
+        total_stall_ms = metrics.sum(:stall_ms)
+        total_gc_ms = metrics.sum(:gc_ms)
+        count = metrics.count
+        
+        {
+          total_io_percentage: calculate_io_percentage(total_run_ms, total_idle_ms),
+          average_response_time_ms: calculate_avg_response_time(total_run_ms, total_idle_ms, total_stall_ms, count),
+          average_stall_ms: (total_stall_ms / count).round(2),
+          average_gc_ms: (total_gc_ms / count).round(2),
+          request_count: count,
+          time_range: {
+            start_time: @start_time,
+            end_time: @end_time,
+            duration_seconds: (@end_time - @start_time).to_i
+          }
+        }
+      end
+
+      def calculate_percentiles(metrics)
+        total_count = metrics.size
+
+        sorted_metrics = if metrics.is_a?(ActiveRecord::Relation)
+          metrics.order(Arel.sql("run_ms + idle_ms + stall_ms")).to_a
+        else
+          metrics.sort_by { |m| m.run_ms + m.idle_ms + m.stall_ms }
+        end
+        
+        p10 = (total_count * 0.1).floor
+        p50 = (total_count * 0.5).floor
+        p60 = (total_count * 0.6).floor
+        p90 = (total_count * 0.9).floor
+        p99 = (total_count * 0.99).floor
+        p999 = (total_count * 0.999).floor
+
+        percentile_ranges = {
+          "p0-10": 0...p10,
+          "p50-60": p50...p60,
+          "p90-99": p90...p99,
+          "p99-99.9": p99...p999,
+          "p99.9-100": p999...total_count
+        }
+
+        result = {
+          overall: "#{total_count} requests"
+        }
+        
+        result.merge!(
+          percentile_ranges.transform_values do |range|
+            range_metrics = sorted_metrics[range]
+            calculate_group_stats_in_memory(range_metrics || [])
+          end
+        )
+
+        result
+      end
+
+      def calculate_action_breakdowns(metrics)
+        metrics_by_action = metrics.group_by do |metric|
+          [metric.controller, metric.action]
+        end
+      
+        metrics_by_action.transform_keys do |(controller, action)|
+          "#{controller}##{action}"
+        end.transform_values do |action_metrics|
+          calculate_percentiles(action_metrics)
+        end
+      end
+
+      def calculate_group_stats_in_memory(metrics)
+        return empty_group_stats if metrics.empty?
+
+        avg_run_ms = (metrics.sum(&:run_ms) / metrics.size).round(1)
+        avg_idle_ms = (metrics.sum(&:idle_ms) / metrics.size).round(1)
+        avg_stall_ms = (metrics.sum(&:stall_ms) / metrics.size).round(1)
+        avg_gc_ms = (metrics.sum(&:gc_ms) / metrics.size).round(1)
+        total_ms = (avg_run_ms + avg_idle_ms + avg_stall_ms).round(1)
+        
+        io_percentage = if (avg_run_ms + avg_idle_ms) > 0
+          ((avg_idle_ms / (avg_run_ms + avg_idle_ms)) * 100).round(1)
+        else
+          0.0
+        end
+
+        {
+          cpu: avg_run_ms,
+          io: avg_idle_ms,
+          stall: avg_stall_ms,
+          gc: avg_gc_ms,
+          total: total_ms,
+          "io%": "#{io_percentage}%",
+          count: metrics.size
+        }
+      end
+
+      def empty_group_stats
+        {
+          cpu: 0.0,
+          io: 0.0,
+          stall: 0.0,
+          gc: 0.0,
+          total: 0.0,
+          "io%": "0.0%",
+          count: 0
+        }
+      end
+  end
+end

data/lib/perfm/heap_dumper.rb

@@ -0,0 +1,80 @@
+require "rbtrace"
+
+module Perfm
+  class HeapDumper
+    class Error < StandardError; end
+
+    class << self
+      def generate
+        new.generate
+      end
+    end
+
+    def generate
+      worker_pid = find_worker_pid
+      generate_dump(worker_pid)
+    end
+
+    private
+
+      def find_worker_pid
+        pid = PidStore.instance.get_first_worker_pid
+        return pid if pid
+
+        raise Error, "No Puma worker processes available"
+      end
+
+      def generate_dump(worker_pid)
+        filename = "heap_dump_pid_#{worker_pid}_time_#{Time.current.to_i}.json"
+        temp_path = Rails.root.join("tmp", filename)
+        FileUtils.mkdir_p(File.dirname(temp_path))
+
+        generate_heap_dump(worker_pid, temp_path)
+        store_dump(temp_path, filename)
+      ensure
+        FileUtils.rm_f(temp_path) if defined?(temp_path) && temp_path
+      end
+
+      def generate_heap_dump(worker_pid, output_path)
+        cmd = build_rbtrace_command(worker_pid, output_path)
+        execute_rbtrace(cmd)
+      end
+
+      def build_rbtrace_command(worker_pid, output_path)
+        <<~COMMAND
+          rbtrace -p #{worker_pid} -e '
+            Thread.new {
+              require "objspace"
+              ObjectSpace.trace_object_allocations_start
+              GC.start
+              File.open("#{output_path}", "w") { |f| 
+                ObjectSpace.dump_all(output: f)
+              }
+            }.join
+          '
+        COMMAND
+      end
+
+      def execute_rbtrace(cmd)
+        output = `#{cmd} 2>&1`
+        return if $?.success?
+
+        raise Error, "rbtrace failed: #{output}"
+      end
+
+      def store_dump(temp_path, filename)
+        File.open(temp_path) do |file|
+          blob = ActiveStorage::Blob.create_and_upload!(
+            io: file,
+            filename: filename,
+            content_type: "application/json",
+            identify: false
+          )
+          
+          puts "Heap dump stored with key: #{blob.key}"
+          
+          blob
+        end
+      end
+  end
+end

data/lib/perfm/metrics/sidekiq.rb

@@ -0,0 +1,69 @@
+module Perfm
+  module Metrics
+    class Sidekiq
+      class << self
+        def setup
+          start_monitoring
+        end
+
+        def start_monitoring
+          Thread.new do
+            while true
+              collect_metrics
+              sleep 5
+            end
+          end
+        end
+
+        def collect_metrics
+          return unless defined?(::Sidekiq)
+
+          ::Sidekiq::Queue.all.each do |queue|
+            record_queue_metrics(queue)
+            
+            if monitor_sidekiq_queues? && valid_queue_name?(queue.name)
+              check_latency_threshold(queue)
+            end
+          end
+        end
+
+        def record_queue_metrics(queue)
+          # TODO: Replace this with sending metrics to NewRelic as perfm-ingester work is not complete
+          Perfm.agent.push_metrics({
+            type: "sidekiq_queue",
+            queue: queue.name,
+            latency: queue.latency,
+            size: queue.size,
+          })
+        end
+
+        def check_latency_threshold(queue)
+          return unless expected_latency = QueueLatency.parse_latency(queue.name)
+          
+          if queue.latency > expected_latency
+            handle_exceeded_latency(queue, expected_latency)
+          end
+        end
+
+        def handle_exceeded_latency(queue, expected_latency)
+          Thread.new do
+            # TODO: Prevent flooding the error monitoring tool if there are a lot of latency exceeded errors
+            raise Errors::LatencyExceededError.new(
+              queue: queue.name,
+              latency: queue.latency,
+              expected_latency: expected_latency
+            )
+          end
+        end
+
+        def monitor_sidekiq_queues?
+          @monitor_sidekiq_queues ||= Perfm.configuration.monitor_sidekiq_queues?
+        end
+  
+        def valid_queue_name?(queue_name)
+          QueueLatency.valid_queue_name?(queue_name)
+        end
+      end
+    end
+  end
+end

data/lib/perfm/middleware/gvl_instrumentation.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "gvl_timing"
+
+module Perfm
+  module Middleware
+    class GvlInstrumentation
+      def initialize(app)
+        @app = app
+        @puma_max_threads = nil
+      end
+  
+      def call(env)
+        response = nil
+        before_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        before_gc_time = GC.total_time
+        
+        timer = GVLTiming.measure do
+          response = @app.call(env)
+        end
+        
+        total_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - before_time
+        gc_time = GC.total_time - before_gc_time
+      
+        begin
+          @puma_max_threads ||= get_puma_max_threads if defined?(::Puma)
+          
+          data = {
+            gc_ms: (gc_time / 1_000_000.0).round(2),
+            run_ms: (timer.cpu_duration * 1000.0).round(2),
+            idle_ms: (timer.idle_duration * 1000.0).round(2),
+            stall_ms: (timer.stalled_duration * 1000.0).round(2),
+            io_percent: (timer.idle_duration / total_time * 100.0).round(1),
+            method: env["REQUEST_METHOD"],
+            controller: nil,
+            action: nil,
+            puma_max_threads: @puma_max_threads
+          }
+          
+          if (controller = env["action_controller.instance"])
+            data[:controller] = controller.controller_path
+            data[:action] = controller.action_name
+          end
+      
+          Perfm.agent.push_metrics(data)
+        rescue => e
+          puts "GVL metrics collection failed: #{e.message}"
+        end
+      
+        response
+      end
+
+      private
+
+      def get_puma_max_threads
+        JSON.parse(Puma.stats)["max_threads"]
+      end
+    end
+  end
+end

data/lib/perfm/pid_store.rb

@@ -0,0 +1,26 @@
+require "singleton"
+
+# TODO: Or read from Puma pidfile?
+# TODO: Handle single mode
+
+module Perfm
+  class PidStore
+    include Singleton
+    
+    def initialize
+      @worker_pids = Concurrent::Array.new
+    end
+
+    def add_worker_pid(pid)
+      @worker_pids << pid
+    end
+
+    def get_first_worker_pid
+      @worker_pids.sample
+    end
+
+    def clear
+      @worker_pids.clear
+    end
+  end
+end

data/lib/perfm/queue.rb

@@ -0,0 +1,56 @@
+module Perfm
+  class Queue
+    FLUSH_INTERVAL = 60
+    FLUSH_THRESHOLD = 100
+
+    def initialize(storage)
+      @metrics = []
+      @storage = storage
+      @mutex = Mutex.new
+      Kernel.at_exit { flush }
+      start_thread
+    end
+
+    def push_metrics(data)
+      mutex.synchronize do
+        @metrics.push(data)
+        wakeup_thread if @metrics.size >= FLUSH_THRESHOLD || !thread.alive?
+      end
+    end
+
+    def collect_pending_metrics
+      result = nil
+      mutex.synchronize do
+        if @metrics.size > 0
+          result = @metrics
+          @metrics = []
+        end
+      end
+      result
+    end
+
+    def flush
+      if data = collect_pending_metrics
+        @storage.store(data)
+      end
+    end
+
+    def flush_indefinitely
+      while true
+        sleep(FLUSH_INTERVAL) and flush
+      end
+    end
+
+    private
+
+    attr_reader :mutex, :thread
+
+    def start_thread
+      @thread = Thread.new { flush_indefinitely }
+    end
+
+    def wakeup_thread
+      (thread && thread.alive?) ? thread.wakeup : start_thread
+    end
+  end
+end

data/lib/perfm/queue_latency.rb

@@ -0,0 +1,23 @@
+module Perfm
+  module QueueLatency
+    QUEUE_PATTERN = /\Awithin_(\d+)_(second|seconds|minute|minutes|hour|hours)\z/i
+
+    def self.parse_latency(queue_name)
+      return unless valid_queue_name?(queue_name)
+
+      match_data = queue_name.match(QUEUE_PATTERN)
+      value = match_data[1].to_i
+      unit = match_data[2].downcase.sub(/s\z/, '')
+
+      case unit
+      when 'second' then value
+      when 'minute' then value * 60
+      when 'hour' then value * 3600
+      end
+    end
+
+    def self.valid_queue_name?(queue_name)
+      queue_name&.match?(QUEUE_PATTERN)
+    end
+  end
+end

data/lib/perfm/storage/api.rb

@@ -0,0 +1,13 @@
+module Perfm
+  module Storage
+    class Api < Base
+      def initialize(client)
+        @client = client
+      end
+
+      def store(metrics)
+        @client.post("/metrics", metrics: metrics)
+      end
+    end
+  end
+end

data/lib/perfm/storage/base.rb

@@ -0,0 +1,9 @@
+module Perfm
+  module Storage
+    class Base
+      def store(metrics)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/perfm/storage/local.rb

@@ -0,0 +1,11 @@
+module Perfm
+  module Storage
+    class Local < Base
+      def store(metrics)
+        return if metrics.empty?
+
+        Perfm::GvlMetric.insert_all(metrics)
+      end
+    end
+  end
+end

data/lib/perfm/version.rb

@@ -0,0 +1,3 @@
+module Perfm
+  VERSION = "1.0.0"
+end

data/lib/perfm.rb

@@ -0,0 +1,67 @@
+require "rails/engine"
+require "active_support/all"
+require "anyway_config"
+
+require "perfm/version"
+require "perfm/engine"
+
+module Perfm
+  autoload :Configuration, "perfm/configuration"
+  autoload :Client, "perfm/client"
+  autoload :Queue, "perfm/queue"
+  autoload :Agent, "perfm/agent"
+  autoload :GvlMetricsAnalyzer, "perfm/gvl_metrics_analyzer"
+  
+  module Storage
+    autoload :Base, "perfm/storage/base"
+    autoload :Api, "perfm/storage/api"
+    autoload :Local, "perfm/storage/local"
+  end
+
+  module Middleware
+    autoload :GvlInstrumentation, "perfm/middleware/gvl_instrumentation"
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def agent
+      @agent
+    end
+
+    def setup!
+      return unless configuration.enabled?
+
+      setup_sidekiq if configuration.monitor_sidekiq?
+      
+      storage = if configuration.storage == :local
+        Storage::Local.new
+      else
+        Storage::Api.new(Client.new(configuration))
+      end
+      
+      @agent = Agent.new(configuration, storage)
+    end
+
+    def generate_heap_dump
+      HeapDumper.generate
+    end
+
+    private
+
+    def setup_sidekiq
+      return unless defined?(::Sidekiq)
+      Metrics::Sidekiq.setup
+    end
+  end
+end
+
+require "perfm/engine" if defined?(Rails)

metadata

@@ -0,0 +1,176 @@
+--- !ruby/object:Gem::Specification
+name: perfm
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Vishnu M
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-05-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: anyway_config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: sidekiq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rbtrace
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: gvl_timing
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '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'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+description: Monitor Rails application performance metrics
+email:
+- vishnu.m@bigbinary.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- app/models/perfm/application_record.rb
+- app/models/perfm/gvl_metric.rb
+- lib/generators/perfm/install/install_generator.rb
+- lib/generators/perfm/install/templates/create_perfm_gvl_metrics.rb.erb
+- lib/generators/perfm/uninstall/templates/drop_perfm_gvl_metrics.rb.erb
+- lib/generators/perfm/uninstall/uninstall_generator.rb
+- lib/perfm.rb
+- lib/perfm/agent.rb
+- lib/perfm/client.rb
+- lib/perfm/configuration.rb
+- lib/perfm/engine.rb
+- lib/perfm/errors/latency_exceeded_error.rb
+- lib/perfm/gvl_metrics_analyzer.rb
+- lib/perfm/heap_dumper.rb
+- lib/perfm/metrics/sidekiq.rb
+- lib/perfm/middleware/gvl_instrumentation.rb
+- lib/perfm/pid_store.rb
+- lib/perfm/queue.rb
+- lib/perfm/queue_latency.rb
+- lib/perfm/storage/api.rb
+- lib/perfm/storage/base.rb
+- lib/perfm/storage/local.rb
+- lib/perfm/version.rb
+homepage: https://github.com/vishnu-m/perfm
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/vishnu-m/perfm
+  source_code_uri: https://github.com/vishnu-m/perfm
+  changelog_uri: https://github.com/vishnu-m/perfm/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Everything Rails performance monitoring
+test_files: []