closeyourit-ruby 0.10.0 → 0.11.0

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,57 +57,42 @@ 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.
+      # Observe the completed attempt after ActiveJob has decided retry/discard.
       initializer "closeyourit.subscribe_active_job_performance" do
-        jobs = CloseYourIt::Subscribers::JobPerformance.new
-
-        ActiveSupport::Notifications.subscribe("perform_start.active_job") do |*args|
-          job = ActiveSupport::Notifications::Event.new(*args).payload[:job]
-          jobs.active_job_started(job) if job
-        end
-
-        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.
-          CloseYourIt.usage_registry.record("job", job.class.name) if job && CloseYourIt.enabled?
-          jobs.active_job_performed(job, event.duration) if job
-        end
+        CloseYourIt::Subscribers::JobPerformance.new.install
       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 +100,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