closeyourit-ruby 0.10.0 → 0.11.0

data/lib/closeyourit/events/log_event.rb

@@ -4,29 +4,29 @@ require "securerandom"
 require_relative "../scrubber"
 
 module CloseYourIt
-  # Voce di log strutturata spedita all'ingest /logs (NON formato Sentry: i log sono uno stream con
-  # message/level/attributes/logger). `message` E `attributes` passano dallo Scrubber (denylist +
-  # pattern) come ErrorEvent — un log può contenere PII/segreti quanto un errore. `trace_id` è
-  # congelato alla COSTRUZIONE (thread della richiesta) → correlazione log↔errori della stessa request
-  # anche quando il flush avviene su un thread timer diverso.
+  # Structured log entry sent to the /logs ingest (NOT Sentry format: logs are a stream with
+  # message/level/attributes/logger). `message` AND `attributes` go through the Scrubber (denylist +
+  # patterns) like ErrorEvent — a log can contain as much PII/secrets as an error. `trace_id` is
+  # frozen at CONSTRUCTION (request thread) → log↔error correlation for the same request even when
+  # the flush happens on a different timer thread.
   class LogEvent < Event
-    # Livelli canonici del backend (enum) + alias dei nomi stile ::Logger. Normalizzati QUI (fonte
-    # unica) così ogni costruzione — via CloseYourIt.log, .logger o diretta — produce un livello valido.
-    # L'indice in LEVELS è anche la severità numerica del livello (debug=0 … fatal=4): la STESSA mappa
-    # di dart/js, così il gating per soglia (`logs_min_level`) filtra identico cross-SDK (CYRB-6).
+    # Backend canonical levels (enum) + aliases of ::Logger-style names. Normalized HERE (single
+    # source) so every construction — via CloseYourIt.log, .logger or directly — yields a valid level.
+    # The index in LEVELS is also the level's numeric severity (debug=0 … fatal=4): the SAME map as
+    # dart/js, so threshold gating (`logs_min_level`) filters identically across SDKs (CYRB-6).
     LEVELS = %w[debug info warning error fatal].freeze
     LEVEL_ALIASES = { "warn" => "warning", "err" => "error", "unknown" => "fatal" }.freeze
 
-    # Normalizza qualsiasi livello (simbolo/stringa, maiuscole, alias) al nome canonico del backend.
-    # Ignoto → "info". Metodo di classe: fonte unica riusata da `CloseYourIt.log` per il gating.
+    # Normalizes any level (symbol/string, uppercase, alias) to the backend canonical name.
+    # Unknown → "info". Class method: single source reused by `CloseYourIt.log` for gating.
     def self.normalize_level(level)
       value = level.to_s.downcase
       value = LEVEL_ALIASES.fetch(value, value)
       LEVELS.include?(value) ? value : "info"
     end
 
-    # Severità numerica del livello (indice in LEVELS), identica alla mappa cross-SDK. Usata per il
-    # confronto con `logs_min_level` prima di costruire/spedire il log.
+    # Numeric severity of the level (index in LEVELS), identical to the cross-SDK map. Used for the
+    # comparison with `logs_min_level` before building/sending the log.
     def self.severity(level)
       LEVELS.index(normalize_level(level))
     end
@@ -38,9 +38,9 @@ module CloseYourIt
       @attributes = attributes || {}
       @logger = logger
       @scrubber = Scrubber.new(configuration)
-      # trace_id catturato QUI, sul thread della richiesta: il LogEvent viene bufferizzato e flushato
-      # su un thread timer diverso, dove lo Scope corrente è di un'ALTRA richiesta (o vuoto) → leggerlo
-      # lazy in to_h romperebbe la correlazione log↔errore. Lo congeliamo alla costruzione.
+      # trace_id captured HERE, on the request thread: the LogEvent is buffered and flushed on a
+      # different timer thread, where the current Scope belongs to ANOTHER request (or is empty) →
+      # reading it lazily in to_h would break log↔error correlation. We freeze it at construction.
       @trace_id = CloseYourIt::Scope.current.trace_id
     end
 
@@ -71,7 +71,7 @@ module CloseYourIt
       @scrubber.filter_params(deep_stringify_keys(@attributes))
     end
 
-    # Chiavi sempre stringa (anche annidate): coerenza col payload JSON e con la denylist dello Scrubber.
+    # Keys always strings (nested too): consistent with the JSON payload and the Scrubber denylist.
     def deep_stringify_keys(value)
       case value
       when Hash  then value.each_with_object({}) { |(key, val), acc| acc[key.to_s] = deep_stringify_keys(val) }

data/lib/closeyourit/events/message_event.rb

@@ -4,9 +4,9 @@ require "securerandom"
 require_relative "../scrubber"
 
 module CloseYourIt
-  # Messaggio diagnostico esplicito (`CloseYourIt.capture_message`) nel formato evento Sentry
-  # (`message.formatted` + level). Fonde lo Scope corrente come ErrorEvent. Il messaggio passa dallo
-  # Scrubber (pattern) come `exception.message` di ErrorEvent — parità PII cross-evento.
+  # Explicit diagnostic message (`CloseYourIt.capture_message`) in Sentry event format
+  # (`message.formatted` + level). Merges the current Scope like ErrorEvent. The message goes through
+  # the Scrubber (patterns) like ErrorEvent's `exception.message` — PII parity across events.
   class MessageEvent < Event
     def initialize(message, level:, configuration:)
       super(configuration)
@@ -21,7 +21,7 @@ module CloseYourIt
         "timestamp" => @occurred_at,
         "platform" => "ruby",
         "level" => @level,
-        # Correlazione log↔errori: stesso trace_id dei log della medesima richiesta (parità con ErrorEvent).
+        # Log↔error correlation: same trace_id as the logs of the same request (parity with ErrorEvent).
         "trace_id" => CloseYourIt::Scope.current.trace_id,
         "environment" => environment,
         "release" => @configuration.release,

data/lib/closeyourit/events/performance_issue_event.rb

@@ -4,10 +4,10 @@ require "securerandom"
 require_relative "../event"
 
 module CloseYourIt
-  # Payload `kind=performance_issue` per la pipeline metriche (`/api/v1/projects/:id/metrics`).
-  # È un VERDETTO aggregato (N+1, slow request, slow external HTTP), non una metrica grezza:
-  # `subtype` lo qualifica, `trace_id` lo correla a log/errori della stessa richiesta. Lo SQL è già
-  # offuscato (è il fingerprint del profilo). I campi nil vengono omessi (slow_request non ha sql).
+  # `kind=performance_issue` payload for the metrics pipeline (`/api/v1/projects/:id/metrics`).
+  # It is an aggregate VERDICT (N+1, slow request, slow external HTTP), not a raw metric:
+  # `subtype` qualifies it, `trace_id` correlates it with logs/errors of the same request. The SQL is
+  # already obfuscated (it is the profile fingerprint). Nil fields are omitted (slow_request has no sql).
   class PerformanceIssueEvent < Event
     def initialize(attrs, configuration)
       super(configuration)

data/lib/closeyourit/events/slow_method_event.rb

@@ -5,10 +5,10 @@ require_relative "../event"
 require_relative "../scrubber"
 
 module CloseYourIt
-  # Payload `kind=slow_method` per la pipeline metriche. Di default solo label + durata + posizione.
-  # Gli argomenti del metodo sono inviati SOLO se `capture_method_arguments` (opt-in, default OFF):
-  # posizionali per indice, kwargs per nome (scrub della chiave sensibile), valore via `inspect`
-  # troncato per sicurezza JSON. Vedi PDR §9.
+  # `kind=slow_method` payload for the metrics pipeline. By default only label + duration + location.
+  # Method arguments are sent ONLY with `capture_method_arguments` (opt-in, default OFF):
+  # positional by index, kwargs by name (sensitive key scrubbing), value via `inspect`
+  # truncated for JSON safety. See PDR §9.
   class SlowMethodEvent < Event
     def initialize(label, duration_ms, location, configuration, args: nil, kwargs: nil)
       super(configuration)
@@ -41,8 +41,8 @@ module CloseYourIt
 
     private
 
-    # Argomenti — SOLO se capture_method_arguments (opt-in). Posizionali per indice; kwargs per nome con
-    # scrub della chiave sensibile (denylist password/token/…). Valore = inspect troncato (JSON-safe).
+    # Arguments — ONLY with capture_method_arguments (opt-in). Positional by index; kwargs by name with
+    # sensitive key scrubbing (denylist password/token/…). Value = truncated inspect (JSON-safe).
     def arguments
       return nil unless @configuration.capture_method_arguments
 

data/lib/closeyourit/events/slow_query_event.rb

@@ -6,8 +6,8 @@ require_relative "../scrubber"
 require_relative "../scope"
 
 module CloseYourIt
-  # Payload `kind=slow_query` per la pipeline metriche (`/api/v1/projects/:id/metrics`).
-  # Lo SQL è offuscato (binds esclusi) — vedi PDR §9.
+  # `kind=slow_query` payload for the metrics pipeline (`/api/v1/projects/:id/metrics`).
+  # The SQL is obfuscated (binds excluded) — see PDR §9.
   class SlowQueryEvent < Event
     def initialize(payload, duration_ms, configuration)
       super(configuration)
@@ -47,8 +47,8 @@ module CloseYourIt
       connection.adapter_name.to_s.downcase
     end
 
-    # Valori dei bind — SOLO se capture_query_bindings (opt-in, default OFF). Scrub per nome colonna
-    # (denylist password/token/…); il valore è reso come stringa per sicurezza JSON.
+    # Bind values — ONLY with capture_query_bindings (opt-in, default OFF). Scrubbed by column name
+    # (denylist password/token/…); the value is rendered as a string for JSON safety.
     def bindings
       return nil unless @configuration.capture_query_bindings
 

data/lib/closeyourit/instrumenter.rb

@@ -3,8 +3,8 @@
 require_relative "events/slow_method_event"
 
 module CloseYourIt
-  # Cronometra blocchi/metodi con `CLOCK_MONOTONIC` e invia un `slow_method` se la durata supera la
-  # soglia. Gli argomenti sono inviati solo se `capture_method_arguments` (opt-in) — vedi SlowMethodEvent.
+  # Times blocks/methods with `CLOCK_MONOTONIC` and sends a `slow_method` when the duration exceeds
+  # the threshold. Arguments are sent only with `capture_method_arguments` (opt-in) — see SlowMethodEvent.
   module Instrumenter
     module_function
 
@@ -13,10 +13,10 @@ module CloseYourIt
       start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       yield
     ensure
-      # `measure` gira DENTRO il metodo dell'app (Monitor fa prepend): un guasto qui — soglia non
-      # configurata, ingest irraggiungibile — solleverebbe in un chiamante che aveva già il suo
-      # risultato. È l'unico ingresso della gemma che era scoperto: ora è come tutti gli altri
-      # (CYRB-24). Un'eccezione del blocco misurato continua invece a propagare intatta.
+      # `measure` runs INSIDE the app's method (Monitor prepends): a failure here — threshold not
+      # configured, unreachable ingest — would raise in a caller that already had its result. It was
+      # the only unguarded entry point of the gem: now it is like all the others (CYRB-24). An
+      # exception from the measured block, instead, keeps propagating untouched.
       begin
         duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000.0
         report(label, duration_ms, location, args: args, kwargs: kwargs)

data/lib/closeyourit/job_context.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "time"
+require "date"
+
+module CloseYourIt
+  # Versioned attempt metadata. Missing clocks stay unknown, never an invented zero.
+  module JobContext
+    def self.build(framework:, name:, queue: nil, job_id: nil, attempt: nil, retry_count: :derive,
+                   enqueued_at: nil, scheduled_at: nil, started_at: nil)
+      enqueued, scheduled, started = [ enqueued_at, scheduled_at, started_at ].map { |value| instant(value) }
+      due = enqueued && scheduled ? [ enqueued, scheduled ].max : enqueued
+      wait = (started - due) * 1000.0 if started && due
+      delay = (scheduled - enqueued) * 1000.0 if enqueued && scheduled
+      attempt = nil unless attempt.is_a?(Integer) && attempt.positive?
+      retry_count = attempt && attempt - 1 if retry_count == :derive
+      retry_count = nil unless retry_count.is_a?(Integer) && retry_count >= 0
+      {
+        "schema_version" => 1, "framework" => framework, "name" => bounded_text(name, 200) || "unknown",
+        "queue" => bounded_text(queue, 128), "job_id" => bounded_text(job_id, 256), "attempt" => attempt,
+        "retry_count" => retry_count, "attempt_outcome" => "unknown", "terminal" => nil,
+        "enqueued_at" => enqueued&.iso8601(6), "scheduled_at" => scheduled&.iso8601(6),
+        "started_at" => started&.iso8601(6), "duration_ms" => nil,
+        "queue_wait_ms" => wait && [ wait, 0.0 ].max,
+        "scheduled_delay_ms" => delay && [ delay, 0.0 ].max, "clock_skew" => !!(wait && wait.negative?)
+      }
+    end
+
+    def self.bounded_text(value, limit)
+      value if value.is_a?(String) && value.length.between?(1, limit) && !value.match?(/[\x00-\x1f\x7f]/)
+    end
+
+    def self.sidekiq_time(value, version:)
+      return value unless value.is_a?(Numeric)
+
+      version.to_s.split(".").first.to_i >= 8 ? value / 1000.0 : value
+    end
+
+    def self.instant(value)
+      case value
+      when Time then value.getutc
+      when Numeric then Time.at(value).utc if value.finite?
+      when String
+        if value.match?(/(?:Z|[+-]\d{2}:\d{2})\z/)
+          DateTime.rfc3339(value)
+          Time.iso8601(value).utc
+        end
+      end
+    rescue ArgumentError, RangeError
+      nil
+    end
+
+    def self.log(context, configuration)
+      return unless configuration.monitor_jobs && configuration.job_lifecycle_logs
+
+      CloseYourIt.log(:info, "Background job attempt finished", logger: "closeyourit.jobs", contexts: { job: context })
+    rescue StandardError
+      CloseYourIt.internal_logger.warn("CloseYourIt job lifecycle emission failed")
+    end
+  end
+end

data/lib/closeyourit/line_cache.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module CloseYourIt
-  # Cache in-process delle righe dei file sorgente, per le context lines dei frame
-  # (pre_context/context_line/post_context). Bounded: oltre MAX_FILES si svuota per intero —
-  # semplice e sufficiente (i file di un'app in errore sono pochi e ricorrenti). Thread-safe.
+  # In-process cache of source file lines, for the frames' context lines
+  # (pre_context/context_line/post_context). Bounded: beyond MAX_FILES it is emptied entirely —
+  # simple and sufficient (the files of an app in error are few and recurring). Thread-safe.
   module LineCache
     MAX_FILES = 200
 
@@ -11,7 +11,7 @@ module CloseYourIt
     @mutex = Mutex.new
 
     class << self
-      # Righe del file (chomp-ate), oppure nil se non leggibile o path sintetico ("(eval)", "(irb)").
+      # The file's lines (chomped), or nil if unreadable or a synthetic path ("(eval)", "(irb)").
       def lines(path)
         return nil if path.nil? || path.empty? || path.start_with?("(")
 

data/lib/closeyourit/log_buffer.rb

@@ -3,11 +3,11 @@
 require "concurrent"
 
 module CloseYourIt
-  # Buffer in-memory thread-safe dei log: accumula i LogEvent e li flusha in batch verso /logs quando
-  # raggiungono `logs_batch_size`, allo scadere di `logs_flush_interval` (timer), o allo shutdown.
-  # Riduce le richieste HTTP — i log sono alto-volume, a differenza di errori/metriche uno-a-uno.
+  # Thread-safe in-memory log buffer: collects LogEvents and flushes them in batches to /logs when
+  # they reach `logs_batch_size`, when `logs_flush_interval` expires (timer), or at shutdown.
+  # Cuts HTTP requests — logs are high-volume, unlike one-to-one errors/metrics.
   class LogBuffer
-    attr_reader :timer # esposto per i test (verifica dell'intervallo configurato)
+    attr_reader :timer # exposed for tests (checks the configured interval)
 
     def initialize(client:, configuration:)
       @client = client
@@ -33,12 +33,12 @@ module CloseYourIt
 
       @client.flush_logs(batch)
     rescue StandardError => e
-      # Il flush gira sia sul thread della richiesta (batch pieno) sia sul thread timer: un to_h /
-      # before_send che solleva su UN evento non deve propagare nell'app né uccidere il TimerTask
-      # (che altrimenti smette di flushare → log accumulati e persi). Ingoiato e loggato.
+      # The flush runs both on the request thread (full batch) and on the timer thread: a to_h /
+      # before_send raising on ONE event must not propagate into the app nor kill the TimerTask
+      # (which would otherwise stop flushing → logs pile up and are lost). Swallowed and logged.
       CloseYourIt.internal_logger.error("CloseYourIt log buffer: #{e.class}: #{e.message}")
-      # Il batch è già stato drenato: se flush_logs solleva, quei log sono persi. Contabilizzali come
-      # scarti per non lasciare un fallimento silenzioso (CYRB-12). `batch.to_a` è nil-safe.
+      # The batch has already been drained: if flush_logs raises, those logs are lost. Count them as
+      # drops so the failure is not silent (CYRB-12). `batch.to_a` is nil-safe.
       batch.to_a.size.times do
         CloseYourIt.stats.increment(:dropped)
         CloseYourIt.notify_diagnostic(:drop, reason: :error)
@@ -60,7 +60,7 @@ module CloseYourIt
       end
     end
 
-    # Avvia il timer di flush periodico alla prima voce (una sola volta).
+    # Starts the periodic flush timer on the first entry (only once).
     def ensure_timer
       return if @timer
 

data/lib/closeyourit/log_device.rb

@@ -1,28 +1,28 @@
 # frozen_string_literal: true
 
 module CloseYourIt
-  # Oggetto Logger-compatibile esposto come `CloseYourIt.logger`: ogni chiamata inoltra a
-  # `CloseYourIt.emit_log` (→ ingest /logs). Usabile come logger esplicito dell'app, anche con attributes:
-  #   CloseYourIt.logger.warn("disco quasi pieno", disk: "sda1")
-  # `warn` mappa sul livello `warning` (enum backend); supporta block e `::Logger#add` per drop-in.
+  # Logger-compatible object exposed as `CloseYourIt.logger`: every call forwards to
+  # `CloseYourIt.emit_log` (→ ingest /logs). Usable as the app's explicit logger, also with attributes:
+  #   CloseYourIt.logger.warn("disk almost full", disk: "sda1")
+  # `warn` maps to the `warning` level (backend enum); supports blocks and `::Logger#add` as a drop-in.
   #
-  # La sorgente del log (campo `logger` del payload) si imposta SOLO via `.named` (child logger, parità
-  # dart/js) o via costruttore — MAI da una keyword dei metodi: così una chiave `logger` passata a un
-  # metodo resta un attributo dati e non viene hijackata come sorgente (CYRB-8).
-  #   payments = CloseYourIt.logger.named("payments") # child con sorgente "payments"
+  # The log source (the payload's `logger` field) is set ONLY via `.named` (child logger, dart/js
+  # parity) or the constructor — NEVER from a method keyword: so a `logger` key passed to a method
+  # stays a data attribute and is not hijacked as the source (CYRB-8).
+  #   payments = CloseYourIt.logger.named("payments") # child with source "payments"
   #   payments.warn("retry", attempt: 3)              # logger=payments, attributes={attempt:3}
-  #   CloseYourIt.logger.warn("disco pieno", logger: "/dev/sda1") # attributes={logger:"/dev/sda1"}
+  #   CloseYourIt.logger.warn("disk full", logger: "/dev/sda1") # attributes={logger:"/dev/sda1"}
   class LogDevice
-    # Severità numeriche ::Logger → livelli CloseYourIt (UNKNOWN→fatal).
+    # ::Logger numeric severities → CloseYourIt levels (UNKNOWN→fatal).
     SEVERITY_LEVELS = { 0 => "debug", 1 => "info", 2 => "warning", 3 => "error", 4 => "fatal", 5 => "fatal" }.freeze
 
-    # `source` = nome della sorgente del log (campo `logger` del payload). Preferire `.named` in app.
+    # `source` = name of the log source (the payload's `logger` field). Prefer `.named` in apps.
     def initialize(source = nil)
       @source = normalize_source(source)
     end
 
-    # Child logger con sorgente esplicita (parità dart/js). Ritorna un NUOVO LogDevice: il logger su
-    # cui è chiamato resta invariato (immutabile), come i child logger cross-SDK.
+    # Child logger with an explicit source (dart/js parity). Returns a NEW LogDevice: the logger it is
+    # called on stays unchanged (immutable), like the cross-SDK child loggers.
     #   CloseYourIt.logger.named("payments").info("retry", attempt: 3)
     def named(source)
       self.class.new(source)
@@ -39,7 +39,7 @@ module CloseYourIt
       message
     end
 
-    # Compat con ::Logger#add(severity, message = nil, progname = nil).
+    # Compatible with ::Logger#add(severity, message = nil, progname = nil).
     def add(severity, message = nil, progname = nil, &block)
       write(SEVERITY_LEVELS.fetch(severity.to_i, "info"), message || progname, {}, &block)
     end
@@ -48,16 +48,16 @@ module CloseYourIt
     private
 
     def write(level, message, attributes, &block)
-      # Gate PRIMA del block: `logger.debug { dump_costoso }` non valuta il block se i log sono spenti.
+      # Gate BEFORE the block: `logger.debug { expensive_dump }` does not evaluate the block when logs are off.
       return unless CloseYourIt.logs_active?
 
       message = block.call if block
-      # Sorgente e attributes separati: gli `attributes` (inclusa un'eventuale chiave `logger`) restano
-      # dati; la sorgente è SOLO `@source` (via `.named`/costruttore) → nessuna collisione (CYRB-8).
+      # Source and attributes kept apart: the `attributes` (including any `logger` key) stay data;
+      # the source is ONLY `@source` (via `.named`/constructor) → no collision (CYRB-8).
       CloseYourIt.emit_log(level, message, source: @source, attributes: attributes)
     end
 
-    # Sorgente vuota/blank → nessuna sorgente (nil); altrimenti stringa (il campo `logger` è testuale).
+    # Empty/blank source → no source (nil); otherwise a string (the `logger` field is textual).
     def normalize_source(source)
       return nil if source.nil?
 

data/lib/closeyourit/monitor.rb

@@ -3,7 +3,7 @@
 require_relative "instrumenter"
 
 module CloseYourIt
-  # Macro per strumentare automaticamente un metodo:
+  # Macro to instrument a method automatically:
   #
   #   class Report
   #     include CloseYourIt::Monitor
@@ -11,7 +11,7 @@ module CloseYourIt
   #     monitor :generate
   #   end
   #
-  # Wrappa il metodo via `Module#prepend` cronometrandolo, senza cambiarne firma/risultato.
+  # Wraps the method via `Module#prepend` timing it, without changing its signature/result.
   module Monitor
     def self.included(base)
       base.extend(ClassMethods)

data/lib/closeyourit/performance/request_profile.rb

@@ -2,11 +2,11 @@
 
 module CloseYourIt
   module Performance
-    # Accumulatore per-richiesta (vive nello Scope, resettato a fine richiesta). Conta le query, le
-    # raggruppa per [fingerprint SQL offuscato, call-site] (il pattern prosopite per l'N+1) e tiene le
-    # chiamate HTTP esterne. Puro stato in memoria: il verdetto lo calcola Performance::Rollup.
+    # Per-request accumulator (lives in the Scope, reset at the end of the request). Counts queries,
+    # groups them by [obfuscated SQL fingerprint, call site] (the prosopite pattern for N+1) and keeps
+    # the external HTTP calls. Pure in-memory state: Performance::Rollup computes the verdict.
     class RequestProfile
-      # Guard di memoria: cap ai gruppi/chiamate distinti tracciati (il conteggio totale resta esatto).
+      # Memory guard: cap on the distinct groups/calls tracked (the total count stays exact).
       MAX_GROUPS = 1000
       MAX_EXTERNAL = 500
 
@@ -19,7 +19,7 @@ module CloseYourIt
         @external_calls = []
       end
 
-      # Una query non di sistema. Le query da cache non sono round-trip DB → non contano per l'N+1.
+      # A non-system query. Cached queries are not DB round-trips → they do not count for N+1.
       def add_query(fingerprint:, source:, duration_ms:, cached: false)
         return if cached
 

data/lib/closeyourit/performance/rollup.rb

@@ -4,8 +4,8 @@ require_relative "../events/performance_issue_event"
 
 module CloseYourIt
   module Performance
-    # Trasforma un RequestProfile (+ durata/route della richiesta) in 0..N verdetti PerformanceIssueEvent.
-    # Le soglie vivono nella Configuration. Detection lato client; dedup/alert lato backend.
+    # Turns a RequestProfile (+ request duration/route) into 0..N PerformanceIssueEvent verdicts.
+    # Thresholds live in the Configuration. Detection on the client; dedup/alerts on the backend.
     class Rollup
       def self.call(...) = new(...).call
 
@@ -28,7 +28,7 @@ module CloseYourIt
 
       private
 
-      # Un verdetto per ogni gruppo [fingerprint, call-site] che ha girato più di n_plus_one_threshold volte.
+      # One verdict for every [fingerprint, call-site] group that ran more than n_plus_one_threshold times.
       def n_plus_one_events
         @profile.query_groups.values.filter_map do |group|
           next unless group[:count] > @config.n_plus_one_threshold

data/lib/closeyourit/rails/active_job_extension.rb

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

data/lib/closeyourit/rails/capture_exceptions.rb

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