txray 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f735a624f2fabb3ab9d3b2133c2b7793d6c836e730a6d71a3a5d21217f49e3d9
-  data.tar.gz: c76ae3d2e4aa426361fc0b2a834c76d5e33e910af92e541eaecacbe80ea462e9
+  metadata.gz: '04384fde1e534819ca3055d82a586c3da880b2ea97aa49d8fbe2c3eaa0182beb'
+  data.tar.gz: d8b1dd217628ad5a12780cd295d27bdb7c934b10907443d6afe95726925c62f2
 SHA512:
-  metadata.gz: a10c45fade77e209f9c5bdc85bcb4453629ad9a2acf63d0067ff16a5a958512a6e4c31f9e1e54aedb60660e9c021d2513fe17b990aeb254ca607347138b73135
-  data.tar.gz: 27f2cdcd1bfaceb62be8ebc3ffedca7f90cf53104fc1f25a79af81ef48051d7e8e2d71649d354a184207ca4c7f347c4316fdd6a6795a1ea57442e5b68a35871d
+  metadata.gz: 4f2ed21c432a811623ddfae148e50cbdd54283b71fc663f5ca67750fdbe5710c5810ec6ee2c64bc9ce134de420b0195f7f30e8ab0c5c1c54cdcfc2522567791f
+  data.tar.gz: 4eab65e95a199496556e0569667b09e414205e0bd8f21fd25af58636ff21a3107ca33b413789a00a8f55d6e4470181b03811e711a02bb007a65d561dfa05b6cc

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.2.1
+
+Nothing in the analyzer, the runtime guard or the reporters changed. This release exists to exercise the publishing pipeline on something low stakes before a release that matters.
+
+- Releases are now published by GitHub Actions through RubyGems trusted publishing, so no API key is created, pasted or stored. Merging a version bump tags the commit, runs the suite, publishes the gem and creates the GitHub release with the notes taken from this file.
+- Corrected the release steps in `CONTRIBUTING.md`, which told contributors to push a version bump straight to a protected `main`.
+
+## 0.2.0
+
+- Track clients held in local variables, instance variables, constants, memoized readers and `delegate` targets, so the request is reported rather than the harmless construction.
+- Resolve `send` and `public_send` with a symbol literal, `define_method` bodies and concern `included` blocks; report genuinely dynamic dispatch as a visible low severity blind spot.
+- Cover custom validations, `before_commit`, advisory locks and migration bodies as transactional scope, and add rules for broadcasts and blocking file, CSV and image work.
+- RuboCop style directive regions: `# txray:disable RULE` ... `# txray:enable RULE`, `all`, and whole file suppression.
+- Rebuilt live monitor with stacked meters, a latency histogram and severity colour, clamped to the terminal; `rails generate txray:install`; `NO_COLOR` support.
+- Report paths relative to the working directory, and escape GitHub workflow commands correctly, so annotations and SARIF attach to the right file.
+- `--format github` now writes a job summary table in addition to inline annotations.
+- Runtime guard supports Rails 7.0 through 8.x, timing the transaction directly on versions that do not emit `start_transaction.active_record`.
+- Clear errors for a malformed config, a missing path and an unparseable file, all of which previously reported a clean scan that never happened.
+
 ## 0.1.0
 
 - Static transaction analysis over explicit transactions, row and advisory locks, save callbacks, custom validations and migrations.

data/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+```sh
+bin/setup
+bundle exec rake        # specs and rubocop
+```
+
+## Adding a rule
+
+A rule is three things and a test.
+
+1. `Rules.register` in `lib/txray/rule.rb`, with the severity, what the reader sees, and the fix.
+2. A branch in `lib/txray/classifier.rb`, or a namespace in `lib/txray/catalog.rb` if the call is recognised by its receiver.
+3. A scenario in `spec/txray/scenarios_spec.rb` that proves it fires, and one that proves it stays quiet on the shape it should ignore.
+
+The second test matters more than the first. A rule that fires on correct code costs more than a rule that misses.
+
+## Adding a transactional scope
+
+`lib/txray/transaction_scope.rb` decides what counts as being inside a transaction. Anything added there needs a case showing that the corresponding commit-time callback is still left alone.
+
+## Testing against other Rails versions
+
+```sh
+RAILS_VERSION=7.1 bundle install && RAILS_VERSION=7.1 bundle exec rspec
+```
+
+CI runs 7.1, 7.2 and 8.0 alongside Ruby 3.2, 3.3 and 3.4.
+
+## Before opening a pull request
+
+Run the scanner against a real application, not only the suite. False positives are the failure mode that matters, and they show up in real code long before they show up in fixtures.
+
+## Releasing
+
+Merging a version bump releases the gem. There is nothing to run by hand.
+
+1. On a branch, bump `Txray::VERSION` in `lib/txray/version.rb` and add a `## x.y.z` section to `CHANGELOG.md`.
+2. Open the pull request and merge it once CI is green.
+
+On every push to `main` the release workflow reads `Txray::VERSION` and stops immediately if that version is already tagged, so ordinary merges do nothing. When the version is new it takes the release notes from the matching changelog section, runs the suite, tags the commit, publishes the gem to RubyGems through trusted publishing, and creates the GitHub release with the notes and the built gem attached.
+
+The tag is created locally and only pushed once the gem is published, so a failure leaves nothing behind: fix it and merge again. A missing changelog section fails before the suite even runs. No API key is involved anywhere.

data/README.md

@@ -16,17 +16,31 @@ app/models/order.rb
 
 ## Install
 
+For the scanner alone:
+
 ```ruby
 group :development, :test do
   gem "txray", require: false
 end
 ```
 
+For the scanner **and** the runtime guard and live monitor, drop `require: false`, or the railtie never loads and the guard silently never installs:
+
+```ruby
+group :development, :test do
+  gem "txray"
+end
+```
+
+Then:
+
 ```sh
 bundle exec txray
 ```
 
-It exits non zero when it finds something, so it drops straight into CI.
+It exits non zero when it finds something, so it drops straight into CI. No configuration is required; everything below has a default.
+
+In a Rails app, `bin/rails generate txray:install` writes a commented `.txray.yml` and prints the next steps. Outside Rails, `bundle exec txray --init` writes the same file.
 
 ## What counts as a transaction
 
@@ -158,14 +172,35 @@ Exclusions apply to the path below the root being scanned, so `vendor` means the
 
 ### Inline suppression
 
+Directives follow the same shape as RuboCop's. A trailing comment silences that line:
+
 ```ruby
 def charge = Faraday.post(url) # txray:disable
+def charge = Faraday.post(url) # txray:disable http-in-transaction
+```
+
+A comment on its own line opens a region that runs until the matching `enable`, or to the end of the file if there is none:
 
+```ruby
 # txray:disable http-in-transaction
 Faraday.post(url)
+Faraday.get(url)
+# txray:enable http-in-transaction
 ```
 
-A bare `# txray:disable` disables every rule on that line; naming rules disables only those. The comment works on the offending line or the line directly above it.
+Name several rules with commas, and re-enable them independently:
+
+```ruby
+# txray:disable http-in-transaction, job-enqueue-in-transaction
+...
+# txray:enable job-enqueue-in-transaction
+```
+
+A bare directive, or `all`, covers every rule. At the top of a file that silences the whole file:
+
+```ruby
+# txray:disable all
+```
 
 ## Command line
 
@@ -189,19 +224,43 @@ Usage: txray [options] [paths]
 ## CI
 
 ```yaml
-- name: Scan for slow transactions
-  run: bundle exec txray --format github
+name: txray
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  transactions:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - name: Scan for slow transactions
+        run: bundle exec txray --format github
 ```
 
-`--format github` writes inline annotations on the pull request. `--format sarif` uploads to GitHub code scanning:
+That one step does three things. It annotates the offending lines inline on the pull request, with the call path and the suggested fix in each annotation. It writes a table of every finding to the job summary, so the run page carries the full list even though GitHub caps how many annotations it will render for a single step. And it exits non zero, so the check fails.
+
+Use `--fail-level high` to annotate everything but only fail the build on the high severity rules, or `--fail-level none` to report without ever failing while you work through a backlog.
+
+To send findings to GitHub code scanning instead, so they appear in the Security tab and track across branches:
 
 ```yaml
-- run: bundle exec txray --format sarif > txray.sarif || true
-- uses: github/codeql-action/upload-sarif@v3
-  with:
-    sarif_file: txray.sarif
+      - run: bundle exec txray --format sarif > txray.sarif
+        continue-on-error: true
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: txray.sarif
 ```
 
+That job needs `permissions: security-events: write`. `continue-on-error` matters: without it a failing scan skips the upload step, and the findings never arrive.
+
+Paths are reported relative to the working directory in every format, which is what GitHub needs to match a finding to a file in the repository.
+
 ## Runtime guard
 
 Static analysis cannot see through metaprogramming, gem internals or a client handed in as an argument. The optional runtime guard catches what is left, from inside a running application:
@@ -215,6 +274,10 @@ runtime:
 
 It reports a transaction that stays open past the threshold, a job enqueued while a transaction is open, mail delivered while a transaction is open, and any `Net::HTTP` request made while a transaction is open (which covers Faraday, HTTParty, RestClient, Octokit and everything else built on it). Each finding is attributed to the transaction that was open, with the duration of the offending call and the application frame that caused it. `on_violation: log` warns, `raise` fails loudly. Run it as `raise` in test and `log` in development.
 
+### Rails versions
+
+The analyzer has no Rails dependency at all. The runtime guard supports **Rails 7.0 through 8.x** and picks its hook accordingly. From Rails 7.2 it subscribes to the `start_transaction.active_record` and `transaction.active_record` notifications. Rails 7.0 and 7.1 do not emit `start_transaction`, and the duration carried by `transaction.active_record` is not the duration of the transaction, so on those versions the guard times `within_new_transaction` itself. Both paths report the same real duration, attribute findings to the transaction that was open, and record the commit or rollback outcome; both are covered by the test suite and exercised in CI against 7.1, 7.2 and 8.0.
+
 Known-good work can be excused:
 
 ```ruby
@@ -229,30 +292,48 @@ end
 
 The guard writes newline delimited JSON to `runtime.log_path`. `txray watch` tails it and renders what your application is doing right now:
 
-```
-  txray watching tmp/txray.ndjson  00:04:12
+![the txray live monitor](https://raw.githubusercontent.com/theowecker/txray/main/doc/monitor.png)
 
-  transactions    142 seen   9 slow   4 with findings
-  duration        p50 12ms   p95 240ms   max 1.84s
-                  ▁▁▂▁▁▁▁▁▁▂▁▁▁▁▁▅▁▁▁▁▁▂▁▁▁▁▁▁▁▁▂█
+The `txns` meter is a stacked bar of clean, slow and flagged transactions. The `time` row is a log scaled sparkline of recent durations next to p50, p95 and max, all coloured against your threshold. Below that is a latency histogram, then the live feed, where findings hang under the transaction that produced them, so you see the 1.84 second transaction and the two calls that account for most of it. Hotspots rank what keeps happening. Everything is coloured by rule severity and clipped to your terminal, down to 60 columns.
 
-  LIVE
-  14:02:11              1.84s  x  app/models/order.rb:31 settle
-                          | http-in-transaction POST api.stripe.com/v1/charges (1.61s)
-                          | mail-in-transaction ReceiptMailer delivered mail (180ms)
-  14:02:10               268ms  !  app/services/checkout.rb:12 call
-  14:02:09                11ms  .  app/models/photo.rb:8 save
+### Turning it on
 
-  HOTSPOTS
-    3x  http-in-transaction              app/models/order.rb:34
-    1x  job-enqueue-in-transaction       app/models/photo.rb:8
+Three steps, in this order:
 
-  ctrl-c to stop
-```
+1. **Gemfile** must not say `require: false` (see Install above), or nothing is ever written.
+2. **Enable the guard**, in `.txray.yml`:
 
-Findings are grouped under the transaction that produced them, so you see the transaction that took 1.84 seconds and the two calls that account for most of it. Ctrl-C prints a summary of the session. Piped to a file or another process it emits the raw event stream instead of the dashboard, so `txray watch | jq` works.
+   ```yaml
+   runtime:
+     enabled: true
+     threshold_ms: 250
+   ```
 
-The log is append only with an exclusive lock per write, so several Puma workers and Sidekiq processes can share one file.
+   or in `config/environments/development.rb`:
+
+   ```ruby
+   config.txray.enabled = true
+   config.txray.threshold_ms = 250
+   ```
+
+3. **Restart the app**, then run the two side by side:
+
+   ```
+   terminal 1:  bin/dev
+   terminal 2:  bundle exec txray watch
+   ```
+
+Exercise the app and transactions appear as they close. Only transactions that ran past the threshold or carried a finding are recorded, so the feed stays quiet until something is actually wrong. If the log does not exist yet, `txray watch` says so and repeats these steps on screen rather than sitting blank.
+
+| Flag | Effect |
+| --- | --- |
+| `--from-start` | replay the existing log instead of only new events |
+| `--threshold 100` | lower the bar to see more |
+| `--file PATH` | watch a different log |
+
+Ctrl-C prints a summary of the session. Piped to a file or another process it emits the raw event stream instead of the dashboard, so `txray watch | jq` works.
+
+The log is append only with an exclusive lock per write, so several Puma workers and Sidekiq processes can share one file. It is newline delimited JSON rather than a text log because the watcher reads it incrementally while it is being written: one line is one complete record, so a partial read is never a partial event, concurrent writers cannot interleave into one record, and the nested findings and durations survive without parsing prose. It is still a plain text file, so `tail -f tmp/txray.ndjson` works.
 
 ## How this differs from what already exists
 
@@ -269,6 +350,8 @@ bin/setup
 bundle exec rake
 ```
 
+Releases are cut by tagging; see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## License
 
 MIT

data/Rakefile

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "rubocop/rake_task"
 

data/doc/monitor.svg

@@ -0,0 +1,229 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="741" height="617" viewBox="0 0 741 617" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13">
+<rect width="741" height="617" rx="8" fill="#16181d"/>
+<rect x="14.0" y="13.5" width="713.0" height="19.0" fill="#3a3f4b"/>
+<text x="14.0" y="27.0" xml:space="preserve" fill="#f5f6f8" font-weight="700"> txray  tmp/txray.ndjson                                                up 00:04:12  2 pids </text>
+<text x="14.0" y="65.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="65.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">txns  </text>
+<text x="76.0" y="65.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">[</text>
+<text x="83.75" y="65.0" xml:space="preserve" fill="#5ddc9a">████████████████████████████████</text>
+<text x="331.75" y="65.0" xml:space="preserve" fill="#e5c07b">█</text>
+<text x="339.5" y="65.0" xml:space="preserve" fill="#ff6b6b">█</text>
+<text x="347.25" y="65.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">]</text>
+<text x="355.0" y="65.0" xml:space="preserve" fill="#c8ccd4">  123 txns</text>
+<text x="432.5" y="65.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62"> · </text>
+<text x="455.75" y="65.0" xml:space="preserve" fill="#5ddc9a">120 ok</text>
+<text x="502.25" y="65.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62"> · </text>
+<text x="525.5" y="65.0" xml:space="preserve" fill="#e5c07b">1 slow</text>
+<text x="572.0" y="65.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62"> · </text>
+<text x="595.25" y="65.0" xml:space="preserve" fill="#ff6b6b">2 flagged</text>
+<text x="14.0" y="84.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="84.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">time  </text>
+<text x="76.0" y="84.0" xml:space="preserve" fill="#5ddc9a">▃</text>
+<text x="83.75" y="84.0" xml:space="preserve" fill="#5ddc9a">▃</text>
+<text x="91.5" y="84.0" xml:space="preserve" fill="#5ddc9a">▄</text>
+<text x="99.25" y="84.0" xml:space="preserve" fill="#5ddc9a">▅</text>
+<text x="107.0" y="84.0" xml:space="preserve" fill="#5ddc9a">▃</text>
+<text x="114.75" y="84.0" xml:space="preserve" fill="#5ddc9a">▄</text>
+<text x="122.5" y="84.0" xml:space="preserve" fill="#5ddc9a">▃</text>
+<text x="130.25" y="84.0" xml:space="preserve" fill="#5ddc9a">▃</text>
+<text x="138.0" y="84.0" xml:space="preserve" fill="#5ddc9a">▃</text>
+<text x="145.75" y="84.0" xml:space="preserve" fill="#5ddc9a">▄</text>
+<text x="153.5" y="84.0" xml:space="preserve" fill="#5ddc9a">▅</text>
+<text x="161.25" y="84.0" xml:space="preserve" fill="#5ddc9a">▃</text>
+<text x="169.0" y="84.0" xml:space="preserve" fill="#5ddc9a">▃</text>
+<text x="176.75" y="84.0" xml:space="preserve" fill="#5ddc9a">▅</text>
+<text x="184.5" y="84.0" xml:space="preserve" fill="#5ddc9a">▄</text>
+<text x="192.25" y="84.0" xml:space="preserve" fill="#5ddc9a">▅</text>
+<text x="200.0" y="84.0" xml:space="preserve" fill="#5ddc9a">▄</text>
+<text x="207.75" y="84.0" xml:space="preserve" fill="#5ddc9a">▄</text>
+<text x="215.5" y="84.0" xml:space="preserve" fill="#5ddc9a">▃</text>
+<text x="223.25" y="84.0" xml:space="preserve" fill="#5ddc9a">▄</text>
+<text x="231.0" y="84.0" xml:space="preserve" fill="#5ddc9a">▅</text>
+<text x="238.75" y="84.0" xml:space="preserve" fill="#5ddc9a">▂</text>
+<text x="246.5" y="84.0" xml:space="preserve" fill="#5ddc9a">▃</text>
+<text x="254.25" y="84.0" xml:space="preserve" fill="#5ddc9a">▂</text>
+<text x="262.0" y="84.0" xml:space="preserve" fill="#5ddc9a">▄</text>
+<text x="269.75" y="84.0" xml:space="preserve" fill="#5ddc9a">▅</text>
+<text x="277.5" y="84.0" xml:space="preserve" fill="#5ddc9a">▄</text>
+<text x="285.25" y="84.0" xml:space="preserve" fill="#5ddc9a">▄</text>
+<text x="293.0" y="84.0" xml:space="preserve" fill="#5ddc9a">▃</text>
+<text x="300.75" y="84.0" xml:space="preserve" fill="#5ddc9a">▄</text>
+<text x="308.5" y="84.0" xml:space="preserve" fill="#5ddc9a">▃</text>
+<text x="316.25" y="84.0" xml:space="preserve" fill="#ff6b6b">▆</text>
+<text x="324.0" y="84.0" xml:space="preserve" fill="#ff6b6b">▇</text>
+<text x="331.75" y="84.0" xml:space="preserve" fill="#ff6b6b">█</text>
+<text x="339.5" y="84.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="355.0" y="84.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">p50</text>
+<text x="378.25" y="84.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="386.0" y="84.0" xml:space="preserve" fill="#5ddc9a">18ms</text>
+<text x="417.0" y="84.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62"> · </text>
+<text x="440.25" y="84.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">p95</text>
+<text x="463.5" y="84.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="471.25" y="84.0" xml:space="preserve" fill="#e5c07b">140ms</text>
+<text x="510.0" y="84.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62"> · </text>
+<text x="533.25" y="84.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">max</text>
+<text x="556.5" y="84.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="564.25" y="84.0" xml:space="preserve" fill="#ff6b6b">1.84s</text>
+<text x="14.0" y="122.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="122.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">  &lt;10ms</text>
+<text x="83.75" y="122.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="91.5" y="122.0" xml:space="preserve" fill="#5ddc9a">███████████████████████████████</text>
+<text x="331.75" y="122.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="339.5" y="122.0" xml:space="preserve" fill="#f0f0f0">45  </text>
+<text x="370.5" y="122.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="386.0" y="122.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">  &lt;50ms</text>
+<text x="440.25" y="122.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="448.0" y="122.0" xml:space="preserve" fill="#5ddc9a">█████████████████████████████</text>
+<text x="672.75" y="122.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">··</text>
+<text x="688.25" y="122.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="696.0" y="122.0" xml:space="preserve" fill="#f0f0f0">42  </text>
+<text x="14.0" y="141.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="141.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62"> &lt;100ms</text>
+<text x="83.75" y="141.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="91.5" y="141.0" xml:space="preserve" fill="#5ddc9a">███████████████████</text>
+<text x="238.75" y="141.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">············</text>
+<text x="331.75" y="141.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="339.5" y="141.0" xml:space="preserve" fill="#f0f0f0">27  </text>
+<text x="370.5" y="141.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="386.0" y="141.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62"> &lt;250ms</text>
+<text x="440.25" y="141.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="448.0" y="141.0" xml:space="preserve" fill="#e5c07b">████</text>
+<text x="479.0" y="141.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">···························</text>
+<text x="688.25" y="141.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="696.0" y="141.0" xml:space="preserve" fill="#f0f0f0">6   </text>
+<text x="14.0" y="160.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="160.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">    &lt;1s</text>
+<text x="83.75" y="160.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="91.5" y="160.0" xml:space="preserve" fill="#ff6b6b">█</text>
+<text x="99.25" y="160.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">······························</text>
+<text x="331.75" y="160.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="339.5" y="160.0" xml:space="preserve" fill="#f0f0f0">2   </text>
+<text x="370.5" y="160.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="386.0" y="160.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">    1s+</text>
+<text x="440.25" y="160.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="448.0" y="160.0" xml:space="preserve" fill="#ff6b6b">█</text>
+<text x="455.75" y="160.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">······························</text>
+<text x="688.25" y="160.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="696.0" y="160.0" xml:space="preserve" fill="#f0f0f0">1   </text>
+<rect x="14.0" y="184.5" width="713.0" height="19.0" fill="#3a3f4b"/>
+<text x="14.0" y="198.0" xml:space="preserve" fill="#f5f6f8" font-weight="700">  TIME       ELAPSED   SOURCE                                                               </text>
+<text x="14.0" y="217.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="217.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">14:12:13</text>
+<text x="91.5" y="217.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="99.25" y="217.0" xml:space="preserve" fill="#ff6b6b">    1.84s</text>
+<text x="169.0" y="217.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="176.75" y="217.0" xml:space="preserve" fill="#ff6b6b">●</text>
+<text x="184.5" y="217.0" xml:space="preserve" fill="#c8ccd4"> app/models/order.rb:31 settle</text>
+<text x="14.0" y="236.0" xml:space="preserve" fill="#c8ccd4">                      </text>
+<text x="184.5" y="236.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">└</text>
+<text x="192.25" y="236.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="200.0" y="236.0" xml:space="preserve" fill="#ff6b6b">http-in-transaction</text>
+<text x="347.25" y="236.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="355.0" y="236.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">POST api.stripe.com/v1/charges (1.61s)</text>
+<text x="14.0" y="255.0" xml:space="preserve" fill="#c8ccd4">                      </text>
+<text x="184.5" y="255.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">└</text>
+<text x="192.25" y="255.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="200.0" y="255.0" xml:space="preserve" fill="#e5c07b">job-enqueue-in-transaction</text>
+<text x="401.5" y="255.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="409.25" y="255.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">ShipJob enqueued</text>
+<text x="14.0" y="274.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="274.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">14:12:04</text>
+<text x="91.5" y="274.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="99.25" y="274.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">        -</text>
+<text x="169.0" y="274.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="176.75" y="274.0" xml:space="preserve" fill="#56b6c2">●</text>
+<text x="184.5" y="274.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="192.25" y="274.0" xml:space="preserve" fill="#56b6c2">cache-in-transaction</text>
+<text x="347.25" y="274.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="355.0" y="274.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">app/models/album.rb:19</text>
+<text x="14.0" y="293.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="293.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">14:11:54</text>
+<text x="91.5" y="293.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="99.25" y="293.0" xml:space="preserve" fill="#ff6b6b">    612ms</text>
+<text x="169.0" y="293.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="176.75" y="293.0" xml:space="preserve" fill="#ff6b6b">●</text>
+<text x="184.5" y="293.0" xml:space="preserve" fill="#c8ccd4"> app/models/photo.rb:44 attach_original</text>
+<text x="14.0" y="312.0" xml:space="preserve" fill="#c8ccd4">                      </text>
+<text x="184.5" y="312.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">└</text>
+<text x="192.25" y="312.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="200.0" y="312.0" xml:space="preserve" fill="#e5c07b">upload-in-transaction</text>
+<text x="362.75" y="312.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="370.5" y="312.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">original.attach(io: file) (540ms)</text>
+<text x="14.0" y="331.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="331.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">14:11:36</text>
+<text x="91.5" y="331.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="99.25" y="331.0" xml:space="preserve" fill="#ff6b6b">    268ms</text>
+<text x="169.0" y="331.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="176.75" y="331.0" xml:space="preserve" fill="#e5c07b">●</text>
+<text x="184.5" y="331.0" xml:space="preserve" fill="#c8ccd4"> app/services/checkout.rb:12 call</text>
+<text x="14.0" y="350.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="350.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">14:09:15</text>
+<text x="91.5" y="350.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="99.25" y="350.0" xml:space="preserve" fill="#5ddc9a">      9ms</text>
+<text x="169.0" y="350.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="176.75" y="350.0" xml:space="preserve" fill="#5ddc9a">·</text>
+<text x="184.5" y="350.0" xml:space="preserve" fill="#c8ccd4"> app/models/photo.rb:8 save</text>
+<text x="14.0" y="369.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="369.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">14:09:14</text>
+<text x="91.5" y="369.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="99.25" y="369.0" xml:space="preserve" fill="#5ddc9a">     18ms</text>
+<text x="169.0" y="369.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="176.75" y="369.0" xml:space="preserve" fill="#5ddc9a">·</text>
+<text x="184.5" y="369.0" xml:space="preserve" fill="#c8ccd4"> app/models/photo.rb:8 save</text>
+<text x="14.0" y="388.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="388.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">14:09:13</text>
+<text x="91.5" y="388.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="99.25" y="388.0" xml:space="preserve" fill="#5ddc9a">      9ms</text>
+<text x="169.0" y="388.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="176.75" y="388.0" xml:space="preserve" fill="#5ddc9a">·</text>
+<text x="184.5" y="388.0" xml:space="preserve" fill="#c8ccd4"> app/models/photo.rb:8 save</text>
+<text x="14.0" y="407.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="407.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">14:09:12</text>
+<text x="91.5" y="407.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="99.25" y="407.0" xml:space="preserve" fill="#5ddc9a">     41ms</text>
+<text x="169.0" y="407.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="176.75" y="407.0" xml:space="preserve" fill="#5ddc9a">·</text>
+<text x="184.5" y="407.0" xml:space="preserve" fill="#c8ccd4"> app/models/photo.rb:8 save</text>
+<text x="14.0" y="426.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="426.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">14:09:11</text>
+<text x="91.5" y="426.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="99.25" y="426.0" xml:space="preserve" fill="#5ddc9a">     18ms</text>
+<text x="169.0" y="426.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="176.75" y="426.0" xml:space="preserve" fill="#5ddc9a">·</text>
+<text x="184.5" y="426.0" xml:space="preserve" fill="#c8ccd4"> app/models/photo.rb:8 save</text>
+<text x="14.0" y="445.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="445.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">14:09:10</text>
+<text x="91.5" y="445.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="99.25" y="445.0" xml:space="preserve" fill="#5ddc9a">     63ms</text>
+<text x="169.0" y="445.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="176.75" y="445.0" xml:space="preserve" fill="#5ddc9a">·</text>
+<text x="184.5" y="445.0" xml:space="preserve" fill="#c8ccd4"> app/models/photo.rb:8 save</text>
+<rect x="14.0" y="469.5" width="713.0" height="19.0" fill="#3a3f4b"/>
+<text x="14.0" y="483.0" xml:space="preserve" fill="#f5f6f8" font-weight="700">  HOTSPOTS                                                                                  </text>
+<text x="14.0" y="502.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="502.0" xml:space="preserve" fill="#f0f0f0">   1x</text>
+<text x="68.25" y="502.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="83.75" y="502.0" xml:space="preserve" fill="#56b6c2">cache-in-transaction            </text>
+<text x="331.75" y="502.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="339.5" y="502.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">app/models/album.rb:19</text>
+<text x="14.0" y="521.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="521.0" xml:space="preserve" fill="#f0f0f0">   1x</text>
+<text x="68.25" y="521.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="83.75" y="521.0" xml:space="preserve" fill="#e5c07b">upload-in-transaction           </text>
+<text x="331.75" y="521.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="339.5" y="521.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">app/models/photo.rb:46</text>
+<text x="14.0" y="540.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="540.0" xml:space="preserve" fill="#f0f0f0">   1x</text>
+<text x="68.25" y="540.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="83.75" y="540.0" xml:space="preserve" fill="#ff6b6b">http-in-transaction             </text>
+<text x="331.75" y="540.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="339.5" y="540.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">app/models/order.rb:34</text>
+<text x="14.0" y="559.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="29.5" y="559.0" xml:space="preserve" fill="#f0f0f0">   1x</text>
+<text x="68.25" y="559.0" xml:space="preserve" fill="#c8ccd4">  </text>
+<text x="83.75" y="559.0" xml:space="preserve" fill="#e5c07b">job-enqueue-in-transaction      </text>
+<text x="331.75" y="559.0" xml:space="preserve" fill="#c8ccd4"> </text>
+<text x="339.5" y="559.0" xml:space="preserve" fill="#c8ccd4" opacity="0.62">app/models/order.rb:38</text>
+<rect x="14.0" y="583.5" width="713.0" height="19.0" fill="#3a3f4b"/>
+<text x="14.0" y="597.0" xml:space="preserve" fill="#f5f6f8" font-weight="700">  ctrl-c  stop                                                                              </text>
+</svg>

data/lib/generators/txray/install_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Txray
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Writes .txray.yml and explains how to turn the runtime guard on."
+
+      def create_config
+        copy_file "txray.yml", ".txray.yml"
+      end
+
+      def explain
+        say ""
+        say "Scan the application:", :green
+        say "  bundle exec txray"
+        say ""
+        say "To watch transactions live, set runtime.enabled to true in .txray.yml,", :green
+        say "make sure the Gemfile does not say require: false, restart, then run:"
+        say "  bundle exec txray watch"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/txray/templates/txray.yml

@@ -0,0 +1,37 @@
+# Where to look. Paths are relative to the project root.
+include:
+  - app
+  - lib
+  - db/migrate
+exclude:
+  - spec
+  - test
+  - vendor
+
+# How far to follow a call out of a transaction before giving up.
+max_depth: 3
+
+# Exit non zero at or above this severity: low, medium, high or none.
+fail_level: low
+
+# Rules to turn off entirely. `txray --rules` lists them all.
+disabled_rules: []
+
+# Raise or lower a rule without turning it off.
+severities: {}
+
+# Your own service wrappers. Any constant under these is treated as a
+# third party client, so a call on one inside a transaction is reported.
+external_clients: []
+
+# The runtime guard. Off by default. It reports transactions that run long
+# and the HTTP, mail and job work that happens while one is open, and writes
+# the event log that `txray watch` reads.
+#
+# The gem must NOT be `require: false` in your Gemfile for this to load.
+runtime:
+  enabled: false
+  threshold_ms: 250
+  on_violation: log # log, or raise to fail loudly in test
+  log_path: tmp/txray.ndjson
+  ignore: []

data/lib/txray/cli.rb

@@ -63,6 +63,9 @@ module Txray
 
       File.write(Config::FILENAME, YAML.dump(Config::DEFAULTS))
       @io.puts "created #{Config::FILENAME}"
+      @io.puts
+      @io.puts "scan with:            bundle exec txray"
+      @io.puts "watch transactions:   set runtime.enabled to true, restart, then bundle exec txray watch"
       EXIT_CLEAN
     end