closeyourit-ruby 0.9.4 → 0.10.2

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

data/lib/closeyourit/subscribers/request_performance.rb

@@ -5,10 +5,10 @@ require_relative "../performance/rollup"
 
 module CloseYourIt
   module Subscribers
-    # A fine richiesta (process_action.action_controller) trasforma il RequestProfile accumulato nello
-    # Scope in verdetti performance_issue e li spedisce (fire-and-forget). Lo Scope — e quindi il
-    # profilo — viene azzerato subito dopo da RequestContext#call (ensure). Logica pura: il wiring ad
-    # ActiveSupport::Notifications vive nel Railtie.
+    # At the end of the request (process_action.action_controller) turns the RequestProfile collected
+    # in the Scope into performance_issue verdicts and sends them (fire-and-forget). The Scope — and so
+    # the profile — is reset right after by RequestContext#call (ensure). Pure logic: the wiring to
+    # ActiveSupport::Notifications lives in the Railtie.
     class RequestPerformance
       def initialize(configuration = nil)
         @configuration = configuration

data/lib/closeyourit/subscribers/slow_query.rb

@@ -6,9 +6,9 @@ require_relative "../scope"
 
 module CloseYourIt
   module Subscribers
-    # Riceve i dati di un evento `sql.active_record` e, se la query supera la soglia
-    # (escludendo SCHEMA/CACHE/TRANSACTION), invia un evento `slow_query`.
-    # Logica pura: il wiring ad ActiveSupport::Notifications vive nel Railtie.
+    # Receives the data of a `sql.active_record` event and, if the query exceeds the threshold
+    # (excluding SCHEMA/CACHE/TRANSACTION), sends a `slow_query` event.
+    # Pure logic: the wiring to ActiveSupport::Notifications lives in the Railtie.
     class SlowQuery
       IGNORED_NAMES = %w[SCHEMA CACHE TRANSACTION].freeze
 
@@ -16,6 +16,26 @@ module CloseYourIt
         @configuration = configuration
       end
 
+      # Entry point of the Railtie's sql.active_record block. `source` is a callable: the call site costs
+      # a full backtrace plus the Rails cleaner, so it is resolved at most once and only when needed.
+      def notify(payload, duration_ms, source)
+        resolved = false
+        site = nil
+        lazy_source = lambda do
+          site = source.call unless resolved
+          resolved = true
+          site
+        end
+        name = payload[:name]
+        sql = payload[:sql]
+        cached = payload.fetch(:cached, false)
+        record(name: name, duration_ms: duration_ms, sql: sql, cached: cached,
+               connection: payload[:connection], binds: payload[:binds],
+               type_casted_binds: payload[:type_casted_binds], source: lazy_source)
+        breadcrumb(name: name, sql: sql, duration_ms: duration_ms, cached: cached)
+        profile(name: name, sql: sql, duration_ms: duration_ms, cached: cached, source: lazy_source)
+      end
+
       def record(name:, duration_ms:, sql:, cached: false, connection: nil,
                  binds: nil, type_casted_binds: nil, source: nil)
         config = @configuration || CloseYourIt.configuration
@@ -25,18 +45,18 @@ module CloseYourIt
 
         event = SlowQueryEvent.new(
           { name: name, sql: sql, cached: cached, connection: connection,
-            binds: binds, type_casted_binds: type_casted_binds, source: source },
+            binds: binds, type_casted_binds: type_casted_binds, source: resolve(source) },
           duration_ms,
           config
         )
         CloseYourIt.capture_event(event)
       rescue StandardError
-        # La telemetria non deve mai disturbare la query ospite.
+        # Telemetry must never disturb the host query.
         nil
       end
 
-      # Breadcrumb per OGNI query non di sistema (non solo lente): SQL offuscato, niente bind.
-      # Dà la cronologia "quali query prima del crash" allegata all'evento d'errore.
+      # Breadcrumb for EVERY non-system query (not only slow ones): obfuscated SQL, no binds.
+      # Gives the "which queries before the crash" history attached to the error event.
       def breadcrumb(name:, sql:, duration_ms:, cached: false)
         config = @configuration || CloseYourIt.configuration
         return if ignored_name?(name)
@@ -49,12 +69,12 @@ module CloseYourIt
           data: { "name" => name, "duration_ms" => duration_ms.to_f.round(2), "cached" => cached }
         )
       rescue StandardError
-        # La telemetria non deve mai disturbare la query ospite.
+        # Telemetry must never disturb the host query.
         nil
       end
 
-      # Spinge OGNI query non di sistema nel RequestProfile dello Scope (per la detection N+1 a fine
-      # richiesta). Solo se detect_performance_issues: fingerprint = SQL offuscato + call-site.
+      # Pushes EVERY non-system query into the Scope's RequestProfile (for N+1 detection at the end of
+      # the request). Only with detect_performance_issues: fingerprint = obfuscated SQL + call site.
       def profile(name:, sql:, duration_ms:, cached: false, source: nil)
         config = @configuration || CloseYourIt.configuration
         return unless config.detect_performance_issues
@@ -62,15 +82,17 @@ module CloseYourIt
 
         CloseYourIt::Scope.current.performance_profile.add_query(
           fingerprint: scrubber(config).obfuscate_sql(sql),
-          source: source, duration_ms: duration_ms, cached: cached
+          source: resolve(source), duration_ms: duration_ms, cached: cached
         )
       rescue StandardError
-        # La telemetria non deve mai disturbare la query ospite.
+        # Telemetry must never disturb the host query.
         nil
       end
 
       private
 
+      def resolve(source) = source.respond_to?(:call) ? source.call : source
+
       def scrubber(config)
         @scrubber ||= Scrubber.new(config)
       end
@@ -79,16 +101,16 @@ module CloseYourIt
         name.nil? || IGNORED_NAMES.include?(name)
       end
 
-      # Query esclusa dalla MISURA dei rallentamenti (config.excluded_query_patterns). Il filtro sta
-      # solo qui, non in #breadcrumb né in #profile:
+      # Query excluded from slowdown MEASUREMENT (config.excluded_query_patterns). The filter lives
+      # only here, not in #breadcrumb nor in #profile:
       #
-      #   - breadcrumb: la cronologia "quali query prima del crash" ha valore diagnostico anche quando
-      #     la query è del framework — nasconderla renderebbe la sequenza incompleta e bugiarda;
-      #   - profile: è per-richiesta e serve la detection N+1, dove una tabella di servizio letta molte
-      #     volte è essa stessa un sintomo da vedere.
+      #   - breadcrumb: the "which queries before the crash" history has diagnostic value even when the
+      #     query belongs to the framework — hiding it would make the sequence incomplete and misleading;
+      #   - profile: it is per-request and serves N+1 detection, where a service table read many times
+      #     is itself a symptom worth seeing.
       #
-      # Un rallentamento va misurato se qualcuno può intervenire; una breadcrumb va tenuta se aiuta a
-      # capire. Sono due domande diverse, e questa lista risponde solo alla prima.
+      # A slowdown is worth measuring if someone can act on it; a breadcrumb is worth keeping if it
+      # helps understanding. They are two different questions, and this list answers only the first.
       def excluded_sql?(config, sql)
         return false if sql.nil?
 

data/lib/closeyourit/trace_context.rb

@@ -3,14 +3,14 @@
 require "securerandom"
 
 module CloseYourIt
-  # Contesto di trace W3C (`traceparent`/`tracestate`, https://www.w3.org/TR/trace-context/).
-  # NON è un tracer: non apre span né misura tempi. È un "propagation bridge" minimale (il ticket:
-  # "Non costruire tracing custom completo") — adotta un contesto entrante valido facendo pass-through
-  # di trace-id/parent-id/flag, oppure ne genera uno root, e sa serializzarsi negli header d'uscita.
-  # Volutamente separato dai formati proprietari: sullo standard, senza dipendere da un vendor.
+  # W3C trace context (`traceparent`/`tracestate`, https://www.w3.org/TR/trace-context/).
+  # It is NOT a tracer: it opens no spans and measures no times. It is a minimal "propagation bridge"
+  # (the ticket: "do not build full custom tracing") — it adopts a valid incoming context passing
+  # through trace-id/parent-id/flags, or generates a root one, and serializes into outgoing headers.
+  # Deliberately separate from proprietary formats: standard-based, with no vendor dependency.
   class TraceContext
-    # traceparent = version "-" trace-id "-" parent-id "-" trace-flags (55 char per la versione 00).
-    # `rest` cattura eventuali campi futuri: ammessi solo da versioni > 00 (forward-compat), vietati su 00.
+    # traceparent = version "-" trace-id "-" parent-id "-" trace-flags (55 chars for version 00).
+    # `rest` captures any future fields: allowed only for versions > 00 (forward-compat), forbidden on 00.
     TRACEPARENT = /
       \A
       (?<version>[0-9a-f]{2})-
@@ -27,10 +27,10 @@ module CloseYourIt
     ZERO_PARENT_ID    = ("0" * 16).freeze
     FLAG_SAMPLED      = 0x01
 
-    # tracestate: lista di membri `key=value` separati da virgola, max 32 (W3C §3.3.1).
+    # tracestate: comma-separated list of `key=value` members, max 32 (W3C §3.3.1).
     TRACESTATE_MAX_MEMBERS = 32
-    # key: lowercase alnum iniziale + set ristretto (incluso `@`/`/` per le chiavi tenant@vendor).
-    # value: caratteri stampabili 0x20–0x7E esclusi `,` (0x2C) e `=` (0x3D).
+    # key: leading lowercase alnum + restricted set (including `@`/`/` for tenant@vendor keys).
+    # value: printable characters 0x20–0x7E except `,` (0x2C) and `=` (0x3D).
     TRACESTATE_MEMBER = %r{\A[a-z0-9][a-z0-9_\-*/@]*=[\x20-\x2b\x2d-\x3c\x3e-\x7e]+\z}
 
     attr_reader :trace_id, :parent_id, :flags, :tracestate
@@ -43,9 +43,9 @@ module CloseYourIt
     end
 
     class << self
-      # Adotta un traceparent entrante. Ritorna nil se malformato (→ il chiamante genera un root o
-      # lascia il contesto assente). Pass-through: mantiene trace-id/parent-id/flag verbatim così il
-      # bridge non inventa span. Il tracestate viene sanificato (membri invalidi scartati, cap a 32).
+      # Adopts an incoming traceparent. Returns nil when malformed (→ the caller generates a root or
+      # leaves the context absent). Pass-through: keeps trace-id/parent-id/flags verbatim so the
+      # bridge invents no spans. The tracestate is sanitized (invalid members dropped, capped at 32).
       def parse(traceparent, tracestate = nil)
         match = TRACEPARENT.match(traceparent.to_s.strip)
         return nil unless match
@@ -62,9 +62,9 @@ module CloseYourIt
         )
       end
 
-      # Nuovo contesto root (nessun traceparent entrante valido). Genera trace-id (16 byte) e parent-id
-      # (8 byte) casuali — SecureRandom è fork-safe, così un worker forkato non riusa gli id del padre.
-      # `sampled` fissa il flag: un root che apriamo noi traccia di default.
+      # New root context (no valid incoming traceparent). Generates random trace-id (16 bytes) and
+      # parent-id (8 bytes) — SecureRandom is fork-safe, so a forked worker does not reuse the parent's
+      # ids. `sampled` sets the flag: a root we open traces by default.
       def generate(sampled: true)
         new(
           trace_id:   SecureRandom.hex(16),
@@ -76,8 +76,8 @@ module CloseYourIt
 
       private
 
-      # Trattiene solo i membri ben formati, nell'ordine originale, fino a 32. Ritorna nil se non ne
-      # resta nessuno → così non propaghiamo mai un tracestate spazzatura o sovradimensionato.
+      # Keeps only well-formed members, in the original order, up to 32. Returns nil if none are left
+      # → so we never propagate a garbage or oversized tracestate.
       def sanitize_tracestate(tracestate)
         return nil if tracestate.nil?
 
@@ -92,14 +92,14 @@ module CloseYourIt
       (flags & FLAG_SAMPLED) != 0
     end
 
-    # traceparent d'uscita, sempre versione 00 (l'unica che sappiamo emettere). I flag sono ri-emessi
-    # per intero (i bit riservati vanno propagati as-is), formattati su due cifre esadecimali.
+    # Outgoing traceparent, always version 00 (the only one we can emit). Flags are re-emitted in full
+    # (reserved bits must be propagated as-is), formatted as two hex digits.
     def traceparent
       format("%s-%s-%s-%02x", CURRENT_VERSION, trace_id, parent_id, flags & 0xff)
     end
 
-    # Header di propagazione W3C: traceparent (+ tracestate se presente). MAI `baggage`: può contenere
-    # contesto interno/PII e non deve varcare il confine (ticket: "baggage sensibile non riceve header").
+    # W3C propagation headers: traceparent (+ tracestate if present). NEVER `baggage`: it may carry
+    # internal context/PII and must not cross the boundary (ticket: "sensitive baggage gets no header").
     def headers
       result = { "traceparent" => traceparent }
       result["tracestate"] = tracestate if tracestate && !tracestate.empty?