txnap 0.1.0

data/lib/txnap/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Txnap
+  class Railtie < Rails::Railtie
+    initializer "txnap.install" do
+      ActiveSupport.on_load(:active_record) { Txnap.install! }
+    end
+  end
+end

data/lib/txnap/registry.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Txnap
+  class Registry
+    def initialize(&warning_handler)
+      @warning_handler = warning_handler
+      @mutex = Mutex.new
+      @traces = {}.compare_by_identity
+    end
+
+    def start(connection, trace)
+      stale_trace = @mutex.synchronize do
+        stale = @traces[connection]
+        @traces[connection] = trace
+        stale
+      end
+      @warning_handler&.call("discarded a stale trace before a new BEGIN") if stale_trace
+      trace
+    end
+
+    def fetch(connection)
+      @mutex.synchronize { @traces[connection] }
+    end
+
+    def bind_transaction(connection, transaction)
+      return unless transaction
+
+      @mutex.synchronize { @traces[connection]&.bind_transaction(transaction) }
+    end
+
+    def finalize(connection, transaction)
+      @mutex.synchronize do
+        trace = @traces[connection]
+        return unless trace
+        matches_transaction = trace.matches_transaction?(transaction)
+        matches_terminal_without_binding = trace.transaction.nil? && trace.terminal?
+        return unless matches_transaction || matches_terminal_without_binding
+
+        @traces.delete(connection)
+      end
+    end
+
+    def size
+      @mutex.synchronize { @traces.size }
+    end
+
+    def reset!
+      @mutex.synchronize { @traces.clear }
+    end
+  end
+end

data/lib/txnap/report.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Txnap
+  EventMetadata = Data.define(:sql, :name, :call_site) do
+    def to_h
+      {sql: sql, name: name, call_site: call_site}
+    end
+  end
+
+  Gap = Data.define(:duration, :after, :before, :locks) do
+    def to_h
+      {
+        duration_ms: duration * 1000.0,
+        after: after&.to_h,
+        before: before&.to_h
+      }
+    end
+  end
+
+  LockCandidate = Data.define(:statement, :table, :kind, :call_site) do
+    def to_h
+      {statement: statement, table: table, kind: kind, call_site: call_site}
+    end
+  end
+
+  class Report
+    attr_reader :outcome,
+      :transaction_duration,
+      :database_time,
+      :longest_gap,
+      :gaps,
+      :locks,
+      :sql_count
+
+    def initialize(outcome:, transaction_duration:, database_time:, gaps:, sql_count:)
+      @outcome = outcome
+      @transaction_duration = transaction_duration
+      @database_time = database_time
+      @gaps = gaps.freeze
+      @longest_gap = gaps.first
+      @locks = (@longest_gap&.locks || []).freeze
+      @sql_count = sql_count
+    end
+
+    def to_h
+      {
+        outcome: outcome,
+        transaction_duration_ms: transaction_duration * 1000.0,
+        database_time_ms: database_time * 1000.0,
+        longest_gap_ms: longest_gap.duration * 1000.0,
+        sql_count: sql_count,
+        gap: longest_gap.to_h,
+        gaps: gaps.map(&:to_h),
+        locks: locks.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/txnap/sql_event_classifier.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Txnap
+  module SqlEventClassifier
+    module_function
+
+    def classify(payload)
+      return :cache if payload[:cached] == true || payload[:name] == "CACHE"
+      return :schema if payload[:name] == "SCHEMA"
+      return :sql unless payload[:name] == "TRANSACTION"
+
+      classify_transaction_sql(payload[:sql])
+    end
+
+    def classify_transaction_sql(sql)
+      statement = Array(sql).join(" ").strip
+
+      return :begin if statement.match?(/\A(?:BEGIN\b|START\s+TRANSACTION\b)/i)
+      return :commit if statement.match?(/\ACOMMIT\b/i)
+      return :transaction if statement.match?(/\AROLLBACK\s+TO\b/i)
+      return :rollback if statement.match?(/\AROLLBACK\b/i)
+
+      :transaction
+    end
+  end
+end

data/lib/txnap/subscribers/sql_subscriber.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Txnap
+  module Subscribers
+    class SqlSubscriber
+      class << self
+        def install
+          @subscription ||= begin
+            subscriber = new
+            ActiveSupport::Notifications.monotonic_subscribe("sql.active_record") do |*args|
+              subscriber.call(*args)
+            end
+          end
+        end
+      end
+
+      def call(_name, start, finish, _id, payload)
+        connection = payload[:connection]
+        return unless connection
+
+        case SqlEventClassifier.classify(payload)
+        when :cache, :schema
+          nil
+        when :begin
+          start_trace(connection, start, finish, payload)
+        when :commit, :rollback
+          registry.fetch(connection)&.record_terminal(start: start, finish: finish, sql: payload[:sql])
+        when :transaction
+          registry.fetch(connection)&.record_transaction(start: start, finish: finish, sql: payload[:sql])
+        when :sql
+          record_sql(connection, start, finish, payload)
+        end
+      rescue => error
+        Txnap.warn("sql subscriber failed: #{error.class}: #{error.message}")
+      end
+
+      private
+
+      def registry
+        Txnap.registry
+      end
+
+      def start_trace(connection, start, finish, payload)
+        registry.start(
+          connection,
+          Trace.new(start: start, finish: finish, sql: payload[:sql])
+        )
+      end
+
+      def record_sql(connection, start, finish, payload)
+        trace = registry.fetch(connection)
+        return unless trace
+
+        call_site = capture_call_site(trace, start)
+        lock_candidate = LockHeuristics.detect(payload[:sql], call_site: call_site)
+        trace.record_sql(
+          start: start,
+          finish: finish,
+          sql: payload[:sql],
+          name: payload[:name],
+          call_site: call_site,
+          lock_candidate: lock_candidate
+        )
+      end
+
+      def capture_call_site(trace, start)
+        case Txnap.configuration.capture_call_sites
+        when :always
+          CallSite.capture
+        when :sampled
+          CallSite.capture if trace.would_update_longest_gap?(start)
+        end
+      end
+    end
+  end
+end

data/lib/txnap/subscribers/transaction_subscriber.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Txnap
+  module Subscribers
+    class TransactionSubscriber
+      class << self
+        def install
+          @subscriptions ||= begin
+            subscriber = new
+            [
+              ActiveSupport::Notifications.monotonic_subscribe("start_transaction.active_record") do |*args|
+                subscriber.start(*args)
+              end,
+              ActiveSupport::Notifications.monotonic_subscribe("transaction.active_record") do |*args|
+                subscriber.finish(*args)
+              end
+            ]
+          end
+        end
+      end
+
+      def start(_name, _start, _finish, _id, payload)
+        connection = payload[:connection]
+        return unless connection
+
+        Txnap.registry.bind_transaction(connection, payload[:transaction])
+      rescue => error
+        Txnap.warn("transaction start subscriber failed: #{error.class}: #{error.message}")
+      end
+
+      def finish(_name, _start, _finish, _id, payload)
+        connection = payload[:connection]
+        return unless connection
+
+        trace = Txnap.registry.finalize(connection, payload[:transaction])
+        Txnap.notify(trace&.to_report(payload[:outcome]))
+      rescue IdleGapDetected
+        raise
+      rescue => error
+        Txnap.warn("transaction finish subscriber failed: #{error.class}: #{error.message}")
+      end
+    end
+  end
+end

data/lib/txnap/trace.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Txnap
+  class Trace
+    TOP_GAPS_LIMIT = 3
+    LOCK_CANDIDATES_LIMIT = 20
+    SQL_LENGTH_LIMIT = 500
+
+    attr_reader :started_at, :database_time, :sql_count, :transaction
+
+    def initialize(start:, finish:, sql:)
+      @started_at = finish
+      @previous_finish = finish
+      @previous_event = metadata(sql, "TRANSACTION", nil)
+      @database_time = positive_duration(start, finish)
+      @sql_count = 0
+      @gaps = []
+      @lock_candidates = []
+      @transaction = nil
+      @ended_at = nil
+    end
+
+    def bind_transaction(transaction)
+      @transaction ||= transaction
+    end
+
+    def matches_transaction?(candidate)
+      transaction && candidate && transaction.equal?(candidate)
+    end
+
+    def terminal?
+      !@ended_at.nil?
+    end
+
+    def would_update_longest_gap?(start)
+      gap_duration(start) > longest_gap_duration
+    end
+
+    def record_sql(start:, finish:, sql:, name:, call_site:, lock_candidate: nil)
+      event = metadata(sql, name, call_site)
+      observe_event(start: start, finish: finish, event: event)
+      @sql_count += 1
+      add_lock_candidate(lock_candidate)
+    end
+
+    def record_transaction(start:, finish:, sql:)
+      observe_event(
+        start: start,
+        finish: finish,
+        event: metadata(sql, "TRANSACTION", nil)
+      )
+    end
+
+    def record_terminal(start:, finish:, sql:)
+      effective_start = [start, @previous_finish].max
+      @ended_at = effective_start
+      record_transaction(start: start, finish: finish, sql: sql)
+    end
+
+    def to_report(outcome)
+      return unless terminal?
+
+      Report.new(
+        outcome: outcome,
+        transaction_duration: positive_duration(started_at, @ended_at),
+        database_time: database_time,
+        gaps: @gaps.dup,
+        sql_count: sql_count
+      )
+    end
+
+    private
+
+    def observe_event(start:, finish:, event:)
+      effective_start = [start, @previous_finish].max
+      effective_finish = [finish, effective_start].max
+
+      observe_gap(effective_start, event)
+      @database_time += effective_finish - effective_start
+      @previous_finish = effective_finish
+      @previous_event = event
+    end
+
+    def observe_gap(next_start, next_event)
+      gap = Gap.new(
+        duration: gap_duration(next_start),
+        after: @previous_event,
+        before: next_event,
+        locks: @lock_candidates.dup.freeze
+      )
+      @gaps << gap
+      @gaps.sort_by! { |candidate| -candidate.duration }
+      @gaps.pop while @gaps.length > TOP_GAPS_LIMIT
+    end
+
+    def gap_duration(next_start)
+      [next_start - @previous_finish, 0.0].max
+    end
+
+    def longest_gap_duration
+      @gaps.first&.duration || 0.0
+    end
+
+    def add_lock_candidate(candidate)
+      return unless candidate
+      return if @lock_candidates.any? do |existing|
+        existing.statement == candidate.statement && existing.table == candidate.table
+      end
+      return if @lock_candidates.length >= LOCK_CANDIDATES_LIMIT
+
+      @lock_candidates << candidate
+    end
+
+    def metadata(sql, name, call_site)
+      normalized_sql = Array(sql).join(" ").gsub(/\s+/, " ").strip
+      normalized_sql = "#{normalized_sql[0, SQL_LENGTH_LIMIT - 1]}…" if normalized_sql.length > SQL_LENGTH_LIMIT
+      EventMetadata.new(sql: normalized_sql.freeze, name: name, call_site: call_site).freeze
+    end
+
+    def positive_duration(start, finish)
+      [finish - start, 0.0].max
+    end
+  end
+end

data/lib/txnap/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Txnap
+  VERSION = "0.1.0"
+end

data/lib/txnap.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "logger"
+
+require "active_support"
+require "active_support/isolated_execution_state"
+require "active_support/notifications"
+
+require_relative "txnap/version"
+require_relative "txnap/errors"
+require_relative "txnap/configuration"
+require_relative "txnap/execution_state"
+require_relative "txnap/sql_event_classifier"
+require_relative "txnap/call_site"
+require_relative "txnap/lock_heuristics"
+require_relative "txnap/report"
+require_relative "txnap/trace"
+require_relative "txnap/registry"
+require_relative "txnap/formatter"
+require_relative "txnap/notifier"
+require_relative "txnap/subscribers/sql_subscriber"
+require_relative "txnap/subscribers/transaction_subscriber"
+
+module Txnap
+  class << self
+    def configure
+      yield(configuration)
+      configuration.validate!
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def registry
+      @registry ||= Registry.new { |message| warn(message) }
+    end
+
+    def install!
+      return false if @installed
+
+      Subscribers::SqlSubscriber.install
+      Subscribers::TransactionSubscriber.install
+      @installed = true
+    end
+
+    def suppress(&block)
+      ExecutionState.suppress(&block)
+    end
+
+    def logger
+      configuration.logger || rails_logger || default_logger
+    end
+
+    def warn(message)
+      logger.warn("[txnap] #{message}")
+    rescue
+      nil
+    end
+
+    def notify(report)
+      Notifier.new(configuration: configuration, logger: logger).call(report)
+    end
+
+    def reset!
+      @configuration = Configuration.new
+      registry.reset!
+    end
+
+    private
+
+    def rails_logger
+      Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
+    end
+
+    def default_logger
+      @default_logger ||= Logger.new($stderr)
+    end
+  end
+end
+
+require_relative "txnap/railtie" if defined?(Rails::Railtie)

data/script/event_probe.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+
+active_record_version = ARGV.fetch(0) { ENV.fetch("ACTIVE_RECORD_VERSION") }
+adapter = ARGV.fetch(1) { ENV.fetch("ADAPTER", "sqlite3") }
+
+gem "activerecord", active_record_version
+gem (adapter == "postgresql") ? "pg" : "sqlite3"
+
+require "active_record"
+require "active_support/notifications"
+
+database_config =
+  if adapter == "postgresql"
+    {
+      adapter: "postgresql",
+      url: ARGV.fetch(2) do
+        ENV.fetch("DATABASE_URL", "postgresql://postgres:postgres@127.0.0.1:55433/txnap")
+      end
+    }
+  else
+    {adapter: "sqlite3", database: ":memory:"}
+  end
+
+ActiveRecord::Base.establish_connection(database_config)
+connection = ActiveRecord::Base.connection
+connection.create_table(:event_probe_records, force: true) do |table|
+  table.string :name, null: false
+end
+
+class EventProbeRecord < ActiveRecord::Base
+end
+
+events = []
+subscriptions = %w[
+  sql.active_record
+  start_transaction.active_record
+  transaction.active_record
+].map do |event_name|
+  ActiveSupport::Notifications.monotonic_subscribe(event_name) do |name, start, finish, _id, payload|
+    events << {
+      event: name,
+      start: start,
+      finish: finish,
+      duration_ms: (finish - start) * 1000,
+      name: payload[:name],
+      sql: payload[:sql],
+      cached: payload[:cached],
+      outcome: payload[:outcome],
+      connection_id: payload[:connection]&.object_id,
+      transaction_id: payload[:transaction]&.object_id
+    }.compact
+  end
+end
+
+ActiveRecord::Base.transaction do
+  sleep 0.01
+  EventProbeRecord.create!(name: "commit")
+
+  ActiveRecord::Base.transaction(requires_new: true) do
+    EventProbeRecord.create!(name: "savepoint")
+  end
+
+  connection.cache do
+    EventProbeRecord.first
+    EventProbeRecord.first
+  end
+  sleep 0.01
+end
+
+begin
+  ActiveRecord::Base.transaction do
+    EventProbeRecord.create!(name: "rollback")
+    raise ActiveRecord::Rollback
+  end
+
+  ActiveRecord::Base.transaction do
+    ActiveRecord::Base.transaction(requires_new: true) do
+      EventProbeRecord.create!(name: "restart")
+      raise ActiveRecord::Rollback
+    end
+    EventProbeRecord.create!(name: "after restart")
+  end
+ensure
+  subscriptions.each { |subscription| ActiveSupport::Notifications.unsubscribe(subscription) }
+end
+
+puts JSON.pretty_generate(
+  active_record: ActiveRecord.version.to_s,
+  adapter: connection.adapter_name,
+  connection_id: connection.object_id,
+  events: events
+)