closeyourit-ruby 0.9.4 → 0.10.2

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_/,
@@ -27,7 +27,7 @@ module CloseYourIt
     ].freeze
 
     attr_accessor :endpoint_url, :token, :project_id, :environment, :before_send, :on_diagnostic,
-                  :async_threads, :background_worker_max_queue,
+                  :async_threads, :background_worker_max_queue, :shutdown_timeout,
                   :slow_query_threshold_ms, :slow_method_threshold_ms,
                   :send_pii, :obfuscate_sql, :send_server_name,
                   :capture_query_bindings, :capture_method_arguments,
@@ -57,136 +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
-
-      # 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).
+      # 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
+
+      # 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
@@ -195,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
@@ -209,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?
@@ -218,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?
@@ -227,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
 
@@ -251,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"] ||
@@ -271,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")
 
@@ -282,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)
@@ -299,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)
 
@@ -318,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

data/lib/closeyourit/event.rb

@@ -4,8 +4,8 @@ require "time"
 require "socket"
 
 module CloseYourIt
-  # Base degli eventi di telemetria. Le sottoclassi implementano `#to_h` e `#ingest_path`
-  # (il path API a cui l'evento va spedito: errori → /events, metriche → /metrics).
+  # Base of telemetry events. Subclasses implement `#to_h` and `#ingest_path`
+  # (the API path the event is sent to: errors → /events, metrics → /metrics).
   class Event
     def initialize(configuration)
       @configuration = configuration
@@ -13,11 +13,11 @@ module CloseYourIt
     end
 
     def to_h
-      raise NotImplementedError, "#{self.class} deve implementare #to_h"
+      raise NotImplementedError, "#{self.class} must implement #to_h"
     end
 
     def ingest_path(_project_id)
-      raise NotImplementedError, "#{self.class} deve implementare #ingest_path"
+      raise NotImplementedError, "#{self.class} must implement #ingest_path"
     end
 
     private
@@ -42,8 +42,8 @@ module CloseYourIt
       hash.reject { |_key, value| value.nil? }
     end
 
-    # Fusione ricorsiva: gli Hash annidati vengono fusi (es. `contexts.runtime` preservato
-    # mentre lo scope aggiunge `contexts.active_job`), gli scalari sovrascritti.
+    # Recursive merge: nested Hashes are merged (e.g. `contexts.runtime` kept while the scope adds
+    # `contexts.active_job`), scalars are overwritten.
     def deep_merge(base, override)
       base.merge(override) do |_key, old_value, new_value|
         if old_value.is_a?(Hash) && new_value.is_a?(Hash)

data/lib/closeyourit/events/error_event.rb

@@ -7,9 +7,9 @@ require_relative "../scrubber"
 require_relative "../line_cache"
 
 module CloseYourIt
-  # Trasforma un'eccezione Ruby nel **payload evento Sentry** che il backend CloseYourIt ingerisce
-  # (Errors::Ingest::Normalize). Usa `backtrace_locations` (niente regex) e mette la cause-chain in
-  # `exception.values` ordinata dall'esterna alla principale (Sentry: values.last = il crash).
+  # Turns a Ruby exception into the **Sentry event payload** the CloseYourIt backend ingests
+  # (Errors::Ingest::Normalize). Uses `backtrace_locations` (no regex) and puts the cause chain in
+  # `exception.values` ordered from the outermost to the main one (Sentry: values.last = the crash).
   class ErrorEvent < Event
     def self.from_exception(exception, configuration:, handled: false, level: "error", contexts: nil)
       new(exception, configuration, handled: handled, level: level, contexts: contexts)
@@ -30,7 +30,7 @@ module CloseYourIt
         "timestamp" => @occurred_at,
         "platform" => "ruby",
         "level" => @level,
-        # Correlazione log↔errori: stesso trace_id dei log della medesima richiesta (popolato dallo Scope).
+        # Log↔error correlation: same trace_id as the logs of the same request (populated by the Scope).
         "trace_id" => CloseYourIt::Scope.current.trace_id,
         "environment" => environment,
         "release" => @configuration.release,
@@ -39,9 +39,9 @@ module CloseYourIt
         "contexts" => { "runtime" => { "name" => "ruby", "version" => RUBY_VERSION } },
         "sdk" => sdk
       )
-      # Fonde il contesto per-richiesta/job (user/tags/extra/contexts/request) raccolto nello Scope.
+      # Merges the per-request/job context (user/tags/extra/contexts/request) collected in the Scope.
       merged = deep_merge(base, CloseYourIt::Scope.current.to_event_hash)
-      # Context extra passato esplicitamente (es. rails_error dall'ErrorReporter).
+      # Extra context passed explicitly (e.g. rails_error from the ErrorReporter).
       @contexts ? deep_merge(merged, { "contexts" => @contexts }) : merged
     end
 
@@ -51,7 +51,7 @@ module CloseYourIt
 
     private
 
-    # Cause-chain → array Sentry: causa più esterna prima, eccezione principale ULTIMA.
+    # Cause chain → Sentry array: outermost cause first, main exception LAST.
     def exception_values
       chain = []
       seen = []
@@ -73,10 +73,10 @@ module CloseYourIt
       }
     end
 
-    # Sentry-style: frame più recente per ultimo; chiavi filename/function/lineno/in_app/abs_path
-    # + snippet di sorgente (pre_context/context_line/post_context) quando il file è leggibile.
-    # `filename` è relativo/basename (culprit confrontabile cross-SDK — CYRB-4); `abs_path` è il
-    # path assoluto per il dettaglio e per leggere il sorgente delle context lines.
+    # Sentry-style: most recent frame last; keys filename/function/lineno/in_app/abs_path
+    # + source snippet (pre_context/context_line/post_context) when the file is readable.
+    # `filename` is relative/basename (culprit comparable across SDKs — CYRB-4); `abs_path` is the
+    # absolute path for the detail view and for reading the context lines' source.
     def frames(locations)
       return [] if locations.nil?
 
@@ -94,15 +94,15 @@ module CloseYourIt
       end
     end
 
-    # Path da mostrare (Sentry `filename`): relativo alla project_root se il file è dentro l'app
-    # (es. "app/models/user.rb"), altrimenti il basename (gem/stdlib/path esterni → "base.rb").
-    # Allinea Ruby agli altri SDK (Dart/JS mandano basename/relativo), così il culprit
-    # "filename in function" è confrontabile a colpo d'occhio su progetti poliglotti. Vedi CYRB-4.
+    # Path to display (Sentry `filename`): relative to project_root if the file is inside the app
+    # (e.g. "app/models/user.rb"), otherwise the basename (gem/stdlib/external paths → "base.rb").
+    # Aligns Ruby with the other SDKs (Dart/JS send basename/relative), so the culprit
+    # "filename in function" is comparable at a glance on polyglot projects. See CYRB-4.
     def relative_filename(path)
       return path if path.nil?
 
       root = @configuration.project_root.to_s
-      prefix = root.empty? ? nil : File.join(root, "") # root con separatore finale, portabile
+      prefix = root.empty? ? nil : File.join(root, "") # root with trailing separator, portable
       return File.basename(path) unless prefix && path.start_with?(prefix)
 
       relative = path[prefix.length..]

data/lib/closeyourit/events/job_metric_event.rb

@@ -4,15 +4,15 @@ require "securerandom"
 require_relative "../event"
 
 module CloseYourIt
-  # Metrica `kind=performance_issue` per un background job che ha superato una soglia di DURATA
-  # (`subtype=slow_job`) o di ATTESA in coda (`subtype=job_queue_latency`). Spedita sulla pipeline
-  # metriche (`/api/v1/projects/:id/metrics`), come slow_query/slow_method e i verdetti performance.
+  # `kind=performance_issue` metric for a background job that exceeded a DURATION threshold
+  # (`subtype=slow_job`) or a queue WAIT threshold (`subtype=job_queue_latency`). Sent on the metrics
+  # pipeline (`/api/v1/projects/:id/metrics`), like slow_query/slow_method and performance verdicts.
   #
-  # `label` è il nome della CLASSE del job — mai gli argomenti (privacy: come slow_method invia solo
-  # label/durata). `attempt` rende visibili i retry; `trace_id` (= job_id ActiveJob / jid Sidekiq)
-  # correla la metrica a log ed errori dello stesso job. `duration_ms` è il valore misurato del subtype
-  # (durata del perform per slow_job, attesa in coda per job_queue_latency) — stessa convenzione del
-  # Rollup. I campi nil vengono omessi.
+  # `label` is the job CLASS name — never the arguments (privacy: like slow_method it sends only
+  # label/duration). `attempt` makes retries visible; `trace_id` (= ActiveJob job_id / Sidekiq jid)
+  # correlates the metric with logs and errors of the same job. `duration_ms` is the subtype's
+  # measured value (perform duration for slow_job, queue wait for job_queue_latency) — same
+  # convention as the Rollup. Nil fields are omitted.
   class JobMetricEvent < Event
     def initialize(attrs, configuration)
       super(configuration)