closeyourit-ruby 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bc659e436ad9b08b9861d4898e6876a3b753ec88ebb7f8e81075729d958fcb4
-  data.tar.gz: 2bb509651ce4aa880a40f2d49f29c9584bb1bfde984b6fba3065c1a954800f82
+  metadata.gz: d77ef65ad83c3890320e2c3c3a002a6708ef52d223204da4b553ac75ec58c4b9
+  data.tar.gz: 4bc0274665e54f19fe33d6e379270f31802a71317075ceae65fecdd4b8a6d66c
 SHA512:
-  metadata.gz: d3cfd52ac4b7ddda5a5a92485ebe1fb4be25b808e706b11af7c5e0c6767fff19af3aa3958a8a3d9e6d94ec6ec36162a942fa439700bd16d07d52987d34a4328e
-  data.tar.gz: fe22c4cae5a0e94f4eeaf8284d00c0a42d51a0d8c3830dcd703abcf9774eaf31c4e5e81c0c4b8ba6331a1e3d331078136b2cf05e09316325c5f545acaa8b9c17
+  metadata.gz: cc89f3b0f20d8781b5a963b9fda04935b735500612db5883b29f86abc92bc560a452abc133db66859b919cdfcd8994ff6c4891fdcafe39a6c7878a960c74b627
+  data.tar.gz: 5b55acc5e39e78e9fc875e6cbfd32dfce56bbb9e27d600ec30f86a6d27d12660c1c61195a28c32f32ac22b418c78ac9d41e83af8bbdbd26f96781d740bd6f1cd

data/README.md

@@ -109,6 +109,7 @@ end
 | `slow_request_threshold_ms` | `1000` | Durata totale della richiesta (ms) oltre cui = `slow_request` |
 | `slow_external_threshold_ms` | `1000` | Durata di una singola HTTP esterna (ms) oltre cui = `slow_external_http` |
 | `capture_external_http` | `true` | Strumenta `Net::HTTP` per rilevare le HTTP esterne (effettivo solo con `detect_performance_issues`) |
+| `job_lifecycle_logs` | `false` | Log informativo per esito di tentativo osservato, opt-in. |
 | `monitor_jobs` | `true` | Misura durata e attesa in coda dei background job (ActiveJob + Sidekiq) → metriche `slow_job`/`job_queue_latency` (vedi [Metriche dei background job](#metriche-dei-background-job)) |
 | `slow_job_threshold_ms` | `5000` | Durata del job (ms) oltre cui = `slow_job` |
 | `job_queue_latency_threshold_ms` | `60000` | Attesa in coda (enqueue→esecuzione, ms) oltre cui = `job_queue_latency` |
@@ -359,7 +360,7 @@ sulla pipeline metriche (`/api/v1/projects/:id/metrics`). Funziona con **ActiveJ
 Due `subtype`:
 
 - **`slow_job`** — la durata del `perform` supera `slow_job_threshold_ms` (default 5000 ms).
-- **`job_queue_latency`** — l'attesa in coda (dall'enqueue all'inizio dell'esecuzione) supera
+- **`job_queue_latency`** — l'attesa dopo la scadenza effettiva (`max(enqueued_at, scheduled_at)`) supera
   `job_queue_latency_threshold_ms` (default 60000 ms): coda intasata o worker insufficienti.
 
 Ogni metrica porta la **label** (nome della classe del job), la **queue**, l'**adapter**
@@ -380,6 +381,20 @@ CloseYourIt.init do |c|
 end
 ```
 
+Il contesto additivo `contexts.job` usa il contratto `schema_version: 1`: separa durata monotona,
+attesa in coda e ritardo programmato. Un orologio mancante resta `null`; un'attesa negativa viene
+azzerata con `clock_skew: true`. Sidekiq 8 usa timestamp in millisecondi, le versioni precedenti
+secondi: la conversione segue la versione del framework, senza euristiche sulla grandezza.
+
+Per osservare anche gli esiti dei tentativi veloci, abilita `c.job_lifecycle_logs = true` (default
+`false`). Emette un log `info` con messaggio fisso `Background job attempt finished` e
+`attributes.contexts.job`, senza argomenti, risultati o header. `retry` non è terminale;
+`discarded` è esplicito; un errore con retry dell'adapter non noto ha `terminal: null`.
+Un `rescue_from` applicativo non identificabile resta `unknown`, non diventa successo.
+ActiveJob dentro Sidekiq è osservato una sola volta quando il subscriber ActiveJob è installato.
+Sampling, disabilitazione o perdita del transport impediscono di considerare questi log un censimento.
+Il raggruppamento backend v1 separa framework, nome, coda e misura; i gruppi legacy restano intatti.
+
 ## Privacy & PII
 
 Privacy-by-default (`send_pii = false`). In sintesi:

data/lib/closeyourit/background_worker.rb

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

data/lib/closeyourit/breadcrumb.rb

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

data/lib/closeyourit/breadcrumb_buffer.rb

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

data/lib/closeyourit/client.rb

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