active_record_query_counter 3.1.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e1c73a61e42bb29aabf511c59f3009a49760a9173eab4686de8ecdf05c9e24b
-  data.tar.gz: 973f7b3a3ea5d285a023eb3545ff2e86350f51b1bd19db668c3efdda5ce976d4
+  metadata.gz: daaa5b12132d82613fb803966073b0b55131f0e47b83c1d05e0e6dca63c3ba98
+  data.tar.gz: ede14e3f86b236a2d39009dfe84d930a0541eea70c1273d7346ff4ac40218154
 SHA512:
-  metadata.gz: 36fc6f8d28bc037c472fb0090828dc545ed8b386f49fbb2222a60313d560efb521ee407da6fb2f9d9a28880a170c7eb00f1a3a644a6f7a3a7d701575da28b07b
-  data.tar.gz: 4f5bbb92f7ea0001e5f902537ec3d41a617af9685efc6c3a15b8abb89ceacc9e35969b7ea0f5ecbe2b664fdd9ab71df50aa4e893a199c3aad8abbb891552c8b5
+  metadata.gz: 03c8d4e734928d45f7a95188e4a9dc805ef45dabef52d0144d4323f5100163c2603955d1ffa3e78f22178fec458932ea8f56ee67f346bb7a51eae83264de4cee
+  data.tar.gz: 38e3d4959598bc8a9d8cd80c06b07fa34485e9a812095be7783f7a8161e3bcf0e4f3aaa619a114fe8beac9b4251bfdc78b3e445b67e5e0fe21a505b865bb33b2

data/CHANGELOG.md

@@ -4,6 +4,16 @@ 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.2.0
+
+### Added
+
+- Connection setup time (time spent in the adapter's `connect!`, `reconnect!`, and `verify!` methods while running a query) is now measured and subtracted from the reported query time, so a query that triggers a reconnect after an idle period or a database failover is no longer reported as an inexplicably slow query. The time is reported separately as `:connection_time` in the `query_time` and `row_count` notification payloads.
+
+### Removed
+
+- Support for ActiveRecord versions prior to 7.1.
+
 ## 3.1.1
 
 ### Fixed

data/README.md

@@ -57,9 +57,11 @@ 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.
+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), the Ruby CPU work of building the result objects, and the time spent establishing or re-establishing the database connection. 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.
+To report the time actually spent waiting on the database as closely as possible, the connection setup time, 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.
+
+Connection setup time is the wall clock time spent inside the adapter's `connect!`, `reconnect!`, and `verify!` methods while running the query. ActiveRecord (re)establishes and verifies connections lazily, from within the query execution path, so when a connection has gone stale — after an idle period, or a database failover (common with clustered databases such as Amazon Aurora) — the reconnect (DNS resolution, TCP connect, TLS handshake, and authentication) happens on the next query and is otherwise charged to it. This is reported separately as `:connection_time` in the notification payloads so these events are diagnosable rather than appearing as inexplicably slow queries.
 
 > [!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.
@@ -118,8 +120,9 @@ Triggered when a query exceeds the query_time threshold with the payload:
 - `: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).
+- `:connection_time` - The time spent establishing, verifying, or reconnecting the database connection 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`.
+The duration of the notification event is the query time: the wall clock time with the connection setup time, 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
 
@@ -132,6 +135,7 @@ Triggered when a query exceeds the row_count threshold with the payload:
 - `: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).
+- `:connection_time` - The time spent establishing, verifying, or reconnecting the database connection while the query ran (in milliseconds).
 
 ##### 3. active_record_query_counter.transaction_time notification
 

data/VERSION

@@ -1 +1 @@
-3.1.1
+3.2.0

data/active_record_query_counter.gemspec

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

data/lib/active_record_query_counter/connection_adapter_extension.rb

@@ -8,19 +8,28 @@ module ActiveRecordQueryCounter
     # measured and is treated as zero.
     CPU_CLOCK_ID = (Process::CLOCK_THREAD_CPUTIME_ID if defined?(Process::CLOCK_THREAD_CPUTIME_ID))
 
+    # Connection adapter methods that establish, verify, or reconnect the underlying database
+    # connection. When these run inside a query (for example when a stale connection is
+    # re-established after an idle period or a database failover), the wall clock time they
+    # consume is spent setting up the connection rather than executing the query. It is measured
+    # separately so it can be subtracted from the reported query time.
+    CONNECTION_SETUP_METHODS = %i[connect! reconnect! verify!].freeze
+
     class << self
       def inject(connection_class)
-        # Rails 7.1+ uses internal_exec_query instead of exec_query.
-        mod = (connection_class.method_defined?(:internal_exec_query) ? InternalExecQuery : ExecQuery)
-        unless connection_class.include?(mod)
-          connection_class.prepend(mod)
+        unless connection_class.include?(InternalExecQuery)
+          connection_class.prepend(InternalExecQuery)
+        end
+
+        unless connection_class.include?(ConnectionSetupExtension)
+          connection_class.prepend(ConnectionSetupExtension)
         end
       end
 
       # 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.
+      # time, thread CPU time, and connection setup 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, Ruby VM work, and (re)establishing the database connection.
       #
       # @param sql [String] the SQL statement being executed
       # @param name [String, nil] the name of the query
@@ -30,13 +39,18 @@ module ActiveRecordQueryCounter
       def measure_query(sql, name, binds)
         gc_start = GC.total_time
         cpu_start = current_cpu_time
+        previous_timer = ActiveRecordQueryCounter.start_connection_timer
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        result = yield
+        begin
+          result = yield
+        ensure
+          connection_time = ActiveRecordQueryCounter.stop_connection_timer(previous_timer)
+        end
         if result.is_a?(ActiveRecord::Result)
           end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           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)
+          ActiveRecordQueryCounter.add_query(sql, name, binds, result.length, start_time, end_time, gc_time, cpu_time, connection_time)
         end
         result
       end
@@ -51,15 +65,27 @@ module ActiveRecordQueryCounter
       end
     end
 
-    module ExecQuery
-      def exec_query(sql, name = nil, binds = [], **kwargs)
+    module InternalExecQuery
+      def internal_exec_query(sql, name = nil, binds = [], **kwargs)
         ConnectionAdapterExtension.measure_query(sql, name, binds) { super }
       end
     end
 
-    module InternalExecQuery
-      def internal_exec_query(sql, name = nil, binds = [], **kwargs)
-        ConnectionAdapterExtension.measure_query(sql, name, binds) { super }
+    # Module prepended to the connection adapter to measure the wall clock time spent
+    # establishing, verifying, or reconnecting the database connection while a query is running
+    # (see {CONNECTION_SETUP_METHODS}). The measured time is accumulated on the current query's
+    # connection timer so it can be subtracted from the reported query time.
+    module ConnectionSetupExtension
+      def connect!(...)
+        ActiveRecordQueryCounter.measure_connection_setup { super }
+      end
+
+      def reconnect!(...)
+        ActiveRecordQueryCounter.measure_connection_setup { super }
+      end
+
+      def verify!(...)
+        ActiveRecordQueryCounter.measure_connection_setup { super }
       end
     end
   end

data/lib/active_record_query_counter.rb

@@ -72,10 +72,11 @@ 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.
+    # time, Ruby thread CPU time, and connection setup 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
@@ -85,16 +86,18 @@ module ActiveRecordQueryCounter
     # @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
+    # @param connection_time [Float] the time in seconds spent establishing, verifying, or
+    #   reconnecting the database connection while the query ran
     # @return [void]
     # @api private
-    def add_query(sql, name, binds, row_count, start_time, end_time, gc_time, cpu_time)
+    def add_query(sql, name, binds, row_count, start_time, end_time, gc_time, cpu_time, connection_time = 0.0)
       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)
+      query_time = database_query_time(elapsed_time, gc_time, cpu_time, connection_time)
       counter.query_count += 1
       counter.row_count += row_count
       counter.query_time += query_time
@@ -107,14 +110,14 @@ module ActiveRecordQueryCounter
       query_time_threshold = counter.thresholds.query_time || -1
       if query_time_threshold.between?(0, query_time)
         trace = backtrace
-        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)
+        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, connection_time: connection_time)
         send_notification("query_time", start_time, notification_end_time, **payload)
       end
 
       row_count_threshold = counter.thresholds.row_count || -1
       if row_count_threshold.between?(0, row_count)
         trace ||= backtrace
-        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)
+        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, connection_time: connection_time)
         send_notification("row_count", start_time, notification_end_time, **payload)
       end
     end
@@ -149,6 +152,54 @@ module ActiveRecordQueryCounter
       counter.rollback_count += 1
     end
 
+    # Begin measuring the time spent establishing, verifying, or reconnecting the database
+    # connection for a single query. Returns the timer that was previously in effect so it can
+    # be restored by {.stop_connection_timer}; this keeps nested queries (should they ever
+    # occur) from leaking connection time into one another.
+    #
+    # @return [Object, nil] the previous connection timer
+    # @api private
+    def start_connection_timer
+      previous_timer = connection_timer
+      self.connection_timer = {elapsed: 0.0, measuring: false}
+      previous_timer
+    end
+
+    # Finish measuring connection setup time for the current query and restore the previously
+    # active timer.
+    #
+    # @param previous_timer [Object, nil] the timer returned by {.start_connection_timer}
+    # @return [Float] the connection setup time in seconds accumulated for the query
+    # @api private
+    def stop_connection_timer(previous_timer)
+      timer = connection_timer
+      self.connection_timer = previous_timer
+      timer ? timer[:elapsed] : 0.0
+    end
+
+    # Measure the wall clock time a connection setup operation (connect, reconnect, or verify)
+    # takes and accumulate it onto the current query's connection timer. When no query is being
+    # measured, or when a connection setup operation is already being measured (for example when
+    # `verify!` delegates to `reconnect!`), the block is yielded without recording so the
+    # interval is only counted once.
+    #
+    # @yield the connection setup operation
+    # @return [Object] the result of the block
+    # @api private
+    def measure_connection_setup
+      timer = connection_timer
+      return yield if timer.nil? || timer[:measuring]
+
+      timer[:measuring] = true
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      begin
+        yield
+      ensure
+        timer[:elapsed] += Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        timer[:measuring] = false
+      end
+    end
+
     # Return the number of queries that have been counted within the current block.
     # Returns nil if not inside a block where queries are being counted.
     #
@@ -295,24 +346,24 @@ module ActiveRecordQueryCounter
 
     private
 
-    # The counter is stored in ActiveSupport::IsolatedExecutionState when available so that
-    # it follows the application's configured isolation level (thread or fiber). The fallback
-    # for ActiveSupport 6.x uses Thread.current, which is fiber-local, so on those versions
-    # queries executed in a fiber spawned inside the block are not counted.
+    # The counter is stored in ActiveSupport::IsolatedExecutionState so that it follows the
+    # application's configured isolation level (thread or fiber).
     def current_counter
-      if defined?(ActiveSupport::IsolatedExecutionState)
-        ActiveSupport::IsolatedExecutionState[:active_record_query_counter]
-      else
-        Thread.current[:active_record_query_counter]
-      end
+      ActiveSupport::IsolatedExecutionState[:active_record_query_counter]
     end
 
     def current_counter=(counter)
-      if defined?(ActiveSupport::IsolatedExecutionState)
-        ActiveSupport::IsolatedExecutionState[:active_record_query_counter] = counter
-      else
-        Thread.current[:active_record_query_counter] = counter
-      end
+      ActiveSupport::IsolatedExecutionState[:active_record_query_counter] = counter
+    end
+
+    # The connection timer accumulates the connection setup time for the query currently being
+    # measured. It is stored with the same isolation as the counter (see {#current_counter}).
+    def connection_timer
+      ActiveSupport::IsolatedExecutionState[:active_record_query_counter_connection_timer]
+    end
+
+    def connection_timer=(timer)
+      ActiveSupport::IsolatedExecutionState[:active_record_query_counter_connection_timer] = timer
     end
 
     def send_notification(name, start_time, end_time, payload = {})
@@ -320,7 +371,7 @@ 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:)
+    def notification_payload(sql:, binds:, row_count:, trace:, elapsed_time:, gc_time:, cpu_time:, connection_time:)
       {
         sql: sql,
         binds: binds,
@@ -328,12 +379,18 @@ module ActiveRecordQueryCounter
         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)
+        cpu_time: (cpu_time * 1000.0).round(6),
+        connection_time: (connection_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.
+    # Estimate the time spent waiting on the database by subtracting the connection setup time,
+    # GC time, and thread CPU time from the wall clock time the query took.
+    #
+    # The connection setup time is a measured sub-interval of the wall clock time that was spent
+    # establishing, verifying, or reconnecting the database connection rather than executing the
+    # query, so it is removed first. This is the time that inflates a trivial query into a
+    # multi-second one after an idle period or a database failover.
     #
     # 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
@@ -347,13 +404,18 @@ module ActiveRecordQueryCounter
     # @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
+    # @param connection_time [Float] the time in seconds spent establishing, verifying, or
+    #   reconnecting the database connection while the query ran
     # @return [Float] the estimated database time in seconds
-    def database_query_time(elapsed_time, gc_time, cpu_time)
+    def database_query_time(elapsed_time, gc_time, cpu_time, connection_time = 0.0)
       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)
+      wait_time = (elapsed_time - connection_time).clamp(0.0, elapsed_time)
+      return 0.0 if wait_time <= 0.0
+
+      query_time = wait_time - (gc_time + cpu_time)
+      query_time = wait_time - [gc_time, cpu_time].max if query_time.negative?
+      query_time.clamp(0.0, wait_time)
     end
 
     def backtrace

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_record_query_counter
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 3.2.0
 platform: ruby
 authors:
 - Brian Durand
@@ -15,28 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
+        version: '7.1'
 email:
 - bbdurand@gmail.com
 executables: []