tensorbuzz-api-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 46aa55521a8826c09ade79fb8d2810b89e91d28ba7834cd2228e13b3a477023d
+  data.tar.gz: bb4ed791180aa9f143ac5482d42fbb3ddd5868201164c300382c1a76266509d6
+SHA512:
+  metadata.gz: 6ca55423d1157f06b20d16c81b31d0e079f114bdfe1ac27642656026c4fd99d7dccc4e3e52f943192b2c22d08cf8383ad72eb676856e6953becfd26768fd6c9f
+  data.tar.gz: 4e484cae7ad39af46a1b502d03a7b8e91eab7452270821e532f744369f448e6d18e252f7cccb16265b1a6f7dc05ffbb19364eeee52749e0afb990f388ad2e726

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kasper Stöckel
+
+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,45 @@
+# tensorbuzz-api-rails for Ruby
+
+Active Record slow-SQL reporting for TensorBuzz, built on the `tensorbuzz-api`
+gem.
+
+## Installation
+
+```ruby
+gem "tensorbuzz-api-rails"
+```
+
+`tensorbuzz-api` is installed automatically; `activesupport` is a runtime
+dependency of this gem.
+
+## Slow SQL
+
+Queries over a threshold are reported to TensorBuzz as
+`TensorBuzz::Api::SlowSql::ExceededThreshold`. The threshold defaults to 200 ms
+and is set per process when the feature is enabled:
+
+```ruby
+require "tensorbuzz/api/slow_sql"
+
+TensorBuzz::SlowSql.enable(threshold_ms: 200)
+```
+
+The report carries the full query text, duration, and the boolean `cached` and
+`in_transaction` flags plus the connection adapter class name in
+`parameters[:slow_sql]`, all derived from the real Active Record notification
+payload, with a backtrace of the code path that issued the statement. Reports
+for the same query at the same code path are suppressed for 30 seconds, so a
+hot N+1 produces one report per window instead of one per statement.
+
+Known-slow paths opt out with a thread-scoped silence block (per worker
+thread — Rails workers handle one request, job, or cable connection at a time):
+
+```ruby
+TensorBuzz::SlowSql.silence do
+  known_slow_path.call
+end
+```
+
+`disable` unsubscribes the listener for teardown and tests.
+
+See the `tensorbuzz-api` README for bug reporting configuration.

data/lib/tensorbuzz/api/rails/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module TensorBuzz
+  module Api
+    module Rails
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/tensorbuzz/api/slow_sql.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+require 'tensorbuzz/api/bug_reporting'
+
+module TensorBuzz
+  module Api
+    module SlowSql
+      DEFAULT_THRESHOLD_MS = 200
+      DEFAULT_WINDOW_SECONDS = 30
+      MAX_TRACKED_KEYS = 4096
+      SQL_MESSAGE_LENGTH = 500
+      SILENCED_COUNT_KEY = :__tensorbuzz_slow_sql_silenced_count
+
+      # Reported as a bug for every SQL statement over the threshold. The message
+      # is intentionally stable per query (no duration) so TensorBuzz groups the
+      # same slow query across instances and processes; the per-instance
+      # duration is in the payload.
+      class ExceededThreshold < RuntimeError
+        attr_reader :sql, :duration_ms
+
+        def initialize(sql, duration_ms)
+          @sql = sql.to_s
+          @duration_ms = duration_ms
+          super("Slow SQL query: #{truncated_message_sql(@sql)}")
+        end
+
+        private
+
+        def truncated_message_sql(sql)
+          return sql if sql.length <= SQL_MESSAGE_LENGTH
+
+          "#{sql[0...SQL_MESSAGE_LENGTH]}…"
+        end
+      end
+
+      # Receives `sql.active_record` notification events and reports those over
+      # the threshold through BugReporting.
+      class Listener
+        attr_reader :threshold_ms
+
+        def initialize(threshold_ms:)
+          @threshold_ms = threshold_ms
+        end
+
+        def call(event)
+          return if SlowSql.silenced?
+          return if event.duration <= threshold_ms
+
+          SlowSql.report(event)
+        end
+      end
+
+      # Installs the listener for all `sql.active_record` events. Idempotent;
+      # calls disable first so a changed threshold takes effect immediately.
+      def self.enable(threshold_ms: DEFAULT_THRESHOLD_MS)
+        disable
+        @listener = Listener.new(threshold_ms: threshold_ms)
+        state_mutex.synchronize { @tracked = {} }
+        ActiveSupport::Notifications.subscribe('sql.active_record', @listener)
+      end
+
+      # Unsubscribes the listener and clears dedupe state.
+      def self.disable
+        ActiveSupport::Notifications.unsubscribe(@listener) if @listener
+        @listener = nil
+        state_mutex.synchronize { @tracked = {} }
+      end
+
+      def self.enabled?
+        !@listener.nil?
+      end
+
+      # Suppresses reporting for the rest of this thread's execution while the
+      # block runs, including nested silences. Per-thread (not per-fiber)
+      # because this Ruby stores local variables only per thread; in a Rails
+      # worker (Puma request, Sidekiq job, ActionCable handler) that is the
+      # natural unit of work and a block never hands another task over on the
+      # same thread.
+      def self.silence
+        Thread.current[SILENCED_COUNT_KEY] = (Thread.current[SILENCED_COUNT_KEY] || 0) + 1
+        yield
+      ensure
+        Thread.current[SILENCED_COUNT_KEY] = (Thread.current[SILENCED_COUNT_KEY] || 0) - 1
+      end
+
+      def self.silenced?
+        (Thread.current[SILENCED_COUNT_KEY] || 0).positive?
+      end
+
+      # Returns true when a report for this key is allowed and records it, so a
+      # hot N+1 of the same slow query sends one report per window instead of
+      # one per statement. All access to the process-wide dedupe state is
+      # synchronized because Rails and Sidekiq emit events from multiple
+      # worker threads.
+      def self.reportable?(key)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        state_mutex.synchronize do
+          entry = @tracked[key]
+          return false if entry && now - entry[0] < DEFAULT_WINDOW_SECONDS
+
+          @tracked[key] = [now, 1]
+          evict_tracked(now)
+          true
+        end
+      end
+
+      def self.report(event)
+        payload = event.payload
+        sql = payload[:sql].to_s
+        return if sql.empty?
+
+        frames = caller
+        cleaner = defined?(::Rails) && Rails.respond_to?(:backtrace_cleaner) ? Rails.backtrace_cleaner : nil
+        backtrace = cleaner ? cleaner.clean(frames) : frames
+        location = backtrace.first
+
+        error = ExceededThreshold.new(sql, event.duration)
+        error.set_backtrace(backtrace)
+
+        # Dedupe on the complete SQL: error.message is truncated to
+        # SQL_MESSAGE_LENGTH for grouping, so distinct statements sharing a
+        # long prefix would otherwise collide on the same key.
+        return unless reportable?("#{sql}|#{location}")
+
+        BugReporting.safely_report(
+          error,
+          parameters: { slow_sql: slow_sql_parameters(event, sql) }
+        )
+      end
+
+      class << self
+        private
+
+        # Derives the reported metadata from the real Active Record
+        # notification payload: Active Record supplies the adapter as
+        # payload[:connection] and the user transaction as an object or nil,
+        # both reported as stable values rather than raw objects.
+        def slow_sql_parameters(event, sql)
+          payload = event.payload
+          {
+            duration_ms: event.duration,
+            sql: sql,
+            cached: payload[:cached] ? true : false,
+            in_transaction: payload[:transaction] ? true : false,
+            adapter: payload[:connection]&.class&.name
+          }
+        end
+
+        # @tracked is a process-wide hash shared by all worker threads.
+        def state_mutex
+          @state_mutex ||= Mutex.new
+        end
+
+        # Bounds the dedupe state: drop entries older than the window, and
+        # when every entry is still fresh evict the oldest ones so the hash
+        # never grows past MAX_TRACKED_KEYS.
+        def evict_tracked(now)
+          return if @tracked.size <= MAX_TRACKED_KEYS
+
+          cutoff = now - DEFAULT_WINDOW_SECONDS
+          @tracked.delete_if { |_, (reported_at, _)| reported_at <= cutoff }
+          return if @tracked.size <= MAX_TRACKED_KEYS
+
+          overflow = @tracked.size - MAX_TRACKED_KEYS
+          oldest = @tracked.sort_by { |_, (reported_at, _)| reported_at }.first(overflow)
+          oldest.each { |(key, _)| @tracked.delete(key) }
+        end
+      end
+    end
+  end
+  SlowSql = Api::SlowSql
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: tensorbuzz-api-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kasper Stöckel
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: tensorbuzz-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: Subscribes to sql.active_record notification events and reports statements
+  over a threshold as TensorBuzz bugs.
+email:
+- k@spernj.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/tensorbuzz/api/rails/version.rb
+- lib/tensorbuzz/api/slow_sql.rb
+homepage: https://github.com/kaspernj/tensorbuzz
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/kaspernj/tensorbuzz/tree/master/tensorbuzz-api-rails
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Active Record slow-SQL reporting for TensorBuzz.
+test_files: []