closeyourit-ruby 0.10.0 → 0.11.0

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,83 +1,83 @@
 # 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}/
 
+    DOLLAR_LITERAL = /\$([A-Za-z_][A-Za-z0-9_]*|)\$.*?(?:\$\1\$|\z)/m
     STRING_LITERAL = /'(?:[^']|'')*'/
-    NUMERIC_LITERAL = /\b\d+(?:\.\d+)?\b/
+    NUMERIC_LITERAL = /(?<![\w$])\d+(?:\.\d+)?\b/
 
     def initialize(configuration)
       @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 +91,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, "?")
+      sql.to_s.gsub(DOLLAR_LITERAL, "?").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 +112,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,40 +4,62 @@ 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
       end
 
       def call(_worker, job, queue)
+        return yield if active_job_owned?(job)
+
         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.
-        latency = Subscribers::JobPerformance.latency_ms(job["enqueued_at"], now: Time.now.utc)
-        yield
+        context = observe(job, queue)
+        value = yield
+        succeeded = true
+        value
       ensure
-        emit(job, queue, started, latency)
+        emit(job, queue, started, context, succeeded) if started
       end
 
       private
 
-      def emit(job, queue, started, latency)
+      def active_job_owned?(job)
+        %w[ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper Sidekiq::ActiveJob::Wrapper].include?(job["class"]) &&
+          Subscribers::JobPerformance.active_job_installed?
+      end
+
+      def observe(job, queue)
+        # Sidekiq 8 changed the timestamp wire unit; do not infer it from magnitude.
+        version = ::Sidekiq::VERSION if defined?(::Sidekiq::VERSION)
+        enqueued = JobContext.sidekiq_time(job["enqueued_at"], version: version)
+        JobContext.build(framework: "sidekiq", name: job["wrapped"] || job["class"],
+          queue: queue || job["queue"], job_id: job["jid"], attempt: attempt(job), retry_count: job["retry_count"],
+          enqueued_at: enqueued, started_at: Time.now.utc)
+      rescue StandardError
+        nil
+      end
+
+      def emit(job, queue, started, context, succeeded)
         duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+        if context
+          context = context.merge("duration_ms" => duration_ms, "attempt_outcome" => succeeded ? "success" : "error",
+            "terminal" => succeeded ? true : nil)
+          JobContext.log(context, CloseYourIt.configuration)
+        end
         subscriber.record(
           job_class: job["wrapped"] || job["class"],
           queue: queue || job["queue"],
           adapter: "sidekiq",
           duration_ms: duration_ms,
-          queue_latency_ms: latency,
+          queue_latency_ms: context && context["queue_wait_ms"],
           attempt: attempt(job),
-          trace_id: job["jid"]
+          trace_id: job["jid"], job_context: context
         )
       rescue StandardError => e
         CloseYourIt.internal_logger.error("CloseYourIt job metrics: #{e.class}: #{e.message}")
@@ -47,8 +69,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

@@ -2,32 +2,66 @@
 
 require "time"
 require_relative "../events/job_metric_event"
+require_relative "../job_context"
 
 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
+      REGISTRY_LOCK = Mutex.new
+      ACTIVE_JOB_SUBSCRIBERS = []
+
+      def self.active_job_installed?
+        REGISTRY_LOCK.synchronize { !ACTIVE_JOB_SUBSCRIBERS.empty? }
+      end
       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).
+      def install
+        REGISTRY_LOCK.synchronize do
+          return self if @subscriptions || !ACTIVE_JOB_SUBSCRIBERS.empty?
+
+          @subscriptions = []
+          { "enqueue_retry" => :retry, "retry_stopped" => :exhausted, "discard" => :discarded }.each do |name, outcome|
+            subscribe(name) { |event| event.payload[:job]&.instance_variable_set(:@__closeyourit_job_outcome, outcome) }
+          end
+          subscribe("perform_start") { |event| active_job_started(event.payload[:job]) if event.payload[:job] }
+          subscribe("perform") do |event|
+            job = event.payload[:job]
+            if job
+              CloseYourIt.usage_registry.record("job", job.class.name) if CloseYourIt.enabled?
+              active_job_performed(job, event.duration, payload: event.payload)
+            end
+          end
+          ACTIVE_JOB_SUBSCRIBERS << self
+          self
+        end
+      end
+
+      def uninstall
+        Array(@subscriptions).each { |subscription| ActiveSupport::Notifications.unsubscribe(subscription) }
+        @subscriptions = nil
+        REGISTRY_LOCK.synchronize { ACTIVE_JOB_SUBSCRIBERS.delete(self) }
+      end
+
+      # 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)
+                 attempt: nil, trace_id: nil, job_context: nil)
         config = configuration
         return unless config.monitor_jobs
 
-        common = { job_class: job_class, queue: queue, adapter: adapter, attempt: attempt, trace_id: trace_id }
+        common = { job_class: job_class, queue: queue, adapter: adapter, attempt: attempt, trace_id: trace_id, job_context: job_context }
         events = []
         events << build(config, "slow_job", duration_ms, common) if slow?(config, duration_ms)
         events << build(config, "job_queue_latency", queue_latency_ms, common) if waited?(config, queue_latency_ms)
@@ -38,34 +72,60 @@ 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)
+        context = JobContext.build(framework: "active_job", name: job.class.name,
+          queue: (job.queue_name if job.respond_to?(:queue_name)), job_id: (job.job_id if job.respond_to?(:job_id)),
+          attempt: (job.executions if job.respond_to?(:executions)), enqueued_at: enqueued_at(job),
+          scheduled_at: (job.scheduled_at if job.respond_to?(:scheduled_at)), started_at: now)
+        job.instance_variable_set(:@__closeyourit_job_context, context)
         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: context["queue_wait_ms"],
           attempt: (job.executions if job.respond_to?(:executions)),
-          trace_id: (job.job_id if job.respond_to?(:job_id))
+          trace_id: (job.job_id if job.respond_to?(:job_id)), job_context: context
         )
       end
 
-      # Hook `perform.active_job`: a fine esecuzione la durata è `event.duration` (ms).
-      def active_job_performed(job, duration_ms)
+      # `perform.active_job` hook: at the end of execution the duration is `event.duration` (ms).
+      def active_job_performed(job, duration_ms, payload: {})
+        context = job.instance_variable_get(:@__closeyourit_job_context)
+        if context
+          outcome, terminal = active_job_outcome(job, payload)
+          context = context.merge("duration_ms" => duration_ms, "attempt_outcome" => outcome, "terminal" => terminal)
+          JobContext.log(context, configuration)
+        end
         record(
           job_class: job.class.name,
           queue: (job.queue_name if job.respond_to?(:queue_name)),
           adapter: "active_job",
           duration_ms: duration_ms,
           attempt: (job.executions if job.respond_to?(:executions)),
-          trace_id: (job.job_id if job.respond_to?(:job_id))
+          trace_id: (job.job_id if job.respond_to?(:job_id)), job_context: context
         )
+      ensure
+        job.remove_instance_variable(:@__closeyourit_job_context) if job.instance_variable_defined?(:@__closeyourit_job_context)
+        job.remove_instance_variable(:@__closeyourit_job_outcome) if job.instance_variable_defined?(:@__closeyourit_job_outcome)
       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`.
+      def active_job_outcome(job, payload)
+        outcome = job.instance_variable_get(:@__closeyourit_job_outcome)
+        return [ "error", nil ] if payload[:exception_object] || payload[:exception]
+        return [ "retry", false ] if outcome == :retry
+        return [ "discarded", true ] if outcome == :discarded
+        return [ "error", nil ] if outcome == :exhausted
+        return [ "unknown", nil ] if outcome == :raised || payload[:aborted]
+
+        [ "success", true ]
+      end
+
+      # 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?
@@ -90,10 +150,28 @@ module CloseYourIt
 
       private
 
+      def subscribe(name, &callback)
+        @subscriptions << ActiveSupport::Notifications.monotonic_subscribe("#{name}.active_job") do |*args|
+          callback.call(ActiveSupport::Notifications::Event.new(*args))
+        rescue StandardError
+          CloseYourIt.internal_logger.warn("CloseYourIt job observation failed")
+        end
+      end
+
       def enqueued_at(job)
         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