closeyourit-ruby 0.10.0 → 0.10.2

data/lib/closeyourit/rails/active_job_extension.rb

@@ -2,29 +2,30 @@
 
 module CloseYourIt
   module Rails
-    # Incluso in ActiveJob::Base (via railtie `on_load(:active_job)`): cattura gli errori dei job
-    # (oggi persi) con il contesto del job. La logica vive in `.monitor`/`.report_discarded` per essere
-    # testabile senza ActiveSupport/ActiveJob.
+    # Included in ActiveJob::Base (via the railtie's `on_load(:active_job)`): captures job errors
+    # (otherwise lost) with the job context. The logic lives in `.monitor`/`.report_discarded` so it
+    # is testable without ActiveSupport/ActiveJob.
     #
-    # CYRB-19: `around_perform` gira DENTRO `perform_now`, mentre `retry_on`/`discard_on` (rescue_from)
-    # sono valutati FUORI, dopo i callback. Catturare nell'around_perform significa quindi segnalare
-    # OGNI tentativo — anche quelli che verranno ritentati con successo — perché il reporter vede
-    # l'errore prima che il retry possa zittirlo, e ogni tentativo solleva una nuova istanza (la
-    # deduplica interna, per-istanza, non interviene). Su ActiveJob 7.1+ deleghiamo la segnalazione ad
-    # `after_discard`, che Rails invoca al fallimento definitivo (retry_on esauriti o eccezione non
-    # gestita), mai sui tentativi che `retry_on` ritenta → una sola occorrenza per job.
+    # CYRB-19: `around_perform` runs INSIDE `perform_now`, while `retry_on`/`discard_on` (rescue_from)
+    # are evaluated OUTSIDE, after the callbacks. Capturing in around_perform therefore means reporting
+    # EVERY attempt — even those that will be retried successfully — because the reporter sees the
+    # error before the retry can silence it, and every attempt raises a new instance (the internal,
+    # per-instance dedup does not kick in). On ActiveJob 7.1+ we delegate reporting to `after_discard`,
+    # which Rails calls on final failure (retry_on exhausted or unhandled exception), never on the
+    # attempts `retry_on` retries → a single occurrence per job.
     #
-    # Limiti noti (per costruzione di ActiveJob, non del client):
-    # - `after_discard` NON scatta per gli errori intercettati da un `rescue_from` custom: sono gestiti
-    #   dall'app, quindi non li segnaliamo più come "non gestiti" (prima lo facevamo, impropriamente).
-    # - I retry a livello di ADAPTER (es. Sidekiq) SENZA `retry_on` risollevano l'errore non gestito:
-    #   `after_discard` scatta a ogni esecuzione, quindi lì la de-duplicazione per tentativo non si
-    #   applica (comportamento invariato rispetto a prima).
-    # Sulle versioni prive di `after_discard` restiamo al fallback legacy (cattura nell'around_perform).
+    # Known limits (by ActiveJob's design, not the client's):
+    # - `after_discard` does NOT fire for errors caught by a custom `rescue_from`: they are handled by
+    #   the app, so we no longer report them as "unhandled" (we used to, improperly).
+    # - ADAPTER-level retries (e.g. Sidekiq) WITHOUT `retry_on` re-raise the unhandled error:
+    #   `after_discard` fires on every execution, so per-attempt dedup does not apply there
+    #   (behavior unchanged from before).
+    # On versions without `after_discard` we keep the legacy fallback (capture in around_perform).
     module ActiveJobExtension
-      # Scope arricchito durante il `perform` tramandato ad `after_discard`. Legato all'ISTANZA del job
-      # (ogni retry ne crea una nuova, deserializzata) → vive esattamente quanto serve, niente bleed tra
-      # job o thread; il reset di fine `perform` lo sgancia solo dallo storage, non muta l'oggetto.
+      # Scope enriched during `perform`, handed over to `after_discard`. Bound to the job INSTANCE
+      # (every retry creates a new, deserialized one) → it lives exactly as long as needed, no bleed
+      # between jobs or threads; the end-of-`perform` reset only detaches it from storage, it does not
+      # mutate the object.
       STASHED_SCOPE_IVAR = :@__closeyourit_stashed_scope
 
       def self.included(base)
@@ -39,9 +40,10 @@ module CloseYourIt
         end
       end
 
-      # Esegue il job arricchendo lo scope con tag/context; resetta lo scope a fine job (no bleed tra
-      # job sullo stesso thread). Su ActiveJob 7.1+ NON cattura l'errore (lo fa `after_discard` solo al
-      # fallimento definitivo): qui tramanda lo scope al job e ri-solleva. Sul fallback legacy cattura.
+      # Runs the job enriching the scope with tags/context; resets the scope at the end of the job (no
+      # bleed between jobs on the same thread). On ActiveJob 7.1+ it does NOT capture the error
+      # (`after_discard` does, only on final failure): here it hands the scope to the job and re-raises.
+      # On the legacy fallback it captures.
       def self.monitor(job)
         return yield unless CloseYourIt.configuration.report_active_job_errors
 
@@ -60,10 +62,10 @@ module CloseYourIt
         end
       end
 
-      # Aggancio `after_discard` (ActiveJob 7.1+): il job è definitivamente fallito, quindi segnaliamo
-      # l'errore UNA sola volta (handled:false). Riprendiamo lo scope arricchito durante il `perform`
-      # (tramandato da `monitor`) così il report conserva breadcrumb/tag/contesti raccolti nel job;
-      # `apply_job_scope` rinfresca i campi standard con `executions` finale senza perdere i custom.
+      # `after_discard` hook (ActiveJob 7.1+): the job has failed for good, so we report the error ONLY
+      # once (handled:false). We restore the scope enriched during `perform` (handed over by `monitor`)
+      # so the report keeps the breadcrumbs/tags/contexts collected in the job; `apply_job_scope`
+      # refreshes the standard fields with the final `executions` without losing the custom ones.
       def self.report_discarded(job, exception)
         return unless CloseYourIt.configuration.report_active_job_errors
 
@@ -78,8 +80,8 @@ module CloseYourIt
         end
       end
 
-      # true quando ActiveJob espone `after_discard` (7.1+): la segnalazione è delegata lì, così
-      # `monitor` non cattura i tentativi intermedi. false → fallback legacy (cattura nell'around_perform).
+      # true when ActiveJob exposes `after_discard` (7.1+): reporting is delegated there, so `monitor`
+      # does not capture intermediate attempts. false → legacy fallback (capture in around_perform).
       def self.report_on_discard?(job)
         job.class.respond_to?(:after_discard)
       end
@@ -93,8 +95,8 @@ module CloseYourIt
         context["executions"] = job.executions if job.respond_to?(:executions)
         CloseYourIt.set_context("active_job", context) unless context.empty?
 
-        # Un trace_id stabile per esecuzione (job_id è unico per run ActiveJob): log ed errore dello
-        # stesso job condividono il trace_id → correlazione log↔errore anche fuori dal ciclo richiesta.
+        # A stable trace_id per execution (job_id is unique per ActiveJob run): logs and error of the
+        # same job share the trace_id → log↔error correlation outside the request cycle too.
         CloseYourIt::Scope.current.trace_id = job.job_id if job.respond_to?(:job_id)
       end
     end

data/lib/closeyourit/rails/capture_exceptions.rb

@@ -2,9 +2,9 @@
 
 module CloseYourIt
   module Rails
-    # Rack middleware: cattura le eccezioni non gestite, le invia a CloseYourIt
-    # e le **ri-solleva** (l'app continua a gestirle come prima). Rack puro, nessuna
-    # dipendenza da Rails → testabile in isolamento.
+    # Rack middleware: captures unhandled exceptions, sends them to CloseYourIt
+    # and **re-raises** them (the app keeps handling them as before). Pure Rack, no
+    # Rails dependency → testable in isolation.
     class CaptureExceptions
       def initialize(app)
         @app = app

data/lib/closeyourit/rails/error_subscriber.rb

@@ -2,13 +2,13 @@
 
 module CloseYourIt
   module Rails
-    # Sottoscrittore di `ActiveSupport::ErrorReporter` (Rails 7+): cattura gli errori HANDLED
-    # riportati via `Rails.error.report`/`Rails.error.handle`. Gli unhandled passano già dal
-    # middleware Rack → la dedup (ivar sull'istanza) evita il doppio invio.
+    # `ActiveSupport::ErrorReporter` subscriber (Rails 7+): captures HANDLED errors reported via
+    # `Rails.error.report`/`Rails.error.handle`. Unhandled ones already go through the Rack
+    # middleware → dedup (ivar on the instance) avoids double sending.
     class ErrorSubscriber
       SEVERITY_TO_LEVEL = { error: "error", warning: "warning", info: "info" }.freeze
 
-      # Sorgenti interne rumorose da non inoltrare (evita loop/duplicati).
+      # Noisy internal sources not to forward (avoids loops/duplicates).
       IGNORED_SOURCES = %w[closeyourit].freeze
 
       def report(error, handled:, severity:, context:, source: nil)

data/lib/closeyourit/rails/log_broadcast.rb

@@ -4,26 +4,26 @@ require "logger"
 
 module CloseYourIt
   module Rails
-    # Sink Logger-compatibile agganciato a Rails.logger (broadcast opt-in, `config.capture_rails_logs`):
-    # ogni log dell'app ≥ soglia (`capture_rails_logs_min_level`, default :warn) viene re-inoltrato a
-    # CloseYourIt.log → ingest /logs. Sotto soglia: no-op (nessun invio). Il default è conservativo
-    # (:warn) per non inondare lo stream col rumore info del framework (CYRB-7). Non scrive su alcun
-    # device (inoltra soltanto).
+    # Logger-compatible sink attached to Rails.logger (opt-in broadcast, `config.capture_rails_logs`):
+    # every app log ≥ threshold (`capture_rails_logs_min_level`, default :warn) is forwarded to
+    # CloseYourIt.log → ingest /logs. Below threshold: no-op (nothing sent). The default is
+    # conservative (:warn) so the stream is not flooded with framework info noise (CYRB-7). It writes
+    # to no device (it only forwards).
     class LogBroadcast < ::Logger
       SEVERITY_LEVELS = { 0 => "debug", 1 => "info", 2 => "warning", 3 => "error", 4 => "fatal", 5 => "fatal" }.freeze
       LEVEL_BY_SYMBOL = { debug: 0, info: 1, warn: 2, warning: 2, error: 3, fatal: 4 }.freeze
 
       def initialize(min_level = :warn)
-        super(nil) # nessun device: inoltra soltanto
+        super(nil) # no device: it only forwards
         self.level = LEVEL_BY_SYMBOL.fetch(min_level.to_sym, 2)
       end
 
-      # Sovrascrive il punto unico di ::Logger: filtra per soglia e per esclusioni, poi re-inoltra a
-      # CloseYourIt.log. Il secondo filtro esiste perché la soglia da sola non distingue il rumore: una
-      # `ActionController::RoutingError` da favicon mancante è un `logger.error` come un altro, e senza
-      # controllare il TESTO rientrava dal canale log dopo essere stata esclusa da quello degli errori
-      # (CYRB-17). Il gating vive qui e non in `CloseYourIt.log`: quel metodo serve anche il dev che
-      # scrive un log di proposito, e le sue righe non si silenziano.
+      # Overrides ::Logger's single entry point: filters by threshold and by exclusions, then forwards
+      # to CloseYourIt.log. The second filter exists because the threshold alone cannot tell noise
+      # apart: an `ActionController::RoutingError` from a missing favicon is a `logger.error` like any
+      # other, and without checking the TEXT it came back through the log channel after being excluded
+      # from the errors one (CYRB-17). Gating lives here and not in `CloseYourIt.log`: that method also
+      # serves the dev who writes a log on purpose, and their lines are never silenced.
       def add(severity, message = nil, progname = nil)
         severity ||= ::Logger::UNKNOWN
         return true if severity < level

data/lib/closeyourit/rails/net_http_patch.rb

@@ -5,15 +5,15 @@ require_relative "../scope"
 
 module CloseYourIt
   module Rails
-    # Prepended a Net::HTTP: cronometra ogni chiamata esterna e la spinge nel RequestProfile dello
-    # Scope, così la finestra della richiesta può rilevare le HTTP esterne lente. Trasparente
-    # (restituisce la risposta originale) e difensivo (no-op se la telemetria è off; mai solleva per
-    # colpa del profiling). Esclude le chiamate verso l'endpoint CloseYourIt stesso (niente loop).
+    # Prepended to Net::HTTP: times every external call and pushes it into the Scope's RequestProfile,
+    # so the request window can detect slow external HTTP. Transparent (returns the original response)
+    # and defensive (no-op when telemetry is off; never raises because of profiling). Excludes calls to
+    # the CloseYourIt endpoint itself (no loop).
     module NetHTTPPatch
       def request(req, body = nil, &block)
         config = CloseYourIt.configuration
-        # Propagazione W3C: indipendente dal profiling (ha il suo opt-in), va fatta PRIMA del round-trip
-        # perché aggiunge header alla richiesta in uscita.
+        # W3C propagation: independent of profiling (it has its own opt-in), must happen BEFORE the
+        # round-trip because it adds headers to the outgoing request.
         inject_trace_context(config, req)
         return super unless config.detect_performance_issues && config.capture_external_http
 
@@ -28,12 +28,12 @@ module CloseYourIt
 
       private
 
-      # Gestisce gli header di trace W3C sulla richiesta in uscita (solo con la propagazione opt-in ON).
-      # Verso una destinazione autorizzata inietta traceparent/tracestate; verso qualsiasi altra li
-      # RIMUOVE. La rimozione è la difesa contro il leak su redirect cross-host: se lo stesso oggetto
-      # request viene riusato per seguire un redirect verso un host non in allowlist, gli header della
-      # chiamata precedente non devono sopravvivere ("host esterni non ricevono header interni" — CYRB-15).
-      # baggage non viene mai né letto né emesso. Difensivo: mai solleva per colpa della propagazione.
+      # Handles the W3C trace headers on the outgoing request (only with opt-in propagation ON).
+      # To an allowed destination it injects traceparent/tracestate; to any other it REMOVES them.
+      # Removal is the defense against leaks on cross-host redirects: if the same request object is
+      # reused to follow a redirect to a host not in the allowlist, the previous call's headers must not
+      # survive ("external hosts do not receive internal headers" — CYRB-15).
+      # baggage is never read nor emitted. Defensive: never raises because of propagation.
       def inject_trace_context(config, req)
         return unless config.propagate_trace_context
 
@@ -47,9 +47,9 @@ module CloseYourIt
         nil
       end
 
-      # Il trace context da consegnare a QUESTA destinazione, o nil se non va propagato nulla: host
-      # assente, endpoint CloseYourIt stesso (niente auto-propagazione), destinazione fuori allowlist,
-      # o scope privo di contesto.
+      # The trace context to deliver to THIS destination, or nil if nothing must be propagated: missing
+      # host, the CloseYourIt endpoint itself (no self-propagation), destination outside the allowlist,
+      # or a scope without context.
       def deliverable_context(config)
         host = address
         return nil if host.nil? || own_endpoint?(config, host)
@@ -58,16 +58,16 @@ module CloseYourIt
         CloseYourIt::Scope.current.trace_context
       end
 
-      # La destinazione è autorizzata a ricevere il trace context? String = host esatto (case-insensitive),
-      # Regexp = pattern (sottodomini/famiglie). Lista vuota → sempre false (nessuna destinazione).
+      # Is the destination allowed to receive the trace context? String = exact host (case-insensitive),
+      # Regexp = pattern (subdomains/families). Empty list → always false (no destination).
       def destination_allowed?(config, host)
         config.trace_propagation_allowlist.any? do |pattern|
           pattern.is_a?(Regexp) ? pattern.match?(host) : pattern.to_s.casecmp?(host)
         end
       end
 
-      # Rimuove gli header di trace W3C che una chiamata precedente sullo stesso oggetto request possa
-      # aver lasciato. Solo i nostri header, mai altro; no-op se il request non li supporta.
+      # Removes the W3C trace headers a previous call on the same request object may have left.
+      # Only our headers, nothing else; no-op if the request does not support them.
       def strip_trace_headers(req)
         return unless req.respond_to?(:delete)
 
@@ -83,7 +83,7 @@ module CloseYourIt
           host: host, path: templatize_path(req), duration_ms: duration_ms
         )
       rescue StandardError
-        # Il profiling non deve mai disturbare la chiamata ospite.
+        # Profiling must never disturb the host call.
         nil
       end
 
@@ -96,8 +96,8 @@ module CloseYourIt
         false
       end
 
-      # Path senza query string, con uuid e run di ≥3 cifre → placeholder (stessa rotta = stessa
-      # signature). La soglia ≥3 cifre preserva le versioni API tipo "/v1" e templatizza gli id reali
+      # Path without query string, with uuids and runs of ≥3 digits → placeholders (same route = same
+      # signature). The ≥3 digit threshold keeps API versions like "/v1" and templatizes real ids
       # ("/v1/charges/ch_12345" → "/v1/charges/ch_<n>", "/users/123" → "/users/<n>").
       def templatize_path(req)
         path = req.respond_to?(:path) ? req.path.to_s : ""

data/lib/closeyourit/rails/query_source.rb

@@ -2,9 +2,9 @@
 
 module CloseYourIt
   module Rails
-    # Call-site applicativo di una query lenta (privacy-safe → sempre inviato): primo frame della
-    # backtrace ripulito da Rails.backtrace_cleaner (rimuove gem/framework, tiene il codice app),
-    # senza il suffisso ":in '...'". Es. "app/models/order.rb:42".
+    # Application call site of a slow query (privacy-safe → always sent): first backtrace frame
+    # cleaned by Rails.backtrace_cleaner (removes gems/framework, keeps app code), without the
+    # ":in '...'" suffix. E.g. "app/models/order.rb:42".
     module QuerySource
       def self.from_caller(backtrace = caller)
         frame = ::Rails.backtrace_cleaner.clean(backtrace).first

data/lib/closeyourit/rails/railtie.rb

@@ -15,13 +15,13 @@ require_relative "../sidekiq/job_metrics_middleware"
 
 module CloseYourIt
   module Rails
-    # Aggancia il client a Rails: Rack middleware di cattura eccezioni +
-    # subscriber `sql.active_record` per le query lente.
+    # Hooks the client into Rails: exception-capturing Rack middleware +
+    # `sql.active_record` subscriber for slow queries.
     class Railtie < ::Rails::Railtie
       initializer "closeyourit.use_rack_middleware" do |app|
         app.config.middleware.use CloseYourIt::Rails::CaptureExceptions
-        # RequestContext deve AVVOLGERE CaptureExceptions: lo scope dev'essere già popolato
-        # quando l'eccezione risale a CaptureExceptions.
+        # RequestContext must WRAP CaptureExceptions: the scope must already be populated
+        # when the exception bubbles up to CaptureExceptions.
         app.config.middleware.insert_before(
           CloseYourIt::Rails::CaptureExceptions,
           CloseYourIt::Rails::RequestContext
@@ -33,43 +33,22 @@ module CloseYourIt
 
         ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
           event = ActiveSupport::Notifications::Event.new(*args)
-          subscriber.record(
-            name: event.payload[:name],
-            duration_ms: event.duration,
-            sql: event.payload[:sql],
-            cached: event.payload.fetch(:cached, false),
-            connection: event.payload[:connection],
-            binds: event.payload[:binds],
-            type_casted_binds: event.payload[:type_casted_binds],
-            source: CloseYourIt::Rails::QuerySource.from_caller
-          )
-          subscriber.breadcrumb(
-            name: event.payload[:name],
-            sql: event.payload[:sql],
-            duration_ms: event.duration,
-            cached: event.payload.fetch(:cached, false)
-          )
-          # Accumula la query nel profilo per-richiesta (detection N+1 a fine richiesta).
-          subscriber.profile(
-            name: event.payload[:name],
-            sql: event.payload[:sql],
-            duration_ms: event.duration,
-            cached: event.payload.fetch(:cached, false),
-            source: CloseYourIt::Rails::QuerySource.from_caller
-          )
+          # Slow query, breadcrumb and per-request profile (N+1 detection). The call site is lazy:
+          # a backtrace for every query was the SDK's biggest cost on the host thread.
+          subscriber.notify(event.payload, event.duration, -> { CloseYourIt::Rails::QuerySource.from_caller })
         end
       end
 
-      # A fine richiesta: trasforma il profilo accumulato in verdetti performance_issue (N+1, slow
-      # request, HTTP esterne lente). Il subscriber è no-op se detect_performance_issues è OFF.
+      # At the end of the request: turns the collected profile into performance_issue verdicts (N+1,
+      # slow request, slow external HTTP). The subscriber is a no-op when detect_performance_issues is OFF.
       initializer "closeyourit.subscribe_request_performance" do
         perf = CloseYourIt::Subscribers::RequestPerformance.new
 
         ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
           event = ActiveSupport::Notifications::Event.new(*args)
           payload = event.payload
-          # CYSK-29 — telemetria d'uso: la rotta è `Controller#action`, MAI l'URL. Il registro fa
-          # una lookup e un increment; il gate usage_enabled sta dentro #record.
+          # CYSK-29 — usage telemetry: the route is `Controller#action`, NEVER the URL. The registry does
+          # one lookup and one increment; the usage_enabled gate lives inside #record.
           CloseYourIt.usage_registry.record("route", "#{payload[:controller]}##{payload[:action]}") if CloseYourIt.enabled?
           perf.record(
             route: "#{payload[:controller]}##{payload[:action]}",
@@ -78,24 +57,25 @@ module CloseYourIt
         end
       end
 
-      # Strumenta Net::HTTP: rileva le chiamate esterne lente (solo con detect_performance_issues) e
-      # propaga il trace context W3C (solo con propagate_trace_context). Prepend incondizionato — i due
-      # opt-in sono valutati per-chiamata nel patch; con entrambi OFF è di fatto no-op (chiama super).
+      # Instruments Net::HTTP: detects slow external calls (only with detect_performance_issues) and
+      # propagates the W3C trace context (only with propagate_trace_context). Unconditional prepend —
+      # the two opt-ins are evaluated per call in the patch; with both OFF it is in effect a no-op (calls super).
       initializer "closeyourit.instrument_net_http" do
         require "net/http"
         ::Net::HTTP.prepend(CloseYourIt::Rails::NetHTTPPatch) unless ::Net::HTTP.ancestors.include?(CloseYourIt::Rails::NetHTTPPatch)
       end
 
-      # Cattura gli errori di ActiveJob/Solid Queue (around_perform).
+      # Captures ActiveJob/Solid Queue errors (around_perform).
       initializer "closeyourit.active_job" do
         ActiveSupport.on_load(:active_job) do
           include CloseYourIt::Rails::ActiveJobExtension
         end
       end
 
-      # Misura durata e attesa in coda dei job ActiveJob via notifiche ActiveSupport: `perform_start`
-      # dà l'attesa (now - enqueued_at) appena il job parte, `perform` dà la durata dell'esecuzione a
-      # fine job. Oltre soglia → metriche slow_job / job_queue_latency. No-op se monitor_jobs è OFF.
+      # Measures duration and queue wait of ActiveJob jobs via ActiveSupport notifications:
+      # `perform_start` gives the wait (now - enqueued_at) as soon as the job starts, `perform` gives
+      # the execution duration at the end. Beyond threshold → slow_job / job_queue_latency metrics.
+      # No-op when monitor_jobs is OFF.
       initializer "closeyourit.subscribe_active_job_performance" do
         jobs = CloseYourIt::Subscribers::JobPerformance.new
 
@@ -107,28 +87,28 @@ module CloseYourIt
         ActiveSupport::Notifications.subscribe("perform.active_job") do |*args|
           event = ActiveSupport::Notifications::Event.new(*args)
           job = event.payload[:job]
-          # CYSK-29 — anche i job dichiarano di essere girati: kind `job`, simbolo = la classe.
+          # CYSK-29 — jobs also declare they ran: kind `job`, symbol = the class.
           CloseYourIt.usage_registry.record("job", job.class.name) if job && CloseYourIt.enabled?
           jobs.active_job_performed(job, event.duration) if job
         end
       end
 
-      # Cattura gli errori HANDLED riportati via Rails.error.report (Rails 7+).
+      # Captures HANDLED errors reported via Rails.error.report (Rails 7+).
       initializer "closeyourit.error_reporter" do
         if ::Rails.respond_to?(:error) && ::Rails.error.respond_to?(:subscribe)
           ::Rails.error.subscribe(CloseYourIt::Rails::ErrorSubscriber.new)
         end
       end
 
-      # Broadcast opt-in di Rails.logger → CloseYourIt.log (config.capture_rails_logs, default OFF).
-      # Spedisce solo i log dell'app ≥ capture_rails_logs_min_level: soglia DEDICATA (default :warn),
-      # distinta da logs_min_level, così il broadcast non inonda lo stream col rumore info del framework
-      # (Started GET, Rendered, ... — una riga per richiesta ad alto traffico, CYRB-7). Richiede
+      # Opt-in Rails.logger → CloseYourIt.log broadcast (config.capture_rails_logs, default OFF).
+      # Sends only app logs ≥ capture_rails_logs_min_level: a DEDICATED threshold (default :warn),
+      # separate from logs_min_level, so the broadcast does not flood the stream with framework info
+      # noise (Started GET, Rendered, ... — one line per request under high traffic, CYRB-7). Requires
       # BroadcastLogger (Rails 7.1+).
-      # `after: :load_config_initializers`: config.capture_rails_logs è impostato in
-      # config/initializers/closeyourit.rb (CloseYourIt.init), che gira DOPO gli initializer dei
-      # railtie. Senza questo `after:` il check leggerebbe il default (false) e il broadcast non
-      # verrebbe mai agganciato → i log dell'app non arriverebbero a CloseYourIt.
+      # `after: :load_config_initializers`: config.capture_rails_logs is set in
+      # config/initializers/closeyourit.rb (CloseYourIt.init), which runs AFTER the railtie
+      # initializers. Without this `after:` the check would read the default (false) and the broadcast
+      # would never be attached → the app logs would never reach CloseYourIt.
       initializer "closeyourit.capture_rails_logs", after: :load_config_initializers do
         config = CloseYourIt.configuration
         if config.capture_rails_logs && ::Rails.logger.respond_to?(:broadcast_to)
@@ -136,9 +116,9 @@ module CloseYourIt
         end
       end
 
-      # Cattura gli errori dei job Sidekiq + misura durata/attesa via server middleware (solo se
-      # Sidekiq è presente). Il middleware è no-op effettivo se monitor_jobs è OFF (la decisione vive
-      # in JobPerformance#record).
+      # Captures Sidekiq job errors + measures duration/wait via server middleware (only when Sidekiq
+      # is present). The middleware is effectively a no-op when monitor_jobs is OFF (the decision
+      # lives in JobPerformance#record).
       initializer "closeyourit.sidekiq" do
         if defined?(::Sidekiq) && ::Sidekiq.respond_to?(:configure_server)
           ::Sidekiq.configure_server do |sidekiq_config|

data/lib/closeyourit/rails/request_body.rb

@@ -6,11 +6,11 @@ require_relative "../scrubber"
 
 module CloseYourIt
   module Rails
-    # Estrae i params del body della richiesta (`request.data`) al momento dell'EVENTO — mai
-    # eagerly a ogni richiesta (zero overhead sul percorso felice). Preferisce i params già
-    # parsati da Rails/Rack presenti in env; ripiega sulla rilettura di rack.input (con rewind)
-    # solo per JSON/form ≤ MAX_BODY_BYTES. Output sanitizzato (upload → "[FILE: …]", oggetti →
-    # "[OBJECT: …]", stringhe troncate) e scrubbato con la stessa denylist del resto del client.
+    # Extracts the request body params (`request.data`) at EVENT time — never eagerly on every
+    # request (zero overhead on the happy path). Prefers the params already parsed by Rails/Rack in
+    # env; falls back to re-reading rack.input (with rewind) only for JSON/form ≤ MAX_BODY_BYTES.
+    # Sanitized output (uploads → "[FILE: …]", objects → "[OBJECT: …]", truncated strings) and
+    # scrubbed with the same denylist as the rest of the client.
     module RequestBody
       MAX_BODY_BYTES = 65_536
       MAX_DEPTH = 8
@@ -31,7 +31,7 @@ module CloseYourIt
 
         private
 
-        # Params già parsati a monte (ActionDispatch o Rack): nessuna rilettura del body.
+        # Params already parsed upstream (ActionDispatch or Rack): no body re-read.
         def parsed_params(env)
           env["action_dispatch.request.request_parameters"] || env["rack.request.form_hash"]
         end
@@ -45,7 +45,7 @@ module CloseYourIt
             value = JSON.parse(raw)
             value.is_a?(Hash) ? value : { "_json" => value }
           when FORM_TYPE
-            # Fallback flat (stdlib): il percorso reale con nesting passa dai params già parsati.
+            # Flat fallback (stdlib): the real path with nesting goes through the already parsed params.
             URI.decode_www_form(raw).to_h
           end
         rescue JSON::ParserError, ArgumentError