active_record_query_counter 2.3.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b460515835154824cb80fec7db1e62dc4f4f983f8779fc1b80bec3c728646a4
-  data.tar.gz: 3d26302dd73d2ae010f4732ca4711a7dd1daa4ca0cca55e5ccd50349e89b282c
+  metadata.gz: 89a919244edbce9bf36bdaa232078b04470f1bacc952469eab4a4fffc2416e08
+  data.tar.gz: 97a66d47fda85ad15b832da3e390f8cc035a374983c64f53e4d673094b54d8b9
 SHA512:
-  metadata.gz: d1af45ed8c0659df4fcbf665621576b07380565a1289458e868b7cb33825c2d055e7b489eb1e490c31a566157a01f328eedd2771f9f3f5bffdece2b357445a01
-  data.tar.gz: ba21e07f668e1c3f97c61ce6f48fd10ef2d019afdd7d9d579e3487c710d58e8b44a9b1c5042572bc74be55a907c506d6385947dbe85a10b14b57e2b7b94037b7
+  metadata.gz: c5c657cf312deb55e21063b5d08f824cd762e42050704b06fc0610e00f938aacac8fc37050c60d293452521841ca614430cb50cd3bf10d3bca794df9d0dee6d0
+  data.tar.gz: d81cb599eea68c911fad417a902848f1b1f2d0f29f4d095b70d5af8ef2f6366dac0e2b2de0fe534ed51fcbffb3d696147edfc53e64b549862a4dfe78a156a54d

data/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 3.0.0
+
+### Changed
+
+- Query time now excludes GC pause time and Ruby thread CPU time so that it more closely reflects the time actually spent waiting on the database. This is what is now reported as the event duration in the `query_time` and `row_count` notifications.
+
+### Added
+
+- Added `:elapsed_time` (the raw wall clock time), `:gc_time`, and `:cpu_time` (all in milliseconds) to the `query_time` and `row_count` notification payloads.
+
+### Removed
+
+- Dropped support for Ruby versions older than 3.1 (required for `GC.total_time`).
+
 ## 2.3.0
 
 ### Added

data/README.md

@@ -55,6 +55,15 @@ ActiveRecordQueryCounter.count_queries do
 end
 ```
 
+### Query Time
+
+The query time (`ActiveRecordQueryCounter.query_time` and the duration reported by the notifications) is **not** the raw wall clock time a query took. The wall clock time includes time the thread was not actually waiting on the database, such as GC pauses (which can be triggered by other threads and stop the world) and the Ruby CPU work of building the result objects. On a busy, multi-threaded server these can add up to seconds, making a trivial query look pathologically slow.
+
+To report the time actually spent waiting on the database as closely as possible, the GC time and thread CPU time that elapsed while the query ran are subtracted from the wall clock time. The raw wall clock time is still available as `:elapsed_time` in the notification payloads.
+
+> [!NOTE]
+> Measuring GC time requires Ruby's GC total time measurement, which is enabled by default (`GC.measure_total_time`). Thread CPU time is measured via `Process::CLOCK_THREAD_CPUTIME_ID`; on platforms that do not provide it, CPU time is treated as zero.
+
 ### Middleware Integration
 
 For **Rails** and **Sidekiq**, middleware is included to enable query counting in web requests and workers.
@@ -106,6 +115,11 @@ Triggered when a query exceeds the query_time threshold with the payload:
 - `:binds` - The bind parameters that were used.
 - `:row_count` - The number of rows returned.
 - `:trace` - The stack trace of where the query was executed.
+- `:elapsed_time` - The raw wall clock time the query took (in milliseconds).
+- `:gc_time` - The GC time that elapsed while the query ran (in milliseconds).
+- `:cpu_time` - The thread CPU time spent while the query ran (in milliseconds).
+
+The duration of the notification event is the query time: the wall clock time with the GC time and CPU time subtracted out (see [Query Time](#query-time)). The raw wall clock time is still available as `:elapsed_time`.
 
 ##### 2. active_record_query_counter.row_count notification
 
@@ -115,6 +129,9 @@ Triggered when a query exceeds the row_count threshold with the payload:
 - `:binds` - The bind parameters that were used.
 - `:row_count` - The number of rows returned.
 - `:trace` - The stack trace of where the query was executed.
+- `:elapsed_time` - The raw wall clock time the query took (in milliseconds).
+- `:gc_time` - The GC time that elapsed while the query ran (in milliseconds).
+- `:cpu_time` - The thread CPU time spent while the query ran (in milliseconds).
 
 ##### 3. active_record_query_counter.transaction_time notification
 

data/VERSION

@@ -1 +1 @@
-2.3.0
+3.0.0

data/active_record_query_counter.gemspec

@@ -34,9 +34,9 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "activerecord", ">= 5.1"
+  spec.add_dependency "activerecord", ">= 6.0"
 
   spec.add_development_dependency "bundler"
 
-  spec.required_ruby_version = ">= 2.5"
+  spec.required_ruby_version = ">= 3.1"
 end

data/lib/active_record_query_counter/connection_adapter_extension.rb

@@ -3,37 +3,63 @@
 module ActiveRecordQueryCounter
   # Module to prepend to the connection adapter to inject the counting behavior.
   module ConnectionAdapterExtension
+    # Clock used to measure the CPU time consumed by the current thread while a query runs.
+    # It is not available on every platform (e.g. Windows), in which case CPU time is not
+    # measured and is treated as zero.
+    CPU_CLOCK_ID = (Process::CLOCK_THREAD_CPUTIME_ID if defined?(Process::CLOCK_THREAD_CPUTIME_ID))
+
     class << self
       def inject(connection_class)
         # Rails 7.1+ uses internal_exec_query instead of exec_query.
-        mod = (connection_class.instance_methods.include?(:internal_exec_query) ? InternalExecQuery : ExecQuery)
+        mod = (connection_class.method_defined?(:internal_exec_query) ? InternalExecQuery : ExecQuery)
         unless connection_class.include?(mod)
           connection_class.prepend(mod)
         end
       end
-    end
 
-    module ExecQuery
-      def exec_query(sql, name = nil, binds = [], *args, **kwargs)
+      # Measure a query by wrapping its execution. In addition to the wall clock time, the GC
+      # time and thread CPU time spent while the query runs are captured so that the time
+      # actually spent waiting on the database can be isolated from time lost to garbage
+      # collection and Ruby VM work.
+      #
+      # @param sql [String] the SQL statement being executed
+      # @param name [String, nil] the name of the query
+      # @param binds [Array] the bind parameters
+      # @yield executes the query and returns its result
+      # @return [Object] the result of the query
+      def measure_query(sql, name, binds)
+        gc_start = GC.total_time
+        cpu_start = current_cpu_time
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        result = super
+        result = yield
         if result.is_a?(ActiveRecord::Result)
           end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          ActiveRecordQueryCounter.add_query(sql, name, binds, result.length, start_time, end_time)
+          cpu_time = current_cpu_time - cpu_start
+          gc_time = (GC.total_time - gc_start) / 1_000_000_000.0
+          ActiveRecordQueryCounter.add_query(sql, name, binds, result.length, start_time, end_time, gc_time, cpu_time)
         end
         result
       end
+
+      private
+
+      # The current thread CPU time in seconds, or 0.0 when the platform does not support it.
+      #
+      # @return [Float]
+      def current_cpu_time
+        CPU_CLOCK_ID ? Process.clock_gettime(CPU_CLOCK_ID) : 0.0
+      end
+    end
+
+    module ExecQuery
+      def exec_query(sql, name = nil, binds = [], *args, **kwargs)
+        ConnectionAdapterExtension.measure_query(sql, name, binds) { super }
+      end
     end
 
     module InternalExecQuery
       def internal_exec_query(sql, name = nil, binds = [], *args, **kwargs)
-        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        result = super
-        if result.is_a?(ActiveRecord::Result)
-          end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          ActiveRecordQueryCounter.add_query(sql, name, binds, result.length, start_time, end_time)
-        end
-        result
+        ConnectionAdapterExtension.measure_query(sql, name, binds) { super }
       end
     end
   end

data/lib/active_record_query_counter.rb

@@ -65,32 +65,51 @@ module ActiveRecordQueryCounter
 
     # Increment the query counters.
     #
+    # The reported query time is the wall clock time spent executing the query with the GC
+    # time and Ruby thread CPU time subtracted out so that it reflects the time actually
+    # spent waiting on the database as closely as possible (see {.database_query_time}). This
+    # query time, rather than the raw wall clock time, is what is accumulated, compared against
+    # the threshold, and used as the duration of the emitted notification.
+    #
+    # @param sql [String] the SQL statement that was executed
+    # @param name [String, nil] the name of the query
+    # @param binds [Array] the bind parameters
     # @param row_count [Integer] the number of rows returned by the query
-    # @param elapsed_time [Float] the time spent executing the query
+    # @param start_time [Float] the monotonic time when the query started
+    # @param end_time [Float] the monotonic time when the query ended
+    # @param gc_time [Float] the GC time in seconds that elapsed while the query ran
+    # @param cpu_time [Float] the thread CPU time in seconds spent while the query ran
     # @return [void]
     # @api private
-    def add_query(sql, name, binds, row_count, start_time, end_time)
+    def add_query(sql, name, binds, row_count, start_time, end_time, gc_time, cpu_time)
       return if IGNORED_STATEMENTS.include?(name)
 
       counter = current_counter
       return unless counter.is_a?(Counter)
 
       elapsed_time = end_time - start_time
+      query_time = database_query_time(elapsed_time, gc_time, cpu_time)
       counter.query_count += 1
       counter.row_count += row_count
-      counter.query_time += elapsed_time
+      counter.query_time += query_time
+
+      # The notification duration is the database query time, so the event ends that long after
+      # it started rather than at the raw wall clock end time.
+      notification_end_time = start_time + query_time
 
       trace = nil
       query_time_threshold = (counter.thresholds.query_time || -1)
-      if query_time_threshold >= 0 && elapsed_time >= query_time_threshold
+      if query_time_threshold >= 0 && query_time >= query_time_threshold
         trace = backtrace
-        send_notification("query_time", start_time, end_time, sql: sql, binds: binds, row_count: row_count, trace: trace)
+        payload = notification_payload(sql: sql, binds: binds, row_count: row_count, trace: trace, elapsed_time: elapsed_time, gc_time: gc_time, cpu_time: cpu_time)
+        send_notification("query_time", start_time, notification_end_time, **payload)
       end
 
       row_count_threshold = (counter.thresholds.row_count || -1)
       if row_count_threshold >= 0 && row_count >= row_count_threshold
         trace ||= backtrace
-        send_notification("row_count", start_time, end_time, sql: sql, binds: binds, row_count: row_count, trace: trace)
+        payload = notification_payload(sql: sql, binds: binds, row_count: row_count, trace: trace, elapsed_time: elapsed_time, gc_time: gc_time, cpu_time: cpu_time)
+        send_notification("row_count", start_time, notification_end_time, **payload)
       end
     end
 
@@ -283,6 +302,42 @@ module ActiveRecordQueryCounter
       ActiveSupport::Notifications.publish("active_record_query_counter.#{name}", start_time, end_time, id, payload)
     end
 
+    def notification_payload(sql:, binds:, row_count:, trace:, elapsed_time:, gc_time:, cpu_time:)
+      {
+        sql: sql,
+        binds: binds,
+        row_count: row_count,
+        trace: trace,
+        elapsed_time: (elapsed_time * 1000.0).round(6),
+        gc_time: (gc_time * 1000.0).round(6),
+        cpu_time: (cpu_time * 1000.0).round(6)
+      }
+    end
+
+    # Estimate the time spent waiting on the database by subtracting the GC time and thread CPU
+    # time from the wall clock time the query took.
+    #
+    # The GC time and CPU time normally measure distinct, non-overlapping intervals: a GC pause
+    # triggered by another thread happens while this thread is parked waiting on the database
+    # (off CPU, so it does not count as CPU time), while CPU time covers the Ruby work of
+    # building the result. They only overlap when the query's own thread triggers a GC, which
+    # runs on that thread and so counts as both GC time and CPU time. When that overlap is large
+    # enough to drive the result negative, only the larger of the two is subtracted so the shared
+    # interval is removed once. The result is clamped so it never exceeds the wall clock time and
+    # is never negative.
+    #
+    # @param elapsed_time [Float] the wall clock time the query took in seconds
+    # @param gc_time [Float] the GC time in seconds that elapsed while the query ran
+    # @param cpu_time [Float] the thread CPU time in seconds spent while the query ran
+    # @return [Float] the estimated database time in seconds
+    def database_query_time(elapsed_time, gc_time, cpu_time)
+      return 0.0 if elapsed_time <= 0.0
+
+      query_time = elapsed_time - (gc_time + cpu_time)
+      query_time = elapsed_time - [gc_time, cpu_time].max if query_time.negative?
+      query_time.clamp(0.0, elapsed_time)
+    end
+
     def backtrace
       caller.reject { |line| line.start_with?(__dir__) }
     end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_record_query_counter
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Brian Durand
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.1'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.1'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -38,7 +37,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email:
 - bbdurand@gmail.com
 executables: []
@@ -66,7 +64,6 @@ metadata:
   homepage_uri: https://github.com/bdurand/active_record_query_counter
   source_code_uri: https://github.com/bdurand/active_record_query_counter
   changelog_uri: https://github.com/bdurand/active_record_query_counter/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -74,15 +71,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Provides detailed insights into how your code interacts with the database
   by hooking into ActiveRecord.