closeyourit-ruby 0.10.0 → 0.10.2

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)

data/lib/closeyourit/events/log_event.rb

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

data/lib/closeyourit/events/message_event.rb

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

data/lib/closeyourit/events/performance_issue_event.rb

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

data/lib/closeyourit/events/slow_method_event.rb

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

data/lib/closeyourit/events/slow_query_event.rb

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

data/lib/closeyourit/instrumenter.rb

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

data/lib/closeyourit/line_cache.rb

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

data/lib/closeyourit/log_buffer.rb

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

data/lib/closeyourit/log_device.rb

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

data/lib/closeyourit/monitor.rb

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

data/lib/closeyourit/performance/request_profile.rb

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

data/lib/closeyourit/performance/rollup.rb

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