closeyourit-ruby 0.10.0 → 0.10.2

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

data/lib/closeyourit/scrubber.rb

@@ -1,73 +1,72 @@
 # frozen_string_literal: true
 
 module CloseYourIt
-  # Rimozione PII dai payload: filtro chiavi sensibili, normalizzazione SQL, scrub messaggi.
-  # Privacy-by-default — vedi PDR §9.
+  # PII removal from payloads: sensitive key filter, SQL normalization, message scrubbing.
+  # Privacy-by-default — see PDR §9.
   class Scrubber
     FILTERED = "[FILTERED]"
 
-    # Token di chiavi sempre redatti (match per sottostringa, normalizzato). Allineato al regex
-    # SENSITIVE_KEY di backend e client Dart (parità client-side) — vedi
-    # Errors/Logs::Ingest::Normalize::SENSITIVE_KEY. Copre credenziali/segreti e PII:
+    # Key tokens that are always redacted (substring match, normalized). Aligned with the
+    # SENSITIVE_KEY regex of the backend and the Dart client (client-side parity) — see
+    # Errors/Logs::Ingest::Normalize::SENSITIVE_KEY. Covers credentials/secrets and PII:
     #   /pass|secret|token|api[_-]?key|apikey|authorization|cookie|csrf|credit|card|cvv|ssn|iban|
     #    email|phone|telephone|mobile|dob|birth|passport|bearer|session|pin|pan/i
-    # `pass` copre password/passwd/pass_code/passkey/passphrase; `cookie` copre set-cookie;
-    # `credit`+`card` coprono credit_card; `phone` copre telephone/smartphone; `birth` copre
-    # date_of_birth. Match per sottostringa → privilegia l'over-redaction (privacy-by-default):
-    # p.es. `company_name` (contiene `pan`) o `shipping` (contiene `pin`) vengono redatti — è
-    # accettabile, meglio redigere troppo che perdere PII.
-    # CYRB-3: la lista ometteva email/phone/dob → i bind delle query lente li leakavano nel pannello.
+    # `pass` covers password/passwd/pass_code/passkey/passphrase; `cookie` covers set-cookie;
+    # `credit`+`card` cover credit_card; `phone` covers telephone/smartphone; `birth` covers
+    # date_of_birth. Substring match → favors over-redaction (privacy-by-default):
+    # e.g. `company_name` (contains `pan`) or `shipping` (contains `pin`) get redacted — that is
+    # acceptable, better to redact too much than to leak PII.
+    # CYRB-3: the list omitted email/phone/dob → slow query binds leaked them into the panel.
     DENYLIST = %w[
       pass secret token api_key apikey authorization
       cookie csrf credit card cvv ssn iban
       email phone telephone mobile dob birth passport bearer session pin pan
     ].freeze
 
-    # CYRB-23 — redazione INTEGRATA delle credenziali di autenticazione nel testo libero.
-    # `filter_params`/`filter_value` coprono gli header STRUTTURATI (la chiave `authorization` è in
-    # DENYLIST); un `Authorization: Bearer <token>` incollato dentro `exception.message` o dentro la
-    # riga di un log è testo, non una chiave, e prima di questo ticket partiva in chiaro perché
-    # `scrub_message` applicava solo i pattern configurati dall'utente (default `[]`).
+    # CYRB-23 — BUILT-IN redaction of authentication credentials in free text.
+    # `filter_params`/`filter_value` cover STRUCTURED headers (the `authorization` key is in
+    # DENYLIST); an `Authorization: Bearer <token>` pasted into `exception.message` or into a log
+    # line is text, not a key, and before this ticket it was sent in clear because `scrub_message`
+    # applied only the user-configured patterns (default `[]`).
     #
-    # Forma del testo redatto (decisa qui una volta per tutti gli SDK — gemelli CYDA-26/CYJS-38/
-    # CYPY-15): chiave e schema restano leggibili, sparisce SOLO la credenziale →
-    # `Authorization: Bearer [FILTERED]`. Il messaggio resta diagnosticamente utile (si vede CHE
-    # c'era un header e con quale schema) senza trasportare il segreto.
+    # Shape of the redacted text (decided here once for all SDKs — twins CYDA-26/CYJS-38/
+    # CYPY-15): key and scheme stay readable, ONLY the credential disappears →
+    # `Authorization: Bearer [FILTERED]`. The message stays useful for diagnosis (you see THAT
+    # there was a header and with which scheme) without carrying the secret.
     AUTH_SCHEME = /(?i:Bearer|Basic|Token)/
 
-    # `token68` (RFC 7235) con padding `=` finale: la forma di una credenziale reale. Minimo 4
-    # caratteri — un `Basic` di credenziali brevi è corto (`dTpw` = `u:p`); a filtrare la prosa
-    # pensa NOT_PROSE, non la lunghezza.
+    # `token68` (RFC 7235) with trailing `=` padding: the shape of a real credential. Minimum 4
+    # characters — a `Basic` with short credentials is short (`dTpw` = `u:p`); filtering out prose
+    # is NOT_PROSE's job, not the length's.
     CREDENTIAL_TOKEN = %r{[A-Za-z0-9\-._~+/]{4,}={0,2}}
 
-    # Guardia anti-falso-positivo per lo schema NUDO: quello che segue NON è una credenziale se ha
-    # la forma di una parola scritta da un umano, cioè sole lettere in UNA di tre forme —
-    # `minuscole`, `Capitalizzata`, `MAIUSCOLE` — e più corta di 20 caratteri. Salva "the bearer of
-    # bad news", "invalid bearer credentials", "Basic HTTP authentication", "Bearer Token expired".
-    # Tutto il resto è credenziale: entropia (cifre, `_`, `-`, `.`), maiuscole interne miste
-    # (`dTpw`, base64) o lunghezza ≥ 20 (nessuna parola è così lunga, mentre un token opaco di sole
-    # minuscole sì).
-    # Trade-off accettato: un CamelCase subito dopo lo schema (`Token MyAppName`) viene redatto.
+    # False-positive guard for the BARE scheme: what follows is NOT a credential if it has the shape
+    # of a human-written word, i.e. letters only in ONE of three forms — `lowercase`, `Capitalized`,
+    # `UPPERCASE` — and shorter than 20 characters. It spares "the bearer of bad news",
+    # "invalid bearer credentials", "Basic HTTP authentication", "Bearer Token expired".
+    # Everything else is a credential: entropy (digits, `_`, `-`, `.`), mixed inner capitals
+    # (`dTpw`, base64) or length ≥ 20 (no word is that long, while an opaque lowercase-only token is).
+    # Accepted trade-off: a CamelCase word right after the scheme (`Token MyAppName`) gets redacted.
     PROSE_WORD = /(?:[a-z]{1,19}|[A-Z][a-z]{0,18}|[A-Z]{1,19})/
     NOT_PROSE = %r{(?!\[FILTERED\])(?!#{PROSE_WORD}(?![A-Za-z0-9\-._~+/=]))}
 
-    # Valore di un header incollato nel testo: sequenza di pezzi non delimitatori, dove una stringa
-    # fra virgolette conta come UN pezzo. NON `\S+`, che si mangerebbe la `)` di
-    # "(Authorization: Bearer <token>)"; ma nemmeno una classe secca, che si fermerebbe alla prima
-    # virgoletta lasciando in chiaro il segreto di `Token token="<token>"` (sintassi RFC 7235 e
-    # `authenticate_with_http_token` di Rails) e di un frammento JSON incollato nel messaggio.
+    # Value of a header pasted into text: a sequence of non-delimiter pieces, where a quoted string
+    # counts as ONE piece. NOT `\S+`, which would eat the `)` of "(Authorization: Bearer <token>)";
+    # but not a plain class either, which would stop at the first quote leaving in clear the secret
+    # of `Token token="<token>"` (RFC 7235 syntax and Rails' `authenticate_with_http_token`) and of a
+    # JSON fragment pasted into the message.
     QUOTED = /"[^"\n]*"|'[^'\n]*'/
     HEADER_VALUE = /(?:#{QUOTED}|[^\s,;)\]}"'<>])+/
 
-    # `Authorization:`/`authorization=` (anche `Proxy-Authorization`, anche `authorization_header`)
-    # seguito dal valore: qui la chiave è esplicita, quindi si redige senza euristica di prosa —
-    # over-redaction voluta, coerente con la DENYLIST. `[ \t]` e non `\s`: mai oltre il newline.
-    # Il lookahead copre lo schema OPZIONALE: senza, su un testo già redatto il motore farebbe
-    # backtracking sul ramo "senza schema" e redigerebbe la parola `Bearer` stessa (non idempotente).
+    # `Authorization:`/`authorization=` (also `Proxy-Authorization`, also `authorization_header`)
+    # followed by the value: here the key is explicit, so it is redacted without prose heuristics —
+    # intentional over-redaction, consistent with the DENYLIST. `[ \t]` not `\s`: never past newline.
+    # The lookahead covers the OPTIONAL scheme: without it, on already redacted text the engine would
+    # backtrack onto the "no scheme" branch and redact the word `Bearer` itself (not idempotent).
     AUTH_HEADER = /((?i:(?:proxy[_-]?)?authorization)[\w-]*["']?[ \t]*[:=][ \t]*)(?!(?:#{AUTH_SCHEME}[ \t]+)?\[FILTERED\])(#{AUTH_SCHEME}[ \t]+)?#{HEADER_VALUE}/
 
-    # Schema nudo (`Bearer <token>` senza il nome dell'header) seguito da qualcosa che ha la forma
-    # di una credenziale: qui la guardia di prosa serve, la parola "bearer" ricorre nei messaggi.
+    # Bare scheme (`Bearer <token>` without the header name) followed by something shaped like a
+    # credential: here the prose guard is needed, the word "bearer" shows up in messages.
     AUTH_CREDENTIAL = /(\b#{AUTH_SCHEME}[ \t]+)#{NOT_PROSE}#{CREDENTIAL_TOKEN}/
 
     STRING_LITERAL = /'(?:[^']|'')*'/
@@ -77,7 +76,7 @@ module CloseYourIt
       @configuration = configuration
     end
 
-    # Filtra ricorsivamente Hash/Array sostituendo i valori delle chiavi sensibili.
+    # Recursively filters Hash/Array replacing the values of sensitive keys.
     def filter_params(value)
       case value
       when Hash
@@ -91,15 +90,15 @@ module CloseYourIt
       end
     end
 
-    # Maschera i literal (stringa/numerici) nello SQL, preservando la struttura.
+    # Masks the (string/numeric) literals in SQL, preserving the structure.
     def obfuscate_sql(sql)
       return sql if sql.nil? || !@configuration.obfuscate_sql
 
       sql.to_s.gsub(STRING_LITERAL, "?").gsub(NUMERIC_LITERAL, "?")
     end
 
-    # Regola integrata (schemi di autenticazione) PRIMA dei pattern utente: le due protezioni si
-    # sommano, la prima non è disattivabile — privacy-by-default (CYRB-23).
+    # Built-in rule (authentication schemes) BEFORE the user patterns: the two protections add up,
+    # the first cannot be disabled — privacy-by-default (CYRB-23).
     def scrub_message(message)
       return message if message.nil?
 
@@ -112,7 +111,7 @@ module CloseYourIt
       end
     end
 
-    # Valore di un singolo bind/argomento: redatto se il nome (colonna/parametro) è sensibile.
+    # Value of a single bind/argument: redacted when the name (column/parameter) is sensitive.
     def filter_value(key, value)
       sensitive_key?(key) ? FILTERED : value
     end

data/lib/closeyourit/sidekiq/error_handler.rb

@@ -2,8 +2,8 @@
 
 module CloseYourIt
   module Sidekiq
-    # Error handler Sidekiq (registrato dal railtie solo se Sidekiq è presente). Sidekiq invoca
-    # `call(exception, context, config)` e NON ri-solleva → qui catturiamo e basta.
+    # Sidekiq error handler (registered by the railtie only when Sidekiq is present). Sidekiq calls
+    # `call(exception, context, config)` and does NOT re-raise → here we just capture.
     class ErrorHandler
       def call(exception, context, _config = nil)
         apply_job_scope(context)

data/lib/closeyourit/sidekiq/job_metrics_middleware.rb

@@ -4,13 +4,12 @@ require_relative "../subscribers/job_performance"
 
 module CloseYourIt
   module Sidekiq
-    # Server middleware Sidekiq (registrato dal railtie solo se Sidekiq è presente) che misura la durata
-    # di esecuzione e l'attesa in coda del job, poi delega a Subscribers::JobPerformance l'emissione
-    # delle metriche oltre soglia. Non altera il job: cronometra attorno allo `yield` e ri-solleva
-    # qualunque errore invariato (la cattura degli errori è dell'ErrorHandler). La misurazione avviene
-    # nell'`ensure`, così è presa anche per i job che sollevano; la telemetria è isolata (un errore nel
-    # nostro codice non disturba mai il job ospite). No-op effettivo se `monitor_jobs` è OFF (la
-    # decisione vive in #record).
+    # Sidekiq server middleware (registered by the railtie only when Sidekiq is present) that measures
+    # the job's execution duration and queue wait, then delegates emitting over-threshold metrics to
+    # Subscribers::JobPerformance. It does not alter the job: it times around `yield` and re-raises
+    # any error unchanged (error capture belongs to the ErrorHandler). Measurement happens in `ensure`,
+    # so it is taken for jobs that raise too; telemetry is isolated (an error in our code never
+    # disturbs the host job). Effectively a no-op when `monitor_jobs` is OFF (the decision lives in #record).
     class JobMetricsMiddleware
       def initialize(subscriber = nil)
         @subscriber = subscriber
@@ -18,8 +17,8 @@ module CloseYourIt
 
       def call(_worker, job, queue)
         started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        # L'attesa in coda si conosce all'INIZIO (now - enqueued_at); Sidekiq mette enqueued_at come
-        # epoch in secondi. Calcolata prima dello yield per non includere la durata del job.
+        # The queue wait is known at the START (now - enqueued_at); Sidekiq stores enqueued_at as epoch
+        # seconds. Computed before the yield so it does not include the job duration.
         latency = Subscribers::JobPerformance.latency_ms(job["enqueued_at"], now: Time.now.utc)
         yield
       ensure
@@ -47,8 +46,8 @@ module CloseYourIt
         @subscriber ||= Subscribers::JobPerformance.new
       end
 
-      # Numero di esecuzione 1-based. Sidekiq NON imposta `retry_count` al primo run (nil), lo porta a 0
-      # al primo retry, 1 al secondo, ... → attempt = retry_count + 2 quando presente, 1 al primo run.
+      # 1-based execution number. Sidekiq does NOT set `retry_count` on the first run (nil), sets it to 0
+      # on the first retry, 1 on the second, ... → attempt = retry_count + 2 when present, 1 on the first run.
       def attempt(job)
         count = job["retry_count"]
         count.nil? ? 1 : count + 2

data/lib/closeyourit/stats.rb

@@ -3,11 +3,11 @@
 require "concurrent"
 
 module CloseYourIt
-  # Contatori diagnostici thread-safe del client: quanti eventi sono stati accodati,
-  # scartati (coda piena / before_send / sampling), spediti con successo, falliti (rete o status
-  # non-2xx) e, tra i falliti, quanti per timeout di rete. Rendono visibili i fallimenti silenziosi
-  # del trasporto fire-and-forget. `timeout` è un sotto-conteggio di `failed` (un timeout resta un
-  # fallimento d'invio): li teniamo distinti per isolare i problemi di connettività dai non-2xx.
+  # Thread-safe client diagnostic counters: how many events were enqueued, dropped (full queue /
+  # before_send / sampling), sent successfully, failed (network or non-2xx status) and, among the
+  # failed, how many by network timeout. They make the silent failures of the fire-and-forget
+  # transport visible. `timeout` is a sub-count of `failed` (a timeout is still a send failure):
+  # we keep them apart to isolate connectivity problems from non-2xx.
   #
   #   CloseYourIt.stats.to_h # => { enqueued: 12, dropped: 0, sent: 11, failed: 1, timeout: 1 }
   class Stats
@@ -31,9 +31,9 @@ module CloseYourIt
       @counters.transform_values(&:value)
     end
 
-    # Fotografia thread-safe dei contatori (ogni valore letto atomicamente). È lo stesso Hash di
-    # `to_h`, con un nome esplicito per il caso d'uso "leggo la diagnostica locale" (CYRB-12): pura
-    # lettura in-memory, non invia mai telemetria.
+    # Thread-safe snapshot of the counters (each value read atomically). It is the same Hash as
+    # `to_h`, with an explicit name for the "read the local diagnostics" use case (CYRB-12): a pure
+    # in-memory read, it never sends telemetry.
     alias_method :snapshot, :to_h
 
     def reset!

data/lib/closeyourit/subscribers/job_performance.rb

@@ -5,23 +5,23 @@ require_relative "../events/job_metric_event"
 
 module CloseYourIt
   module Subscribers
-    # Misura durata di esecuzione e attesa in coda (queue latency) dei background job — ActiveJob e
-    # Sidekiq — e, oltre le soglie configurate, emette metriche performance_issue (subtype `slow_job`
-    # e `job_queue_latency`). Logica PURA e SENZA STATO condiviso: tutto arriva per parametri, quindi
-    # job concorrenti sullo stesso thread/processo non si contaminano. Il wiring ad
-    # ActiveSupport::Notifications e al middleware Sidekiq vive altrove (Railtie / JobMetricsMiddleware).
-    # Rispetta il master switch `monitor_jobs`, le soglie e il `jobs_sample_rate`.
+    # Measures execution duration and queue wait (queue latency) of background jobs — ActiveJob and
+    # Sidekiq — and, beyond the configured thresholds, emits performance_issue metrics (subtypes
+    # `slow_job` and `job_queue_latency`). PURE logic WITHOUT shared state: everything comes in as
+    # parameters, so concurrent jobs on the same thread/process do not contaminate each other. The
+    # wiring to ActiveSupport::Notifications and the Sidekiq middleware lives elsewhere (Railtie /
+    # JobMetricsMiddleware). Honors the `monitor_jobs` master switch, the thresholds and `jobs_sample_rate`.
     class JobPerformance
       def initialize(configuration = nil)
         @configuration = configuration
       end
 
-      # Punto unico di decisione: dai valori misurati (durata e/o attesa) costruisce 0..2 metriche,
-      # applica le soglie (stretto `>`, così X non genera rumore e X+1 sì) e il sampling, poi le spedisce
-      # fire-and-forget. `duration_ms` e `queue_latency_ms` sono opzionali: ActiveJob li fornisce da due
-      # hook distinti (perform_start → attesa, perform → durata), Sidekiq entrambi in una sola chiamata.
-      # Il sampling è applicato SOLO ai candidati già oltre soglia (i job normali non consumano né
-      # generano nulla).
+      # Single decision point: from the measured values (duration and/or wait) it builds 0..2 metrics,
+      # applies the thresholds (strict `>`, so X makes no noise and X+1 does) and sampling, then sends
+      # them fire-and-forget. `duration_ms` and `queue_latency_ms` are optional: ActiveJob provides them
+      # from two separate hooks (perform_start → wait, perform → duration), Sidekiq both in one call.
+      # Sampling is applied ONLY to candidates already beyond the threshold (normal jobs neither
+      # consume nor generate anything).
       def record(job_class:, queue: nil, adapter: nil, duration_ms: nil, queue_latency_ms: nil,
                  attempt: nil, trace_id: nil)
         config = configuration
@@ -38,19 +38,20 @@ module CloseYourIt
         nil
       end
 
-      # Hook `perform_start.active_job`: l'attesa in coda è nota appena il job parte (now - enqueued_at).
+      # `perform_start.active_job` hook: the queue wait is known as soon as the job starts (now - the
+      # moment it was due to run).
       def active_job_started(job, now: Time.now.utc)
         record(
           job_class: job.class.name,
           queue: (job.queue_name if job.respond_to?(:queue_name)),
           adapter: "active_job",
-          queue_latency_ms: self.class.latency_ms(enqueued_at(job), now: now),
+          queue_latency_ms: self.class.latency_ms(due_at(job), now: now),
           attempt: (job.executions if job.respond_to?(:executions)),
           trace_id: (job.job_id if job.respond_to?(:job_id))
         )
       end
 
-      # Hook `perform.active_job`: a fine esecuzione la durata è `event.duration` (ms).
+      # `perform.active_job` hook: at the end of execution the duration is `event.duration` (ms).
       def active_job_performed(job, duration_ms)
         record(
           job_class: job.class.name,
@@ -62,10 +63,10 @@ module CloseYourIt
         )
       end
 
-      # Normalizza `enqueued_at` (Time, epoch Numerico in secondi come Sidekiq, o String ISO8601) in
-      # attesa (ms) rispetto a `now`. nil o non parsabile → nil: nessuna metrica di attesa (adapter che
-      # non popola l'istante di enqueue). Clamp a 0 se negativa (clock skew, enqueue "nel futuro"): lo
-      # schema di ingest esige `duration_ms >= 0`.
+      # Normalizes `enqueued_at` (Time, Numeric epoch in seconds like Sidekiq, or ISO8601 String) into
+      # a wait (ms) relative to `now`. nil or unparsable → nil: no wait metric (adapter that does not
+      # populate the enqueue instant). Clamped to 0 when negative (clock skew, enqueue "in the future"):
+      # the ingest schema requires `duration_ms >= 0`.
       def self.latency_ms(enqueued_at, now:)
         started = to_time(enqueued_at)
         return nil if started.nil?
@@ -94,6 +95,16 @@ module CloseYourIt
         job.enqueued_at if job.respond_to?(:enqueued_at)
       end
 
+      # A job delayed on purpose (set(wait:), retry_on backoff) is due at scheduled_at, not when it was
+      # enqueued: the planned delay is not queue wait (CYRB-27). No enqueued_at still means no metric.
+      def due_at(job)
+        enqueued = self.class.to_time(enqueued_at(job))
+        scheduled = self.class.to_time(job.scheduled_at) if job.respond_to?(:scheduled_at)
+        return enqueued if enqueued.nil? || scheduled.nil?
+
+        [ enqueued, scheduled ].max
+      end
+
       def configuration
         @configuration || CloseYourIt.configuration
       end