closeyourit-ruby 0.9.4 → 0.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1d5e126aa96c17501b6830b9c7763979c239cd4bf4b0e0d43685b0652025378
-  data.tar.gz: c2d52c988da1288a5cea2986261481ec87fd67db8f3fb0921e2161c90653022e
+  metadata.gz: 866fd0b6c34af299e0e538ddb181b1f6b3fd961da1e638226a81ad8b8ea15c0b
+  data.tar.gz: eaf0d4530e9015f7353790aeffe104f04a2f80d46c4c7622ad7dad3302bd75fe
 SHA512:
-  metadata.gz: e9b3c6b9d352ad92055e710951157956c6fa3a75c8cbcee6bf6f9dbdbd3eb829ac6c990f54a38a72ef141c2e8d5a71eb714905355cbeee7be94a3957d6f6b22e
-  data.tar.gz: 6bc37b84e2d6a19e6690df0c40732df11fcf32069f1c9942f2d2ddbf6bb76cedb29a94e86c6fd4269002c9f0f9a4c352c53e1c0b41da9a32f5588503ad645b45
+  metadata.gz: b4193d36f1123b89bdf11998ebcd5ea445b0b84c325ccae654d434d2d94158d6dd9c920b0e879167f0fba5cbaa7615f42a3d2cd11f3f61d8ade9f3eaee18917f
+  data.tar.gz: 7a4d366fbf67b5720d878e2e1febbcda5500c6063d8f654e450c10b68789964a7c8b15390e23d4516d9220ea6cb2ffbde619900ec2871fe7b8b20fd23c967b8b

data/README.md

@@ -79,6 +79,7 @@ end
 | `before_send` | `nil` | `->(payload) { ... }` — scrub finale; ritorna payload o `nil` per scartare |
 | `sample_rate` | `1.0` | Frazione di errori/messaggi inviata (`1.0` tutto, `0.0` niente) |
 | `async_threads` | `cpu/2` | Thread di invio; `0` = sincrono (test) |
+| `shutdown_timeout` | `15` | Secondi di attesa, alla chiusura, perché gli invii in volo completino; scaduto il tempo gli eventi residui sono contati come `dropped` (vedi [Flush di fine-vita](#flush-di-fine-vita)) |
 | `trap_signals` | `false` | Intercetta `SIGTERM` per garantire il flush di fine-vita (deploy/Kamal); opt-in perché sovrascrive un eventuale handler `TERM` dell'app ospite (vedi [Flush di fine-vita](#flush-di-fine-vita)) |
 | `slow_query_threshold_ms` | `100` | Soglia query lente |
 | `excluded_query_patterns` | `solid_queue_`, `solid_cache_`, `solid_cable_` | Query da NON misurare come rallentamento — **Regexp** (pattern) o **String** (testo letterale). Vale solo per la misura: breadcrumb e profiling N+1 vedono tutto |
@@ -227,6 +228,11 @@ buffer), così i log sotto-batch di rake/CLI non vanno persi all'uscita. `SIGTER
 termina il processo **senza** eseguire gli `at_exit`: imposta `trap_signals = true` per intercettarlo e
 convertirlo in un exit pulito, oppure chiama `CloseYourIt.shutdown` esplicitamente prima di terminare.
 
+Il drain attende fino a `shutdown_timeout` secondi (default `15`, il tetto di durata di una singola
+POST verso l'ingest). Gli eventi ancora in coda quando il tempo scade sono contati come `dropped`
+nello snapshot diagnostico di fine-vita: nessuna perdita silenziosa. Abbassa il valore se l'uscita
+del processo deve essere più rapida della consegna.
+
 #### Server che forkano (Puma cluster, Sidekiq, Unicorn)
 
 I server che precaricano l'app (`preload_app!`) inizializzano la gemma nel processo **master**, poi

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,34 +13,53 @@ 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
 
-    def shutdown(timeout = 1)
+    # 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)
 
       @executor.shutdown
-      @executor.wait_for_termination(timeout)
+      terminated = @executor.wait_for_termination(timeout)
+      report_abandoned(timeout) unless terminated
+      terminated
     end
 
     private
 
+    # 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 expired after #{timeout}s, #{abandoned} events abandoned"
+      )
+      abandoned.times do
+        CloseYourIt.stats.increment(:dropped)
+        CloseYourIt.notify_diagnostic(:drop, reason: :shutdown_timeout)
+      end
+    end
+
     def build_executor(threads, max_queue)
       return Concurrent::ImmediateExecutor.new if threads <= 0
 

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,35 +36,25 @@ 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?
 
-      payloads = events.map(&:to_h)
-      if @configuration.before_send
-        kept = payloads.filter_map { |payload| @configuration.before_send.call(payload) }
-        # I log che before_send porta a nil sono scarti voluti: contabilizzali come gli errori/metriche
-        # (parità con #capture_event), altrimenti sparirebbero silenziosamente dai contatori (CYRB-12).
-        (payloads.size - kept.size).times do
-          CloseYourIt.stats.increment(:dropped)
-          CloseYourIt.notify_diagnostic(:drop, reason: :before_send)
-        end
-        payloads = kept
-      end
+      payloads = events.filter_map { |event| build_log_payload(event) }
       return nil if payloads.empty?
 
       path = events.first.ingest_path(@configuration.project_id)
@@ -78,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,
@@ -95,7 +85,30 @@ module CloseYourIt
     end
 
     def shutdown
-      @worker.shutdown
+      @worker.shutdown(@configuration.shutdown_timeout)
+    end
+
+    private
+
+    # 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?
+
+      # 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 dropped — #{e.class}: #{e.message}")
+      CloseYourIt.stats.increment(:dropped)
+      CloseYourIt.notify_diagnostic(:drop, reason: :error, error: e.class.name)
+      nil
     end
   end
 end