closeyourit-ruby 0.10.0 → 0.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bc659e436ad9b08b9861d4898e6876a3b753ec88ebb7f8e81075729d958fcb4
-  data.tar.gz: 2bb509651ce4aa880a40f2d49f29c9584bb1bfde984b6fba3065c1a954800f82
+  metadata.gz: 866fd0b6c34af299e0e538ddb181b1f6b3fd961da1e638226a81ad8b8ea15c0b
+  data.tar.gz: eaf0d4530e9015f7353790aeffe104f04a2f80d46c4c7622ad7dad3302bd75fe
 SHA512:
-  metadata.gz: d3cfd52ac4b7ddda5a5a92485ebe1fb4be25b808e706b11af7c5e0c6767fff19af3aa3958a8a3d9e6d94ec6ec36162a942fa439700bd16d07d52987d34a4328e
-  data.tar.gz: fe22c4cae5a0e94f4eeaf8284d00c0a42d51a0d8c3830dcd703abcf9774eaf31c4e5e81c0c4b8ba6331a1e3d331078136b2cf05e09316325c5f545acaa8b9c17
+  metadata.gz: b4193d36f1123b89bdf11998ebcd5ea445b0b84c325ccae654d434d2d94158d6dd9c920b0e879167f0fba5cbaa7615f42a3d2cd11f3f61d8ade9f3eaee18917f
+  data.tar.gz: 7a4d366fbf67b5720d878e2e1febbcda5500c6063d8f654e450c10b68789964a7c8b15390e23d4516d9220ea6cb2ffbde619900ec2871fe7b8b20fd23c967b8b

data/lib/closeyourit/background_worker.rb

@@ -3,9 +3,9 @@
 require "concurrent"
 
 module CloseYourIt
-  # Esegue l'invio fire-and-forget. Con `threads == 0` esegue sincrono (test/dev);
-  # altrimenti usa una thread-pool con coda bounded e `fallback_policy: :discard`
-  # (se la coda è piena l'evento si perde, mai backpressure sulla request).
+  # Runs the send fire-and-forget. With `threads == 0` it runs synchronously (test/dev);
+  # otherwise it uses a thread pool with a bounded queue and `fallback_policy: :discard`
+  # (when the queue is full the event is lost, never backpressure on the request).
   class BackgroundWorker
     attr_reader :executor
 
@@ -13,29 +13,29 @@ module CloseYourIt
       @executor = build_executor(threads.to_i, max_queue)
     end
 
-    # Ritorna true se l'evento è stato accettato (o eseguito sincrono), false se scartato
-    # perché la coda era piena (`fallback_policy: :discard`). Mai backpressure sulla request.
+    # Returns true if the event was accepted (or run synchronously), false if dropped
+    # because the queue was full (`fallback_policy: :discard`). Never backpressure on the request.
     def perform(&block)
       accepted = @executor.post do
         block.call
       rescue Exception => e # rubocop:disable Lint/RescueException
-        # Mai propagare: la telemetria non deve poter crashare l'app ospite.
+        # Never propagate: telemetry must not be able to crash the host app.
         CloseYourIt.internal_logger.error("CloseYourIt background worker: #{e.class}: #{e.message}")
       end
 
       unless accepted
         CloseYourIt.stats.increment(:dropped)
-        CloseYourIt.internal_logger.warn("CloseYourIt background worker: coda piena, evento scartato")
+        CloseYourIt.internal_logger.warn("CloseYourIt background worker: queue full, event dropped")
         CloseYourIt.notify_diagnostic(:drop, reason: :queue_full)
       end
 
       accepted
     end
 
-    # Drena la coda attendendo fino a `timeout` secondi. Il default è il tetto di durata di UNA POST
-    # (Transport::MAX_REQUEST_SECONDS): aspettare meno abbandona invii ancora sani, ed è quello che
-    # succedeva con il vecchio secondo fisso (CYRB-24). Se il drain scade, i task rimasti in coda sono
-    # persi: contali come `dropped`, altrimenti lo snapshot di fine vita dichiara zero perdite.
+    # Drains the queue waiting up to `timeout` seconds. The default is the duration cap of ONE POST
+    # (Transport::MAX_REQUEST_SECONDS): waiting less abandons still healthy sends, which is what
+    # happened with the old fixed one second (CYRB-24). If the drain expires, the tasks left in the
+    # queue are lost: count them as `dropped`, otherwise the end-of-life snapshot reports zero losses.
     def shutdown(timeout = Transport::MAX_REQUEST_SECONDS)
       return unless @executor.respond_to?(:shutdown)
 
@@ -47,12 +47,12 @@ module CloseYourIt
 
     private
 
-    # Task accodati e mai eseguiti al momento della scadenza del drain. `queue_length` non esiste
-    # sull'ImmediateExecutor (sincrono, niente coda) → zero residui.
+    # Tasks queued and never run when the drain expired. `queue_length` does not exist on the
+    # ImmediateExecutor (synchronous, no queue) → zero left over.
     def report_abandoned(timeout)
       abandoned = @executor.respond_to?(:queue_length) ? @executor.queue_length.to_i : 0
       CloseYourIt.internal_logger.warn(
-        "CloseYourIt background worker: drain scaduto dopo #{timeout}s, #{abandoned} eventi abbandonati"
+        "CloseYourIt background worker: drain expired after #{timeout}s, #{abandoned} events abandoned"
       )
       abandoned.times do
         CloseYourIt.stats.increment(:dropped)

data/lib/closeyourit/breadcrumb.rb

@@ -3,8 +3,8 @@
 require "time"
 
 module CloseYourIt
-  # Singola briciola di contesto (query, navigazione, evento custom) precedente a un errore.
-  # Forma evento Sentry (`breadcrumbs.values[]`). Il `data` è già scrubato a monte (module API).
+  # A single context breadcrumb (query, navigation, custom event) preceding an error.
+  # Sentry event shape (`breadcrumbs.values[]`). `data` is already scrubbed upstream (module API).
   class Breadcrumb
     def initialize(message: nil, category: nil, type: "default", level: "info", data: {}, timestamp: nil)
       @timestamp = timestamp || Time.now.utc.iso8601

data/lib/closeyourit/breadcrumb_buffer.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module CloseYourIt
-  # Ring buffer limitato di breadcrumb. Vive nello Scope (un buffer per execution-context),
-  # scritto solo dal thread proprietario → niente mutex. Oltre `max_size` droppa il più vecchio.
+  # Bounded breadcrumb ring buffer. It lives in the Scope (one buffer per execution context),
+  # written only by the owning thread → no mutex. Beyond `max_size` it drops the oldest.
   class BreadcrumbBuffer
     def initialize(max_size)
       @max_size = max_size.to_i

data/lib/closeyourit/client.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module CloseYourIt
-  # Compone Transport + BackgroundWorker: applica `before_send` e dispatcha
-  # l'invio in modo fire-and-forget.
+  # Combines Transport + BackgroundWorker: applies `before_send` and dispatches
+  # the send fire-and-forget.
   class Client
-    # Tetto di log per singola richiesta a /logs. Il backend rifiuta un batch oltre questo limite
-    # (413 R413-LOG-002) scartando l'INTERA richiesta — e il buffer è già stato drenato → log persi.
-    # Deve restare ≤ del limite server (LOGS_MAX_BATCH backend = 1000). Vedi #flush_logs.
+    # Log cap per single request to /logs. The backend rejects a batch beyond this limit
+    # (413 R413-LOG-002) dropping the WHOLE request — and the buffer has already been drained → lost
+    # logs. Must stay ≤ the server limit (backend LOGS_MAX_BATCH = 1000). See #flush_logs.
     LOGS_MAX_BATCH = 1000
 
     def initialize(configuration)
@@ -22,7 +22,7 @@ module CloseYourIt
       payload = event.to_h
       payload = @configuration.before_send.call(payload) if @configuration.before_send
       if payload.nil?
-        # before_send ha scartato l'evento (ritorna nil): scarto voluto, reso visibile (CYRB-12).
+        # before_send dropped the event (returned nil): an intentional drop, made visible (CYRB-12).
         CloseYourIt.stats.increment(:dropped)
         CloseYourIt.notify_diagnostic(:drop, reason: :before_send)
         return nil
@@ -36,21 +36,21 @@ module CloseYourIt
       end
       payload
     rescue StandardError => e
-      # La telemetria non deve MAI propagare nel path dell'app ospite: capture_event è invocato dal
-      # subscriber sql.active_record, che gira nel thread della query. to_h (scrubber su bind
-      # malformato) e before_send sono valutati qui in modo sincrono → se sollevano, assorbiamo,
-      # logghiamo e scartiamo l'evento invece di disturbare la query ospite. Vedi CYRB-2.
+      # Telemetry must NEVER propagate into the host app's path: capture_event is called by the
+      # sql.active_record subscriber, which runs on the query's thread. to_h (scrubber on a malformed
+      # bind) and before_send are evaluated here synchronously → if they raise, we absorb, log and
+      # drop the event instead of disturbing the host query. See CYRB-2.
       CloseYourIt.internal_logger.error("CloseYourIt client: #{e.class}: #{e.message}")
       CloseYourIt.stats.increment(:dropped)
       CloseYourIt.notify_diagnostic(:drop, reason: :error, error: e.class.name)
       nil
     end
 
-    # Invia un batch di log come ARRAY a /logs (l'endpoint accetta singolo o array). before_send è
-    # applicato a ciascun payload; quelli scartati (nil) non vengono inviati. I payload oltre
-    # LOGS_MAX_BATCH sono spezzati in più POST sequenziali (un chunk = un POST), così un flush grande
-    # non viene rigettato in blocco dal backend e perso — vedi R3 / LOGS_MAX_BATCH. Un flush entro il
-    # limite resta un singolo POST.
+    # Sends a batch of logs as an ARRAY to /logs (the endpoint accepts a single item or an array).
+    # before_send is applied to each payload; dropped ones (nil) are not sent. Payloads beyond
+    # LOGS_MAX_BATCH are split into several sequential POSTs (one chunk = one POST), so a large flush
+    # is not rejected as a whole by the backend and lost — see R3 / LOGS_MAX_BATCH. A flush within
+    # the limit stays a single POST.
     def flush_logs(events)
       return nil if events.nil? || events.empty?
 
@@ -68,8 +68,8 @@ module CloseYourIt
       payloads
     end
 
-    # CYSK-29 — il flush della telemetria d'uso: UNA POST per finestra, payload privo di dati utente
-    # per costruzione (route = Controller#action). Fire-and-forget via worker, come tutto il resto.
+    # CYSK-29 — the usage telemetry flush: ONE POST per window, a payload free of user data by
+    # construction (route = Controller#action). Fire-and-forget via the worker, like everything else.
     def flush_usage(symbols:, truncated:, window_started_at:, window_ended_at:)
       payload = {
         environment: @configuration.environment.to_s,
@@ -90,22 +90,22 @@ module CloseYourIt
 
     private
 
-    # Costruisce il payload di UNA voce di log. `to_h` (scrubber su un byte non UTF-8) e `before_send`
-    # possono sollevare: qui il buffer è già stato drenato, quindi una sola voce rotta valutata
-    # insieme alle altre porterebbe via l'intero batch di voci sane. Ogni voce è isolata e scartata
-    # da sola, come fa il client JS (CYRB-24). `nil` = voce da non spedire, già contabilizzata.
+    # Builds the payload of ONE log entry. `to_h` (scrubber on a non-UTF-8 byte) and `before_send`
+    # may raise: here the buffer has already been drained, so a single broken entry evaluated together
+    # with the others would take the whole batch of healthy entries with it. Each entry is isolated
+    # and dropped on its own, like the JS client does (CYRB-24). `nil` = entry not to send, already counted.
     def build_log_payload(event)
       payload = event.to_h
       payload = @configuration.before_send.call(payload) if @configuration.before_send
       return payload unless payload.nil?
 
-      # Scarto voluto di before_send: contabilizzato come in #capture_event, altrimenti sparirebbe
-      # silenziosamente dai contatori (CYRB-12).
+      # Intentional before_send drop: counted as in #capture_event, otherwise it would silently
+      # disappear from the counters (CYRB-12).
       CloseYourIt.stats.increment(:dropped)
       CloseYourIt.notify_diagnostic(:drop, reason: :before_send)
       nil
     rescue StandardError => e
-      CloseYourIt.internal_logger.error("CloseYourIt client: log scartato — #{e.class}: #{e.message}")
+      CloseYourIt.internal_logger.error("CloseYourIt client: log dropped — #{e.class}: #{e.message}")
       CloseYourIt.stats.increment(:dropped)
       CloseYourIt.notify_diagnostic(:drop, reason: :error, error: e.class.name)
       nil

data/lib/closeyourit/configuration.rb

@@ -4,22 +4,22 @@ require "uri"
 require "concurrent"
 
 module CloseYourIt
-  # Tiene tutte le opzioni del client. Costruita da `CloseYourIt.init { |c| ... }`.
-  # Senza `endpoint_url`/`token`/`project_id` (o con `http://` in produzione) il client è no-op.
+  # Holds all client options. Built by `CloseYourIt.init { |c| ... }`.
+  # Without `endpoint_url`/`token`/`project_id` (or with `http://` in production) the client is a no-op.
   class Configuration
     DEFAULT_EXCLUDED_EXCEPTIONS = %w[
       ActionController::RoutingError
       ActiveRecord::RecordNotFound
     ].freeze
 
-    # Header HTTP catturati nel contesto request (mai Authorization/Cookie → niente PII/segreti).
+    # HTTP headers captured in the request context (never Authorization/Cookie → no PII/secrets).
     DEFAULT_REQUEST_HEADER_ALLOWLIST = %w[Accept Content-Type User-Agent Referer].freeze
 
-    # Tabelle di servizio del Solid stack: sono infrastruttura del framework, non codice
-    # dell'applicazione. Una loro query lenta non si può correggere leggendo il proprio repo — dice
-    # solo che il database è in contesa, cosa che le query dell'app raccontano già. Escluse per
-    # DEFAULT dalla misura dei rallentamenti perché altrimenti la sommergono: su closeyourit-rails il
-    # 2026-07-30 erano circa 2.740 campioni su 4.400 (62%), tutti fra i 250 e i 655 ms (CYRB-18).
+    # Solid stack service tables: they are framework infrastructure, not application code. A slow
+    # query on them cannot be fixed by reading your own repo — it only says the database is under
+    # contention, which the app's queries already show. Excluded by DEFAULT from slowdown measurement
+    # because otherwise they flood it: on closeyourit-rails on 2026-07-30 they were about 2,740
+    # samples out of 4,400 (62%), all between 250 and 655 ms (CYRB-18).
     DEFAULT_EXCLUDED_QUERY_PATTERNS = [
       /\bsolid_queue_/,
       /\bsolid_cache_/,
@@ -57,140 +57,140 @@ module CloseYourIt
       @excluded_exceptions = DEFAULT_EXCLUDED_EXCEPTIONS.dup
       @before_send         = nil
 
-      # Hook diagnostico opt-in: `->(event, details) { ... }` invocato a ogni tappa del ciclo di vita
-      # di un evento (:enqueue, :send, :drop, :timeout, :shutdown) con dettagli privi di dati sensibili
-      # (es. `{ reason: :queue_full }`, `{ status: 429 }`). Locale e non ricorsivo: non invia telemetria
-      # e non può innescare loop di auto-monitoraggio (vedi CloseYourIt.notify_diagnostic, CYRB-12).
+      # Opt-in diagnostic hook: `->(event, details) { ... }` called at every stage of an event's
+      # lifecycle (:enqueue, :send, :drop, :timeout, :shutdown) with details free of sensitive data
+      # (e.g. `{ reason: :queue_full }`, `{ status: 429 }`). Local and non-recursive: it sends no
+      # telemetry and cannot trigger self-monitoring loops (see CloseYourIt.notify_diagnostic, CYRB-12).
       @on_diagnostic = nil
 
       @async_threads               = default_threads
       @background_worker_max_queue  = 30
-      # Quanto attendere, alla chiusura del processo, che gli invii in volo completino. Default: il
-      # tetto di durata di UNA POST, così l'ultimo batch non viene abbandonato a metà (CYRB-24).
-      # Abbassalo se l'uscita del processo deve essere più rapida della consegna.
+      # How long to wait, on process exit, for in-flight sends to complete. Default: the duration cap
+      # of ONE POST, so the last batch is not abandoned halfway (CYRB-24).
+      # Lower it if process exit must be faster than delivery.
       @shutdown_timeout = Transport::MAX_REQUEST_SECONDS
 
-      # Intercetta SIGTERM per garantire il flush di fine-vita (deploy/Kamal): SIGTERM di default
-      # termina il processo SENZA eseguire gli at_exit. OPT-IN perché sovrascrive un eventuale handler
-      # TERM dell'app ospite. Vedi CloseYourIt.shutdown / register_shutdown_flush (CYRB-5).
+      # Intercepts SIGTERM to guarantee the end-of-life flush (deploy/Kamal): by default SIGTERM ends
+      # the process WITHOUT running at_exit. OPT-IN because it overrides any TERM handler of the host
+      # app. See CloseYourIt.shutdown / register_shutdown_flush (CYRB-5).
       @trap_signals = false
 
       @slow_query_threshold_ms  = 100
       @slow_method_threshold_ms = 200
-      # Query da NON misurare come rallentamento (match sul testo SQL). Default: le tabelle di servizio
-      # del Solid stack. Chi vuole misurarle davvero azzera la lista.
+      # Queries NOT to measure as slowdowns (match on the SQL text). Default: the Solid stack service
+      # tables. Whoever really wants to measure them clears the list.
       @excluded_query_patterns = DEFAULT_EXCLUDED_QUERY_PATTERNS.dup
 
       @send_pii         = false
       @obfuscate_sql    = true
       @send_server_name = true
 
-      # Contesto HTTP della richiesta (method/url/header allowlist). Body/query/IP solo con send_pii.
+      # HTTP request context (method/url/header allowlist). Body/query/IP only with send_pii.
       @capture_request          = true
       @request_header_allowlist = DEFAULT_REQUEST_HEADER_ALLOWLIST.dup
 
-      # Righe di sorgente attorno a ogni frame dello stacktrace (pre/context/post). 0 = disattivo.
+      # Source lines around each stacktrace frame (pre/context/post). 0 = disabled.
       @context_lines = 3
 
-      # Params del body della richiesta nell'evento (`request.data`), estratti LAZY solo quando
-      # l'errore accade, sanitizzati e scrubbati (denylist + filter_parameters). Il backend
-      # ri-scruba difensivamente. Upload → placeholder, cap 64 KB.
+      # Request body params in the event (`request.data`), extracted LAZILY only when the error
+      # happens, sanitized and scrubbed (denylist + filter_parameters). The backend scrubs again
+      # defensively. Uploads → placeholder, 64 KB cap.
       @capture_request_body = true
 
-      # Breadcrumbs: cronologia (query offuscate, eventi custom) allegata all'errore.
+      # Breadcrumbs: history (obfuscated queries, custom events) attached to the error.
       @breadcrumbs_enabled = true
       @max_breadcrumbs     = 100
 
-      # Sampling probabilistico di errori/messaggi (1.0 = invia tutto, 0.0 = niente).
+      # Probabilistic sampling of errors/messages (1.0 = send everything, 0.0 = nothing).
       @sample_rate = 1.0
 
-      # Cattura errori handled (Rails.error.report) e degli ActiveJob/Sidekiq (oggi persi).
+      # Captures handled errors (Rails.error.report) and ActiveJob/Sidekiq errors (otherwise lost).
       @capture_handled_errors   = true
       @report_active_job_errors = true
 
-      # Cattura valori dei parametri — opt-in, default OFF (privacy). I bind/argomenti possono contenere PII.
+      # Captures parameter values — opt-in, default OFF (privacy). Binds/arguments may contain PII.
       @capture_query_bindings   = false
       @capture_method_arguments = false
 
-      # Log strutturati (CloseYourIt.log / .logger). Master switch + sampling + batching dedicati.
+      # Structured logs (CloseYourIt.log / .logger). Dedicated master switch + sampling + batching.
       @logs_enabled        = true
       @logs_sample_rate    = 1.0
       @logs_batch_size     = 50
       @logs_flush_interval = 5
 
-      # CYSK-29 — telemetria d'uso: quali rotte/job/chiavi girano davvero. Il payload è privo di
-      # dati utente per costruzione (route = Controller#action, mai l'URL), quindi il default è ON:
-      # trenta giorni di raccolta facoltativa hanno insegnato che facoltativo significa mai.
-      # Il registro si svuota a ogni flush: il tetto limita i simboli DISTINTI per finestra.
+      # CYSK-29 — usage telemetry: which routes/jobs/keys actually run. The payload carries no user
+      # data by construction (route = Controller#action, never the URL), so the default is ON:
+      # thirty days of optional collection taught us that optional means never.
+      # The registry is emptied on every flush: the cap limits DISTINCT symbols per window.
       @usage_enabled        = true
       @usage_flush_interval = 300
       @usage_max_symbols    = 2000
-      # Broadcast opt-in di Rails.logger → CloseYourIt.log (default OFF; spedisce solo ≥ soglia).
+      # Opt-in Rails.logger broadcast → CloseYourIt.log (default OFF; sends only ≥ threshold).
       @capture_rails_logs = false
       @logs_min_level     = :info
-      # Soglia DEDICATA del broadcast Rails.logger, distinta da logs_min_level (che governa
-      # CloseYourIt.log/.logger, dove è il dev a scegliere cosa loggare). Default :warn — conservativo:
-      # senza, in produzione ad alto traffico OGNI riga info del framework (Started GET, Rendered, ...)
-      # inonderebbe lo stream con decine di migliaia di log-entry/min (CYRB-7). Chi vuole anche gli info
-      # del framework la abbassa esplicitamente (es. :info).
+      # DEDICATED threshold of the Rails.logger broadcast, separate from logs_min_level (which governs
+      # CloseYourIt.log/.logger, where the dev chooses what to log). Default :warn — conservative:
+      # without it, in high-traffic production EVERY framework info line (Started GET, Rendered, ...)
+      # would flood the stream with tens of thousands of log entries/min (CYRB-7). Whoever also wants
+      # the framework info lines lowers it explicitly (e.g. :info).
       @capture_rails_logs_min_level = :warn
-      # Rumore del broadcast Rails.logger che NON è un'eccezione, e quindi excluded_exceptions non può
-      # coprire: righe ripetute del framework o di una gemma. Regexp sul testo del messaggio, default
-      # vuoto. Vale SOLO per il broadcast automatico, mai per CloseYourIt.log esplicito.
+      # Rails.logger broadcast noise that is NOT an exception, so excluded_exceptions cannot cover it:
+      # repeated framework or gem lines. Regexp on the message text, empty by default. Applies ONLY
+      # to the automatic broadcast, never to an explicit CloseYourIt.log.
       @excluded_log_patterns = []
 
-      # Performance issue detection (verdetti aggregati: N+1, slow request, HTTP esterne lente).
-      # OPT-IN, default OFF: profila OGNI query della richiesta → overhead non trascurabile, va attivato
-      # consapevolmente per-app. Le soglie sono conservative (poco rumore). Vedi Performance::Rollup.
+      # Performance issue detection (aggregate verdicts: N+1, slow request, slow external HTTP).
+      # OPT-IN, default OFF: it profiles EVERY query of the request → non-negligible overhead, enable it
+      # deliberately per app. Thresholds are conservative (little noise). See Performance::Rollup.
       @detect_performance_issues = false
-      @n_plus_one_threshold      = 10        # stesso fingerprint+call-site eseguito > N volte in una richiesta
-      @query_count_threshold     = 100       # troppe query totali in una richiesta
-      @query_time_threshold_ms   = 500       # tempo DB totale per richiesta oltre cui = high_query_count
-      @slow_request_threshold_ms = 1000      # durata totale della richiesta
-      @slow_external_threshold_ms = 1000     # singola chiamata HTTP esterna
-      @capture_external_http     = true      # strumenta Net::HTTP (solo se detect_performance_issues)
-
-      # Metriche dei background job: durata di esecuzione e attesa in coda (queue latency) per ActiveJob
-      # e Sidekiq. ON di default (a differenza di detect_performance_issues): la visibilità dei job
-      # lenti/in ritardo/ritentati non deve richiedere strumentazione manuale in ogni app (CYRB-14), e
-      # l'overhead è basso — una notifica per job, non il profiling di ogni query. Il rumore è tenuto a
-      # bada dalle soglie (job normali sotto soglia = niente metrica) e dal sampling. La label è il nome
-      # della classe del job; gli argomenti non vengono MAI inviati.
+      @n_plus_one_threshold      = 10        # same fingerprint+call-site run > N times in one request
+      @query_count_threshold     = 100       # too many total queries in one request
+      @query_time_threshold_ms   = 500       # total DB time per request beyond which = high_query_count
+      @slow_request_threshold_ms = 1000      # total request duration
+      @slow_external_threshold_ms = 1000     # single external HTTP call
+      @capture_external_http     = true      # instruments Net::HTTP (only with detect_performance_issues)
+
+      # Background job metrics: execution duration and queue wait (queue latency) for ActiveJob and
+      # Sidekiq. ON by default (unlike detect_performance_issues): visibility of slow/late/retried jobs
+      # must not require manual instrumentation in every app (CYRB-14), and the overhead is low — one
+      # notification per job, not profiling of every query. Noise is kept down by the thresholds
+      # (normal jobs under threshold = no metric) and by sampling. The label is the job class name;
+      # arguments are NEVER sent.
       @monitor_jobs                   = true
-      @slow_job_threshold_ms          = 5000     # durata del perform oltre cui = slow_job
-      @job_queue_latency_threshold_ms = 60_000   # attesa enqueue→esecuzione oltre cui = job_queue_latency
-      @jobs_sample_rate               = 1.0      # frazione dei candidati oltre soglia effettivamente inviata
-
-      # Propagazione W3C trace context (traceparent/tracestate) verso i servizi esterni chiamati via
-      # Net::HTTP. OPT-IN, default OFF: iniettare header d'uscita attraversa un trust boundary e va deciso
-      # per-app. È limitata PER DESTINAZIONE dalla allowlist (host esatti, case-insensitive, o Regexp per i
-      # sottodomini); lista vuota = nessuna destinazione. Mai verso host non elencati, mai come `baggage`
-      # (che può portare PII). In ingresso un traceparent valido diventa il trace_id degli eventi
-      # CloseYourIt → gli errori/metriche della richiesta si correlano alla traccia distribuita (CYRB-15).
+      @slow_job_threshold_ms          = 5000     # perform duration beyond which = slow_job
+      @job_queue_latency_threshold_ms = 60_000   # enqueue→execution wait beyond which = job_queue_latency
+      @jobs_sample_rate               = 1.0      # fraction of over-threshold candidates actually sent
+
+      # W3C trace context propagation (traceparent/tracestate) to external services called via
+      # Net::HTTP. OPT-IN, default OFF: injecting outgoing headers crosses a trust boundary and must be
+      # decided per app. It is limited PER DESTINATION by the allowlist (exact hosts, case-insensitive,
+      # or Regexp for subdomains); empty list = no destination. Never to unlisted hosts, never as
+      # `baggage` (which may carry PII). Inbound, a valid traceparent becomes the trace_id of the
+      # CloseYourIt events → the request's errors/metrics correlate with the distributed trace (CYRB-15).
       @propagate_trace_context     = false
       @trace_propagation_allowlist = []
 
-      # Radice del progetto: base per il filename relativo dei frame (culprit cross-SDK). Lazy:
-      # auto-rilevata da Rails.root o Dir.pwd al primo accesso se non impostata esplicitamente.
+      # Project root: base for the relative frame filename (cross-SDK culprit). Lazy: auto-detected
+      # from Rails.root or Dir.pwd on first access when not set explicitly.
       @project_root = nil
 
       @filter_parameters      = []
       @scrub_message_patterns = []
     end
 
-    # Classi/stringhe → nome (String); i Regexp restano Regexp (match per pattern su nome/messaggio).
+    # Classes/strings → name (String); Regexps stay Regexps (pattern match on name/message).
     def excluded_exceptions=(list)
       @excluded_exceptions = Array(list).map { |item| item.is_a?(Regexp) ? item : item.to_s }
     end
 
-    # Pattern del broadcast Rails.logger da scartare. Le stringhe diventano Regexp (match letterale
-    # sul testo): chi scrive `config.excluded_log_patterns = ["Rendered layout"]` intende quello.
+    # Rails.logger broadcast patterns to drop. Strings become Regexps (literal match on the text):
+    # whoever writes `config.excluded_log_patterns = ["Rendered layout"]` means exactly that.
     def excluded_log_patterns=(list)
       @excluded_log_patterns = Array(list).map { |item| item.is_a?(Regexp) ? item : Regexp.new(Regexp.escape(item.to_s)) }
     end
 
-    # Query da non misurare. Stessa normalizzazione di excluded_log_patterns: String = testo letterale
-    # (un nome di tabella si scrive così, non come pattern), Regexp = pattern.
+    # Queries not to measure. Same normalization as excluded_log_patterns: String = literal text
+    # (a table name is written that way, not as a pattern), Regexp = pattern.
     def excluded_query_patterns=(list)
       @excluded_query_patterns = Array(list).map { |item| item.is_a?(Regexp) ? item : Regexp.new(Regexp.escape(item.to_s)) }
     end
@@ -199,8 +199,8 @@ module CloseYourIt
       @filter_parameters = Array(list)
     end
 
-    # Destinazioni autorizzate a ricevere gli header di trace W3C. String = host esatto (match
-    # case-insensitive), Regexp = pattern (per sottodomini/famiglie di host). Lista vuota = nessuno.
+    # Destinations allowed to receive the W3C trace headers. String = exact host (case-insensitive
+    # match), Regexp = pattern (for subdomains/host families). Empty list = none.
     def trace_propagation_allowlist=(list)
       @trace_propagation_allowlist = Array(list)
     end
@@ -213,8 +213,8 @@ module CloseYourIt
       environment.to_s == "production"
     end
 
-    # Il client invia solo con credenziali complete (endpoint + token + project_id) e trasporto
-    # sicuro (http:// ammesso fuori produzione).
+    # The client sends only with complete credentials (endpoint + token + project_id) and a secure
+    # transport (http:// allowed outside production).
     def enabled?
       return false if blank?(endpoint_url) || blank?(token) || blank?(project_id)
       return false if insecure_endpoint? && production?
@@ -222,8 +222,8 @@ module CloseYourIt
       true
     end
 
-    # Logga i warning di configurazione (es. endpoint http://, project_id/endpoint malformati).
-    # Non solleva mai: coerente con la filosofia no-op del client. Chiamata da `CloseYourIt.init`.
+    # Logs configuration warnings (e.g. http:// endpoint, malformed project_id/endpoint).
+    # Never raises: consistent with the client's no-op philosophy. Called by `CloseYourIt.init`.
     def validate!
       CloseYourIt.internal_logger.warn(insecure_endpoint_message) if insecure_endpoint?
       CloseYourIt.internal_logger.warn(malformed_project_id_message) if malformed_project_id?
@@ -231,22 +231,22 @@ module CloseYourIt
       self
     end
 
-    # Release effettiva: quella impostata, altrimenti auto-rilevata (ENV di deploy/CI o git).
+    # Effective release: the one set, otherwise auto-detected (deploy/CI ENV or git).
     def release
       return @release unless @release.nil?
 
       @release = detect_release
     end
 
-    # Radice del progetto effettiva: quella impostata, altrimenti auto-rilevata (Rails.root o Dir.pwd).
-    # Usata per rendere `frame.filename` relativo (culprit confrontabile cross-SDK — CYRB-4).
+    # Effective project root: the one set, otherwise auto-detected (Rails.root or Dir.pwd).
+    # Used to make `frame.filename` relative (culprit comparable across SDKs — CYRB-4).
     def project_root
       return @project_root unless @project_root.nil?
 
       @project_root = detect_project_root
     end
 
-    # Rails.root quando l'app gira sotto Rails, altrimenti la working directory. Mai solleva.
+    # Rails.root when the app runs under Rails, otherwise the working directory. Never raises.
     def detect_project_root
       return ::Rails.root.to_s if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
 
@@ -255,12 +255,12 @@ module CloseYourIt
       Dir.pwd
     end
 
-    # Un tag semver (con `v` opzionale) è preferito allo short SHA come release: converge con quello
-    # che registra la CI (che tagga), mentre lo short SHA crea release duplicate lato backend (CYRB-9).
+    # A semver tag (optional `v`) is preferred to the short SHA as release: it converges with what the
+    # CI records (it tags), while the short SHA creates duplicate releases on the backend (CYRB-9).
     SEMVER_TAG = /\Av?\d+\.\d+\.\d+([-+.].+)?\z/
 
-    # Auto-rilevamento release: prima un tag semver (APP_GIT_TAG/GIT_TAG), poi lo short SHA dalle env
-    # di deploy/CI o dal git. Mai solleva.
+    # Release auto-detection: first a semver tag (APP_GIT_TAG/GIT_TAG), then the short SHA from the
+    # deploy/CI env or from git. Never raises.
     def detect_release
       detect_tag ||
         ENV["KAMAL_VERSION"] ||
@@ -275,8 +275,8 @@ module CloseYourIt
 
     private
 
-    # `.git` è una directory in un checkout normale, un file in un worktree → File.directory?
-    # è false nei worktree, così i test non lanciano subprocess git (deterministico).
+    # `.git` is a directory in a normal checkout and a file in a worktree → File.directory? is false
+    # in worktrees, so tests do not spawn git subprocesses (deterministic).
     def git_revision
       return nil unless File.directory?(".git")
 
@@ -286,9 +286,9 @@ module CloseYourIt
       nil
     end
 
-    # Tag semver da APP_GIT_TAG poi GIT_TAG: accetta solo un valore non-blank con forma semver
-    # (v opzionale + MAJOR.MINOR.PATCH + eventuale suffisso). Scarta `unknown`, vuoto, nomi di
-    # branch, ecc. → nil, così detect_release cade sulla catena SHA.
+    # Semver tag from APP_GIT_TAG then GIT_TAG: accepts only a non-blank value shaped like semver
+    # (optional v + MAJOR.MINOR.PATCH + optional suffix). Rejects `unknown`, empty, branch names,
+    # etc. → nil, so detect_release falls back to the SHA chain.
     def detect_tag
       tag = ENV["APP_GIT_TAG"] || ENV["GIT_TAG"]
       return nil if blank?(tag)
@@ -303,17 +303,17 @@ module CloseYourIt
       !uri.nil? && uri.scheme != "https"
     end
 
-    # Avvisa se il project_id è valorizzato ma non sembra uno UUID (l'errore tipico è incollare
-    # uno slug/nome al posto dell'id). Non blocca: il server è l'autorità sulla validità.
+    # Warns when project_id is set but does not look like a UUID (the typical mistake is pasting a
+    # slug/name instead of the id). It does not block: the server is the authority on validity.
     def malformed_project_id?
       !blank?(project_id) && !UUID_FORMAT.match?(project_id.to_s)
     end
 
     def malformed_project_id_message
-      "CloseYourIt: project_id (#{project_id}) non ha forma UUID — verifica di aver copiato l'id corretto."
+      "CloseYourIt: project_id (#{project_id}) is not shaped like a UUID — check that you copied the right id."
     end
 
-    # Avvisa se endpoint_url è valorizzato ma non parsabile o privo di host.
+    # Warns when endpoint_url is set but not parsable or has no host.
     def malformed_endpoint?
       return false if blank?(endpoint_url)
 
@@ -322,12 +322,12 @@ module CloseYourIt
     end
 
     def malformed_endpoint_message
-      "CloseYourIt: endpoint_url (#{endpoint_url}) non è un URL valido (host mancante)."
+      "CloseYourIt: endpoint_url (#{endpoint_url}) is not a valid URL (missing host)."
     end
 
     def insecure_endpoint_message
-      tail = production? ? "Telemetria DISABILITATA in production." : "Consentito solo in sviluppo."
-      "CloseYourIt: endpoint_url usa http:// non sicuro (#{endpoint_url}) — il token viaggerebbe in chiaro. #{tail}"
+      tail = production? ? "Telemetry DISABLED in production." : "Allowed only in development."
+      "CloseYourIt: endpoint_url uses insecure http:// (#{endpoint_url}) — the token would travel in clear text. #{tail}"
     end
 
     def parsed_endpoint