railwatch 0.1.0

data/lib/railwatch/configuration.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # All settings, each overridable by a RAILWATCH_* env var. Mirrors the shape of
+  # Laravel Nightwatch's config so the two products document the same knobs.
+  class Configuration
+    RECORD_TYPES = %i[queries cache_events mail broadcasts notifications outgoing_requests
+                      storage_ops view_renders logs transactions deprecations sessions].freeze
+
+    # Framework/vendor noise excluded by default so a fresh install isn't
+    # dominated by Rails' own housekeeping. Both lists are opt-in to disable
+    # via capture_default_vendor_commands / capture_default_vendor_cache_keys.
+    DEFAULT_VENDOR_COMMANDS = %w[
+      db:migrate db:schema:load db:schema:dump db:seed db:prepare
+      assets:precompile assets:clobber tmp:cache:clear log:clear
+    ].freeze
+
+    DEFAULT_VENDOR_CACHE_KEYS = [
+      /\Arack::attack/, /\Aflipper/, /\Asolid_cable/,
+      /\Aactive_storage/, /\Amigration_/, /\Aschema_cache/
+    ].freeze
+    # The same list as one anchored alternation: one regex run per cache
+    # event instead of six.
+    DEFAULT_VENDOR_CACHE_KEY = Regexp.union(DEFAULT_VENDOR_CACHE_KEYS).freeze
+
+    # Scratch roots. A deployed script ships in the image (under Rails.root,
+    # or wherever the ops scripts live); a `.rb` file under one of these was
+    # written by a human in a shell session, so `rails runner /tmp/probe.rb`
+    # counts as interactive. Deliberately narrow -- two literal temp roots,
+    # never "outside Rails.root" -- because a cron script going silent is the
+    # failure this must not cause.
+    DEFAULT_INTERACTIVE_RUNNER_PATHS = %w[/tmp/ /var/tmp/].freeze
+
+    # Requests that are part of keeping the app observable rather than the
+    # application itself. Monitoring these creates noise (/up) or wraps
+    # Railwatch's own browser transport in another request execution (the
+    # beacon). Apps can replace this list through RAILWATCH_IGNORED_REQUEST_PATHS
+    # or append exact paths/regexps in their initializer.
+    DEFAULT_IGNORED_REQUEST_PATHS = %w[/up /railwatch/beacon].freeze
+
+    # Exceptions that are routine 4xx plumbing rather than application bugs.
+    # The Rails-relevant subset of Sentry's own defaults
+    # (Sentry::Configuration::IGNORE_DEFAULT + PUMA_IGNORE_DEFAULT and
+    # Sentry::Rails::Configuration::IGNORE_DEFAULT), so a Sentry app migrating
+    # to Railwatch sees the same signal-to-noise out of the box.
+    DEFAULT_IGNORED_EXCEPTIONS = %w[
+      SignalException
+      ActionController::BadRequest
+      ActionController::InvalidAuthenticityToken
+      ActionController::RoutingError
+      ActionController::UnknownFormat
+      ActionController::UnknownHttpMethod
+      ActionDispatch::Http::MimeNegotiation::InvalidType
+      ActionDispatch::Http::Parameters::ParseError
+      ActiveRecord::RecordNotFound
+      Puma::HttpParserError
+      Puma::HttpParserError501
+      Rack::QueryParser::InvalidParameterError
+      Rack::QueryParser::ParameterTypeError
+    ].freeze
+
+    attr_accessor :enabled, :token, :ingest_url, :allow_http, :server, :environment,
+                  :sample, :log_level, :capture_request_payload,
+                  :capture_exception_source, :capture_exception_locals, :redact_headers, :redact_params,
+                  :buffer_size, :buffer_bytes, :execution_buffer_bytes, :batch_bytes,
+                  :backpressure,
+                  :flush_interval, :flush_threshold,
+                  :connect_timeout, :timeout, :shutdown_timeout,
+                  :slow_query_threshold_ms, :n_plus_one_threshold,
+                  :max_view_renders_per_execution, :ignored_cache_key_prefixes,
+                  :beacon_enabled, :beacon_rate_limit, :debug, :capture_default_vendor_commands,
+                  :capture_default_vendor_cache_keys, :on_unrecoverable,
+                  :capture_framework_events,
+                  :tail_sample_slow_ms, :failure_context, :propagate_traces, :trace_propagation_hosts,
+                  :health_interval, :capture_query_explain, :explain_threshold_ms,
+                  :capture_sql_values,
+                  :ignored_exceptions, :capture_rescued_exceptions,
+                  :profile_sample, :profile_slow_ms, :profile_interval_us, :profiler,
+                  :capture_job_arguments, :capture_job_retry_errors, :capture_response_body_on_error, :max_attachment_bytes,
+                  :track_sessions, :session_flush_interval, :session_timeout,
+                  :capture_console, :interactive_runner_paths, :ignored_request_paths
+
+    attr_reader :deploy, :deploy_source, :detect_deploy, :user_resolver, :beacon_user_resolver,
+                :fingerprint_resolver, :redactors, :rejectors, :before_ingest, :backpressure_high_water
+
+    def initialize
+      @enabled = env_bool("RAILWATCH_ENABLED", true)
+      @token = ENV["RAILWATCH_TOKEN"]
+      @ingest_url = ENV.fetch("RAILWATCH_INGEST_URL", "https://railwatch.rebulk.com")
+      @allow_http = env_bool("RAILWATCH_ALLOW_HTTP", false)
+      @project_root = defined?(Rails) ? Rails.root : Dir.pwd
+      @detect_deploy = env_bool("RAILWATCH_DETECT_DEPLOY", true)
+      detect_release
+      # Kamal names the container after the host plus a container id, so a
+      # bare hostname changes on every deploy and never matches the host the
+      # post-deploy hook registers as expected. KAMAL_HOST, which Kamal sets
+      # in every container it starts, is that host.
+      @server = ENV["RAILWATCH_SERVER"] || ENV["KAMAL_HOST"] || Socket.gethostname
+      @environment = nil # resolved lazily from Rails.env
+      @sample = {
+        requests: env_float("RAILWATCH_REQUEST_SAMPLE_RATE", 1.0),
+        jobs: env_float("RAILWATCH_JOB_SAMPLE_RATE", 1.0),
+        commands: env_float("RAILWATCH_COMMAND_SAMPLE_RATE", 1.0),
+        scheduled_tasks: env_float("RAILWATCH_SCHEDULED_TASK_SAMPLE_RATE", 1.0),
+        channels: env_float("RAILWATCH_CHANNEL_SAMPLE_RATE", 1.0),
+        exceptions: env_float("RAILWATCH_EXCEPTION_SAMPLE_RATE", 1.0)
+      }
+      self.ignore = RECORD_TYPES.select { |t| env_bool("RAILWATCH_IGNORE_#{t.to_s.upcase}", false) }
+      @log_level = (ENV["RAILWATCH_LOG_LEVEL"] || "info").to_sym
+      @capture_request_payload = env_bool("RAILWATCH_CAPTURE_REQUEST_PAYLOAD", false)
+      @capture_exception_source = env_bool("RAILWATCH_CAPTURE_EXCEPTION_SOURCE_CODE", true)
+      @capture_exception_locals = env_bool("RAILWATCH_CAPTURE_EXCEPTION_LOCALS", false)
+      @redact_headers = ENV.fetch("RAILWATCH_REDACT_HEADERS", "Authorization,Cookie,Set-Cookie,Proxy-Authorization,X-CSRF-Token,X-XSRF-TOKEN").split(",").map(&:strip)
+      @redact_params = ENV.fetch("RAILWATCH_REDACT_PARAMS", "password,password_confirmation,authenticity_token,_token").split(",").map(&:strip)
+      # At least Execution::MAX_RECORDS: finish_execution writes a kept
+      # execution's whole tree into this queue at once, and a queue smaller
+      # than the tree drops the tree's own oldest records -- the outgoing
+      # requests and first queries at the top of a long job.
+      @buffer_size = env_int("RAILWATCH_BUFFER_SIZE", 10_000)
+      # A record count does not bound memory: 10,000 records is a few
+      # megabytes of ordinary telemetry, or a gigabyte of captured
+      # attachments. These are the byte ceilings that do -- one execution's
+      # tree, the reporter queue, and one delivery.
+      @buffer_bytes = env_int("RAILWATCH_BUFFER_BYTES", 16 * 1024 * 1024)
+      @execution_buffer_bytes = env_int("RAILWATCH_EXECUTION_BUFFER_BYTES", 8 * 1024 * 1024)
+      @batch_bytes = env_int("RAILWATCH_BATCH_BYTES", 8 * 1024 * 1024)
+      @backpressure = env_bool("RAILWATCH_BACKPRESSURE", true)
+      self.backpressure_high_water = env_float("RAILWATCH_BACKPRESSURE_HIGH_WATER", 0.8)
+      @flush_interval = env_float("RAILWATCH_FLUSH_INTERVAL", 2.0)
+      @flush_threshold = env_int("RAILWATCH_FLUSH_THRESHOLD", 500)
+      @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)
+      @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
+      @ignored_cache_key_prefixes = []
+      @capture_default_vendor_commands = env_bool("RAILWATCH_CAPTURE_DEFAULT_VENDOR_COMMANDS", false)
+      @capture_default_vendor_cache_keys = env_bool("RAILWATCH_CAPTURE_DEFAULT_VENDOR_CACHE_KEYS", false)
+      @capture_framework_events = env_bool("RAILWATCH_CAPTURE_FRAMEWORK_EVENTS", false)
+      @on_unrecoverable = nil
+      @beacon_enabled = env_bool("RAILWATCH_BEACON", true)
+      # The beacon is unauthenticated and forces Railwatch.keep! for browser
+      # errors, so without a ceiling anyone can spend an app's event quota
+      # from a shell. Per client IP per minute; 0 turns the limit off, and a
+      # negative value is normalized to 0 rather than left to mean anything.
+      @beacon_rate_limit = [ env_int("RAILWATCH_BEACON_RATE_LIMIT", 120), 0 ].max
+      @debug = env_bool("RAILWATCH_DEBUG", false)
+      # Tail-based sampling: a head-sampled-out execution is still kept when
+      # it ran at least this long, raised, or Railwatch.keep! was called. nil = off.
+      @tail_sample_slow_ms = ENV["RAILWATCH_TAIL_SAMPLE_SLOW_MS"]&.then { |v| Float(v) }
+      # Failure context: how many of a head-sampled-out execution's child
+      # records to hold in a ring so an unhandled exception can ship what led
+      # up to it. 0 = off, which is the default -- a sampled-out execution
+      # then builds and buffers nothing, exactly as before.
+      @failure_context = env_int("RAILWATCH_FAILURE_CONTEXT", 0)
+      @propagate_traces = env_bool("RAILWATCH_PROPAGATE_TRACES", true)
+      @trace_propagation_hosts = ENV["RAILWATCH_TRACE_PROPAGATION_HOSTS"]&.split(",")&.map(&:strip)
+      @health_interval = env_float("RAILWATCH_HEALTH_INTERVAL", 15.0)
+      @capture_query_explain = env_bool("RAILWATCH_CAPTURE_QUERY_EXPLAIN", false)
+      @explain_threshold_ms = env_float("RAILWATCH_EXPLAIN_THRESHOLD_MS", 100.0)
+      # SQL literals routinely carry email addresses, tokens, and other
+      # customer data. Query records therefore carry only the normalized
+      # statement shape unless an application deliberately opts in.
+      @capture_sql_values = env_bool("RAILWATCH_CAPTURE_SQL_VALUES", false)
+      @ignored_exceptions = ENV["RAILWATCH_IGNORED_EXCEPTIONS"]&.split(",")&.map(&:strip) || DEFAULT_IGNORED_EXCEPTIONS.dup
+      @capture_rescued_exceptions = env_bool("RAILWATCH_CAPTURE_RESCUED_EXCEPTIONS", true)
+      # Sampling profiler: profile this fraction of sampled-in requests/jobs
+      # (0 = off), and always profile ones slower than profile_slow_ms once
+      # tail sampling keeps them. Uses vernier when available, else stackprof.
+      @profile_sample = env_float("RAILWATCH_PROFILE_SAMPLE_RATE", 0.0)
+      @profile_slow_ms = ENV["RAILWATCH_PROFILE_SLOW_MS"]&.then { |v| Float(v) }
+      @profile_interval_us = env_int("RAILWATCH_PROFILE_INTERVAL_US", 1_000)
+      @profiler = ENV["RAILWATCH_PROFILER"]&.to_sym
+      @capture_job_arguments = env_bool("RAILWATCH_CAPTURE_JOB_ARGUMENTS", false)
+      @capture_job_retry_errors = env_bool("RAILWATCH_CAPTURE_JOB_RETRY_ERRORS", false)
+      @capture_response_body_on_error = env_bool("RAILWATCH_CAPTURE_RESPONSE_BODY_ON_ERROR", false)
+      @max_attachment_bytes = env_int("RAILWATCH_MAX_ATTACHMENT_BYTES", 1_048_576)
+      # Release health: one `session` record per browser tab (the beacon
+      # client) and per authenticated/cookied server session (Railwatch::Sessions).
+      @track_sessions = env_bool("RAILWATCH_TRACK_SESSIONS", true)
+      @session_flush_interval = env_float("RAILWATCH_SESSION_FLUSH_INTERVAL", 60.0)
+      @session_timeout = env_float("RAILWATCH_SESSION_TIMEOUT", 1800.0)
+      # Interactive sessions: a `bin/rails console` process captures nothing
+      # at all, and a typed/piped `bin/rails runner` ships its command record
+      # but not its exception. A deployed script always reports.
+      @capture_console = env_bool("RAILWATCH_CAPTURE_CONSOLE", false)
+      @interactive_runner_paths = ENV["RAILWATCH_INTERACTIVE_RUNNER_PATHS"]&.split(",")&.map(&:strip) ||
+        DEFAULT_INTERACTIVE_RUNNER_PATHS.dup
+      @ignored_request_paths = ENV["RAILWATCH_IGNORED_REQUEST_PATHS"]&.split(",")&.map(&:strip)&.reject(&:empty?) ||
+        DEFAULT_IGNORED_REQUEST_PATHS.dup
+      @user_resolver = nil
+      @beacon_user_resolver = nil
+      @fingerprint_resolver = nil
+      @redactors = Hash.new { |h, k| h[k] = [] }
+      @rejectors = Hash.new { |h, k| h[k] = [] }
+      @before_ingest = []
+    end
+
+    def deploy=(value)
+      @deploy = value
+      @deploy_source = "config/initializers/railwatch.rb"
+      @deploy_overridden = true
+    end
+
+    def detect_deploy=(value)
+      @detect_deploy = value
+      detect_release unless @deploy_overridden
+    end
+
+    def user(&block)
+      @user_resolver = block
+    end
+
+    # Railwatch.beacon_user { |request| ... }: who is behind a browser beacon.
+    # The beacon is handled by the gem's own engine controller, outside the
+    # app's ApplicationController, so an app that authenticates in a
+    # before_action (a signed session cookie looked up per request, say)
+    # has not run it by the time the beacon is read. Return the user object
+    # the `user` block understands, or nil. Not needed when the app sets
+    # Current.user in middleware or uses Warden, which the default resolution
+    # already reads.
+    def beacon_user(&block)
+      @beacon_user_resolver = block
+    end
+
+    # Railwatch.fingerprint { |error, default| ... }: one block, called with
+    # the error and the parts Railwatch would have hashed. Passing no block
+    # clears it.
+    def fingerprint(&block)
+      @fingerprint_resolver = block
+    end
+
+    def enabled?
+      @enabled && token.present?
+    end
+
+    def ingest_url_allowed?
+      uri = URI.parse(ingest_url.to_s)
+      return true if uri.scheme == "https"
+      return false unless uri.scheme == "http"
+
+      allow_http || %w[localhost 127.0.0.1 ::1 [::1]].include?(uri.host)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    attr_reader :ignore
+
+    # Stored alongside a frozen Set so the per-record ignored? check is a
+    # single Set lookup instead of an Array#include? scan on every record.
+    def ignore=(value)
+      unknown = Array(value) - RECORD_TYPES
+      raise ArgumentError, "unknown record type(s): #{unknown.join(', ')}" if unknown.any?
+
+      @ignore = value
+      @ignored_set = Set.new(value).freeze
+    end
+
+    def ignored?(type)
+      @ignored_set.include?(type)
+    end
+
+    def sample_rate(kind)
+      @sample.fetch(kind, 1.0).to_f.clamp(0.0, 1.0)
+    end
+
+    def backpressure_high_water=(value)
+      fraction = Float(value, exception: false)
+      @backpressure_high_water = if fraction&.finite? && fraction.positive? && fraction <= 1.0
+        fraction
+      else
+        0.8
+      end
+    end
+
+    def environment_name
+      @environment || (defined?(Rails) ? Rails.env.to_s : "production")
+    end
+
+    # Matches Railwatch.reject_cache_keys entries and DEFAULT_VENDOR_CACHE_KEYS
+    # against a cache key. A Regexp is used as-is. A String starting with "^"
+    # or containing another regex metacharacter is compiled as a Regexp; a
+    # String ending in "*" matches as a prefix; any other String must match
+    # exactly (so "session:" no longer accidentally matches "usersession:").
+    CACHE_KEY_METACHARS = /[.?+()|{}\[\]]/
+    def self.match_cache_key?(pattern, key)
+      case pattern
+      when Regexp
+        pattern.match?(key)
+      when String
+        if pattern.start_with?("^") || CACHE_KEY_METACHARS.match?(pattern)
+          Regexp.new(pattern).match?(key)
+        elsif pattern.end_with?("*")
+          key.start_with?(pattern[0..-2])
+        else
+          key == pattern
+        end
+      else
+        false
+      end
+    end
+
+    private
+
+    def detect_release
+      @deploy_source = nil
+      if @detect_deploy
+        @deploy = ReleaseDetector.detect(project_root: @project_root) { |source| @deploy_source = source }
+        return
+      end
+
+      @deploy_source = %w[RAILWATCH_DEPLOY KAMAL_VERSION].find { |key| ENV[key].to_s.strip != "" }
+      value = @deploy_source ? ENV[@deploy_source].to_s.strip : ""
+      @deploy = ReleaseDetector::SHA.match?(value) ? value[0, 12] : value
+      @deploy = nil if @deploy.empty?
+    end
+
+    def env_bool(key, default)
+      return default unless ENV.key?(key)
+      %w[1 true yes on].include?(ENV[key].to_s.downcase)
+    end
+
+    # String#to_f/#to_i turn a typo into 0.0/0 -- a zero buffer, timeout, or
+    # interval -- so parse strictly and keep the documented default instead.
+    def env_float(key, default)
+      ENV.key?(key) ? Float(ENV[key], exception: false) || default : default
+    end
+
+    def env_int(key, default)
+      ENV.key?(key) ? Integer(ENV[key], 10, exception: false) || default : default
+    end
+  end
+end

data/lib/railwatch/console.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # `bin/rails console` is a person at a prompt, not a server. sentry-rails
+  # never hooked the console at all, and that was right: an engineer poking at
+  # production types typos, and a typo is not an issue. Railwatch subscribes to
+  # far more than Sentry did (every query, every log line, `Rails.error`), and
+  # it starts reporter/health/session threads at boot -- none of which belong
+  # behind an IRB prompt someone leaves open for an hour.
+  #
+  # So a console process goes quiet: nothing is captured, no thread is
+  # started, and no `process`/`health` record is sent. Opt back in with
+  # `config.capture_console = true` (or RAILWATCH_CAPTURE_CONSOLE=1) for the
+  # rare "trace what I'm about to do in here" session.
+  #
+  # A `rails runner` script is NOT this: it is a deployed execution and keeps
+  # reporting -- see Railwatch::Patches::RunnerCommand for where that line is.
+  module Console
+    module_function
+
+    # railties defines Rails::Console when it loads the console command, which
+    # happens before the application boots, so this is already true by the
+    # time the engine's initializers run.
+    def detected?
+      !!defined?(::Rails::Console)
+    end
+
+    def quiet?
+      detected? && !Railwatch.config.capture_console
+    end
+
+    # Idempotent, and the whole of quiet mode: every record path, the
+    # subscriber install, the after_initialize `process` record, and the
+    # reporter/health/sessions threads are already gated on Railwatch.enabled?.
+    # Returns whether this call is what silenced the process.
+    def silence!
+      return false unless quiet? && Railwatch.config.enabled
+
+      Railwatch.debug { "console detected -- capturing nothing in this process (set config.capture_console = true, or RAILWATCH_CAPTURE_CONSOLE=1, to capture a console session)" }
+      Railwatch.config.enabled = false
+      # No-ops unless a console got here after boot (the railtie's `console`
+      # block) with the threads already running.
+      Health.stop!
+      Sessions.stop!
+      true
+    end
+  end
+end

data/lib/railwatch/context.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Bridges Rails' three context stores. Anything an app already sets on
+  # ActiveSupport::ExecutionContext, Rails.error, or Rails.event shows up on
+  # Railwatch records; Railwatch.context writes to all three.
+  module Context
+    LIMIT = 65_536
+    EMPTY_JSON = "{}".freeze
+    # Present, and true, on a context that did not fit in LIMIT bytes.
+    TRUNCATION_KEY = "_railwatch_truncated"
+    TRUNCATION_MARKER = "[TRUNCATED]"
+
+    module_function
+
+    def set(**attrs)
+      ActiveSupport::ExecutionContext.set(**attrs)
+      Rails.error.set_context(**attrs) if defined?(Rails) && Rails.respond_to?(:error)
+      Rails.event.set_context(**attrs) if defined?(Rails) && Rails.respond_to?(:event)
+      # An explicit tenant is bound to the running execution here rather than
+      # read back out of ActiveSupport::ExecutionContext on demand: reading it
+      # there means ExecutionContext.to_h, which dups the whole store, and
+      # current_tenant is called once per record from Execution#envelope.
+      # Binding it also requalifies the records already buffered for this
+      # execution (Execution#tenant=).
+      tenant = attrs[:tenant]
+      Current.execution&.tenant = tenant.to_s if tenant
+      attrs
+    end
+
+    def current
+      ctx = {}
+      ctx.merge!(ActiveSupport::ExecutionContext.to_h.except(:controller, :job))
+      ctx.merge!(Rails.event.context) if defined?(Rails) && Rails.respond_to?(:event) && Rails.event.respond_to?(:context)
+      ctx
+    rescue StandardError
+      {}
+    end
+
+    def serialized
+      ctx = current
+      return EMPTY_JSON if ctx.empty?
+
+      serialize(ctx)
+    rescue StandardError
+      EMPTY_JSON
+    end
+
+    # Context is application data -- an app that puts an API token or a
+    # password in it should get the same treatment request params get, rather
+    # than having it written verbatim onto every record built while it is set.
+    def serialize(context)
+      filtered = Railwatch.redactor.params(context)
+      json = JSON.generate(filtered)
+      json.bytesize > LIMIT ? truncate(filtered) : json
+    end
+
+    # An oversized context used to be byteslice'd, which cut the JSON
+    # mid-string or mid-object: the platform could not parse it, so the whole
+    # context was lost rather than most of it. Rebuild a smaller context
+    # instead. Whole values are kept while they fit, an oversized String is
+    # cut and marked, anything that still does not fit is dropped, and
+    # `_railwatch_truncated` says it happened. The result is always valid JSON.
+    def truncate(filtered)
+      out = { TRUNCATION_KEY => true }
+      budget = LIMIT - JSON.generate(out).bytesize
+      filtered.each do |key, value|
+        next if key.to_s == TRUNCATION_KEY
+
+        cost = pair_bytes(key, value)
+        if cost > budget && value.is_a?(String)
+          value = truncated_string(value, budget - (cost - JSON.generate(value).bytesize)) or next
+          cost = pair_bytes(key, value)
+        end
+        next if cost > budget
+
+        budget -= cost
+        out[key] = value
+      end
+      JSON.generate(out)
+    end
+
+    # What this pair costs inside a larger object: the encoded `{"k":v}` less
+    # its two braces, plus the comma that separates it from the pair before.
+    def pair_bytes(key, value)
+      JSON.generate(key.to_s => value).bytesize - 1
+    end
+
+    # `room` is a floor rather than a fit: JSON escaping can expand one
+    # character into six bytes, so the caller re-measures the pair and drops
+    # it if the escaped result is still too large.
+    def truncated_string(value, room)
+      keep = room - TRUNCATION_MARKER.bytesize - 2
+      return nil if keep <= 0
+
+      "#{value.byteslice(0, keep).to_s.scrub("")}#{TRUNCATION_MARKER}"
+    end
+
+    def current_tenant
+      exe = Current.execution
+      return exe.tenant if exe&.tenant
+
+      if defined?(::TenantRecord) && ::TenantRecord.respond_to?(:current_tenant)
+        ::TenantRecord.current_tenant&.to_s
+      elsif defined?(::ActiveRecord::Tenanted) && ::ActiveRecord::Base.respond_to?(:current_tenant)
+        ::ActiveRecord::Base.current_tenant&.to_s
+      end
+    rescue StandardError
+      nil
+    end
+  end
+end
+
+module Railwatch
+  module Context
+    def self.serialized_with(extra)
+      ctx = current.merge(extra || {})
+      return EMPTY_JSON if ctx.empty?
+
+      serialize(ctx)
+    rescue StandardError
+      EMPTY_JSON
+    end
+  end
+end

data/lib/railwatch/controller_helpers.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Adds `railwatch_sample` to controllers (route-level sampling, like
+  # Nightwatch's Sample middleware) and captures the Inertia component name
+  # when the app renders through inertia_rails.
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # railwatch_sample 0.1, only: :index
+      def railwatch_sample(rate, **options)
+        before_action(**options) { Railwatch.sample(rate) }
+      end
+
+      def railwatch_never_sample(**options)
+        before_action(**options) { Railwatch.dont_sample }
+      end
+    end
+  end
+end

data/lib/railwatch/current.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Thread- or fiber-local pointer to the running Execution. Uses the same
+  # isolation level as Rails (config.active_support.isolation_level) so Solid
+  # Queue fiber workers and Puma threads both work.
+  module Current
+    KEY = :railwatch_execution
+
+    module_function
+
+    def execution
+      ActiveSupport::IsolatedExecutionState[KEY]
+    end
+
+    def execution=(value)
+      ActiveSupport::IsolatedExecutionState[KEY] = value
+    end
+
+    def with(execution)
+      previous = self.execution
+      self.execution = execution
+      yield execution
+    ensure
+      self.execution = previous
+    end
+
+    def clear
+      ActiveSupport::IsolatedExecutionState.delete(KEY)
+    end
+  end
+end