perfm 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e1cff83c55f6245ed510d9f41fe5c169a662173e243ba0e8fb58c10d3274933
-  data.tar.gz: 3084b6db3933db8c23045b49374ac1474ad070b586a716452c095075be135a71
+  metadata.gz: c533c4d2398428da1e5d70056f68282566ffb4a6521737b8fa402a133ede71dd
+  data.tar.gz: 50f92a5880b9bd8773ea4f8692f0e40eb531606b1e5b9e38b5cf77d4c3fc2453
 SHA512:
-  metadata.gz: a511d3fbefdb4554f5f87fa27f09e3f1c64d590dcac763e9cc0ca8b9e53c867ccf80337ff465edd0bcd2b6a63f88b27277d26121cc0dd87abec6411bab1e7e3e
-  data.tar.gz: cb3838701d25771a72c52866b6aaa7bddf215452f1980495c36854655da73ec254088a2e6d38d660e9b59242f5b6cd8f7db3001e74d7d89a2cf68eb76cee50f2
+  metadata.gz: 70e239a276d658595cae7ad6f2dd366d1d25faaff2f42e6404688fe860b92eafb9a2c94df2ea74b5424a44f592f52422261de81bc26ab1512553f37a2705b5df
+  data.tar.gz: 2ccdb7cda8634d8d381d36c3ccf798020fa6837c1aaa9e63db749ab334674f28892f85fcf4308fe87aaf9b7446923104f1c54e01d11516f358f91410057cac86

data/README.md

@@ -1,16 +1,17 @@
-Perfm
-==============
+# 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
------------------
+## 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
------------------
+## Installation
+
 Add perfm to your Gemfile.
+
 ```ruby
 gem 'perfm'
 ```
@@ -23,8 +24,8 @@ 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
------------------
+## Configuration
+
 Configure Perfm in an initializer:
 
 ```ruby
@@ -83,7 +84,6 @@ The following features are currently in beta and may have limited functionality
 
 ### 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
@@ -101,9 +101,31 @@ When enabled, Perfm will monitor your Sidekiq queues and raise a `Perfm::Errors:
 
 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)
+- `within_X_seconds` (e.g., within_5_seconds)
+- `within_X_minutes` (e.g., within_2_minutes)
+- `within_X_hours` (e.g., within_1_hours)
+
+### Sidekiq GVL Instrumentation
+
+To enable GVL instrumentation for Sidekiq, first run the generator to add migrations for the required table to store the metrics.
+
+```bash
+bin/rails generate perfm:sidekiq_gvl_metrics
+```
+
+Then enable the `monitor_sidekiq_gvl` configuration in your initializer.
+
+```ruby
+Perfm.configure do |config|
+  config.monitor_sidekiq_gvl = true
+end
+```
+
+When enabled, Perfm will collect GVL metrics at a job level, similar to how it collects metrics for HTTP requests. This can be used to analyze GVL metrics specifically for Sidekiq queues to understand their I/O characteristics.
+
+```ruby
+Perfm::SidekiqGvlMetric.calculate_queue_io_percentage("within_5_seconds")
+```
 
 ### Heap analyzer
 
@@ -145,6 +167,7 @@ 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

data/app/models/perfm/sidekiq_gvl_metric.rb

@@ -0,0 +1,22 @@
+module Perfm
+  class SidekiqGvlMetric < ApplicationRecord
+    self.table_name = "perfm_sidekiq_gvl_metrics"
+
+    scope :within_time_range, ->(start_time, end_time) { 
+      where(created_at: start_time..end_time) 
+    }
+
+    def self.calculate_queue_io_percentage(queue_name, start_time: nil, end_time: nil)
+      scope = where(queue: queue_name)
+      scope = scope.within_time_range(start_time, end_time) if start_time && end_time
+
+      total_run_ms = scope.sum(:run_ms)
+      total_idle_ms = scope.sum(:idle_ms)
+      
+      total_time = total_run_ms + total_idle_ms
+      return 0.0 if total_time == 0
+      
+      ((total_idle_ms.to_f / total_time) * 100.0).round(2)
+    end
+  end
+end

data/lib/generators/perfm/sidekiq_gvl_metrics/sidekiq_gvl_metrics_generator.rb

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

data/lib/generators/perfm/sidekiq_gvl_metrics/templates/create_perfm_sidekiq_gvl_metrics.rb.erb

@@ -0,0 +1,17 @@
+class CreatePerfmSidekiqGvlMetrics < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :perfm_sidekiq_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 :job_class
+      t.string :queue
+
+      t.index [:job_class, :queue]
+
+      t.timestamps
+    end
+  end
+end 

data/lib/perfm/agent.rb

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

data/lib/perfm/configuration.rb

@@ -6,6 +6,7 @@ module Perfm
       enabled: true,
       monitor_sidekiq: false,
       monitor_gvl: false,
+      monitor_sidekiq_gvl: false,
       monitor_sidekiq_queues: false,
       storage: :api,
       api_url: nil,
@@ -20,6 +21,10 @@ module Perfm
       enabled? && monitor_gvl
     end
 
+    def monitor_sidekiq_gvl?
+      enabled? && monitor_sidekiq_gvl
+    end
+
     def enabled?
       enabled
     end

data/lib/perfm/engine.rb

@@ -6,6 +6,14 @@ module Perfm
       if Perfm.configuration.monitor_gvl?
         app.config.middleware.insert(0, Perfm::Middleware::GvlInstrumentation)
       end
+      
+      if Perfm.configuration.monitor_sidekiq_gvl? && defined?(Sidekiq)
+        Sidekiq.configure_server do |config|
+          config.server_middleware do |chain|
+            chain.add Perfm::Middleware::SidekiqGvlInstrumentation
+          end
+        end
+      end
     end
   end
 end

data/lib/perfm/middleware/sidekiq_gvl_instrumentation.rb

@@ -0,0 +1,35 @@
+require "gvl_timing"
+
+module Perfm
+  module Middleware
+    class SidekiqGvlInstrumentation
+      def call(job_instance, job_payload, queue)
+        before_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        before_gc_time = GC.total_time
+        
+        timer = GVLTiming.measure do
+          yield
+        end
+        
+        total_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - before_time
+        gc_time = GC.total_time - before_gc_time
+      
+        begin
+          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),
+            job_class: job_payload["class"],
+            queue: queue
+          }
+      
+          Perfm.agent.push_sidekiq_metrics(data)
+        rescue => e
+          puts "Sidekiq GVL metrics collection failed: #{e.message}"
+        end
+      end
+    end
+  end
+end 

data/lib/perfm/sidekiq_gvl_metrics_analyzer.rb

@@ -0,0 +1,127 @@
+require "json"
+
+module Perfm
+  class SidekiqGvlMetricsAnalyzer
+    attr_reader :start_time, :end_time, :query
+
+    def initialize(start_time: nil, end_time: nil, job_class: nil, queue: nil)
+      @start_time = start_time
+      @end_time = end_time
+      @query = SidekiqGvlMetric.where(true)
+      @query = @query.where(job_class: job_class) if job_class
+      @query = @query.where(queue: queue) if queue
+      @query = @query.where(created_at: start_time..end_time) if start_time && end_time
+    end
+
+    def analyze
+      return {} if query.count.zero?
+
+      result = {}
+      result[:total_io_percentage] = total_io_percentage
+      result[:total_io_and_stall_percentage] = total_io_and_stall_percentage
+      result[:average_processing_time_ms] = average_processing_time_ms
+      result[:average_stall_ms] = average_stall_ms
+      result[:job_count] = job_count
+      result[:time_range] = time_range_info
+      result[:by_job_class] = metrics_by_job_class
+      result[:by_queue] = metrics_by_queue
+      result
+    end
+
+    private
+
+    def average_io_ms
+      query.average(:idle_ms).to_f
+    end
+
+    def average_stall_ms
+      query.average(:stall_ms).to_f
+    end
+
+    def average_run_ms
+      query.average(:run_ms).to_f
+    end
+
+    def average_processing_time_ms
+      average_run_ms + average_io_ms + average_stall_ms
+    end
+
+    def job_count
+      query.count
+    end
+
+    def total_io_percentage
+      (average_io_ms / average_processing_time_ms * 100).round(1)
+    end
+
+    def total_io_and_stall_percentage
+      ((average_io_ms + average_stall_ms) / average_processing_time_ms * 100).round(1)
+    end
+
+    def time_range_info
+      range_start = start_time || query.minimum(:created_at)
+      range_end = end_time || query.maximum(:created_at)
+      duration = range_end - range_start
+
+      {
+        start_time: range_start.iso8601,
+        end_time: range_end.iso8601,
+        duration_seconds: duration.to_i
+      }
+    end
+
+    def metrics_by_job_class
+      results = {}
+      
+      job_classes = query.distinct.pluck(:job_class)
+      job_classes.each do |job_class|
+        job_query = query.where(job_class: job_class)
+        
+        job_avg_processing_ms = job_query.average(:run_ms).to_f + 
+                              job_query.average(:idle_ms).to_f + 
+                              job_query.average(:stall_ms).to_f
+        
+        job_avg_io_ms = job_query.average(:idle_ms).to_f
+        job_avg_stall_ms = job_query.average(:stall_ms).to_f
+        
+        results[job_class] = {
+          count: job_query.count,
+          average_processing_time_ms: job_avg_processing_ms.round(1),
+          average_io_ms: job_avg_io_ms.round(1),
+          average_stall_ms: job_avg_stall_ms.round(1),
+          io_percentage: (job_avg_io_ms / job_avg_processing_ms * 100).round(1),
+          io_and_stall_percentage: ((job_avg_io_ms + job_avg_stall_ms) / job_avg_processing_ms * 100).round(1)
+        }
+      end
+      
+      results
+    end
+    
+    def metrics_by_queue
+      results = {}
+      
+      queues = query.distinct.pluck(:queue)
+      queues.each do |queue|
+        queue_query = query.where(queue: queue)
+        
+        queue_avg_processing_ms = queue_query.average(:run_ms).to_f + 
+                                queue_query.average(:idle_ms).to_f + 
+                                queue_query.average(:stall_ms).to_f
+        
+        queue_avg_io_ms = queue_query.average(:idle_ms).to_f
+        queue_avg_stall_ms = queue_query.average(:stall_ms).to_f
+        
+        results[queue] = {
+          count: queue_query.count,
+          average_processing_time_ms: queue_avg_processing_ms.round(1),
+          average_io_ms: queue_avg_io_ms.round(1),
+          average_stall_ms: queue_avg_stall_ms.round(1),
+          io_percentage: (queue_avg_io_ms / queue_avg_processing_ms * 100).round(1),
+          io_and_stall_percentage: ((queue_avg_io_ms + queue_avg_stall_ms) / queue_avg_processing_ms * 100).round(1)
+        }
+      end
+      
+      results
+    end
+  end
+end 

data/lib/perfm/storage/local.rb

@@ -4,7 +4,11 @@ module Perfm
       def store(metrics)
         return if metrics.empty?
 
-        Perfm::GvlMetric.insert_all(metrics)
+        if metrics.first.key?(:job_class)
+          SidekiqGvlMetric.insert_all(metrics)
+        else
+          Perfm::GvlMetric.insert_all(metrics)
+        end
       end
     end
   end

data/lib/perfm/version.rb

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

data/lib/perfm.rb

@@ -11,6 +11,7 @@ module Perfm
   autoload :Queue, "perfm/queue"
   autoload :Agent, "perfm/agent"
   autoload :GvlMetricsAnalyzer, "perfm/gvl_metrics_analyzer"
+  autoload :SidekiqGvlMetricsAnalyzer, "perfm/sidekiq_gvl_metrics_analyzer"
   
   module Storage
     autoload :Base, "perfm/storage/base"
@@ -20,6 +21,7 @@ module Perfm
 
   module Middleware
     autoload :GvlInstrumentation, "perfm/middleware/gvl_instrumentation"
+    autoload :SidekiqGvlInstrumentation, "perfm/middleware/sidekiq_gvl_instrumentation"
   end
 
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: perfm
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Vishnu M
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-05 00:00:00.000000000 Z
+date: 2025-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -114,7 +114,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.21'
-description: Monitor Rails application performance metrics
+description: Perfm aims to be a performance monitoring tool for Ruby on Rails applications.
 email:
 - vishnu.m@bigbinary.com
 executables: []
@@ -126,8 +126,11 @@ files:
 - Rakefile
 - app/models/perfm/application_record.rb
 - app/models/perfm/gvl_metric.rb
+- app/models/perfm/sidekiq_gvl_metric.rb
 - lib/generators/perfm/install/install_generator.rb
 - lib/generators/perfm/install/templates/create_perfm_gvl_metrics.rb.erb
+- lib/generators/perfm/sidekiq_gvl_metrics/sidekiq_gvl_metrics_generator.rb
+- lib/generators/perfm/sidekiq_gvl_metrics/templates/create_perfm_sidekiq_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
@@ -140,20 +143,22 @@ files:
 - lib/perfm/heap_dumper.rb
 - lib/perfm/metrics/sidekiq.rb
 - lib/perfm/middleware/gvl_instrumentation.rb
+- lib/perfm/middleware/sidekiq_gvl_instrumentation.rb
 - lib/perfm/pid_store.rb
 - lib/perfm/queue.rb
 - lib/perfm/queue_latency.rb
+- lib/perfm/sidekiq_gvl_metrics_analyzer.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
+homepage: https://github.com/bigbinary/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
+  homepage_uri: https://github.com/bigbinary/perfm
+  source_code_uri: https://github.com/bigbinary/perfm
+  changelog_uri: https://github.com/bigbinary/perfm/blob/master/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -169,8 +174,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: Everything Rails performance monitoring
+summary: 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.
 test_files: []