txnap 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e25e7973412d6c47a46bd8200327ab03514e2487dd17b806be084ff4bed447e3
+  data.tar.gz: 905642c31d101baaf851397e3888efda9b1cea8ffef45f92d50fa15536ca2718
+SHA512:
+  metadata.gz: 8519156462359a000ed5d280a5401aeca9d7a1c598abc90d7fcdae0286f5372b2a2f5346e077bae29b8e9be91a85be747268bd88e533ef9e789c9db1422dedae
+  data.tar.gz: 19c6b62e818a98cdb2188553b8f18fa574dcae81b059dcb6d202a30d1dd5e53a6dd29500853124c3e939cd0729c51badd64137a6b83eca5e972e7b796f5de46e

data/Appraisals

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+appraise "rails_7_2" do
+  gem "activerecord", "~> 7.2.0"
+end
+
+appraise "rails_8_0" do
+  gem "activerecord", "~> 8.0.0"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,233 @@
+# Txnap
+
+Catch transactions napping with locks held.
+
+`txnap` detects time spent away from the database while an
+Active Record transaction is materially open.
+
+A transaction can take one second even when its SQL totals only 30 ms. The
+remaining 970 ms may be Ruby computation, file I/O, an external request, a
+`sleep`, or Fiber scheduling while row locks are still held. Slow-query tools
+do not expose that gap.
+
+This gem measures from the completion of the real `BEGIN` through the start of
+`COMMIT` or `ROLLBACK`, then reports the longest interval between database
+events. It never changes transaction behavior.
+
+## Installation
+
+The gem has not been published yet. Until the first release, install it from
+Git:
+
+```ruby
+gem "txnap", github: "ydah/txnap"
+```
+
+It supports Active Record 7.2 and 8.0. Rails applications install the
+notification subscribers automatically.
+
+## Usage
+
+Configure the detector in an initializer:
+
+```ruby
+Txnap.configure do |config|
+  config.mode = :log
+  config.gap_threshold = 0.1
+  config.min_transaction_duration = 0.0
+  config.only_with_locks = false
+  config.capture_call_sites = :always
+  config.ignore_if = nil
+end
+```
+
+Non-Rails Active Record applications must also call:
+
+```ruby
+Txnap.install!
+```
+
+A report looks like:
+
+```text
+Txnap::IdleGapDetected
+
+Transaction held for 1,024 ms (BEGIN → COMMIT)
+Database time: 31 ms
+Longest non-database gap: 742 ms
+
+Gap occurred between:
+  after:  UPDATE "users" SET ... (app/services/checkout.rb:88)
+  before: INSERT INTO "audit_logs" ... (app/services/checkout.rb:131)
+
+Locks possibly held during the gap:
+  UPDATE users (row lock)  app/services/checkout.rb:88
+
+Move slow non-database work (I/O, rendering, external calls,
+heavy computation) outside the transaction.
+```
+
+### Configuration
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `mode` | `:log` | `:log` writes a warning. `:raise` is intended for tests. |
+| `gap_threshold` | `0.1` | Inclusive longest-gap threshold in seconds. |
+| `min_transaction_duration` | `0.0` | Ignore shorter materialized transactions. |
+| `only_with_locks` | `false` | Report only when the longest gap follows likely lock acquisition. |
+| `capture_call_sites` | `:always` | `:always`, `:sampled`, or `:off`. |
+| `ignore_if` | `nil` | A callable receiving the report; truthy suppresses notification. |
+| `logger` | Rails logger | Optional logger override. |
+
+`:sampled` calls `caller_locations` only when an SQL event creates a new
+longest-gap candidate. This lowers overhead, but one side of a reported gap can
+have no call site. `:off` retains SQL text without application locations.
+
+`:raise` runs from the `transaction.active_record` finish notification. A
+commit has already succeeded by this point, so the exception cannot roll it
+back. The exception message states this explicitly.
+
+### Suppression and filtering
+
+Suppress a known-safe block in the current isolated execution context:
+
+```ruby
+Txnap.suppress do
+  ApplicationRecord.transaction { rebuild_local_cache }
+end
+```
+
+Or filter completed reports:
+
+```ruby
+Txnap.configure do |config|
+  config.ignore_if = ->(report) {
+    report.transaction_duration < 0.5 && report.locks.empty?
+  }
+end
+```
+
+### Notifications and APM integration
+
+Every accepted report emits `idle_gap.txnap`. Numeric durations
+are unrounded milliseconds; rounding happens only in log formatting.
+
+```ruby
+ActiveSupport::Notifications.subscribe("idle_gap.txnap") do |event|
+  payload = event.payload
+
+  MyAPM.record_custom_event(
+    "ActiveRecordIdleGap",
+    transaction_ms: payload[:transaction_duration_ms],
+    database_ms: payload[:database_time_ms],
+    longest_gap_ms: payload[:longest_gap_ms],
+    sql_count: payload[:sql_count]
+  )
+end
+```
+
+The payload also includes the gap's preceding and following SQL metadata, the
+three longest gaps, likely locks, and the transaction outcome.
+
+## What is and is not measured
+
+- The origin is the finish of the actual `BEGIN` SQL notification.
+- The endpoint is the start of `COMMIT` or `ROLLBACK`.
+- Transaction control SQL contributes to database time.
+- Schema notifications and query-cache hits are ignored as timeline
+  boundaries. Modern Rails marks cache hits with `payload[:cached] == true`;
+  their event name is not reliably `CACHE`.
+- Savepoints join the real transaction timeline and do not create reports of
+  their own.
+- Memory is bounded: each trace retains the previous event, the three longest
+  gaps, and at most 20 distinct lock candidates rather than all SQL.
+
+Active Record lazily materializes transactions. Therefore this code does not
+report the sleep:
+
+```ruby
+ApplicationRecord.transaction do
+  sleep 0.3
+  User.create!
+end
+```
+
+The database has no open transaction and holds no locks until `User.create!`
+causes `BEGIN`. Excluding that pre-BEGIN time is intentional.
+
+Lock reporting is heuristic. It recognizes `INSERT`, `UPDATE`, `DELETE`,
+locking `SELECT`, `LOCK TABLE`, and common PostgreSQL/MySQL advisory-lock
+functions. It does not parse primary keys or prove that a lock is still held.
+
+Fiber or async scheduler waits count as gaps when the checked-out connection
+remains in a transaction. That is intentional: another Fiber may run, but the
+database session can still retain locks.
+
+## Related safeguards
+
+[Isolator](https://github.com/palkan/isolator) detects specific side effects
+such as HTTP calls or job enqueueing inside transactions. This gem detects
+elapsed time regardless of the work type, including CPU-only work and unknown
+I/O. The tools are complementary.
+
+For PostgreSQL, also configure
+`idle_in_transaction_session_timeout` as a server-side last line of defense.
+This gem provides application context and early visibility; it is not a
+replacement for the database timeout.
+
+## Compatibility
+
+| Ruby | Active Record 7.2 | Active Record 8.0 |
+| --- | --- | --- |
+| 3.2 | supported | supported |
+| 3.3 | supported | supported |
+| 3.4 | supported | supported |
+| 4.0 | supported | supported |
+
+Rails 7.1 and earlier are not supported because the implementation relies on
+the 7.2 transaction lifecycle notifications. SQLite is used for the main test
+suite and PostgreSQL 16 for adapter and concurrent-connection smoke tests.
+
+## Performance
+
+The benchmark measures `transaction { one SQL }` before subscriptions, with
+no-op notification subscribers, and with detection enabled:
+
+```bash
+bundle exec ruby benchmark/transaction.rb
+DATABASE_URL=postgresql://... bundle exec ruby benchmark/transaction.rb
+```
+
+On Ruby 4.0.0, Active Record 8.0.5, and a local PostgreSQL 16 Docker container,
+with call-site capture disabled, a five-second run measured 1,473 i/s without
+the detector and 1,417 i/s with it: **3.78% overhead**. A SQLite in-memory
+microbenchmark is dominated by notification and Ruby bookkeeping and is not
+representative of networked database latency.
+
+Re-run the benchmark on the same database topology and Ruby version used by
+the application. Enable `:sampled` or `:off` call-site capture in
+latency-sensitive production environments.
+
+## Development
+
+Install dependencies and run the default RSpec plus Standard Ruby checks:
+
+```bash
+bundle install
+bundle exec rake
+```
+
+Run both supported Active Record families:
+
+```bash
+bundle exec appraisal rails_7_2 rspec
+bundle exec appraisal rails_8_0 rspec
+```
+
+Use `TIME_SCALE=1.5` to relax timing windows on slower CI workers. Event payload
+spike results and reproduction commands are in
+[`spec/fixtures/event_payloads.md`](spec/fixtures/event_payloads.md).
+
+## License
+
+The gem is available under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "standard/rake"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[spec standard]

data/benchmark/transaction.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "fileutils"
+
+require "active_record"
+
+database_config = ENV["DATABASE_URL"] || {adapter: "sqlite3", database: ":memory:"}
+ActiveRecord::Base.establish_connection(database_config)
+connection = ActiveRecord::Base.connection
+connection.select_value("SELECT 1")
+
+warmup = ENV.fetch("WARMUP", "2").to_i
+time = ENV.fetch("TIME", "5").to_i
+
+measure = lambda do |label|
+  Benchmark.ips do |benchmark|
+    benchmark.config(warmup: warmup, time: time)
+    benchmark.report(label) do
+      connection.transaction { connection.select_value("SELECT 1") }
+    end
+  end.entries.fetch(0).ips
+end
+
+baseline_ips = measure.call("without txnap")
+
+require_relative "../lib/txnap"
+
+notification_subscriptions = %w[
+  sql.active_record
+  start_transaction.active_record
+  transaction.active_record
+].map do |event_name|
+  ActiveSupport::Notifications.monotonic_subscribe(event_name) { nil }
+end
+notification_ips = measure.call("notification subscribers only")
+notification_subscriptions.each { |subscription| ActiveSupport::Notifications.unsubscribe(subscription) }
+
+Txnap.configure do |config|
+  config.gap_threshold = 60.0
+  config.capture_call_sites = :off
+end
+Txnap.install!
+
+instrumented_ips = measure.call("with txnap")
+overhead = ((baseline_ips - instrumented_ips) / baseline_ips) * 100
+
+puts format(
+  "baseline=%.1f i/s notifications=%.1f i/s instrumented=%.1f i/s overhead=%+.2f%%",
+  baseline_ips,
+  notification_ips,
+  instrumented_ips,
+  overhead
+)

data/gemfiles/rails_7_2.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 7.2.0"
+
+gemspec path: "../"

data/gemfiles/rails_8_0.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "~> 8.0.0"
+
+gemspec path: "../"

data/gemfiles/rails_main.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gem "activerecord", github: "rails/rails"
+
+gemspec path: "../"

data/lib/txnap/call_site.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Txnap
+  module CallSite
+    LIB_ROOT = File.expand_path("..", __dir__)
+
+    module_function
+
+    def capture(locations = caller_locations(2, 80))
+      location = locations.find { |candidate| application_location?(candidate) }
+      return unless location
+
+      "#{display_path(location)}:#{location.lineno}"
+    end
+
+    def application_location?(location)
+      path = location.absolute_path || location.path
+      return false if path.nil? || path.start_with?(LIB_ROOT)
+      return false if path.include?("/gems/activerecord-") || path.include?("/gems/activesupport-")
+      return false if path.include?("/gems/bundler-") || path.start_with?("<internal:")
+
+      true
+    end
+
+    def display_path(location)
+      path = location.absolute_path || location.path
+      working_directory = "#{Dir.pwd}/"
+      path.start_with?(working_directory) ? path.delete_prefix(working_directory) : path
+    end
+  end
+end

data/lib/txnap/configuration.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Txnap
+  class Configuration
+    MODES = %i[log raise].freeze
+    CAPTURE_CALL_SITES = %i[always sampled off].freeze
+
+    attr_accessor :gap_threshold,
+      :min_transaction_duration,
+      :only_with_locks,
+      :capture_call_sites,
+      :ignore_if,
+      :logger
+    attr_reader :mode
+
+    def initialize
+      @mode = :log
+      @gap_threshold = 0.1
+      @min_transaction_duration = 0.0
+      @only_with_locks = false
+      @capture_call_sites = :always
+      @ignore_if = nil
+      @logger = nil
+    end
+
+    def mode=(value)
+      @mode = value&.to_sym
+    end
+
+    def validate!
+      validate_choice!(:mode, mode, MODES)
+      validate_non_negative_number!(:gap_threshold, gap_threshold)
+      validate_non_negative_number!(:min_transaction_duration, min_transaction_duration)
+      validate_boolean!(:only_with_locks, only_with_locks)
+      validate_choice!(:capture_call_sites, capture_call_sites, CAPTURE_CALL_SITES)
+      validate_callable!(:ignore_if, ignore_if)
+      self
+    end
+
+    private
+
+    def validate_choice!(name, value, choices)
+      return if choices.include?(value)
+
+      raise ConfigurationError, "#{name} must be one of: #{choices.join(", ")}"
+    end
+
+    def validate_non_negative_number!(name, value)
+      return if value.is_a?(Numeric) && value.finite? && value >= 0
+
+      raise ConfigurationError, "#{name} must be a finite, non-negative number"
+    end
+
+    def validate_boolean!(name, value)
+      return if value == true || value == false
+
+      raise ConfigurationError, "#{name} must be true or false"
+    end
+
+    def validate_callable!(name, value)
+      return if value.nil? || value.respond_to?(:call)
+
+      raise ConfigurationError, "#{name} must respond to call"
+    end
+  end
+end

data/lib/txnap/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Txnap
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class IdleGapDetected < Error; end
+end

data/lib/txnap/execution_state.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Txnap
+  module ExecutionState
+    KEY = :txnap_suppression_depth
+
+    module_function
+
+    def suppress
+      state[KEY] = suppression_depth + 1
+      yield
+    ensure
+      state[KEY] = [suppression_depth - 1, 0].max
+    end
+
+    def suppressed?
+      suppression_depth.positive?
+    end
+
+    def suppression_depth
+      state[KEY] || 0
+    end
+
+    def state
+      ActiveSupport::IsolatedExecutionState
+    end
+  end
+end

data/lib/txnap/formatter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Txnap
+  class Formatter
+    def call(report)
+      gap = report.longest_gap
+      lines = [
+        "Txnap::IdleGapDetected",
+        "",
+        "Transaction held for #{milliseconds(report.transaction_duration)} ms (BEGIN → #{report.outcome.to_s.upcase})",
+        "Database time: #{milliseconds(report.database_time)} ms",
+        "Longest non-database gap: #{milliseconds(gap.duration)} ms",
+        "",
+        "Gap occurred between:",
+        "  after:  #{event(gap.after)}",
+        "  before: #{event(gap.before)}"
+      ]
+
+      append_locks(lines, report.locks)
+      lines.concat([
+        "",
+        "Move slow non-database work (I/O, rendering, external calls,",
+        "heavy computation) outside the transaction."
+      ])
+      lines.join("\n")
+    end
+
+    private
+
+    def milliseconds(seconds)
+      (seconds * 1000).round
+    end
+
+    def event(metadata)
+      return "(transaction boundary)" unless metadata
+
+      [metadata.sql, metadata.call_site && "(#{metadata.call_site})"].compact.join(" ")
+    end
+
+    def append_locks(lines, locks)
+      return if locks.empty?
+
+      lines.concat(["", "Locks possibly held during the gap:"])
+      locks.each do |lock|
+        location = lock.call_site && "  #{lock.call_site}"
+        lines << "  #{lock.statement} #{lock.table} (#{lock.kind})#{location}"
+      end
+    end
+  end
+end

data/lib/txnap/lock_heuristics.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Txnap
+  module LockHeuristics
+    IDENTIFIER_PART = /(?:"(?:[^"]|"")*"|`(?:[^`]|``)*`|\[[^\]]+\]|[a-z_][a-z0-9_$]*)/i
+    QUALIFIED_IDENTIFIER = /#{IDENTIFIER_PART}(?:\s*\.\s*#{IDENTIFIER_PART})*/
+    ADVISORY_FUNCTION = /
+      (?:
+        pg_(?:try_)?advisory_(?:xact_)?lock(?:_shared)?
+        |
+        get_lock
+      )
+    /ix
+
+    module_function
+
+    def detect(sql, call_site: nil)
+      statement = strip_leading_comments(Array(sql).join(" "))
+      return if statement.empty?
+
+      operation, table, kind =
+        case statement
+        when /\AINSERT(?:\s+OR\s+\w+)?\s+INTO\s+(#{QUALIFIED_IDENTIFIER})/io
+          ["INSERT", normalize_identifier(Regexp.last_match(1)), "row lock"]
+        when /\AUPDATE\s+(?:ONLY\s+)?(#{QUALIFIED_IDENTIFIER})/io
+          ["UPDATE", normalize_identifier(Regexp.last_match(1)), "row lock"]
+        when /\ADELETE\s+FROM\s+(?:ONLY\s+)?(#{QUALIFIED_IDENTIFIER})/io
+          ["DELETE", normalize_identifier(Regexp.last_match(1)), "row lock"]
+        when /\ALOCK\s+TABLE\s+(?:ONLY\s+)?(#{QUALIFIED_IDENTIFIER})/io
+          ["LOCK TABLE", normalize_identifier(Regexp.last_match(1)), "table lock"]
+        else
+          detect_select_or_advisory(statement)
+        end
+
+      return unless operation
+
+      LockCandidate.new(
+        statement: operation,
+        table: table,
+        kind: kind,
+        call_site: call_site
+      ).freeze
+    end
+
+    def detect_select_or_advisory(statement)
+      if statement.match?(/\ASELECT\b/im) &&
+          statement.match?(/\bFOR\s+(?:NO\s+KEY\s+)?(?:UPDATE|SHARE|KEY\s+SHARE)\b/im)
+        table = statement[/\bFROM\s+(#{QUALIFIED_IDENTIFIER})/io, 1]
+        return ["SELECT", normalize_identifier(table), "row lock"] if table
+      end
+
+      function = statement[ADVISORY_FUNCTION]
+      return unless function
+
+      ["ADVISORY LOCK", function.downcase, "advisory lock"]
+    end
+
+    def strip_leading_comments(sql)
+      remaining = sql.lstrip
+
+      loop do
+        stripped =
+          if remaining.start_with?("--")
+            remaining.sub(/\A--[^\n]*(?:\n|\z)/, "").lstrip
+          elsif remaining.start_with?("/*")
+            remaining.sub(/\A\/\*.*?\*\//m, "").lstrip
+          else
+            remaining
+          end
+        return remaining if stripped == remaining
+
+        remaining = stripped
+      end
+    end
+
+    def normalize_identifier(identifier)
+      return unless identifier
+
+      identifier.split(/\s*\.\s*/).map do |part|
+        case part
+        when /\A"(.*)"\z/m
+          Regexp.last_match(1).gsub('""', '"')
+        when /\A`(.*)`\z/m
+          Regexp.last_match(1).gsub("``", "`")
+        when /\A\[(.*)\]\z/m
+          Regexp.last_match(1)
+        else
+          part
+        end
+      end.join(".")
+    end
+  end
+end

data/lib/txnap/notifier.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Txnap
+  class Notifier
+    EVENT_NAME = "idle_gap.txnap"
+
+    def initialize(configuration:, logger:)
+      @configuration = configuration
+      @logger = logger
+    end
+
+    def call(report)
+      return false unless report
+      return false unless report.longest_gap.duration >= configuration.gap_threshold
+      return false unless report.transaction_duration >= configuration.min_transaction_duration
+      return false if configuration.only_with_locks && report.locks.empty?
+      return false if ExecutionState.suppressed?
+      return false if ignored?(report)
+
+      ActiveSupport::Notifications.instrument(EVENT_NAME, report.to_h)
+      message = Formatter.new.call(report)
+
+      raise IdleGapDetected, raise_message(message, report) if configuration.mode == :raise
+
+      logger.warn(message)
+      true
+    end
+
+    private
+
+    attr_reader :configuration, :logger
+
+    def ignored?(report)
+      predicate = configuration.ignore_if
+      return false unless predicate
+
+      predicate.arity.zero? ? predicate.call : predicate.call(report)
+    end
+
+    def raise_message(message, report)
+      suffix =
+        if report.outcome.to_sym == :commit
+          "The transaction has already been committed; this exception cannot roll it back."
+        else
+          "The transaction has already finished; this exception cannot change its outcome."
+        end
+
+      "#{message}\n\n#{suffix}"
+    end
+  end
+end