closeyourit-ruby 0.10.0 → 0.10.2

data/lib/closeyourit/subscribers/request_performance.rb

@@ -5,10 +5,10 @@ require_relative "../performance/rollup"
 
 module CloseYourIt
   module Subscribers
-    # A fine richiesta (process_action.action_controller) trasforma il RequestProfile accumulato nello
-    # Scope in verdetti performance_issue e li spedisce (fire-and-forget). Lo Scope — e quindi il
-    # profilo — viene azzerato subito dopo da RequestContext#call (ensure). Logica pura: il wiring ad
-    # ActiveSupport::Notifications vive nel Railtie.
+    # At the end of the request (process_action.action_controller) turns the RequestProfile collected
+    # in the Scope into performance_issue verdicts and sends them (fire-and-forget). The Scope — and so
+    # the profile — is reset right after by RequestContext#call (ensure). Pure logic: the wiring to
+    # ActiveSupport::Notifications lives in the Railtie.
     class RequestPerformance
       def initialize(configuration = nil)
         @configuration = configuration

data/lib/closeyourit/subscribers/slow_query.rb

@@ -6,9 +6,9 @@ require_relative "../scope"
 
 module CloseYourIt
   module Subscribers
-    # Riceve i dati di un evento `sql.active_record` e, se la query supera la soglia
-    # (escludendo SCHEMA/CACHE/TRANSACTION), invia un evento `slow_query`.
-    # Logica pura: il wiring ad ActiveSupport::Notifications vive nel Railtie.
+    # Receives the data of a `sql.active_record` event and, if the query exceeds the threshold
+    # (excluding SCHEMA/CACHE/TRANSACTION), sends a `slow_query` event.
+    # Pure logic: the wiring to ActiveSupport::Notifications lives in the Railtie.
     class SlowQuery
       IGNORED_NAMES = %w[SCHEMA CACHE TRANSACTION].freeze
 
@@ -16,6 +16,26 @@ module CloseYourIt
         @configuration = configuration
       end
 
+      # Entry point of the Railtie's sql.active_record block. `source` is a callable: the call site costs
+      # a full backtrace plus the Rails cleaner, so it is resolved at most once and only when needed.
+      def notify(payload, duration_ms, source)
+        resolved = false
+        site = nil
+        lazy_source = lambda do
+          site = source.call unless resolved
+          resolved = true
+          site
+        end
+        name = payload[:name]
+        sql = payload[:sql]
+        cached = payload.fetch(:cached, false)
+        record(name: name, duration_ms: duration_ms, sql: sql, cached: cached,
+               connection: payload[:connection], binds: payload[:binds],
+               type_casted_binds: payload[:type_casted_binds], source: lazy_source)
+        breadcrumb(name: name, sql: sql, duration_ms: duration_ms, cached: cached)
+        profile(name: name, sql: sql, duration_ms: duration_ms, cached: cached, source: lazy_source)
+      end
+
       def record(name:, duration_ms:, sql:, cached: false, connection: nil,
                  binds: nil, type_casted_binds: nil, source: nil)
         config = @configuration || CloseYourIt.configuration
@@ -25,18 +45,18 @@ module CloseYourIt
 
         event = SlowQueryEvent.new(
           { name: name, sql: sql, cached: cached, connection: connection,
-            binds: binds, type_casted_binds: type_casted_binds, source: source },
+            binds: binds, type_casted_binds: type_casted_binds, source: resolve(source) },
           duration_ms,
           config
         )
         CloseYourIt.capture_event(event)
       rescue StandardError
-        # La telemetria non deve mai disturbare la query ospite.
+        # Telemetry must never disturb the host query.
         nil
       end
 
-      # Breadcrumb per OGNI query non di sistema (non solo lente): SQL offuscato, niente bind.
-      # Dà la cronologia "quali query prima del crash" allegata all'evento d'errore.
+      # Breadcrumb for EVERY non-system query (not only slow ones): obfuscated SQL, no binds.
+      # Gives the "which queries before the crash" history attached to the error event.
       def breadcrumb(name:, sql:, duration_ms:, cached: false)
         config = @configuration || CloseYourIt.configuration
         return if ignored_name?(name)
@@ -49,12 +69,12 @@ module CloseYourIt
           data: { "name" => name, "duration_ms" => duration_ms.to_f.round(2), "cached" => cached }
         )
       rescue StandardError
-        # La telemetria non deve mai disturbare la query ospite.
+        # Telemetry must never disturb the host query.
         nil
       end
 
-      # Spinge OGNI query non di sistema nel RequestProfile dello Scope (per la detection N+1 a fine
-      # richiesta). Solo se detect_performance_issues: fingerprint = SQL offuscato + call-site.
+      # Pushes EVERY non-system query into the Scope's RequestProfile (for N+1 detection at the end of
+      # the request). Only with detect_performance_issues: fingerprint = obfuscated SQL + call site.
       def profile(name:, sql:, duration_ms:, cached: false, source: nil)
         config = @configuration || CloseYourIt.configuration
         return unless config.detect_performance_issues
@@ -62,15 +82,17 @@ module CloseYourIt
 
         CloseYourIt::Scope.current.performance_profile.add_query(
           fingerprint: scrubber(config).obfuscate_sql(sql),
-          source: source, duration_ms: duration_ms, cached: cached
+          source: resolve(source), duration_ms: duration_ms, cached: cached
         )
       rescue StandardError
-        # La telemetria non deve mai disturbare la query ospite.
+        # Telemetry must never disturb the host query.
         nil
       end
 
       private
 
+      def resolve(source) = source.respond_to?(:call) ? source.call : source
+
       def scrubber(config)
         @scrubber ||= Scrubber.new(config)
       end
@@ -79,16 +101,16 @@ module CloseYourIt
         name.nil? || IGNORED_NAMES.include?(name)
       end
 
-      # Query esclusa dalla MISURA dei rallentamenti (config.excluded_query_patterns). Il filtro sta
-      # solo qui, non in #breadcrumb né in #profile:
+      # Query excluded from slowdown MEASUREMENT (config.excluded_query_patterns). The filter lives
+      # only here, not in #breadcrumb nor in #profile:
       #
-      #   - breadcrumb: la cronologia "quali query prima del crash" ha valore diagnostico anche quando
-      #     la query è del framework — nasconderla renderebbe la sequenza incompleta e bugiarda;
-      #   - profile: è per-richiesta e serve la detection N+1, dove una tabella di servizio letta molte
-      #     volte è essa stessa un sintomo da vedere.
+      #   - breadcrumb: the "which queries before the crash" history has diagnostic value even when the
+      #     query belongs to the framework — hiding it would make the sequence incomplete and misleading;
+      #   - profile: it is per-request and serves N+1 detection, where a service table read many times
+      #     is itself a symptom worth seeing.
       #
-      # Un rallentamento va misurato se qualcuno può intervenire; una breadcrumb va tenuta se aiuta a
-      # capire. Sono due domande diverse, e questa lista risponde solo alla prima.
+      # A slowdown is worth measuring if someone can act on it; a breadcrumb is worth keeping if it
+      # helps understanding. They are two different questions, and this list answers only the first.
       def excluded_sql?(config, sql)
         return false if sql.nil?
 

data/lib/closeyourit/trace_context.rb

@@ -3,14 +3,14 @@
 require "securerandom"
 
 module CloseYourIt
-  # Contesto di trace W3C (`traceparent`/`tracestate`, https://www.w3.org/TR/trace-context/).
-  # NON è un tracer: non apre span né misura tempi. È un "propagation bridge" minimale (il ticket:
-  # "Non costruire tracing custom completo") — adotta un contesto entrante valido facendo pass-through
-  # di trace-id/parent-id/flag, oppure ne genera uno root, e sa serializzarsi negli header d'uscita.
-  # Volutamente separato dai formati proprietari: sullo standard, senza dipendere da un vendor.
+  # W3C trace context (`traceparent`/`tracestate`, https://www.w3.org/TR/trace-context/).
+  # It is NOT a tracer: it opens no spans and measures no times. It is a minimal "propagation bridge"
+  # (the ticket: "do not build full custom tracing") — it adopts a valid incoming context passing
+  # through trace-id/parent-id/flags, or generates a root one, and serializes into outgoing headers.
+  # Deliberately separate from proprietary formats: standard-based, with no vendor dependency.
   class TraceContext
-    # traceparent = version "-" trace-id "-" parent-id "-" trace-flags (55 char per la versione 00).
-    # `rest` cattura eventuali campi futuri: ammessi solo da versioni > 00 (forward-compat), vietati su 00.
+    # traceparent = version "-" trace-id "-" parent-id "-" trace-flags (55 chars for version 00).
+    # `rest` captures any future fields: allowed only for versions > 00 (forward-compat), forbidden on 00.
     TRACEPARENT = /
       \A
       (?<version>[0-9a-f]{2})-
@@ -27,10 +27,10 @@ module CloseYourIt
     ZERO_PARENT_ID    = ("0" * 16).freeze
     FLAG_SAMPLED      = 0x01
 
-    # tracestate: lista di membri `key=value` separati da virgola, max 32 (W3C §3.3.1).
+    # tracestate: comma-separated list of `key=value` members, max 32 (W3C §3.3.1).
     TRACESTATE_MAX_MEMBERS = 32
-    # key: lowercase alnum iniziale + set ristretto (incluso `@`/`/` per le chiavi tenant@vendor).
-    # value: caratteri stampabili 0x20–0x7E esclusi `,` (0x2C) e `=` (0x3D).
+    # key: leading lowercase alnum + restricted set (including `@`/`/` for tenant@vendor keys).
+    # value: printable characters 0x20–0x7E except `,` (0x2C) and `=` (0x3D).
     TRACESTATE_MEMBER = %r{\A[a-z0-9][a-z0-9_\-*/@]*=[\x20-\x2b\x2d-\x3c\x3e-\x7e]+\z}
 
     attr_reader :trace_id, :parent_id, :flags, :tracestate
@@ -43,9 +43,9 @@ module CloseYourIt
     end
 
     class << self
-      # Adotta un traceparent entrante. Ritorna nil se malformato (→ il chiamante genera un root o
-      # lascia il contesto assente). Pass-through: mantiene trace-id/parent-id/flag verbatim così il
-      # bridge non inventa span. Il tracestate viene sanificato (membri invalidi scartati, cap a 32).
+      # Adopts an incoming traceparent. Returns nil when malformed (→ the caller generates a root or
+      # leaves the context absent). Pass-through: keeps trace-id/parent-id/flags verbatim so the
+      # bridge invents no spans. The tracestate is sanitized (invalid members dropped, capped at 32).
       def parse(traceparent, tracestate = nil)
         match = TRACEPARENT.match(traceparent.to_s.strip)
         return nil unless match
@@ -62,9 +62,9 @@ module CloseYourIt
         )
       end
 
-      # Nuovo contesto root (nessun traceparent entrante valido). Genera trace-id (16 byte) e parent-id
-      # (8 byte) casuali — SecureRandom è fork-safe, così un worker forkato non riusa gli id del padre.
-      # `sampled` fissa il flag: un root che apriamo noi traccia di default.
+      # New root context (no valid incoming traceparent). Generates random trace-id (16 bytes) and
+      # parent-id (8 bytes) — SecureRandom is fork-safe, so a forked worker does not reuse the parent's
+      # ids. `sampled` sets the flag: a root we open traces by default.
       def generate(sampled: true)
         new(
           trace_id:   SecureRandom.hex(16),
@@ -76,8 +76,8 @@ module CloseYourIt
 
       private
 
-      # Trattiene solo i membri ben formati, nell'ordine originale, fino a 32. Ritorna nil se non ne
-      # resta nessuno → così non propaghiamo mai un tracestate spazzatura o sovradimensionato.
+      # Keeps only well-formed members, in the original order, up to 32. Returns nil if none are left
+      # → so we never propagate a garbage or oversized tracestate.
       def sanitize_tracestate(tracestate)
         return nil if tracestate.nil?
 
@@ -92,14 +92,14 @@ module CloseYourIt
       (flags & FLAG_SAMPLED) != 0
     end
 
-    # traceparent d'uscita, sempre versione 00 (l'unica che sappiamo emettere). I flag sono ri-emessi
-    # per intero (i bit riservati vanno propagati as-is), formattati su due cifre esadecimali.
+    # Outgoing traceparent, always version 00 (the only one we can emit). Flags are re-emitted in full
+    # (reserved bits must be propagated as-is), formatted as two hex digits.
     def traceparent
       format("%s-%s-%s-%02x", CURRENT_VERSION, trace_id, parent_id, flags & 0xff)
     end
 
-    # Header di propagazione W3C: traceparent (+ tracestate se presente). MAI `baggage`: può contenere
-    # contesto interno/PII e non deve varcare il confine (ticket: "baggage sensibile non riceve header").
+    # W3C propagation headers: traceparent (+ tracestate if present). NEVER `baggage`: it may carry
+    # internal context/PII and must not cross the boundary (ticket: "sensitive baggage gets no header").
     def headers
       result = { "traceparent" => traceparent }
       result["tracestate"] = tracestate if tracestate && !tracestate.empty?

data/lib/closeyourit/transport.rb

@@ -6,22 +6,22 @@ require "uri"
 require "timeout"
 
 module CloseYourIt
-  # Spedisce un payload a un path di ingest (errori → /events, metriche → /metrics) via HTTP POST
-  # con `Authorization: Bearer`. Mai solleva: ogni errore di rete è loggato e ingoiato.
+  # Sends a payload to an ingest path (errors → /events, metrics → /metrics) via HTTP POST
+  # with `Authorization: Bearer`. Never raises: every network error is logged and swallowed.
   class Transport
     OPEN_TIMEOUT = 2
     READ_TIMEOUT = 3
-    # Net::HTTP non segue i redirect: l'host canonico può rispondere 301 (es. apex → www).
-    # Ri-POSTiamo a Location preservando metodo + body, così l'evento non si perde in silenzio.
+    # Net::HTTP does not follow redirects: the canonical host may answer 301 (e.g. apex → www).
+    # We re-POST to Location keeping method + body, so the event is not silently lost.
     MAX_REDIRECTS = 2
 
-    # Durata massima di UNA send_event: apertura + lettura, ripetute a ogni redirect seguito. È il
-    # tetto che il drain di fine vita deve poter aspettare, altrimenti abbandona un invio ancora sano
+    # Maximum duration of ONE send_event: open + read, repeated for every followed redirect. It is the
+    # cap the end-of-life drain must be able to wait for, otherwise it abandons a still healthy send
     # (CYRB-24).
     MAX_REQUEST_SECONDS = (OPEN_TIMEOUT + READ_TIMEOUT) * (MAX_REDIRECTS + 1)
 
-    # Un timeout di rete (apertura o lettura) è un fallimento d'invio speciale: lo isoliamo dai non-2xx
-    # e dagli altri errori di rete perché segnala tipicamente problemi di connettività (CYRB-12).
+    # A network timeout (open or read) is a special send failure: we keep it apart from non-2xx and
+    # other network errors because it typically signals connectivity problems (CYRB-12).
     TIMEOUT_ERRORS = [ Net::OpenTimeout, Net::ReadTimeout, Timeout::Error ].freeze
 
     def initialize(configuration)
@@ -35,7 +35,7 @@ module CloseYourIt
         CloseYourIt.notify_diagnostic(:send, status: response.code.to_i)
       else
         CloseYourIt.stats.increment(:failed)
-        CloseYourIt.internal_logger.warn("CloseYourIt transport: HTTP #{response.code}#{error_detail(response)} su #{path}")
+        CloseYourIt.internal_logger.warn("CloseYourIt transport: HTTP #{response.code}#{error_detail(response)} on #{path}")
         CloseYourIt.notify_diagnostic(:drop, reason: :response, status: response.code.to_i)
       end
       response
@@ -80,8 +80,8 @@ module CloseYourIt
       http.read_timeout = READ_TIMEOUT
 
       request = Net::HTTP::Post.new(uri.request_uri)
-      # Il Bearer è un segreto d'ingest: non ri-inviarlo dopo un redirect verso un host diverso
-      # (o un downgrade https→http), per non consegnarlo a un endpoint non fidato.
+      # The Bearer is an ingest secret: do not resend it after a redirect to a different host
+      # (or an https→http downgrade), so it is never handed to an untrusted endpoint.
       request["Authorization"] = "Bearer #{@configuration.token}" if authorize
       request["Content-Type"] = "application/json"
       request["User-Agent"] = "closeyourit-ruby/#{VERSION}"
@@ -90,16 +90,16 @@ module CloseYourIt
       http.request(request)
     end
 
-    # Location può essere assoluto (https://www.…) o relativo (/api/…): risolvilo sull'URI corrente.
+    # Location may be absolute (https://www.…) or relative (/api/…): resolve it against the current URI.
     def redirect_uri(current, location)
       target = URI.parse(location)
       target.relative? ? current + target : target
     end
 
-    # Il Bearer va ri-inviato solo se il redirect resta sull'autorità dell'endpoint configurato:
-    # stesso host (o la sua variante www), stessa porta effettiva e senza downgrade https→http.
-    # La porta fa parte del confine di fiducia (CYRB-22): sullo stesso server una porta diversa è
-    # un servizio distinto, che non deve ricevere il segreto d'ingest.
+    # The Bearer is resent only if the redirect stays on the configured endpoint's authority:
+    # same host (or its www variant), same effective port and no https→http downgrade.
+    # The port is part of the trust boundary (CYRB-22): on the same server a different port is a
+    # separate service, which must not receive the ingest secret.
     def same_authority?(origin, target)
       return false if origin.scheme == "https" && target.scheme != "https"
       return false unless canonical_host(origin) == canonical_host(target)
@@ -107,21 +107,21 @@ module CloseYourIt
       origin.port == target.port || canonical_upgrade?(origin, target)
     end
 
-    # Un endpoint configurato in `http` che redirige a `https` resta fidato: la porta cambia solo
-    # perché cambia lo schema (80 → 443), non perché punti a un servizio su porta non standard.
+    # An endpoint configured as `http` that redirects to `https` stays trusted: the port changes only
+    # because the scheme changes (80 → 443), not because it points to a service on a non-standard port.
     def canonical_upgrade?(origin, target)
       origin.scheme == "http" && target.scheme == "https" &&
         origin.port == origin.default_port && target.port == target.default_port
     end
 
-    # Una porta esplicita pari alla default (`:443` su https) equivale a ometterla: `URI#port` la
-    # normalizza già, qui resta solo da neutralizzare la variante www dell'host canonico.
+    # An explicit port equal to the default (`:443` on https) is the same as omitting it: `URI#port`
+    # already normalizes it, only the www variant of the canonical host is left to neutralize here.
     def canonical_host(uri)
       uri.host.to_s.sub(/\Awww\./, "")
     end
 
-    # Estrae " R…: messaggio" dall'envelope d'errore del backend, così il dev vede il codice d'errore
-    # nel log diagnostico (non solo lo status HTTP). Silenzioso se il body non è l'envelope atteso.
+    # Extracts " R…: message" from the backend error envelope, so the dev sees the error code in the
+    # diagnostic log (not only the HTTP status). Silent if the body is not the expected envelope.
     def error_detail(response)
       body = JSON.parse(response.body.to_s)
       error = body["error"]

data/lib/closeyourit/usage_registry.rb

@@ -3,25 +3,26 @@
 require "concurrent"
 
 module CloseYourIt
-  # CYSK-29 — la telemetria d'uso: registra QUALI simboli girano davvero (route come
-  # `Controller#action`, job, chiavi custom letterali) e li flusha in una POST ogni
-  # `usage_flush_interval` secondi per processo. Sul percorso caldo: una lookup e un increment.
+  # CYSK-29 — usage telemetry: records WHICH symbols actually run (routes as `Controller#action`,
+  # jobs, literal custom keys) and flushes them in one POST every `usage_flush_interval` seconds per
+  # process. On the hot path: one lookup and one increment.
   #
-  # Le regole che rendono il sistema immune alle perdite:
-  # - i conteggi sono INDICATIVI, solo `last_seen_at` è portante: un flush perso costa una finestra
-  #   su un simbolo che si rivede subito dopo;
-  # - il registro SI SVUOTA a ogni flush: il tetto (`usage_max_symbols`) limita i simboli distinti
-  #   visti in una finestra — una grandezza legata al traffico, non alla dimensione del codice;
-  # - oltre il tetto il flush porta `truncated: true`, e lato scanner quel flag SQUALIFICA il kind;
-  # - nessun sampling, mai: un campionamento su una rotta chiamata 3 volte al mese fabbrica
-  #   esattamente il falso «mai vista» che il sistema esiste per evitare;
-  # - `route` è `Controller#action`, MAI l'URL: niente path, parametri, user, IP.
+  # The rules that make the system immune to losses:
+  # - counts are INDICATIVE, only `last_seen_at` is load-bearing: a lost flush costs one window on a
+  #   symbol that shows up again right after;
+  # - the registry is EMPTIED on every flush: the cap (`usage_max_symbols`) limits the distinct
+  #   symbols seen in one window — a quantity tied to traffic, not to code size;
+  # - beyond the cap the flush carries `truncated: true`, and on the scanner side that flag
+  #   DISQUALIFIES the kind;
+  # - no sampling, ever: sampling a route called 3 times a month fabricates exactly the false
+  #   "never seen" the system exists to avoid;
+  # - `route` is `Controller#action`, NEVER the URL: no path, parameters, user, IP.
   class UsageRegistry
-    # I simboli vengono da payload di framework o da stringhe letterali: il pattern è il contratto.
+    # Symbols come from framework payloads or literal strings: the pattern is the contract.
     SYMBOL_FORMAT = %r{\A[A-Za-z0-9_:#./-]{1,200}\z}
     KINDS = %w[route job custom].freeze
 
-    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
@@ -61,8 +62,8 @@ module CloseYourIt
 
       @client.flush_usage(**payload)
     rescue StandardError => e
-      # Il flush gira sul thread timer: un errore non deve propagare nell'app né uccidere il
-      # TimerTask. La semantica portante è last_seen_at: una finestra persa non falsifica niente.
+      # The flush runs on the timer thread: an error must not propagate into the app nor kill the
+      # TimerTask. The load-bearing semantics is last_seen_at: a lost window falsifies nothing.
       CloseYourIt.internal_logger.error("CloseYourIt usage registry: #{e.class}: #{e.message}")
     end
 

data/lib/closeyourit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CloseYourIt
-  VERSION = "0.10.0"
+  VERSION = "0.10.2"
 end