closeyourit-ruby 0.10.0 → 0.11.0

data/lib/closeyourit-ruby.rb

@@ -40,39 +40,39 @@ require_relative "closeyourit/rails/error_subscriber"
 require_relative "closeyourit/sidekiq/error_handler"
 require_relative "closeyourit/sidekiq/job_metrics_middleware"
 
-# CloseYourIt — client di telemetria (errori + statistiche di query/metodi lenti)
-# che invia gli eventi all'endpoint di ingest di CloseYourIt.
+# CloseYourIt — telemetry client (errors + slow query/method statistics)
+# that sends events to the CloseYourIt ingest endpoint.
 #
-# Entry point della gemma (file con trattino come `sentry-ruby`):
-# `require "closeyourit-ruby"` carica il modulo `CloseYourIt`.
+# Gem entry point (hyphenated file name, like `sentry-ruby`):
+# `require "closeyourit-ruby"` loads the `CloseYourIt` module.
 module CloseYourIt
-  # Eccezione base interna: usata per evitare loop (le nostre eccezioni non vengono catturate).
+  # Internal base exception: used to avoid loops (our own exceptions are never captured).
   class Error < StandardError; end
 
   CAPTURED_FLAG = :@__closeyourit_captured
 
-  # Flag thread-local che segna "sono già dentro l'hook diagnostico": impedisce che una notifica
-  # emessa DENTRO l'hook (o da codice da esso invocato) rientri e riesegua l'hook → niente loop di
-  # auto-monitoraggio (CYRB-12). È per-thread perché le tappe girano su thread diversi (worker pool
-  # per send/timeout, thread chiamante per enqueue/drop).
+  # Thread-local flag meaning "already inside the diagnostic hook": it stops a notification emitted
+  # INSIDE the hook (or by code it calls) from re-entering and re-running the hook → no
+  # self-monitoring loop (CYRB-12). It is per-thread because the stages run on different threads
+  # (worker pool for send/timeout, calling thread for enqueue/drop).
   DIAGNOSTIC_GUARD = :__closeyourit_in_diagnostic
 
   class << self
-    # Configura il client. Senza token/endpoint → no-op.
+    # Configures the client. Without token/endpoint → no-op.
     #
-    # Una re-init SPEGNE prima il client e il log buffer della configurazione precedente (CYRB-10):
-    # azzerarli e basta lascerebbe orfani il thread del worker pool e il TimerTask del buffer, e gli
-    # eventi ancora in coda andrebbero persi o flushati fuori tempo dal timer orfano con la vecchia
-    # credenziale. Riusa la semantica di fine-vita di #shutdown (flush del buffer → drain del worker
-    # con timeout, CYRB-5) — così la coda precedente è svuotata in modo prevedibile con la sua config.
-    # Idempotente: alla prima init (o senza eventi catturati) @client/@log_buffer sono nil → no-op.
+    # A re-init first SHUTS DOWN the client and log buffer of the previous configuration (CYRB-10):
+    # just clearing them would orphan the worker pool thread and the buffer's TimerTask, and events
+    # still queued would be lost or flushed late by the orphan timer with the old credential. It
+    # reuses the end-of-life semantics of #shutdown (buffer flush → worker drain with timeout,
+    # CYRB-5), so the previous queue is drained predictably with its own config.
+    # Idempotent: on the first init (or with no captured events) @client/@log_buffer are nil → no-op.
     def init
       shutdown
       @configuration = Configuration.new
       @client = nil
       @log_buffer = nil
       @usage_registry = nil
-      @shutdown_notified = false # nuova sessione: :shutdown potrà essere notificato di nuovo
+      @shutdown_notified = false # new session: :shutdown can be notified again
       yield(@configuration) if block_given?
       @configuration.validate!
       register_shutdown_flush
@@ -91,8 +91,8 @@ module CloseYourIt
       configuration.enabled?
     end
 
-    # Cattura un'eccezione e la spedisce (fire-and-forget). No-op se disabilitato,
-    # se l'eccezione è esclusa o già catturata.
+    # Captures an exception and sends it (fire-and-forget). No-op when disabled,
+    # or when the exception is excluded or already captured.
     def capture_exception(exception, handled: false, level: "error", contexts: nil)
       return nil if in_diagnostic?
       return nil unless enabled?
@@ -108,7 +108,7 @@ module CloseYourIt
       client.capture_event(event)
     end
 
-    # Spedisce un evento già costruito (slow_query/slow_method).
+    # Sends an already built event (slow_query/slow_method).
     def capture_event(event)
       return nil if in_diagnostic?
       return nil unless enabled?
@@ -116,7 +116,7 @@ module CloseYourIt
       client.capture_event(event)
     end
 
-    # Invia un messaggio diagnostico esplicito (non un'eccezione). Soggetto a sampling + scope.
+    # Sends an explicit diagnostic message (not an exception). Subject to sampling + scope.
     #   CloseYourIt.capture_message("cache miss storm", level: "warning")
     def capture_message(message, level: "info")
       return nil if in_diagnostic?
@@ -127,14 +127,14 @@ module CloseYourIt
       client.capture_event(event)
     end
 
-    # Cronometra un blocco e invia un slow_method se supera la soglia.
+    # Times a block and sends a slow_method if it exceeds the threshold.
     #   CloseYourIt.measure("checkout.total") { ... }
     def measure(label, &block)
       Instrumenter.measure(label, &block)
     end
 
-    # --- Scope per-richiesta/job (user/tags/extra/contexts) ---
-    # Arricchiscono l'evento corrente; resettati a fine richiesta/job da middleware e estensioni.
+    # --- Per-request/job scope (user/tags/extra/contexts) ---
+    # They enrich the current event; reset at the end of the request/job by middleware and extensions.
 
     def set_user(attributes)
       Scope.current.set_user(attributes)
@@ -164,8 +164,8 @@ module CloseYourIt
       Scope.reset!
     end
 
-    # Aggiunge una briciola di contesto (query, navigazione, evento custom) all'evento corrente.
-    # No-op se breadcrumbs disabilitati; `data` viene scrubato (denylist) prima di essere salvato.
+    # Adds a context breadcrumb (query, navigation, custom event) to the current event.
+    # No-op when breadcrumbs are disabled; `data` is scrubbed (denylist) before being stored.
     def add_breadcrumb(message: nil, category: nil, type: "default", level: "info", data: {})
       return nil unless configuration.breadcrumbs_enabled
 
@@ -175,35 +175,35 @@ module CloseYourIt
       )
     end
 
-    # Logger interno della gemma (warning/errori diagnostici su stdout). NON è il logging applicativo:
-    # per spedire log strutturati a CloseYourIt usa `CloseYourIt.log` / `CloseYourIt.logger`.
+    # The gem's internal logger (diagnostic warnings/errors on stdout). It is NOT application logging:
+    # to send structured logs to CloseYourIt use `CloseYourIt.log` / `CloseYourIt.logger`.
     def internal_logger
       @internal_logger ||= default_internal_logger
     end
 
     attr_writer :internal_logger
 
-    # Logger applicativo Logger-compatibile: inoltra ogni messaggio a `CloseYourIt.log` (→ ingest /logs).
+    # Logger-compatible application logger: forwards every message to `CloseYourIt.log` (→ ingest /logs).
     #   CloseYourIt.logger.info("ordine creato", order_id: 1)
     def logger
       @app_logger ||= LogDevice.new
     end
 
-    # API esplicita: costruisce e bufferizza una voce di log strutturata (batch verso /logs,
-    # fire-and-forget). Il `level` è normalizzato ai livelli canonici (`:warn`→`warning`, downcase;
-    # ignoto→`info`). Il keyword `logger:` = nome della sorgente del log; ogni altra keyword è un
-    # attributo dati. I log sotto `logs_min_level` sono scartati con la stessa mappa numerica di
-    # dart/js (regola standardize, not adapt — CYRB-6): niente costruzione né invio.
+    # Explicit API: builds and buffers a structured log entry (batched to /logs, fire-and-forget).
+    # `level` is normalized to the canonical levels (`:warn`→`warning`, downcase; unknown→`info`).
+    # The `logger:` keyword = name of the log source; every other keyword is a data attribute.
+    # Logs below `logs_min_level` are dropped with the same numeric map as dart/js
+    # (standardize, not adapt rule — CYRB-6): nothing is built or sent.
     #   CloseYourIt.log(:info, "ordine creato", order_id: 1)
     #   CloseYourIt.log(:warn, "retry", logger: "payments", attempt: 3)
     def log(level, message, logger: nil, **attributes)
       emit_log(level, message, source: logger, attributes: attributes)
     end
 
-    # Percorso a basso livello (gating + costruzione + buffer) con sorgente e attributes SEPARATI e
-    # non-ambigui: usato da `LogDevice` per trattare una chiave `logger` come attributo dati (mai come
-    # sorgente) e per impostare la sorgente solo via `.named` (child logger, parità dart/js — CYRB-8).
-    # Le app usano `CloseYourIt.log` / `CloseYourIt.logger`.
+    # Low-level path (gating + building + buffer) with SEPARATE, unambiguous source and attributes:
+    # used by `LogDevice` to treat a `logger` key as a data attribute (never as the source) and to set
+    # the source only via `.named` (child logger, dart/js parity — CYRB-8).
+    # Apps use `CloseYourIt.log` / `CloseYourIt.logger`.
     def emit_log(level, message, source: nil, attributes: {})
       return nil if in_diagnostic?
       return nil unless logs_enabled?
@@ -216,26 +216,26 @@ module CloseYourIt
       nil
     end
 
-    # Vero se i log sono attivi (master switch + flag): usato da LogDevice per NON valutare i block
-    # costosi (`logger.debug { dump }`) quando il logging è spento.
+    # True when logs are active (master switch + flag): used by LogDevice to NOT evaluate expensive
+    # blocks (`logger.debug { dump }`) when logging is off.
     def logs_active?
       logs_enabled?
     end
 
-    # Vero se una riga del broadcast Rails.logger va scartata: nomina un'eccezione già presente in
-    # `excluded_exceptions`, oppure combacia con `excluded_log_patterns`.
+    # True when a line of the Rails.logger broadcast must be dropped: it names an exception already
+    # listed in `excluded_exceptions`, or it matches `excluded_log_patterns`.
     #
-    # Serve perché un'eccezione esclusa dal canale ERRORI rientrava da quello dei LOG: Rails la
-    # registra con `logger.error`, il broadcast inoltrava la riga senza guardarla, e il rumore che
-    # `excluded_exceptions` aveva appena scartato ricompariva come log-entry. Il 2026-07-30 erano
-    # 48.000 voci su 49.985 nello stream, quasi tutte `ActionController::RoutingError` da favicon
-    # mancanti e scansioni di bot — che è nella lista di default dalla prima riga (CYRB-17).
+    # Needed because an exception excluded from the ERRORS channel came back through the LOGS one:
+    # Rails records it with `logger.error`, the broadcast forwarded the line without looking at it,
+    # and the noise `excluded_exceptions` had just dropped reappeared as a log entry. On 2026-07-30
+    # it was 48,000 entries out of 49,985 in the stream, almost all `ActionController::RoutingError`
+    # from missing favicons and bot scans — which has been in the default list from day one (CYRB-17).
     #
-    # `ignored_exception?` non è applicabile: qui la classe arriva come TESTO dentro il messaggio, non
-    # come oggetto con `ancestors` da confrontare. Da cui il match per sottostringa sui matcher String.
+    # `ignored_exception?` does not apply: here the class arrives as TEXT inside the message, not as
+    # an object with `ancestors` to compare. Hence the substring match on String matchers.
     #
-    # Vale SOLO per il mirror automatico di Rails.logger: un `CloseYourIt.log` scritto di proposito
-    # dallo sviluppatore non si silenzia mai (chi lo scrive ha già deciso che vuole quella riga).
+    # It applies ONLY to the automatic Rails.logger mirror: a `CloseYourIt.log` written on purpose by
+    # the developer is never silenced (whoever writes it has already decided they want that line).
     def ignored_log_message?(text)
       text = text.to_s
       return false if text.empty?
@@ -245,7 +245,7 @@ module CloseYourIt
         if matcher.is_a?(Regexp)
           matcher.match?(text)
         else
-          # Un matcher vuoto combacerebbe con qualunque riga: mai silenziare tutto per una lista sporca.
+          # An empty matcher would match any line: never silence everything because of a dirty list.
           !matcher.empty? && text.include?(matcher)
         end
       end
@@ -253,27 +253,27 @@ module CloseYourIt
       named || config.excluded_log_patterns.any? { |pattern| pattern.match?(text) }
     end
 
-    # Forza l'invio dei log bufferizzati (chiamato anche allo shutdown del processo).
+    # Forces sending of buffered logs (also called at process shutdown).
     def flush_logs
       @log_buffer&.flush
       nil
     end
 
-    # Flush di fine-vita: svuota i log bufferizzati E drena il worker asincrono, attendendo (fino a un
-    # timeout breve) che gli invii in volo verso l'ingest completino. Solo flushare il buffer li
-    # accoderebbe nel worker che verrebbe poi ucciso alla terminazione → log persi (CYRB-5). Drena
-    # TUTTO il worker (log + errori + metriche fire-and-forget), non solo i log. Registrato su at_exit
-    # da CloseYourIt.init; con `config.trap_signals` viene raggiunto anche su SIGTERM. Idempotente:
-    # richiamarlo è sicuro (buffer già vuoto, worker già fermo → no-op).
+    # End-of-life flush: empties the buffered logs AND drains the async worker, waiting (up to a short
+    # timeout) for in-flight sends to the ingest to complete. Only flushing the buffer would queue
+    # them in the worker, which is then killed on termination → lost logs (CYRB-5). It drains the
+    # WHOLE worker (logs + errors + fire-and-forget metrics), not only logs. Registered on at_exit by
+    # CloseYourIt.init; with `config.trap_signals` it is also reached on SIGTERM. Idempotent: calling
+    # it again is safe (buffer already empty, worker already stopped → no-op).
     def shutdown
-      # Ordine critico: prima i buffer (accodano l'ultimo batch nel worker), poi il worker (li drena).
+      # Order matters: buffers first (they queue the last batch in the worker), then the worker (drains them).
       @usage_registry&.shutdown
       @log_buffer&.shutdown
       @client&.shutdown
-      # Riepilogo di fine-vita: l'app riceve lo snapshot dei contatori senza log rumorosi. Emesso una
-      # sola volta per sessione (uno shutdown esplicito seguito dall'at_exit non deve duplicarlo; il
-      # flag è azzerato a ogni init). Lo snapshot è best-effort: eventuali invii ancora in volo oltre il
-      # breve timeout di drain possono non esservi riflessi — il drain non blocca l'uscita (CYRB-5).
+      # End-of-life summary: the app receives the counters snapshot without noisy logs. Emitted once
+      # per session (an explicit shutdown followed by the at_exit must not duplicate it; the flag is
+      # reset on every init). The snapshot is best-effort: sends still in flight beyond the short
+      # drain timeout may not be reflected — the drain does not block exit (CYRB-5).
       unless @shutdown_notified
         @shutdown_notified = true
         notify_diagnostic(:shutdown, stats: stats.to_h)
@@ -281,35 +281,35 @@ module CloseYourIt
       nil
     end
 
-    # Ripristina le risorse di invio in un processo figlio dopo un fork. Chiamalo dai worker hook dei
-    # server che forkano (Puma `on_worker_boot`, Sidekiq/Unicorn `after_fork`) per ricreare SUBITO worker
-    # pool e log buffer nel figlio, invece di attendere la rilevazione lazy al primo evento. Opzionale:
-    # la gemma rileva comunque il cambio PID da sé (vedi #ensure_current_process!). Idempotente e sicuro
-    # anche se client/buffer non sono ancora stati materializzati (→ no-op, verranno creati lazy).
+    # Restores the sending resources in a child process after a fork. Call it from the worker hooks of
+    # forking servers (Puma `on_worker_boot`, Sidekiq/Unicorn `after_fork`) to recreate the worker pool
+    # and log buffer in the child RIGHT AWAY, instead of waiting for lazy detection on the first event.
+    # Optional: the gem detects the PID change on its own anyway (see #ensure_current_process!).
+    # Idempotent and safe even if client/buffer were not materialized yet (→ no-op, created lazily).
     def after_fork
       discard_inherited_client!
       @pid = Process.pid
       nil
     end
 
-    # Contatori diagnostici del client (accodati/scartati/spediti/falliti/timeout).
+    # Client diagnostic counters (enqueued/dropped/sent/failed/timeout).
     #   CloseYourIt.stats.to_h # => { enqueued: …, dropped: …, sent: …, failed: …, timeout: … }
     def stats
       @stats ||= Stats.new
     end
 
-    # Notifica una tappa del ciclo di vita di un evento all'hook `on_diagnostic` (se configurato).
-    # `event` è uno tra :enqueue, :send, :drop, :timeout, :shutdown; `details` un Hash privo di dati
-    # sensibili (es. `{ reason: :queue_full }`, `{ status: 429 }`). Chiamato da Client/Transport/
-    # BackgroundWorker/LogBuffer. Garanzie (CYRB-12):
-    #   * NON invia telemetria: tocca solo l'hook dell'app e i contatori in-memory;
-    #   * NON innesca loop di auto-monitoraggio: durante l'hook il guard è alzato, e finché è alzato
-    #     sono soppressi SIA i `notify_diagnostic` annidati SIA le API di telemetria (`capture_*`/log,
-    #     vedi #in_diagnostic?). Poiché l'accodamento della telemetria è sincrono nel thread dell'hook
-    #     (solo l'invio HTTP è async), sopprimere l'accodamento chiude il loop anche cross-thread;
-    #   * NON solleva: un hook difettoso è isolato (logga su internal_logger) e mai propagato nell'app.
-    # L'hook osserva sempre la configurazione CORRENTE: una notifica in volo che completa dopo una
-    # re-init raggiunge l'hook nuovo (best-effort, coerente col modello fire-and-forget).
+    # Notifies a stage of an event's lifecycle to the `on_diagnostic` hook (if configured).
+    # `event` is one of :enqueue, :send, :drop, :timeout, :shutdown; `details` a Hash free of
+    # sensitive data (e.g. `{ reason: :queue_full }`, `{ status: 429 }`). Called by Client/Transport/
+    # BackgroundWorker/LogBuffer. Guarantees (CYRB-12):
+    #   * it does NOT send telemetry: it only touches the app hook and the in-memory counters;
+    #   * it does NOT trigger self-monitoring loops: during the hook the guard is raised, and while it
+    #     is raised BOTH nested `notify_diagnostic` calls AND the telemetry APIs (`capture_*`/log, see
+    #     #in_diagnostic?) are suppressed. Since telemetry enqueueing is synchronous on the hook's
+    #     thread (only the HTTP send is async), suppressing enqueueing closes the loop cross-thread too;
+    #   * it does NOT raise: a faulty hook is isolated (logs to internal_logger), never propagated.
+    # The hook always sees the CURRENT configuration: an in-flight notification completing after a
+    # re-init reaches the new hook (best-effort, consistent with the fire-and-forget model).
     def notify_diagnostic(event, **details)
       hook = configuration.on_diagnostic
       return nil if hook.nil?
@@ -326,15 +326,15 @@ module CloseYourIt
       nil
     end
 
-    # CYSK-29 — il registro della telemetria d'uso (una lookup + increment sul percorso caldo).
+    # CYSK-29 — the usage telemetry registry (one lookup + increment on the hot path).
     def usage_registry
       ensure_current_process!
       @usage_registry ||= UsageRegistry.new(client: client, configuration: configuration)
     end
 
-    # CYSK-29 — dichiara che un pezzo di codice è stato ESEGUITO. `key` deve essere una stringa
-    # LETTERALE (mai interpolata con dati): è l'unico modo onesto di rispondere a «questo ramo viene
-    # mai preso?». No-op se la gemma non è configurata o usage_enabled è OFF.
+    # CYSK-29 — declares that a piece of code was EXECUTED. `key` must be a LITERAL string (never
+    # interpolated with data): it is the only honest way to answer "is this branch ever taken?".
+    # No-op when the gem is not configured or usage_enabled is OFF.
     def used(key)
       return nil unless configured? && enabled?
 
@@ -344,14 +344,14 @@ module CloseYourIt
 
     private
 
-    # Vero se il thread corrente sta eseguendo l'hook diagnostico: le API di telemetria diventano no-op
-    # per impedire che un hook (mal scritto) generi altra telemetria e inneschi auto-monitoraggio.
+    # True when the current thread is running the diagnostic hook: the telemetry APIs become no-ops
+    # so a (badly written) hook cannot generate more telemetry and trigger self-monitoring.
     def in_diagnostic?
       Thread.current[DIAGNOSTIC_GUARD] == true
     end
 
-    # Registra uno scarto: incrementa il contatore aggregato `dropped` e notifica `:drop` con il motivo
-    # (queue_full/before_send/sampled/error). Un unico punto tiene allineati snapshot e hook.
+    # Records a drop: increments the aggregate `dropped` counter and notifies `:drop` with the reason
+    # (queue_full/before_send/sampled/error). A single place keeps snapshot and hook aligned.
     def record_drop(reason, **details)
       stats.increment(:dropped)
       notify_diagnostic(:drop, reason: reason, **details)
@@ -369,43 +369,43 @@ module CloseYourIt
     end
 
 
-    # Rileva un fork confrontando il PID del processo in cui @client/@log_buffer sono stati materializzati
-    # con quello corrente. In un figlio forkato i due oggetti sono ereditati dal padre, ma i loro thread
-    # — il worker pool di Client e il TimerTask di LogBuffer — vivono solo nel padre (il fork copia il
-    # solo thread chiamante): gli eventi accodati non partirebbero mai, restando affidati a thread che
-    # esistono soltanto nel padre. Al cambio di PID abbandoniamo i riferimenti ereditati SENZA #shutdown
-    # (nessun join possibile sui thread del padre, e un flush del buffer rispedirebbe eventi del padre) →
-    # i getter li ricreano lazy sotto il processo corrente. Nel padre lo stato resta invariato.
+    # Detects a fork by comparing the PID of the process where @client/@log_buffer were materialized
+    # with the current one. In a forked child both objects are inherited from the parent, but their
+    # threads — the Client worker pool and the LogBuffer TimerTask — live only in the parent (fork
+    # copies only the calling thread): queued events would never leave, being left to threads that
+    # exist only in the parent. On a PID change we drop the inherited references WITHOUT #shutdown
+    # (no join is possible on the parent's threads, and a buffer flush would resend the parent's
+    # events) → the getters recreate them lazily under the current process. The parent is unchanged.
     def ensure_current_process!
       pid = Process.pid
       return if @pid == pid
 
-      discard_inherited_client! if @pid # non alla prima materializzazione (@pid nil): nulla da abbandonare
+      discard_inherited_client! if @pid # not on first materialization (@pid nil): nothing to drop
       @pid = pid
     end
 
-    # Sgancia i riferimenti a client e log buffer senza drenarli. Usato sia dalla rilevazione lazy del
-    # fork sia da #after_fork: nel figlio i thread sottostanti non esistono, quindi non c'è nulla da
-    # joinare e non si deve flushare (rispedirebbe gli eventi del padre). Il GC raccoglie i vecchi
-    # oggetti; i getter ne creano di nuovi al prossimo accesso.
+    # Releases the client and log buffer references without draining them. Used both by lazy fork
+    # detection and by #after_fork: in the child the underlying threads do not exist, so there is
+    # nothing to join and nothing must be flushed (it would resend the parent's events). GC collects
+    # the old objects; the getters create new ones on the next access.
     def discard_inherited_client!
       @client = nil
       @log_buffer = nil
       @usage_registry = nil
     end
 
-    # I log seguono il master switch del client + il proprio flag dedicato.
+    # Logs follow the client master switch + their own dedicated flag.
     def logs_enabled?
       enabled? && configuration.logs_enabled
     end
 
-    # Gating per soglia: il log è scartato se la sua severità è sotto `logs_min_level`. La severità è
-    # la mappa numerica di LogEvent (debug=0 … fatal=4), identica cross-SDK → filtra come dart/js.
+    # Threshold gating: the log is dropped when its severity is below `logs_min_level`. Severity is
+    # LogEvent's numeric map (debug=0 … fatal=4), identical across SDKs → filters like dart/js.
     def log_below_min_level?(level)
       LogEvent.severity(level) < LogEvent.severity(configuration.logs_min_level)
     end
 
-    # Sampling indipendente dei log (1.0 = tutti, 0.0 = nessuno).
+    # Independent log sampling (1.0 = all, 0.0 = none).
     def logs_sampled?
       rate = configuration.logs_sample_rate.to_f
       return true if rate >= 1.0
@@ -414,16 +414,16 @@ module CloseYourIt
       Random.rand < rate
     end
 
-    # Allo shutdown del processo svuota i log bufferizzati e drena il worker asincrono. Senza, i log
-    # sotto-batch dei processi brevi (rake/CLI) e gli ultimi eventi accodati andrebbero persi all'uscita.
-    # Con `config.trap_signals` intercetta anche SIGTERM, che di default salta gli at_exit (deploy/Kamal
-    # perderebbero il flush). Vedi #shutdown (CYRB-5).
+    # At process shutdown, empties the buffered logs and drains the async worker. Without it, the
+    # sub-batch logs of short processes (rake/CLI) and the last queued events would be lost on exit.
+    # With `config.trap_signals` it also intercepts SIGTERM, which skips at_exit by default
+    # (deploy/Kamal would lose the flush). See #shutdown (CYRB-5).
     #
-    # L'at_exit si registra una sola volta per processo (@shutdown_registered evita N flush da init
-    # multiple), ma il trap SIGTERM è valutato PRIMA del guard e a OGNI init: deve seguire la config
-    # CORRENTE, altrimenti una init che attiva `trap_signals` dopo una prima con la flag OFF non lo
-    # installerebbe mai (il guard di idempotenza ritornerebbe prima). `Signal.trap` è idempotente →
-    # reinstallare lo stesso handler è innocuo.
+    # The at_exit is registered once per process (@shutdown_registered avoids N flushes from multiple
+    # inits), but the SIGTERM trap is evaluated BEFORE the guard and on EVERY init: it must follow the
+    # CURRENT config, otherwise an init enabling `trap_signals` after a first one with the flag OFF
+    # would never install it (the idempotency guard would return first). `Signal.trap` is idempotent
+    # → reinstalling the same handler is harmless.
     def register_shutdown_flush
       install_term_trap if configuration.trap_signals
 
@@ -433,17 +433,17 @@ module CloseYourIt
       at_exit { shutdown }
     end
 
-    # SIGTERM termina il processo SENZA eseguire gli at_exit → il flush di fine-vita non girerebbe.
-    # Convertiamo TERM in un exit pulito: `exit` solleva SystemExit sul thread principale, che ESEGUE
-    # gli at_exit (incluso #shutdown) in contesto normale — niente lavoro pesante nel trap handler
-    # (Mutex/wait_for_termination in trap context solleverebbero ThreadError). Opt-in: sovrascrive un
-    # eventuale handler TERM dell'app ospite.
+    # SIGTERM ends the process WITHOUT running at_exit → the end-of-life flush would not run.
+    # We turn TERM into a clean exit: `exit` raises SystemExit on the main thread, which RUNS the
+    # at_exit hooks (including #shutdown) in normal context — no heavy work in the trap handler
+    # (Mutex/wait_for_termination in trap context would raise ThreadError). Opt-in: it overrides any
+    # TERM handler of the host app.
     def install_term_trap
       Signal.trap("TERM") { exit }
     rescue ArgumentError, RuntimeError => e
-      # Contesti dove TERM non è trap-abile (piattaforma senza TERM, thread non-main): non fatale,
-      # resta comunque l'at_exit per le uscite normali.
-      internal_logger.warn("CloseYourIt: trap SIGTERM non installato (#{e.class}: #{e.message})")
+      # Contexts where TERM cannot be trapped (platform without TERM, non-main thread): not fatal,
+      # the at_exit still covers normal exits.
+      internal_logger.warn("CloseYourIt: SIGTERM trap not installed (#{e.class}: #{e.message})")
     end
 
     def ignored_exception?(exception)
@@ -459,7 +459,7 @@ module CloseYourIt
       end
     end
 
-    # Sampling probabilistico: 1.0 invia sempre, 0.0 mai, intermedio via Random.rand.
+    # Probabilistic sampling: 1.0 always sends, 0.0 never, in between via Random.rand.
     def sampled?
       rate = configuration.sample_rate.to_f
       return true if rate >= 1.0
@@ -485,5 +485,5 @@ module CloseYourIt
   end
 end
 
-# Integrazione Rails automatica (solo se Rails è presente).
+# Automatic Rails integration (only when Rails is present).
 require_relative "closeyourit/rails/railtie" if defined?(::Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: closeyourit-ruby
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Alessio Bussolari
@@ -62,6 +62,7 @@ files:
 - lib/closeyourit/events/slow_method_event.rb
 - lib/closeyourit/events/slow_query_event.rb
 - lib/closeyourit/instrumenter.rb
+- lib/closeyourit/job_context.rb
 - lib/closeyourit/line_cache.rb
 - lib/closeyourit/log_buffer.rb
 - lib/closeyourit/log_device.rb