railwatch 0.8.6 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c483283faabf8cf2552cedbd8568e6d06f815c8e5bdf4f2cdffe1909a82fa80b
-  data.tar.gz: 2f56eb2aed77f09e55d869117c3f9bf1d6140f00fa93ebd2a5c2c89e4da62b7b
+  metadata.gz: 3cd11714c7a290f5f6717f3b8f239b72b669fce39a2797a59fcb862595925778
+  data.tar.gz: 147d3416d6d047a6c87b8ccdb9d2b67b8e2a6058f881956241f65dff0ea239c5
 SHA512:
-  metadata.gz: a80ac73b1c0e36d6fb681da86848ac37f3bde8d6b867fbd0a5134087da9c134344595fd1407f49f72f00d8573d2304b9944b2e667ae44fa63cd9c2337527da5a
-  data.tar.gz: a3e7028f181c255b69d0831f9e9a56c163b48bdacccca8464b3d05f6233976a2d412d06d11f3ad5320430186e2c067830e96ee048f415281933da5a6bc41a22f
+  metadata.gz: 774a7cbf876e5220af985a97a2cc6919ebb91ff9ea7a38e414956b1c0cbf3cedb723cbc470baaa807fa7343295117576df15485923502d855212e83698bee592
+  data.tar.gz: c0d3106cd7c800cf938daf056ce9c279b10e5013af618b39e4e31411517dc578a4e71fd711b5a4158e3b4acdb76964476ca298377f792c0b8f40319ad13c877e

data/AGENTS.md

@@ -102,6 +102,7 @@ expect { Checkout.new(cart).total }.to record_railwatch_span("checkout.total")
 expect { importer.run }.to record_railwatch_exception(ArgumentError)
 expect { importer.run }.not_to record_railwatch_exceptions
 expect { SyncCustomers.run }.to have_railwatch_outgoing_requests(at_most: 1)
+expect { post "/orders", params: }.not_to have_railwatch_http_in_transaction
 
 records = railwatch_capture { get "/widgets" }   # everything the block produced
 ```

data/CHANGELOG.md

@@ -6,6 +6,34 @@
      filled in by the release commit, which is also the only commit that
      touches lib/railwatch/version.rb and Gemfile.lock. See CONTRIBUTING.md. -->
 
+## 0.9.0 (2026-10-08)
+
+- An `outgoing_request` now says whether it was made inside a database
+  transaction (`in_transaction`), like Isolator: the transaction and its
+  locks wait on the other service, and a rollback cannot undo the call. Only
+  transactions the execution began count, so transactional test fixtures do
+  not. New `have_railwatch_http_in_transaction` matcher and
+  `refute_railwatch_http_in_transaction` assertion, and a telemetry migration
+  adding the column to `outgoing_requests`.
+
+## 0.8.7 (2026-10-06)
+
+- A migration of the railwatch databases waits up to 60 s for SQLite's
+  write lock instead of the database's own `timeout` (5 s in the generated
+  `database.yml`). A deploy migrates while the previous release is still
+  serving, and on an embedded install that release's writer keeps
+  committing telemetry to the same file: about a second per transaction on
+  a warm 15 GB file, several seconds while the deploy's image build has the
+  disk. rebulk-system's container entrypoint ran `db:prepare` into that,
+  got `SQLite3::BusyException: database is locked` from the first
+  migration that needed a write, and crash-looped until the health check
+  gave up. Only the connection Active Record migrates with is changed, only
+  while it migrates, and only for a database whose `migrations_paths` are
+  this gem's; the app's requests keep failing fast. It applies with
+  Railwatch disabled, which is how an entrypoint migrates.
+  `RAILWATCH_MIGRATION_BUSY_TIMEOUT` (`c.migration_busy_timeout`, seconds)
+  sets it; keep it inside the deploy's health-check window.
+
 ## 0.8.6 (2026-10-06)
 
 - An install upgrading from 0.5.0 or older can migrate again. 0.5.1

data/app/models/railwatch/ingest/mapper.rb

@@ -216,7 +216,7 @@ module Railwatch
         when "mail" then child(Telemetry::Mail, rec, %w[mailer subject to cc bcc attachments delivery_method perform_deliveries duration failed message_id])
         when "broadcast" then child(Telemetry::Broadcast, rec, %w[kind stream channel action bytes duration failed])
         when "notification" then child(Telemetry::Notification, rec, %w[notifier delivery_method channel duration failed])
-        when "outgoing_request" then child(Telemetry::OutgoingRequest, rec, %w[host method url duration status_code request_size response_size error source response_body])
+        when "outgoing_request" then child(Telemetry::OutgoingRequest, rec, %w[host method url duration status_code request_size response_size error source response_body in_transaction])
         when "llm_call" then child(Telemetry::LlmCall, rec, %w[operation provider model response_model tool_name duration status error
           streaming message_count tool_count input_tokens output_tokens cache_read_tokens cache_write_tokens thinking_tokens
           cost_nanos workflow_id workflow_name workflow_step_id workflow_step_name workflow_step_parent_id prompt completion

data/db/railwatch_telemetry_migrate/20261008000000_add_in_transaction_to_outgoing_requests.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# An outgoing HTTP call made while the execution held a database transaction
+# open: the transaction (and on SQLite with BEGIN IMMEDIATE, the writer lock)
+# stays held for the whole round trip. Same meaning as queries.in_transaction.
+class AddInTransactionToOutgoingRequests < ActiveRecord::Migration[8.1]
+  def change
+    add_column :outgoing_requests, :in_transaction, :boolean, default: false
+  end
+end

data/docs/records.md

@@ -500,6 +500,7 @@ never double-recorded.
 | `response_size` | Bytes, from `Content-Length` or body size. |
 | `error` | `"Class: message"`, truncated to 255 chars, if the request raised. |
 | `response_body` | First 4 KiB of the response body, but only when `config.capture_response_body_on_error` is on (off by default) *and* the response was an error. A body that parses as a JSON object is run through the same parameter filter as request params and re-serialized; anything else is stored as it arrived. nil in every other case — including a connection failure, where there is no response (on the Net::HTTP path a body is read only if Net::HTTP already buffered it, so a response being streamed through `read_body` is never consumed; on the Faraday path the body is taken only once a status came back, so an outgoing request payload can never be filed as a response). |
+| `in_transaction` | True when the execution had a database transaction (or savepoint) of its own open for this call, so the transaction and its locks were held for the whole round trip and a rollback cannot undo what the call did. Only transactions the execution began count: one already open when it started, such as a test's transactional fixture, does not. Active Record begins a transaction at its first statement, so a `transaction do` block that has not yet run one is not open. A job performed inline inherits its parent's. The `have_railwatch_http_in_transaction` matcher fails a spec on it. |
 | `source` | App-code call site (Net::HTTP path only). |
 
 ### `llm_call`

data/docs/testing.md

@@ -109,11 +109,26 @@ expect { SyncCustomers.run }.to have_railwatch_outgoing_requests(at_most: 1)
 Same bounds as `have_railwatch_queries`. Failures list the method and URL of
 every request the block made.
 
+### `have_railwatch_http_in_transaction`
+
+```ruby
+expect { post "/orders", params: }.not_to have_railwatch_http_in_transaction
+```
+
+Railwatch's version of [Isolator](https://github.com/palkan/isolator): fails
+when the block makes an outgoing HTTP call while a database transaction it
+opened is still open. The transaction, and every lock it holds, waits on the
+other service, and rolling back cannot undo what the call did. The negated
+failure message lists each such call with the app line that made it. Only
+transactions opened inside the block count, so a suite's transactional
+fixtures never trip it.
+
 ## Minitest assertions
 
 ```ruby
 assert_railwatch_queries(at_most: 5) { OrderSummary.new(order).to_h }
 refute_railwatch_n_plus_one { get widgets_url }
+refute_railwatch_http_in_transaction { post orders_url, params: }
 assert_railwatch_span("checkout.total") { Checkout.new(cart).total }
 ```
 

data/lib/railwatch/configuration.rb

@@ -76,7 +76,7 @@ module Railwatch
                   :buffer_size, :buffer_bytes, :execution_buffer_bytes, :batch_bytes,
                   :backpressure,
                   :flush_interval, :flush_threshold,
-                  :connect_timeout, :timeout, :shutdown_timeout,
+                  :connect_timeout, :timeout, :shutdown_timeout, :migration_busy_timeout,
                   :slow_query_threshold_ms, :n_plus_one_threshold,
                   :max_view_renders_per_execution, :ignored_cache_key_prefixes,
                   :beacon_enabled, :beacon_rate_limit, :beacon_global_rate_limit, :beacon_allowed_origins,
@@ -187,6 +187,13 @@ module Railwatch
       @connect_timeout = env_float("RAILWATCH_CONNECT_TIMEOUT", 1.0)
       @timeout = env_float("RAILWATCH_TIMEOUT", 3.0)
       @shutdown_timeout = env_float("RAILWATCH_SHUTDOWN_TIMEOUT", 2.0)
+      # Seconds a migration of the railwatch databases waits for SQLite's
+      # write lock (Patches::MigrationBusyTimeout). A deploy migrates while
+      # the old release's writer is still committing to the same file; the
+      # database's own `timeout` (5 s) is too short to get between its
+      # transactions when the disk is busy. Kept under a typical health-check
+      # window (Kamal's deploy_timeout defaults to 30 s and is often 90 s).
+      @migration_busy_timeout = env_float("RAILWATCH_MIGRATION_BUSY_TIMEOUT", 60.0)
       @slow_query_threshold_ms = env_float("RAILWATCH_SLOW_QUERY_MS", 5.0)
       @n_plus_one_threshold = env_int("RAILWATCH_N_PLUS_ONE_THRESHOLD", 5)
       @max_view_renders_per_execution = 20

data/lib/railwatch/execution.rb

@@ -132,6 +132,7 @@ module Railwatch
       @record_limit = @failure_context ? Railwatch.config.failure_context : MAX_RECORDS
       @byte_limit = Railwatch.config.execution_buffer_bytes
       @transaction_statement_counts = Hash.new(0)
+      @open_transactions = 0
       @allocations_start = GC.stat(:total_allocated_objects)
       @gc_time_start = GC.stat(:time) if GC_TIME_SUPPORTED
     end
@@ -306,6 +307,24 @@ module Railwatch
       @transaction_statement_counts.delete(transaction_object_id) || 0
     end
 
+    # Database transactions (and savepoints) this execution has BEGUN and not
+    # yet finished, so an outgoing HTTP call can say whether it held one open.
+    # Only transactions opened during the execution count: a test's
+    # transactional fixture is already open when the execution starts, and
+    # flagging every request spec would make the signal useless. A nested
+    # execution (perform_now inside a request) inherits its parent's.
+    def transaction_opened
+      @open_transactions += 1
+    end
+
+    def transaction_closed
+      @open_transactions -= 1 if @open_transactions.positive?
+    end
+
+    def in_transaction?
+      @open_transactions.positive? || (parent_execution&.in_transaction? || false)
+    end
+
     def duration
       Clock.micros_since(@started_mono)
     end

data/lib/railwatch/faraday.rb

@@ -53,7 +53,8 @@ module Railwatch
                      url: Record.url_without_sensitive_components(url, limit: 2048),
                      duration: Clock.micros_since(start), status_code: env.status.to_i,
                      error: error && "#{error.class}: #{error.message}"[0, 255],
-                     response_body: response_body(env))
+                     response_body: response_body(env),
+                     in_transaction: Railwatch.execution&.in_transaction? || false)
     end
 
     # Faraday threads one Env through the whole stack, and the adapter

data/lib/railwatch/minitest.rb

@@ -32,6 +32,13 @@ module Railwatch
              "detected:#{SpecHelper.n_plus_one_lines(n_plus_ones)}"
     end
 
+    def refute_railwatch_http_in_transaction(&block)
+      offending = railwatch_capture(&block).select { |r| r[:t] == "outgoing_request" && r[:in_transaction] }
+      assert offending.empty?,
+             "Expected no outgoing HTTP requests inside a database transaction, but the block made " \
+             "#{offending.size}:#{SpecHelper.outgoing_lines(offending)}"
+    end
+
     def assert_railwatch_span(name, &block)
       spans = railwatch_capture(&block).select { |r| r[:t] == "span" }
       assert spans.any? { |s| s[:name] == name },

data/lib/railwatch/patches/migration_busy_timeout.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Railwatch
+  module Patches
+    # Gives the migration connection to a Railwatch database a long SQLite
+    # busy timeout, for the migration only.
+    #
+    # A deploy migrates while the previous release is still serving, and on
+    # an embedded install that release's writer process is committing
+    # telemetry to the same file the whole time. Each of its transactions
+    # takes SQLite's single write lock: about a second on a warm 15 GB file
+    # (the export sender's claim scans the destination's whole delivery
+    # history), several seconds while a deploy's image build has the disk.
+    # The migration connection waited only the database's configured
+    # `timeout` -- 5 s in the generated database.yml -- and then raised
+    # SQLite3::BusyException, which db:prepare reports as a failed migration
+    # and the container entrypoint as a failed boot. That is how a deploy of
+    # rebulk-system crash-looped eight times without one migration running.
+    #
+    # The configured timeout is the right one for the app's own requests,
+    # which should fail fast rather than queue behind ingest. A migration is
+    # the opposite: it runs once, before the server binds, and waiting is the
+    # only way through. So only the connection Active Record migrates with is
+    # changed, only while it migrates, and only for a database whose
+    # migrations_paths include this gem's. The host's own databases keep
+    # their timeouts.
+    module MigrationBusyTimeout
+      def migrate(*, **)
+        pool = migration_connection_pool
+        raw = Railwatch::Patches::MigrationBusyTimeout.lengthen(pool)
+        super
+      ensure
+        Railwatch::Patches::MigrationBusyTimeout.restore(pool, raw) if raw
+      end
+
+      class << self
+        # The raw SQLite connection whose timeout was lengthened, or nil when
+        # this is not a Railwatch database (or not SQLite).
+        def lengthen(pool)
+          return unless railwatch_database?(pool.db_config)
+
+          raw = pool.lease_connection.raw_connection
+          return unless raw.respond_to?(:busy_handler_timeout=)
+
+          raw.busy_handler_timeout = (Railwatch.config.migration_busy_timeout.to_f * 1000).to_i
+          raw
+        rescue StandardError => e
+          Railwatch.debug { "migration busy timeout not applied: #{e.class}: #{e.message}" }
+          nil
+        end
+
+        # Back to what database.yml says, so a connection that outlives the
+        # migration (db:migrate in a long-lived process, a spec) behaves as
+        # configured afterwards.
+        def restore(pool, raw)
+          timeout = pool.db_config.configuration_hash[:timeout]
+          if timeout
+            raw.busy_handler_timeout = Integer(timeout)
+          else
+            raw.busy_handler(nil)
+          end
+        rescue StandardError => e
+          Railwatch.debug { "migration busy timeout not restored: #{e.class}: #{e.message}" }
+        end
+
+        def railwatch_database?(db_config)
+          ours = %i[railwatch railwatch_telemetry].map { |name| File.expand_path(Railwatch.migrations_path(name)) }
+          Array(db_config.migrations_paths).any? { |path| ours.include?(File.expand_path(path.to_s, Rails.root.to_s)) }
+        end
+      end
+    end
+  end
+end

data/lib/railwatch/patches/net_http.rb

@@ -68,6 +68,7 @@ module Railwatch
           response_size: response ? (response["Content-Length"]&.to_i || response.body&.bytesize rescue nil) : nil,
           error: error && "#{error.class}: #{error.message}"[0, 255],
           response_body: response_body(response, error),
+          in_transaction: Railwatch.execution&.in_transaction? || false,
           source: Backtrace.caller_location(skip: 4))
       rescue StandardError => e
         Railwatch.debug { "outgoing request record failed: #{e.message}" }

data/lib/railwatch/patches.rb

@@ -4,6 +4,7 @@ require "railwatch/patches/net_http"
 require "railwatch/patches/rake_task"
 require "railwatch/patches/runner_command"
 require "railwatch/patches/inertia"
+require "railwatch/patches/migration_busy_timeout"
 
 module Railwatch
   module Patches
@@ -22,6 +23,16 @@ module Railwatch
     # From Rails::Engine#load_tasks, which has already required rake.
     def install_rake_task!
       ::Rake::Task.prepend(RakeTask) unless ::Rake::Task.ancestors.include?(RakeTask)
+      install_migration_busy_timeout!
+    end
+
+    # db:prepare and db:migrate run as rake tasks, so this goes in with the
+    # rake patch. Unlike it, this one is not gated on Railwatch.enabled?: a
+    # container entrypoint migrates with Railwatch switched off, and that is
+    # exactly the migration that has to wait out the old release's writer.
+    def install_migration_busy_timeout!
+      tasks = ::ActiveRecord::Tasks::DatabaseTasks.singleton_class
+      tasks.prepend(MigrationBusyTimeout) unless tasks.ancestors.include?(MigrationBusyTimeout)
     end
 
     # From Rails::Application#load_runner, which RunnerCommand#perform calls

data/lib/railwatch/rspec.rb

@@ -136,4 +136,27 @@ RSpec::Matchers.define :have_railwatch_outgoing_requests do |bounds|
   end
 end
 
+# Isolator's check: an HTTP call made while a database transaction this
+# block opened is still open holds that transaction (and its locks) for the
+# whole round trip, and a rollback cannot undo what the call did.
+RSpec::Matchers.define :have_railwatch_http_in_transaction do
+  supports_block_expectations
+
+  match do |block|
+    @offending = railwatch_capture(&block).select { |r| r[:t] == "outgoing_request" && r[:in_transaction] }
+    @offending.any?
+  end
+
+  description { "make an outgoing HTTP request inside a database transaction" }
+
+  failure_message do
+    "expected the block to make an outgoing HTTP request inside a database transaction, but it made none"
+  end
+
+  failure_message_when_negated do
+    "expected no outgoing HTTP requests inside a database transaction, but the block made " \
+      "#{@offending.size}:#{Railwatch::SpecHelper.outgoing_lines(@offending)}"
+  end
+end
+
 RSpec.configure { |config| config.include Railwatch::SpecHelper } if defined?(RSpec.configure)

data/lib/railwatch/spec_helper.rb

@@ -115,7 +115,7 @@ module Railwatch
       end
 
       def outgoing_lines(records)
-        lines(records) { |r| "#{r[:method]} #{truncate(r[:url])}" }
+        lines(records) { |r| "#{r[:method]} #{truncate(r[:url])}#{" at #{r[:source]}" if r[:source]}" }
       end
 
       def exception_lines(records)

data/lib/railwatch/subscribers/queries.rb

@@ -148,8 +148,16 @@ module Railwatch
           end
         end
 
+        # Fired when a transaction or savepoint actually sends BEGIN (Active
+        # Record opens them lazily), paired with transaction.active_record
+        # below on commit, rollback, or restart.
+        subscribe_payload("start_transaction.active_record") do |_payload|
+          execution&.transaction_opened
+        end
+
         subscribe("transaction.active_record") do |event|
           exe = execution
+          exe&.transaction_closed
           exe&.count(:transactions)
           p = event.payload
           # Taken (and removed) whether or not a record is built: the

data/lib/railwatch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Railwatch
-  VERSION = "0.8.6"
+  VERSION = "0.9.0"
 end

data/lib/railwatch/wire_fixtures.json

@@ -538,6 +538,7 @@
     "response_size": 2,
     "error": null,
     "response_body": null,
+    "in_transaction": false,
     "source": "/spec/railwatch/wire_fixtures_spec.rb"
   },
   "storage_op": {

data/lib/railwatch.rb

@@ -389,7 +389,8 @@ module Railwatch
         host = (URI(url.to_s).host rescue nil)
         record(:outgoing_request, group: Record.group_hash(host, method.to_s.upcase),
                timestamp: started_at, host: host, method: method.to_s.upcase,
-               url: url.to_s[0, 2048], duration: Clock.micros_since(start), status_code: result.status.to_i)
+               url: url.to_s[0, 2048], duration: Clock.micros_since(start), status_code: result.status.to_i,
+               in_transaction: execution&.in_transaction? || false)
       end
       result
     end

data/llms.txt

@@ -26,7 +26,7 @@
 - [Embedded mode](docs/embedded.md): the default install — the dashboard inside the app, its two SQLite databases, dashboard authentication, the Puma writer process, maintenance without a job worker, disk reclaim, and optional export to Railwatch Cloud.
 - [Configuration](docs/configuration.md): every configuration option and its `RAILWATCH_*` environment variable, plus the full public facade, redaction, rejection, transport and buffering behaviour, and the rake tasks.
 - [Record types](docs/records.md): every record type the gem ships and every attribute on it, including RubyLLM calls (tokens, cost, finish reason, tool calls, workflows), sourced from the code that builds it.
-- [Testing](docs/testing.md): the RSpec and Minitest matchers (`have_railwatch_queries`, `have_railwatch_n_plus_one`, `record_railwatch_span`, `record_railwatch_exception`, `have_railwatch_outgoing_requests`) and a CI performance-gate recipe.
+- [Testing](docs/testing.md): the RSpec and Minitest matchers (`have_railwatch_queries`, `have_railwatch_n_plus_one`, `record_railwatch_span`, `record_railwatch_exception`, `have_railwatch_outgoing_requests`, `have_railwatch_http_in_transaction`) and a CI performance-gate recipe.
 - [Production source maps](docs/source-maps.md): hidden Vite maps, private upload before publishing assets, safe opt-in deletion, resolved browser stacks and default issue grouping.
 - [AI assistants and MCP](docs/ai-and-mcp.md): Railwatch Cloud's MCP endpoint, how to get a token, paste-ready client configuration for Claude Code, Claude Desktop, Cursor, VS Code, and Zed, and every tool, prompt, and resource the server exposes.
 - [Replacing Sentry](docs/replacing-sentry.md): a step-by-step migration — removing the gems, porting each option, rewriting each call site, breadcrumbs, spans, profiling, attachments, `before_send`, fingerprints, and release health.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: railwatch
 version: !ruby/object:Gem::Version
-  version: 0.8.6
+  version: 0.9.0
 platform: ruby
 authors:
 - Cole Robertson
@@ -406,6 +406,7 @@ files:
 - db/railwatch_telemetry_migrate/20260922000000_add_covering_indexes_for_dashboard_aggregates.rb
 - db/railwatch_telemetry_migrate/20260923000000_add_people_index.rb
 - db/railwatch_telemetry_migrate/20260925000000_add_tenant_summary_index.rb
+- db/railwatch_telemetry_migrate/20261008000000_add_in_transaction_to_outgoing_requests.rb
 - docs/ai-and-mcp.md
 - docs/configuration.md
 - docs/embedded.md
@@ -453,6 +454,7 @@ files:
 - lib/railwatch/minitest.rb
 - lib/railwatch/patches.rb
 - lib/railwatch/patches/inertia.rb
+- lib/railwatch/patches/migration_busy_timeout.rb
 - lib/railwatch/patches/net_http.rb
 - lib/railwatch/patches/rake_task.rb
 - lib/railwatch/patches/runner_command.rb