active_record_query_counter 3.1.1 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e1c73a61e42bb29aabf511c59f3009a49760a9173eab4686de8ecdf05c9e24b
-  data.tar.gz: 973f7b3a3ea5d285a023eb3545ff2e86350f51b1bd19db668c3efdda5ce976d4
+  metadata.gz: 499ad971fe53532f23bfa674961133b6c39f850b39d89b102d959be760ba386c
+  data.tar.gz: 0f2eb66f8d2d274ddd2b173fce6f21ba35a7069d398f0f72e03052905f0b9221
 SHA512:
-  metadata.gz: 36fc6f8d28bc037c472fb0090828dc545ed8b386f49fbb2222a60313d560efb521ee407da6fb2f9d9a28880a170c7eb00f1a3a644a6f7a3a7d701575da28b07b
-  data.tar.gz: 4f5bbb92f7ea0001e5f902537ec3d41a617af9685efc6c3a15b8abb89ceacc9e35969b7ea0f5ecbe2b664fdd9ab71df50aa4e893a199c3aad8abbb891552c8b5
+  metadata.gz: 8ead36fbb297cfb37af6ccb6c5b50903c123224c5c0ff72f96cb9ccf4caeac02da8e12b34858f91d7ef4ea153383babe0c6eac37e59bace9491707542ccac48b
+  data.tar.gz: d3042dca0d9c1b0624338367461c0277360a676061dd62dd4f2ba101cfdf7831c67a1382637703e4d91d7da51bfc90e0829b2792ff2b20fecfbcee892b48fff4

data/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.3.0
+
+### Added
+
+- `TransactionInfo#query_count` reports the number of queries executed within the transaction.
+- `TransactionInfo#gc_time` and `TransactionInfo#cpu_time` report the GC time and thread CPU time in seconds that elapsed while the transaction was open.
+- `TransactionInfo#idle_time` estimates the time the transaction was open but not spent executing queries, running Ruby code, or paused for garbage collection. A large value indicates the process was waiting on something other than the database (an HTTP request, a sleep, a lock, etc.) while it held the transaction open.
+- The `transaction_time` notification payload now includes `:queries` along with `:gc_time`, `:cpu_time`, and `:idle_time` in milliseconds. The queries are an array of new `ActiveRecordQueryCounter::QueryInfo` objects; each includes the SQL statement, query name, row count, start and end times, and the GC, CPU, and connection setup times measured for the query. Bind parameter values are not included.
+- The full query details for a transaction only live in a transient `ActiveRecordQueryCounter::TransactionDetails` object that populates the `transaction_time` notification payload and is then released. The `TransactionInfo` objects retained for the duration of a `count_queries` block hold only counts and timings, so memory stays flat even when a process creates many implicit transactions (for example, many saves without an explicit transaction).
+
+## 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

@@ -14,6 +14,9 @@ It measures database usage within a block of code, including:
 - The number of transactions used
 - The total time spent inside transactions
 - The number of transactions that were rolled back
+- The queries executed inside each transaction, with the time each one took
+- The GC time and CPU time spent inside each transaction
+- The idle time inside each transaction spent waiting on things other than the database
 
 This gem is designed to help you:
 
@@ -57,9 +60,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 +123,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,21 +138,29 @@ 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
 
 Triggered when a transaction exceeds the transaction_time threshold with the payload:
 
 - `:trace` - The stack trace of where the transaction was completed.
+- `:queries` - An array of `ActiveRecordQueryCounter::QueryInfo` objects for the queries executed within the transaction. Each object includes the SQL statement, query name, row count, and timing details. Bind parameter values are not included.
+- `:gc_time` - The GC time that elapsed while the transaction was open (in milliseconds).
+- `:cpu_time` - The thread CPU time spent while the transaction was open (in milliseconds).
+- `:idle_time` - The estimated time the transaction was open but not spent executing queries, running Ruby code, or paused for garbage collection (in milliseconds). A large value indicates the process was waiting on something other than the database (an HTTP request, a sleep, a lock, etc.) while it held the transaction open.
 
 ##### 4. active_record_query_counter.transaction_count notification
 
 Triggered when transactions exceed the transaction_count threshold with the payload:
 
-- `:transactions` - An array of `ActiveRecordQueryCounter::TransactionInfo` objects.
+- `:transactions` - An array of `ActiveRecordQueryCounter::TransactionInfo` objects. Each object includes the number of queries executed within the transaction (`query_count`), the GC time (`gc_time`) and thread CPU time (`cpu_time`) in seconds spent while the transaction was open, and the estimated idle time (`idle_time`) in seconds spent waiting on things other than the database.
 
 The duration of the notification event is the time between when the first transaction was started and the last transaction was completed.
 
+> [!NOTE]
+> The full query details for a transaction are only available in the `transaction_time` notification payload. They are released after the notification fires; the `TransactionInfo` objects retained for the duration of a `count_queries` block hold only counts and timings so that memory stays flat even when many transactions are created. Query details are also only collected while queries are being counted inside a `count_queries` block (or the bundled middleware).
+
 #### Setting Thresholds
 
 Thresholds can be configured **globally** in an initializer:

data/VERSION

@@ -1 +1 @@
-3.1.1
+3.3.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

@@ -3,63 +3,76 @@
 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))
+    # 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
       # @param binds [Array] the bind parameters
+      # @param connection [Object, nil] the connection adapter the query is being executed on
       # @yield executes the query and returns its result
       # @return [Object] the result of the query
-      def measure_query(sql, name, binds)
+      def measure_query(sql, name, binds, connection = nil)
         gc_start = GC.total_time
-        cpu_start = current_cpu_time
+        cpu_start = ActiveRecordQueryCounter.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
+          cpu_time = ActiveRecordQueryCounter.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, connection: connection)
         end
         result
       end
+    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
+    module InternalExecQuery
+      def internal_exec_query(sql, name = nil, binds = [], **kwargs)
+        ConnectionAdapterExtension.measure_query(sql, name, binds, self) { super }
       end
     end
 
-    module ExecQuery
-      def 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
-    end
 
-    module InternalExecQuery
-      def internal_exec_query(sql, name = nil, binds = [], **kwargs)
-        ConnectionAdapterExtension.measure_query(sql, name, binds) { super }
+      def reconnect!(...)
+        ActiveRecordQueryCounter.measure_connection_setup { super }
+      end
+
+      def verify!(...)
+        ActiveRecordQueryCounter.measure_connection_setup { super }
       end
     end
   end

data/lib/active_record_query_counter/counter.rb

@@ -41,9 +41,14 @@ module ActiveRecordQueryCounter
     # @param trace [Array<String>] the trace of the transaction
     # @param start_time [Float] the monotonic time when the transaction began
     # @param end_time [Float] the monotonic time when the transaction ended
+    # @param query_count [Integer] the number of queries executed within the transaction
+    # @param gc_time [Float] the GC time in seconds that elapsed while the transaction was open
+    # @param cpu_time [Float] the thread CPU time in seconds spent while the transaction was open
+    # @param idle_time [Float] the time in seconds the transaction was open but not spent on
+    #   queries, Ruby code, or garbage collection
     # @return [void]
     # @api private
-    def add_transaction(trace:, start_time:, end_time:)
+    def add_transaction(trace:, start_time:, end_time:, query_count: 0, gc_time: 0.0, cpu_time: 0.0, idle_time: 0.0)
       trace_transactions = @transactions_hash[trace]
       if trace_transactions
         # Memory optimization so that we don't store duplicate traces for every transaction in a loop.
@@ -53,7 +58,7 @@ module ActiveRecordQueryCounter
         @transactions_hash[trace] = trace_transactions
       end
 
-      trace_transactions << TransactionInfo.new(start_time: start_time, end_time: end_time, trace: trace)
+      trace_transactions << TransactionInfo.new(start_time: start_time, end_time: end_time, trace: trace, query_count: query_count, gc_time: gc_time, cpu_time: cpu_time, idle_time: idle_time)
     end
 
     # Return the number of transactions that have been tracked by the counter.

data/lib/active_record_query_counter/query_info.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ActiveRecordQueryCounter
+  # Data structure for storing information about a query executed within a transaction.
+  # Note that the start and end times are monotonic time and not wall clock time. Bind
+  # parameter values are deliberately not stored since they can contain sensitive data.
+  class QueryInfo
+    attr_reader :sql, :name, :row_count, :start_time, :end_time, :gc_time, :cpu_time, :connection_time
+
+    def initialize(sql:, name:, row_count:, start_time:, end_time:, gc_time: 0.0, cpu_time: 0.0, connection_time: 0.0)
+      @sql = sql
+      @name = name
+      @row_count = row_count
+      @start_time = start_time
+      @end_time = end_time
+      @gc_time = gc_time
+      @cpu_time = cpu_time
+      @connection_time = connection_time
+    end
+
+    # Return the wall clock time spent executing the query.
+    #
+    # @return [Float]
+    def elapsed_time
+      end_time - start_time
+    end
+  end
+end

data/lib/active_record_query_counter/transaction_details.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ActiveRecordQueryCounter
+  # Data structure with the full details about a transaction, including the queries executed
+  # within it. Note that the start and end times are monotonic time and not wall clock time.
+  #
+  # This object is transient. It is created when a transaction is recorded to build the
+  # `transaction_time` notification payload and to derive the retained
+  # {ActiveRecordQueryCounter::TransactionInfo}, and is then released so the query details
+  # do not accumulate in memory.
+  class TransactionDetails
+    attr_reader :start_time, :end_time, :trace, :queries, :gc_time, :cpu_time
+
+    def initialize(start_time:, end_time:, trace:, queries: [], gc_time: 0.0, cpu_time: 0.0)
+      @start_time = start_time
+      @end_time = end_time
+      @trace = trace
+      @queries = queries
+      @gc_time = gc_time
+      @cpu_time = cpu_time
+    end
+
+    # Return the time spent in the transaction.
+    #
+    # @return [Float]
+    def elapsed_time
+      end_time - start_time
+    end
+
+    # Return the number of queries executed within the transaction.
+    #
+    # @return [Integer]
+    def query_count
+      queries.size
+    end
+
+    # Estimate the time the transaction was open but not spent executing queries, running Ruby
+    # code, or paused for garbage collection. A large value indicates the process was waiting
+    # on something other than the database (an HTTP request, a sleep, a lock, etc.) while it
+    # held the transaction open.
+    #
+    # The wall clock time of each query is subtracted first since it already includes any GC
+    # and CPU time that occurred while the query ran. Only the GC and CPU time that occurred
+    # outside of queries is then subtracted from the remainder. GC and CPU time normally cover
+    # distinct intervals, but they overlap when this thread triggers a GC; when subtracting
+    # both would drive the result negative, only the larger of the two is subtracted so the
+    # shared interval is removed once (the same heuristic used for the query time). The result
+    # is clamped so it is never negative and never exceeds the elapsed time.
+    #
+    # @return [Float]
+    def idle_time
+      return 0.0 if elapsed_time <= 0.0
+
+      queries_elapsed_time = 0.0
+      queries_gc_time = 0.0
+      queries_cpu_time = 0.0
+      queries.each do |query|
+        queries_elapsed_time += query.elapsed_time
+        queries_gc_time += query.gc_time
+        queries_cpu_time += query.cpu_time
+      end
+
+      remaining_time = elapsed_time - queries_elapsed_time
+      return 0.0 if remaining_time <= 0.0
+
+      other_gc_time = (gc_time - queries_gc_time).clamp(0.0, remaining_time)
+      other_cpu_time = (cpu_time - queries_cpu_time).clamp(0.0, remaining_time)
+
+      idle_time = remaining_time - (other_gc_time + other_cpu_time)
+      idle_time = remaining_time - [other_gc_time, other_cpu_time].max if idle_time.negative?
+      idle_time.clamp(0.0, remaining_time)
+    end
+  end
+end

data/lib/active_record_query_counter/transaction_extension.rb

@@ -16,6 +16,9 @@ module ActiveRecordQueryCounter
     def initialize(...)
       super
       @active_record_query_counter_start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @active_record_query_counter_gc_start = GC.total_time
+      @active_record_query_counter_cpu_start = ActiveRecordQueryCounter.current_cpu_time
+      @active_record_query_counter_queries = ActiveRecordQueryCounter.register_transaction_queries(connection)
     end
 
     def commit(...)
@@ -44,8 +47,17 @@ module ActiveRecordQueryCounter
       return unless start_time
 
       @active_record_query_counter_start_time = nil
+      ActiveRecordQueryCounter.unregister_transaction_queries(connection)
       end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      ActiveRecordQueryCounter.add_transaction(start_time, end_time)
+      gc_time = (GC.total_time - @active_record_query_counter_gc_start) / 1_000_000_000.0
+      cpu_time = ActiveRecordQueryCounter.current_cpu_time - @active_record_query_counter_cpu_start
+      ActiveRecordQueryCounter.add_transaction(
+        start_time,
+        end_time,
+        queries: @active_record_query_counter_queries,
+        gc_time: gc_time,
+        cpu_time: cpu_time
+      )
       ActiveRecordQueryCounter.increment_rollbacks if rollback
     end
   end

data/lib/active_record_query_counter/transaction_info.rb

@@ -1,15 +1,24 @@
 # frozen_string_literal: true
 
 module ActiveRecordQueryCounter
-  # Data structure for storing information about a transaction. Note that the start and end
-  # times are monotonic time and not wall clock time.
+  # Data structure for storing the counts and timings of a transaction. Note that the start
+  # and end times are monotonic time and not wall clock time.
+  #
+  # This structure deliberately does not hold the queries executed within the transaction so
+  # that retaining it for the duration of a `count_queries` block stays cheap. The full query
+  # details are only available transiently in the `transaction_time` notification payload
+  # (see {ActiveRecordQueryCounter::TransactionDetails}).
   class TransactionInfo
-    attr_reader :start_time, :end_time, :trace
+    attr_reader :start_time, :end_time, :trace, :query_count, :gc_time, :cpu_time, :idle_time
 
-    def initialize(start_time:, end_time:, trace:)
+    def initialize(start_time:, end_time:, trace:, query_count: 0, gc_time: 0.0, cpu_time: 0.0, idle_time: 0.0)
       @start_time = start_time
       @end_time = end_time
       @trace = trace
+      @query_count = query_count
+      @gc_time = gc_time
+      @cpu_time = cpu_time
+      @idle_time = idle_time
     end
 
     # Return the time spent in the transaction.

data/lib/active_record_query_counter.rb

@@ -4,7 +4,9 @@ require "securerandom"
 
 require_relative "active_record_query_counter/connection_adapter_extension"
 require_relative "active_record_query_counter/counter"
+require_relative "active_record_query_counter/query_info"
 require_relative "active_record_query_counter/thresholds"
+require_relative "active_record_query_counter/transaction_details"
 require_relative "active_record_query_counter/transaction_info"
 require_relative "active_record_query_counter/transaction_extension"
 
@@ -26,6 +28,10 @@ module ActiveRecordQueryCounter
   IGNORED_STATEMENTS = %w[SCHEMA EXPLAIN].freeze
   private_constant :IGNORED_STATEMENTS
 
+  # Clock used to measure the CPU time consumed by the current thread. 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))
+
   @lock = Mutex.new
   @default_thresholds = Thresholds.new
 
@@ -72,10 +78,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,20 +92,38 @@ 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
+    # @param connection [Object, nil] the connection adapter the query was executed on; used to
+    #   attach the query to the transaction currently open on that connection, if any
     # @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, connection: nil)
       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
 
+      queries = transaction_queries(connection)
+      if queries
+        queries << QueryInfo.new(
+          sql: sql,
+          name: name,
+          row_count: row_count,
+          start_time: start_time,
+          end_time: end_time,
+          gc_time: gc_time,
+          cpu_time: cpu_time,
+          connection_time: connection_time
+        )
+      end
+
       # 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
@@ -107,14 +132,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
@@ -123,18 +148,50 @@ module ActiveRecordQueryCounter
     #
     # @param start_time [Float] the time the transaction started
     # @param end_time [Float] the time the transaction ended
+    # @param queries [Array<ActiveRecordQueryCounter::QueryInfo>] the queries executed within
+    #   the transaction
+    # @param gc_time [Float] the GC time in seconds that elapsed while the transaction was open
+    # @param cpu_time [Float] the thread CPU time in seconds spent while the transaction was open
     # @return [void]
     # @api private
-    def add_transaction(start_time, end_time)
+    def add_transaction(start_time, end_time, queries: [], gc_time: 0.0, cpu_time: 0.0)
       counter = current_counter
       return unless counter.is_a?(Counter)
 
-      trace = backtrace
-      counter.add_transaction(trace: trace, start_time: start_time, end_time: end_time)
+      # The details object holds the full query information. Only the counts and timings
+      # derived from it are retained on the counter; the details are released when this
+      # method returns so the query data does not accumulate in memory.
+      details = TransactionDetails.new(
+        start_time: start_time,
+        end_time: end_time,
+        trace: backtrace,
+        queries: queries,
+        gc_time: gc_time,
+        cpu_time: cpu_time
+      )
+
+      counter.add_transaction(
+        trace: details.trace,
+        start_time: start_time,
+        end_time: end_time,
+        query_count: details.query_count,
+        gc_time: gc_time,
+        cpu_time: cpu_time,
+        idle_time: details.idle_time
+      )
 
       transaction_time_threshold = counter.thresholds.transaction_time || -1
       if transaction_time_threshold.between?(0, end_time - start_time)
-        send_notification("transaction_time", start_time, end_time, trace: backtrace)
+        send_notification(
+          "transaction_time",
+          start_time,
+          end_time,
+          trace: details.trace,
+          queries: details.queries,
+          gc_time: (gc_time * 1000.0).round(6),
+          cpu_time: (cpu_time * 1000.0).round(6),
+          idle_time: (details.idle_time * 1000.0).round(6)
+        )
       end
     end
 
@@ -149,6 +206,91 @@ module ActiveRecordQueryCounter
       counter.rollback_count += 1
     end
 
+    # The current thread CPU time in seconds, or 0.0 when the platform does not support it.
+    #
+    # @return [Float]
+    # @api private
+    def current_cpu_time
+      CPU_CLOCK_ID ? Process.clock_gettime(CPU_CLOCK_ID) : 0.0
+    end
+
+    # Register a new query list for a transaction that was opened on a connection. Queries
+    # executed on that connection will be appended to the list until it is unregistered.
+    # Registering a connection always replaces any list already registered for it.
+    #
+    # The list is bound to the counter that is active when the transaction is opened. Queries
+    # counted by a different counter (e.g. a nested `count_queries` block) are not appended,
+    # so the recorded query count for the transaction stays consistent with the counter that
+    # recorded the transaction.
+    #
+    # @param connection [Object] the connection adapter the transaction was opened on
+    # @return [Array<ActiveRecordQueryCounter::QueryInfo>] the registered query list
+    # @api private
+    def register_transaction_queries(connection)
+      registry = ActiveSupport::IsolatedExecutionState[:active_record_query_counter_transaction_queries] ||= {}
+      queries = []
+      registry[connection] = {counter: current_counter, queries: queries}
+      queries
+    end
+
+    # Remove the registered query list for a connection when its transaction has ended.
+    #
+    # @param connection [Object] the connection adapter the transaction was opened on
+    # @return [void]
+    # @api private
+    def unregister_transaction_queries(connection)
+      ActiveSupport::IsolatedExecutionState[:active_record_query_counter_transaction_queries]&.delete(connection)
+      nil
+    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 +437,34 @@ 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
+
+    # The query list registered for the transaction currently open on a connection, or nil
+    # when the connection is unknown, has no open transaction, or the transaction was opened
+    # under a different counter than the current one.
+    def transaction_queries(connection)
+      return nil if connection.nil?
+
+      entry = ActiveSupport::IsolatedExecutionState[:active_record_query_counter_transaction_queries]&.[](connection)
+      entry[:queries] if entry && entry[:counter].equal?(current_counter)
     end
 
     def send_notification(name, start_time, end_time, payload = {})
@@ -320,7 +472,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 +480,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 +505,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.3.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: []
@@ -51,9 +37,11 @@ files:
 - lib/active_record_query_counter.rb
 - lib/active_record_query_counter/connection_adapter_extension.rb
 - lib/active_record_query_counter/counter.rb
+- lib/active_record_query_counter/query_info.rb
 - lib/active_record_query_counter/rack_middleware.rb
 - lib/active_record_query_counter/sidekiq_middleware.rb
 - lib/active_record_query_counter/thresholds.rb
+- lib/active_record_query_counter/transaction_details.rb
 - lib/active_record_query_counter/transaction_extension.rb
 - lib/active_record_query_counter/transaction_info.rb
 homepage: https://github.com/bdurand/active_record_query_counter