closeyourit-ruby 0.9.4 → 0.10.2

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

data/lib/closeyourit/rails/request_context.rb

@@ -5,16 +5,16 @@ require_relative "../trace_context"
 
 module CloseYourIt
   module Rails
-    # Rack middleware: popola lo Scope con il contesto HTTP della richiesta (method/url/header)
-    # così l'evento d'errore catturato a valle sa "in quale pagina" è capitato. Deve avvolgere
-    # `CaptureExceptions` (insert_before) per essere già popolato quando l'eccezione risale.
-    # Rack puro (legge `env`, nessuna dipendenza da Rails) → testabile in isolamento.
+    # Rack middleware: populates the Scope with the request's HTTP context (method/url/headers)
+    # so the error event captured downstream knows "on which page" it happened. It must wrap
+    # `CaptureExceptions` (insert_before) to be already populated when the exception bubbles up.
+    # Pure Rack (reads `env`, no Rails dependency) → testable in isolation.
     class RequestContext
-      # Header con prefisso non-HTTP_ in env Rack.
+      # Headers without the HTTP_ prefix in the Rack env.
       RAW_HEADERS = %w[CONTENT_TYPE CONTENT_LENGTH].freeze
 
-      # Cookie di correlazione scritto dal browser SDK (session replay): id opaco della
-      # sessione di replay, trasportato da ogni richiesta same-origin.
+      # Correlation cookie written by the browser SDK (session replay): opaque id of the
+      # replay session, carried by every same-origin request.
       REPLAY_COOKIE = "cyi_replay"
 
       def initialize(app)
@@ -23,19 +23,19 @@ module CloseYourIt
 
       def call(env)
         if enabled?
-          # Contesto di trace W3C (solo con propagazione opt-in): adottato dall'header entrante o generato.
+          # W3C trace context (only with opt-in propagation): adopted from the incoming header or generated.
           context = trace_context_for(env)
           CloseYourIt::Scope.current.trace_context = context
-          # trace_id sempre (correlazione log↔errori), anche con capture_request OFF. Con un trace context
-          # W3C il trace_id degli eventi È il trace-id W3C → l'errore/metrica si allinea alla traccia
-          # distribuita propagata a valle (mapping trace_id, CYRB-15); altrimenti request_id come prima.
+          # trace_id always (log↔error correlation), even with capture_request OFF. With a W3C trace
+          # context the events' trace_id IS the W3C trace-id → the error/metric lines up with the
+          # distributed trace propagated downstream (trace_id mapping, CYRB-15); otherwise request_id as before.
           CloseYourIt::Scope.current.trace_id = context ? context.trace_id : trace_id_for(env)
-          # Correlazione errore server ↔ session replay: l'id dal cookie finisce sullo scope
-          # → contexts.replay.replay_id dell'evento (stesso punto del percorso JS).
+          # Server error ↔ session replay correlation: the id from the cookie lands on the scope
+          # → the event's contexts.replay.replay_id (same spot as the JS path).
           CloseYourIt::Scope.current.replay_session_id = replay_session_id_for(env)
           if CloseYourIt.configuration.capture_request
             CloseYourIt::Scope.current.request = build_request(env)
-            # Riferimento all'env per l'estrazione LAZY del body (request.data) a evento costruito.
+            # Reference to the env for LAZY body extraction (request.data) once the event is built.
             CloseYourIt::Scope.current.rack_env = env
           end
         end
@@ -52,10 +52,10 @@ module CloseYourIt
         false
       end
 
-      # Contesto di trace W3C della richiesta, SOLO con la propagazione opt-in attiva (altrimenti nil →
-      # comportamento storico invariato). Adotta un traceparent/tracestate entrante valido (correlazione
-      # distribuita), altrimenti genera un root: così anche i servizi che ORIGINANO traffico partono con
-      # un trace-id W3C propagabile a valle. Un traceparent malformato è ignorato → si genera un root.
+      # W3C trace context of the request, ONLY with opt-in propagation on (otherwise nil → historical
+      # behavior unchanged). Adopts a valid incoming traceparent/tracestate (distributed correlation),
+      # otherwise generates a root: so services that ORIGINATE traffic also start with a W3C trace-id
+      # that can be propagated downstream. A malformed traceparent is ignored → a root is generated.
       def trace_context_for(env)
         return nil unless CloseYourIt.configuration.propagate_trace_context
 
@@ -63,28 +63,28 @@ module CloseYourIt
           CloseYourIt::TraceContext.generate
       end
 
-      # Riusa il request id di Rails/Rack se presente (stessa correlazione dei log applicativi),
-      # altrimenti ne genera uno.
+      # Reuses the Rails/Rack request id when present (same correlation as the application logs),
+      # otherwise generates one.
       def trace_id_for(env)
         env["action_dispatch.request_id"] ||
           env["HTTP_X_REQUEST_ID"].to_s.split(",").first&.strip.then { |id| id&.empty? ? nil : id } ||
           SecureRandom.uuid
       end
 
-      # Estrae `cyi_replay` dal cookie della richiesta (nil se assente). Rack puro.
+      # Extracts `cyi_replay` from the request cookie (nil if absent). Pure Rack.
       def replay_session_id_for(env)
         cookie = env["HTTP_COOKIE"]
         return nil if cookie.nil? || cookie.empty?
 
-        # `rack/utils` caricato lazy: il middleware gira solo dentro un'app Rack (dove Rack c'è di
-        # sicuro), così `require "closeyourit-ruby"` non forza Rack in app non-web (CLI/worker) e la
-        # gemma resta installabile senza dichiarare `rack` tra le dipendenze (CYRB-13).
+        # `rack/utils` loaded lazily: the middleware runs only inside a Rack app (where Rack is surely
+        # present), so `require "closeyourit-ruby"` does not force Rack on non-web apps (CLI/workers)
+        # and the gem stays installable without declaring `rack` as a dependency (CYRB-13).
         require "rack/utils"
         Rack::Utils.parse_cookies_header(cookie)[REPLAY_COOKIE].to_s.then { |id| id.empty? ? nil : id }
       end
 
-      # Forma `request` Sentry. URL senza query string; header solo dall'allowlist (mai
-      # Authorization/Cookie). query_string + IP solo con send_pii (opt-in).
+      # Sentry `request` shape. URL without query string; headers only from the allowlist (never
+      # Authorization/Cookie). query_string + IP only with send_pii (opt-in).
       def build_request(env)
         request = {
           "method"  => env["REQUEST_METHOD"],
@@ -101,7 +101,7 @@ module CloseYourIt
 
         request
       rescue StandardError
-        # La telemetria non deve mai disturbare la richiesta ospite.
+        # Telemetry must never disturb the host request.
         nil
       end
 

data/lib/closeyourit/scope.rb

@@ -4,29 +4,29 @@ require_relative "breadcrumb_buffer"
 require_relative "performance/request_profile"
 
 module CloseYourIt
-  # Contesto per-richiesta (o per-job) isolato per execution-context (Fiber storage):
-  # user/tags/extra/contexts/request. Letto da ErrorEvent#to_h sul thread chiamante (sincrono)
-  # → il worker di invio non lo vede mai e lo scope non cola tra richieste.
+  # Per-request (or per-job) context isolated per execution context (Fiber storage):
+  # user/tags/extra/contexts/request. Read by ErrorEvent#to_h on the calling thread (synchronous)
+  # → the send worker never sees it and the scope does not leak between requests.
   class Scope
     STORAGE_KEY = :__closeyourit_scope
 
     class << self
-      # Scope dell'execution-context corrente. Usa `ActiveSupport::IsolatedExecutionState` quando
-      # presente (rispetta isolation_level: thread su Puma, fiber su Falcon), altrimenti
-      # `Thread.current` (thread-local puro, NON ereditato dai thread figli → niente bleed).
+      # Scope of the current execution context. Uses `ActiveSupport::IsolatedExecutionState` when
+      # present (honors isolation_level: thread on Puma, fiber on Falcon), otherwise
+      # `Thread.current` (pure thread-local, NOT inherited by child threads → no bleed).
       def current
         store[STORAGE_KEY] ||= new
       end
 
-      # Re-installa uno scope salvato in precedenza. Serve a `after_discard` (ActiveJob 7.1+) per
-      # riprendere lo scope arricchito durante il `perform` — tag/contesti/breadcrumb, incluse le query —
-      # dopo che il reset di fine `perform` l'ha sganciato dallo storage (CYRB-19). Simmetrico a `reset!`.
+      # Reinstalls a previously saved scope. Used by `after_discard` (ActiveJob 7.1+) to get back the
+      # scope enriched during `perform` — tags/contexts/breadcrumbs, queries included — after the
+      # end-of-`perform` reset detached it from storage (CYRB-19). Symmetric to `reset!`.
       def current=(scope)
         store[STORAGE_KEY] = scope
       end
 
-      # Azzera lo scope corrente — chiamato in `ensure` da middleware e job (su Puma il
-      # thread è riusato: senza reset lo scope colerebbe nella richiesta successiva).
+      # Clears the current scope — called in `ensure` by middleware and jobs (on Puma the
+      # thread is reused: without a reset the scope would leak into the next request).
       def reset!
         store[STORAGE_KEY] = nil
       end
@@ -73,8 +73,8 @@ module CloseYourIt
       @breadcrumbs.add(breadcrumb)
     end
 
-    # Profilo di performance per-richiesta (query + HTTP esterne). Lazy: creato al primo accesso,
-    # azzerato da #clear a fine richiesta. Il verdetto lo calcola Subscribers::RequestPerformance.
+    # Per-request performance profile (queries + external HTTP). Lazy: created on first access,
+    # reset by #clear at the end of the request. Subscribers::RequestPerformance computes the verdict.
     def performance_profile
       @performance_profile ||= Performance::RequestProfile.new
     end
@@ -88,17 +88,17 @@ module CloseYourIt
       @rack_env    = nil
       @trace_id    = nil
       @replay_session_id = nil
-      # Contesto di trace W3C della richiesta (CloseYourIt::TraceContext): popolato solo con la
-      # propagazione opt-in attiva, consumato dal patch Net::HTTP per gli header d'uscita.
+      # W3C trace context of the request (CloseYourIt::TraceContext): populated only when opt-in
+      # propagation is on, consumed by the Net::HTTP patch for outgoing headers.
       @trace_context = nil
       @breadcrumbs = BreadcrumbBuffer.new(CloseYourIt.configuration.max_breadcrumbs)
       @performance_profile = nil
     end
 
-    # Sottoinsieme non vuoto in forma evento Sentry (user/tags/extra/contexts/request),
-    # fuso nel payload da ErrorEvent#to_h. tags/extra/contexts passano dallo Scrubber (denylist
-    # ricorsiva per chiave): il backend NON li ri-scruba (Errors::Ingest::Normalize li conserva
-    # verbatim), quindi questa è l'unica rete di sicurezza contro le chiavi sensibili lì — R2.
+    # Non-empty subset in Sentry event shape (user/tags/extra/contexts/request), merged into the
+    # payload by ErrorEvent#to_h. tags/extra/contexts go through the Scrubber (recursive denylist by
+    # key): the backend does NOT scrub them again (Errors::Ingest::Normalize keeps them verbatim),
+    # so this is the only safety net against sensitive keys there — R2.
     def to_event_hash
       {
         "user"        => serialize_user,
@@ -112,26 +112,26 @@ module CloseYourIt
 
     private
 
-    # contexts utente + `replay.replay_id` (session replay) quando presente sullo scope: il
-    # backend legge contexts.replay.replay_id per legare l'errore server al video (stesso punto
-    # del percorso JS). replay/replay_id non sono chiavi sensibili → sopravvivono allo Scrubber.
+    # User contexts + `replay.replay_id` (session replay) when present on the scope: the backend
+    # reads contexts.replay.replay_id to link the server error to the video (same spot as the JS
+    # path). replay/replay_id are not sensitive keys → they survive the Scrubber.
     def contexts_payload
       merged = @contexts.dup
       merged["replay"] = { "replay_id" => @replay_session_id } if @replay_session_id
       scrub(presence(merged))
     end
 
-    # Redige i valori delle chiavi sensibili preservando la struttura (es. contexts.runtime resta
-    # intatto, solo i valori sotto chiavi sensibili diventano [FILTERED]). Riusa lo Scrubber della
-    # configurazione, lo stesso percorso di breadcrumb.data e degli attributi di log.
+    # Redacts the values of sensitive keys preserving the structure (e.g. contexts.runtime stays
+    # intact, only values under sensitive keys become [FILTERED]). Reuses the configuration's
+    # Scrubber, the same path as breadcrumb.data and log attributes.
     def scrub(hash)
       return hash if hash.nil?
 
       Scrubber.new(CloseYourIt.configuration).filter_params(hash)
     end
 
-    # Request context + body params (`request.data`) estratti LAZY qui — cioè solo quando un
-    # evento viene davvero costruito, mai sul percorso felice della richiesta.
+    # Request context + body params (`request.data`) extracted LAZILY here — i.e. only when an
+    # event is actually built, never on the request's happy path.
     def request_payload
       return nil if @request.nil?
 
@@ -148,8 +148,8 @@ module CloseYourIt
       nil
     end
 
-    # `user.id` sempre; email/ip_address/username solo con `send_pii` (il backend li strippa
-    # comunque — difesa in profondità).
+    # `user.id` always; email/ip_address/username only with `send_pii` (the backend strips them
+    # anyway — defense in depth).
     def serialize_user
       return nil if @user.empty?
       return @user if CloseYourIt.configuration.send_pii