closeyourit-ruby 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c80dd7130394211bc1c0ebbf7a13bbe9906951b667734380bdf38aac53f194ae
-  data.tar.gz: 9adde552df65cee4cd32d47161bdd84fbe5a69c06698b9fc5c9cfd5a1a2a1088
+  metadata.gz: '083ced8226884d6ceed86ae4da2a17cb7f9bfdfa5f3cd6073ac09268c4545d6e'
+  data.tar.gz: 75b18abef8b8c45ae14647c4bc102276286a2c71c1056d37274d0fe350f20555
 SHA512:
-  metadata.gz: 1f7cc16b574bfc124e9f9f49037a7045dc30a7125da890f78ae6c7c36712a418da61dbd2170a12a8d34be35ea5fc8fb96568dc58e1e573677fe67afb902c071e
-  data.tar.gz: aa9871930fa03617485c993e2f84db54aeb23ecd092c8a2a15a463e9dcda75c710d3cadef95f14081bbe3844cca50f4215ef0c5b40cb149e205ff1d6e701a575
+  metadata.gz: c9285e453091b8f89bc360e1a274fc72fa7b312cd2fd2ac7f8dddb0636a7a49e6f7782f0af5b8e2cb20275e841566731fe48174dddf6f502cb9eb92646bae216
+  data.tar.gz: 1bcd7478c0d2d5572c0fa761e0b16a6bacffef89bd227a36fae117cea468fdd538bf9f011d839fa378a29871a1b2e8efdfc3ef2c467df684096eff585206a7d3

data/README.md

@@ -74,6 +74,7 @@ end
 | `async_threads` | `cpu/2` | Thread di invio; `0` = sincrono (test) |
 | `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 |
 | `slow_method_threshold_ms` | `200` | Soglia metodi lenti |
 | `capture_request` | `true` | Cattura il contesto HTTP della richiesta (method/url/header allowlist) |
 | `request_header_allowlist` | `Accept`, `Content-Type`, `User-Agent`, `Referer` | Header inviati (mai Authorization/Cookie) |
@@ -92,6 +93,7 @@ end
 | `logs_flush_interval` | `5` | Secondi tra i flush periodici del buffer log |
 | `capture_rails_logs` | `false` | Inoltra anche `Rails.logger` allo stream — attenzione al volume (soglia `capture_rails_logs_min_level`) |
 | `capture_rails_logs_min_level` | `:warn` | Soglia **dedicata** del broadcast `Rails.logger` (distinta da `logs_min_level`): default conservativo per non inondare lo stream col rumore `info` del framework |
+| `excluded_log_patterns` | `[]` | Righe del broadcast `Rails.logger` da scartare per **testo** — **Regexp** (pattern) o **String** (testo letterale). Per il rumore che non è un'eccezione; le eccezioni le copre già `excluded_exceptions` |
 | `detect_performance_issues` | `false` | Master switch dei **verdetti** performance (N+1, query count, request/HTTP esterne lente). Opt-in: profila ogni query → overhead (vedi [Performance issues](#performance-issues-opt-in)) |
 | `n_plus_one_threshold` | `10` | Ripetizioni dello stesso `[fingerprint, call-site]` in una richiesta oltre cui = `n_plus_one` |
 | `query_count_threshold` | `100` | Query totali in una richiesta oltre cui = `high_query_count` |
@@ -99,6 +101,10 @@ 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`) |
+| `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` |
+| `jobs_sample_rate` | `1.0` | Frazione dei job oltre soglia effettivamente inviata (`1.0` tutti, `0.0` niente) |
 
 ## Cosa cattura
 
@@ -172,6 +178,21 @@ Abbassala esplicitamente (es. `config.capture_rails_logs_min_level = :info`) sol
 `info` del framework. I log dei background job ereditano il `trace_id = job_id`, così log ed errore
 dello stesso job si correlano.
 
+Il broadcast rispetta anche **`excluded_exceptions`**: se la riga nomina una classe esclusa non viene
+inoltrata. Serve perché un'eccezione tolta dal canale errori rientrava da quello dei log — Rails la
+registra comunque con `logger.error`. Con le esclusioni di default questo copre già
+`ActionController::RoutingError`, cioè le favicon mancanti e le scansioni dei bot, che in produzione
+sono la voce di gran lunga più numerosa dello stream. Per il rumore ripetuto che **non** è
+un'eccezione c'è `excluded_log_patterns`:
+
+```ruby
+config.excluded_log_patterns = [ /SolidQueue-[\d.]+ Error in thread/, "Rendered layout" ]
+```
+
+Le stringhe valgono come testo letterale (vengono escapate), i `Regexp` come pattern. Entrambe le
+liste gatano **solo** il mirror di `Rails.logger`: un `CloseYourIt.log` scritto di proposito non viene
+mai silenziato.
+
 #### Flush di fine-vita
 
 Il buffer log viene svuotato automaticamente allo **shutdown del processo**: `CloseYourIt.init` registra
@@ -180,6 +201,31 @@ 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.
 
+#### Server che forkano (Puma cluster, Sidekiq, Unicorn)
+
+I server che precaricano l'app (`preload_app!`) inizializzano la gemma nel processo **master**, poi
+forkano i worker. Il worker pool asincrono e il timer del buffer log sono **thread**, e i thread non
+sopravvivono a un `fork`: nel figlio quelle risorse sarebbero ereditate ma inerti e gli eventi non
+partirebbero mai. La gemma **rileva il cambio di PID da sé** (lazy, al primo evento del figlio) e ricrea
+worker e buffer nel processo corrente — nella maggior parte dei casi non devi fare nulla.
+
+Per ricrearle **subito** dopo il fork (invece di attendere il primo evento) chiama
+`CloseYourIt.after_fork` nel worker hook del tuo server:
+
+```ruby
+# Puma (config/puma.rb)
+on_worker_boot { CloseYourIt.after_fork }
+
+# Sidekiq (config/initializers/sidekiq.rb)
+Sidekiq.configure_server { |config| config.on(:startup) { CloseYourIt.after_fork } }
+
+# Unicorn (config/unicorn.rb)
+after_fork { |server, worker| CloseYourIt.after_fork }
+```
+
+`CloseYourIt.after_fork` abbandona le risorse ereditate **senza drenarle** (non tenta un join sui thread
+del padre e non riflusha il buffer, che rispedirebbe eventi del padre) ed è sicuro da chiamare più volte.
+
 ### Contesto, breadcrumbs e messaggi (manuale)
 
 ```ruby
@@ -201,6 +247,21 @@ all'evento d'errore catturato nello stesso contesto di esecuzione.
 Il Railtie si iscrive a `sql.active_record`: ogni query oltre `slow_query_threshold_ms` (esclusi
 `SCHEMA`/`CACHE`) viene inviata come `slow_query` alla pipeline metriche. Lo SQL è **offuscato** (bind esclusi).
 
+Sono escluse anche le query che combaciano con `excluded_query_patterns` — di default le tabelle di
+servizio del Solid stack (`solid_queue_`, `solid_cache_`, `solid_cable_`). Sono infrastruttura del
+framework: una loro query lenta non si corregge leggendo il proprio repo, dice solo che il database è
+in contesa, e in compenso sommerge le query dell'applicazione (su un backend reale erano il **62%**
+dei campioni). Per misurarle davvero azzera la lista:
+
+```ruby
+config.excluded_query_patterns = []                      # misura tutto
+config.excluded_query_patterns += [ "pg_stat_activity" ]  # o aggiungi le tue
+```
+
+Il filtro vale solo per la **misura**: le breadcrumb «quali query prima del crash» e il profiling N+1
+continuano a vedere tutte le query, perché lì una tabella di servizio letta molte volte è essa stessa
+un sintomo.
+
 ### Metodi lenti → metriche
 
 ```ruby
@@ -257,6 +318,36 @@ tutte ritoccabili.
 > switch. (Pendant server-side dei verdetti `performance_issue` di closeyourit-js: qui i `subtype`
 > sono quelli del backend Rails — N+1, query count, request/HTTP esterne lente.)
 
+## Metriche dei background job
+
+Oltre agli **errori** dei job (sezione precedente), la gemma misura **automaticamente** durata di
+esecuzione e attesa in coda dei background job e, oltre le soglie, invia metriche `performance_issue`
+sulla pipeline metriche (`/api/v1/projects/:id/metrics`). Funziona con **ActiveJob** (via notifiche
+`ActiveSupport::Notifications`) e con **Sidekiq** (server middleware), senza strumentazione manuale.
+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_threshold_ms` (default 60000 ms): coda intasata o worker insufficienti.
+
+Ogni metrica porta la **label** (nome della classe del job), la **queue**, l'**adapter**
+(`active_job`/`sidekiq`), l'**attempt** (numero di esecuzione: rende visibili i **retry**), la
+**release** e il **trace_id** (= `job_id` / `jid`, che correla la metrica a log ed errori dello stesso
+job). **Gli argomenti del job non vengono mai inviati** (solo la label).
+
+È **ON di default** (a differenza dei verdetti performance opt-in): la visibilità dei job lenti, in
+ritardo o ripetutamente ritentati non deve richiedere configurazione in ogni app, e l'overhead è basso
+(una notifica per job, non il profiling di ogni query). Il rumore è tenuto a bada dalle **soglie** (i
+job normali restano sotto soglia → nessuna metrica) e dal **sampling** (`jobs_sample_rate`, applicato
+solo ai job già oltre soglia). Per spegnerlo del tutto:
+
+```ruby
+CloseYourIt.init do |c|
+  # …endpoint_url / token / project_id…
+  c.monitor_jobs = false
+end
+```
+
 ## Privacy & PII
 
 Privacy-by-default (`send_pii = false`). In sintesi:
@@ -277,17 +368,45 @@ Privacy-by-default (`send_pii = false`). In sintesi:
 Il trasporto è fire-and-forget: non solleva mai e non blocca la request. Per non lasciare
 fallimenti silenziosi, ogni risposta HTTP non-2xx (es. `401` token errato, `404` progetto
 inesistente) viene loggata a `warn`, così come gli eventi scartati a coda piena. I contatori
-sono ispezionabili a runtime:
+sono ispezionabili a runtime (`snapshot` è un alias di `to_h`):
 
 ```ruby
 CloseYourIt.stats.to_h
-# => { enqueued: 128, dropped: 0, sent: 126, failed: 2 }
+# => { enqueued: 128, dropped: 1, sent: 125, failed: 2, timeout: 1 }
 ```
 
 - `enqueued` — eventi accettati per l'invio
-- `dropped` — scartati perché la coda async era piena (mai backpressure)
+- `dropped` — scartati prima dell'invio: coda async piena, `before_send` → `nil`/eccezione, sampling
 - `sent` — risposta HTTP 2xx
 - `failed` — errore di rete o status non-2xx (vedi i log a `warn`)
+- `timeout` — sotto-conteggio di `failed`: fallimenti per timeout di rete (connettività)
+
+### Hook `on_diagnostic` (opt-in)
+
+Per osservare il ciclo di vita di ogni evento senza abilitare log rumorosi, registra un hook. È
+invocato a ogni tappa — `:enqueue`, `:send`, `:drop`, `:timeout`, `:shutdown` — con dettagli privi
+di dati sensibili:
+
+```ruby
+CloseYourIt.init do |c|
+  # ...
+  c.on_diagnostic = ->(event, details) do
+    StatsD.increment("closeyourit.#{event}", tags: details) # es. inoltra a metriche interne
+  end
+end
+```
+
+- `:enqueue` — `{ path: … }` accodato per l'invio
+- `:send` — `{ status: 202 }` consegnato (2xx)
+- `:drop` — scartato: `{ reason: :queue_full | :before_send | :sampled | :error | :response | :network, … }`
+- `:timeout` — `{ error: "Net::OpenTimeout" }` timeout di rete
+- `:shutdown` — `{ stats: {…} }` snapshot alla terminazione del processo, emesso una sola volta per
+  sessione (best-effort: invii ancora in volo oltre il breve timeout di drain possono non esservi
+  riflessi — il drain non blocca l'uscita)
+
+L'hook è **locale e non ricorsivo**: non invia mai telemetria, e una notifica emessa dal suo interno
+è soppressa — non può innescare loop di auto-monitoraggio. Un hook che solleva è isolato (loggato,
+mai propagato nell'app). Tienilo veloce: gira sincrono nel thread chiamante, come `before_send`.
 
 ## Sviluppo
 

data/lib/closeyourit/background_worker.rb

@@ -26,6 +26,7 @@ module CloseYourIt
       unless accepted
         CloseYourIt.stats.increment(:dropped)
         CloseYourIt.internal_logger.warn("CloseYourIt background worker: coda piena, evento scartato")
+        CloseYourIt.notify_diagnostic(:drop, reason: :queue_full)
       end
 
       accepted

data/lib/closeyourit/client.rb

@@ -21,11 +21,19 @@ module CloseYourIt
     def capture_event(event)
       payload = event.to_h
       payload = @configuration.before_send.call(payload) if @configuration.before_send
-      return nil if payload.nil?
+      if payload.nil?
+        # before_send ha scartato l'evento (ritorna nil): scarto voluto, reso visibile (CYRB-12).
+        CloseYourIt.stats.increment(:dropped)
+        CloseYourIt.notify_diagnostic(:drop, reason: :before_send)
+        return nil
+      end
 
       path = event.ingest_path(@configuration.project_id)
       accepted = @worker.perform { @transport.send_event(payload, path: path) }
-      CloseYourIt.stats.increment(:enqueued) if accepted
+      if accepted
+        CloseYourIt.stats.increment(:enqueued)
+        CloseYourIt.notify_diagnostic(:enqueue, path: path)
+      end
       payload
     rescue StandardError => e
       # La telemetria non deve MAI propagare nel path dell'app ospite: capture_event è invocato dal
@@ -33,6 +41,8 @@ module CloseYourIt
       # 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.
       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
 
@@ -45,13 +55,25 @@ module CloseYourIt
       return nil if events.nil? || events.empty?
 
       payloads = events.map(&:to_h)
-      payloads = payloads.filter_map { |payload| @configuration.before_send.call(payload) } if @configuration.before_send
+      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
       return nil if payloads.empty?
 
       path = events.first.ingest_path(@configuration.project_id)
       payloads.each_slice(LOGS_MAX_BATCH) do |chunk|
         accepted = @worker.perform { @transport.send_event(chunk, path: path) }
-        CloseYourIt.stats.increment(:enqueued) if accepted
+        next unless accepted
+
+        CloseYourIt.stats.increment(:enqueued)
+        CloseYourIt.notify_diagnostic(:enqueue, path: path, batch: chunk.size)
       end
       payloads
     end

data/lib/closeyourit/configuration.rb

@@ -15,7 +15,18 @@ module CloseYourIt
     # Header HTTP catturati nel contesto request (mai Authorization/Cookie → niente PII/segreti).
     DEFAULT_REQUEST_HEADER_ALLOWLIST = %w[Accept Content-Type User-Agent Referer].freeze
 
-    attr_accessor :endpoint_url, :token, :project_id, :environment, :before_send,
+    # 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).
+    DEFAULT_EXCLUDED_QUERY_PATTERNS = [
+      /\bsolid_queue_/,
+      /\bsolid_cache_/,
+      /\bsolid_cable_/
+    ].freeze
+
+    attr_accessor :endpoint_url, :token, :project_id, :environment, :before_send, :on_diagnostic,
                   :async_threads, :background_worker_max_queue,
                   :slow_query_threshold_ms, :slow_method_threshold_ms,
                   :send_pii, :obfuscate_sql, :send_server_name,
@@ -28,9 +39,12 @@ module CloseYourIt
                   :capture_rails_logs, :logs_min_level, :capture_rails_logs_min_level,
                   :detect_performance_issues, :n_plus_one_threshold, :query_count_threshold,
                   :query_time_threshold_ms, :slow_request_threshold_ms, :slow_external_threshold_ms,
-                  :capture_external_http, :trap_signals
+                  :capture_external_http, :trap_signals,
+                  :monitor_jobs, :slow_job_threshold_ms, :job_queue_latency_threshold_ms,
+                  :jobs_sample_rate
     attr_writer :release, :project_root
-    attr_reader :excluded_exceptions, :filter_parameters, :scrub_message_patterns
+    attr_reader :excluded_exceptions, :excluded_log_patterns, :excluded_query_patterns,
+                :filter_parameters, :scrub_message_patterns
 
     def initialize
       @endpoint_url = ENV.fetch("CLOSEYOURIT_ENDPOINT_URL", nil)
@@ -42,6 +56,12 @@ 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).
+      @on_diagnostic = nil
+
       @async_threads               = default_threads
       @background_worker_max_queue  = 30
 
@@ -52,6 +72,9 @@ module CloseYourIt
 
       @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.
+      @excluded_query_patterns = DEFAULT_EXCLUDED_QUERY_PATTERNS.dup
 
       @send_pii         = false
       @obfuscate_sql    = true
@@ -98,6 +121,10 @@ module CloseYourIt
       # 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).
       @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.
+      @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
@@ -110,6 +137,17 @@ module CloseYourIt
       @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.
+      @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
+
       # 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 = nil
@@ -123,6 +161,18 @@ module CloseYourIt
       @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.
+    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.
+    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
+
     def filter_parameters=(list)
       @filter_parameters = Array(list)
     end
@@ -177,9 +227,15 @@ module CloseYourIt
       Dir.pwd
     end
 
-    # Auto-rilevamento release dalle env di deploy/CI o dal git short SHA. Mai solleva.
+    # 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).
+    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.
     def detect_release
-      ENV["KAMAL_VERSION"] ||
+      detect_tag ||
+        ENV["KAMAL_VERSION"] ||
         ENV["GIT_SHA"] ||
         ENV["GIT_REVISION"] ||
         ENV["SOURCE_VERSION"] ||
@@ -202,6 +258,16 @@ 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.
+    def detect_tag
+      tag = ENV["APP_GIT_TAG"] || ENV["GIT_TAG"]
+      return nil if blank?(tag)
+
+      SEMVER_TAG.match?(tag) ? tag : nil
+    end
+
     UUID_FORMAT = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
 
     def insecure_endpoint?

data/lib/closeyourit/events/job_metric_event.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+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.
+  #
+  # `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.
+  class JobMetricEvent < Event
+    def initialize(attrs, configuration)
+      super(configuration)
+      @attrs = attrs
+    end
+
+    def to_h
+      compact(
+        "kind" => "performance_issue",
+        "subtype" => @attrs[:subtype],
+        "sample_id" => SecureRandom.uuid,
+        "duration_ms" => @attrs[:duration_ms]&.round(2),
+        "occurred_at" => @occurred_at,
+        "environment" => environment,
+        "release" => @configuration.release,
+        "trace_id" => @attrs[:trace_id],
+        "label" => @attrs[:job_class],
+        "queue" => @attrs[:queue],
+        "adapter" => @attrs[:adapter],
+        "attempt" => @attrs[:attempt],
+        "sdk" => sdk
+      )
+    end
+
+    def ingest_path(project_id)
+      "/api/v1/projects/#{project_id}/metrics"
+    end
+  end
+end

data/lib/closeyourit/log_buffer.rb

@@ -37,6 +37,12 @@ module CloseYourIt
       # 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.
       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.
+      batch.to_a.size.times do
+        CloseYourIt.stats.increment(:dropped)
+        CloseYourIt.notify_diagnostic(:drop, reason: :error)
+      end
     end
 
     def shutdown

data/lib/closeyourit/rails/log_broadcast.rb

@@ -18,13 +18,20 @@ module CloseYourIt
         self.level = LEVEL_BY_SYMBOL.fetch(min_level.to_sym, 2)
       end
 
-      # Sovrascrive il punto unico di ::Logger: filtra per soglia e re-inoltra a CloseYourIt.log.
+      # Sovrascrive il punto unico di ::Logger: filtra per soglia e per esclusioni, poi re-inoltra a
+      # CloseYourIt.log. Il secondo filtro esiste perché la soglia da sola non distingue il rumore: una
+      # `ActionController::RoutingError` da favicon mancante è un `logger.error` come un altro, e senza
+      # controllare il TESTO rientrava dal canale log dopo essere stata esclusa da quello degli errori
+      # (CYRB-17). Il gating vive qui e non in `CloseYourIt.log`: quel metodo serve anche il dev che
+      # scrive un log di proposito, e le sue righe non si silenziano.
       def add(severity, message = nil, progname = nil)
         severity ||= ::Logger::UNKNOWN
         return true if severity < level
 
         text = message || (block_given? ? yield : nil) || progname
-        CloseYourIt.log(SEVERITY_LEVELS.fetch(severity, "info"), text) unless text.nil?
+        return true if text.nil? || CloseYourIt.ignored_log_message?(text)
+
+        CloseYourIt.log(SEVERITY_LEVELS.fetch(severity, "info"), text)
         true
       end
     end

data/lib/closeyourit/rails/railtie.rb

@@ -10,6 +10,8 @@ require_relative "log_broadcast"
 require_relative "net_http_patch"
 require_relative "../subscribers/slow_query"
 require_relative "../subscribers/request_performance"
+require_relative "../subscribers/job_performance"
+require_relative "../sidekiq/job_metrics_middleware"
 
 module CloseYourIt
   module Rails
@@ -87,6 +89,24 @@ module CloseYourIt
         end
       end
 
+      # Misura durata e attesa in coda dei job ActiveJob via notifiche ActiveSupport: `perform_start`
+      # dà l'attesa (now - enqueued_at) appena il job parte, `perform` dà la durata dell'esecuzione a
+      # fine job. Oltre soglia → metriche slow_job / job_queue_latency. No-op se monitor_jobs è OFF.
+      initializer "closeyourit.subscribe_active_job_performance" do
+        jobs = CloseYourIt::Subscribers::JobPerformance.new
+
+        ActiveSupport::Notifications.subscribe("perform_start.active_job") do |*args|
+          job = ActiveSupport::Notifications::Event.new(*args).payload[:job]
+          jobs.active_job_started(job) if job
+        end
+
+        ActiveSupport::Notifications.subscribe("perform.active_job") do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          job = event.payload[:job]
+          jobs.active_job_performed(job, event.duration) if job
+        end
+      end
+
       # Cattura gli errori HANDLED riportati via Rails.error.report (Rails 7+).
       initializer "closeyourit.error_reporter" do
         if ::Rails.respond_to?(:error) && ::Rails.error.respond_to?(:subscribe)
@@ -110,11 +130,16 @@ module CloseYourIt
         end
       end
 
-      # Cattura gli errori dei job Sidekiq (solo se Sidekiq è presente).
+      # Cattura gli errori dei job Sidekiq + misura durata/attesa via server middleware (solo se
+      # Sidekiq è presente). Il middleware è no-op effettivo se monitor_jobs è OFF (la decisione vive
+      # in JobPerformance#record).
       initializer "closeyourit.sidekiq" do
         if defined?(::Sidekiq) && ::Sidekiq.respond_to?(:configure_server)
           ::Sidekiq.configure_server do |sidekiq_config|
             sidekiq_config.error_handlers << CloseYourIt::Sidekiq::ErrorHandler.new
+            sidekiq_config.server_middleware do |chain|
+              chain.add CloseYourIt::Sidekiq::JobMetricsMiddleware
+            end
           end
         end
       end

data/lib/closeyourit/rails/request_context.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "securerandom"
-require "rack/utils"
 
 module CloseYourIt
   module Rails
@@ -60,6 +59,10 @@ module CloseYourIt
         cookie = env["HTTP_COOKIE"]
         return nil if cookie.nil? || cookie.empty?
 
+        # `rack/utils` caricato lazy: il middleware gira solo dentro un'app Rack (dove Rack c'è di
+        # sicuro), così `require "closeyourit-ruby"` non forza Rack in app non-web (CLI/worker) e la
+        # gemma resta installabile senza dichiarare `rack` tra le dipendenze (CYRB-13).
+        require "rack/utils"
         Rack::Utils.parse_cookies_header(cookie)[REPLAY_COOKIE].to_s.then { |id| id.empty? ? nil : id }
       end
 

data/lib/closeyourit/sidekiq/job_metrics_middleware.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "../subscribers/job_performance"
+
+module CloseYourIt
+  module Sidekiq
+    # Server middleware Sidekiq (registrato dal railtie solo se Sidekiq è presente) che misura la durata
+    # di esecuzione e l'attesa in coda del job, poi delega a Subscribers::JobPerformance l'emissione
+    # delle metriche oltre soglia. Non altera il job: cronometra attorno allo `yield` e ri-solleva
+    # qualunque errore invariato (la cattura degli errori è dell'ErrorHandler). La misurazione avviene
+    # nell'`ensure`, così è presa anche per i job che sollevano; la telemetria è isolata (un errore nel
+    # nostro codice non disturba mai il job ospite). No-op effettivo se `monitor_jobs` è OFF (la
+    # decisione vive in #record).
+    class JobMetricsMiddleware
+      def initialize(subscriber = nil)
+        @subscriber = subscriber
+      end
+
+      def call(_worker, job, queue)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        # L'attesa in coda si conosce all'INIZIO (now - enqueued_at); Sidekiq mette enqueued_at come
+        # epoch in secondi. Calcolata prima dello yield per non includere la durata del job.
+        latency = Subscribers::JobPerformance.latency_ms(job["enqueued_at"], now: Time.now.utc)
+        yield
+      ensure
+        emit(job, queue, started, latency)
+      end
+
+      private
+
+      def emit(job, queue, started, latency)
+        duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+        subscriber.record(
+          job_class: job["wrapped"] || job["class"],
+          queue: queue || job["queue"],
+          adapter: "sidekiq",
+          duration_ms: duration_ms,
+          queue_latency_ms: latency,
+          attempt: attempt(job),
+          trace_id: job["jid"]
+        )
+      rescue StandardError => e
+        CloseYourIt.internal_logger.error("CloseYourIt job metrics: #{e.class}: #{e.message}")
+      end
+
+      def subscriber
+        @subscriber ||= Subscribers::JobPerformance.new
+      end
+
+      # Numero di esecuzione 1-based. Sidekiq NON imposta `retry_count` al primo run (nil), lo porta a 0
+      # al primo retry, 1 al secondo, ... → attempt = retry_count + 2 quando presente, 1 al primo run.
+      def attempt(job)
+        count = job["retry_count"]
+        count.nil? ? 1 : count + 2
+      end
+    end
+  end
+end

data/lib/closeyourit/stats.rb

@@ -4,12 +4,14 @@ require "concurrent"
 
 module CloseYourIt
   # Contatori diagnostici thread-safe del client: quanti eventi sono stati accodati,
-  # scartati (coda piena), spediti con successo o falliti (rete o status non-2xx).
-  # Servono a rendere visibili i fallimenti silenziosi del trasporto fire-and-forget.
+  # scartati (coda piena / before_send / sampling), spediti con successo, falliti (rete o status
+  # non-2xx) e, tra i falliti, quanti per timeout di rete. Rendono visibili i fallimenti silenziosi
+  # del trasporto fire-and-forget. `timeout` è un sotto-conteggio di `failed` (un timeout resta un
+  # fallimento d'invio): li teniamo distinti per isolare i problemi di connettività dai non-2xx.
   #
-  #   CloseYourIt.stats.to_h # => { enqueued: 12, dropped: 0, sent: 11, failed: 1 }
+  #   CloseYourIt.stats.to_h # => { enqueued: 12, dropped: 0, sent: 11, failed: 1, timeout: 1 }
   class Stats
-    COUNTERS = %i[enqueued dropped sent failed].freeze
+    COUNTERS = %i[enqueued dropped sent failed timeout].freeze
 
     def initialize
       @counters = COUNTERS.to_h { |name| [ name, Concurrent::AtomicFixnum.new(0) ] }
@@ -29,6 +31,11 @@ module CloseYourIt
       @counters.transform_values(&:value)
     end
 
+    # Fotografia thread-safe dei contatori (ogni valore letto atomicamente). È lo stesso Hash di
+    # `to_h`, con un nome esplicito per il caso d'uso "leggo la diagnostica locale" (CYRB-12): pura
+    # lettura in-memory, non invia mai telemetria.
+    alias_method :snapshot, :to_h
+
     def reset!
       @counters.each_value { |counter| counter.value = 0 }
       self

data/lib/closeyourit/subscribers/job_performance.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../events/job_metric_event"
+
+module CloseYourIt
+  module Subscribers
+    # Misura durata di esecuzione e attesa in coda (queue latency) dei background job — ActiveJob e
+    # Sidekiq — e, oltre le soglie configurate, emette metriche performance_issue (subtype `slow_job`
+    # e `job_queue_latency`). Logica PURA e SENZA STATO condiviso: tutto arriva per parametri, quindi
+    # job concorrenti sullo stesso thread/processo non si contaminano. Il wiring ad
+    # ActiveSupport::Notifications e al middleware Sidekiq vive altrove (Railtie / JobMetricsMiddleware).
+    # Rispetta il master switch `monitor_jobs`, le soglie e il `jobs_sample_rate`.
+    class JobPerformance
+      def initialize(configuration = nil)
+        @configuration = configuration
+      end
+
+      # Punto unico di decisione: dai valori misurati (durata e/o attesa) costruisce 0..2 metriche,
+      # applica le soglie (stretto `>`, così X non genera rumore e X+1 sì) e il sampling, poi le spedisce
+      # fire-and-forget. `duration_ms` e `queue_latency_ms` sono opzionali: ActiveJob li fornisce da due
+      # hook distinti (perform_start → attesa, perform → durata), Sidekiq entrambi in una sola chiamata.
+      # Il sampling è applicato SOLO ai candidati già oltre soglia (i job normali non consumano né
+      # generano nulla).
+      def record(job_class:, queue: nil, adapter: nil, duration_ms: nil, queue_latency_ms: nil,
+                 attempt: nil, trace_id: nil)
+        config = configuration
+        return unless config.monitor_jobs
+
+        common = { job_class: job_class, queue: queue, adapter: adapter, attempt: attempt, trace_id: trace_id }
+        events = []
+        events << build(config, "slow_job", duration_ms, common) if slow?(config, duration_ms)
+        events << build(config, "job_queue_latency", queue_latency_ms, common) if waited?(config, queue_latency_ms)
+        return if events.empty?
+        return unless sampled?(config)
+
+        events.each { |event| CloseYourIt.capture_event(event) }
+        nil
+      end
+
+      # Hook `perform_start.active_job`: l'attesa in coda è nota appena il job parte (now - enqueued_at).
+      def active_job_started(job, now: Time.now.utc)
+        record(
+          job_class: job.class.name,
+          queue: (job.queue_name if job.respond_to?(:queue_name)),
+          adapter: "active_job",
+          queue_latency_ms: self.class.latency_ms(enqueued_at(job), now: now),
+          attempt: (job.executions if job.respond_to?(:executions)),
+          trace_id: (job.job_id if job.respond_to?(:job_id))
+        )
+      end
+
+      # Hook `perform.active_job`: a fine esecuzione la durata è `event.duration` (ms).
+      def active_job_performed(job, duration_ms)
+        record(
+          job_class: job.class.name,
+          queue: (job.queue_name if job.respond_to?(:queue_name)),
+          adapter: "active_job",
+          duration_ms: duration_ms,
+          attempt: (job.executions if job.respond_to?(:executions)),
+          trace_id: (job.job_id if job.respond_to?(:job_id))
+        )
+      end
+
+      # Normalizza `enqueued_at` (Time, epoch Numerico in secondi come Sidekiq, o String ISO8601) in
+      # attesa (ms) rispetto a `now`. nil o non parsabile → nil: nessuna metrica di attesa (adapter che
+      # non popola l'istante di enqueue). Clamp a 0 se negativa (clock skew, enqueue "nel futuro"): lo
+      # schema di ingest esige `duration_ms >= 0`.
+      def self.latency_ms(enqueued_at, now:)
+        started = to_time(enqueued_at)
+        return nil if started.nil?
+
+        ms = (now - started) * 1000.0
+        ms.negative? ? 0.0 : ms
+      end
+
+      def self.to_time(value)
+        case value
+        when Time    then value
+        when Numeric then Time.at(value)
+        when String  then parse_time(value)
+        end
+      end
+
+      def self.parse_time(value)
+        Time.parse(value)
+      rescue ArgumentError
+        nil
+      end
+
+      private
+
+      def enqueued_at(job)
+        job.enqueued_at if job.respond_to?(:enqueued_at)
+      end
+
+      def configuration
+        @configuration || CloseYourIt.configuration
+      end
+
+      def slow?(config, duration_ms)
+        duration_ms && config.slow_job_threshold_ms && duration_ms > config.slow_job_threshold_ms
+      end
+
+      def waited?(config, latency_ms)
+        latency_ms && config.job_queue_latency_threshold_ms &&
+          latency_ms > config.job_queue_latency_threshold_ms
+      end
+
+      def sampled?(config)
+        rate = config.jobs_sample_rate.to_f
+        return true if rate >= 1.0
+        return false if rate <= 0.0
+
+        Random.rand < rate
+      end
+
+      def build(config, subtype, duration_ms, common)
+        JobMetricEvent.new(common.merge(subtype: subtype, duration_ms: duration_ms), config)
+      end
+    end
+  end
+end

data/lib/closeyourit/subscribers/slow_query.rb

@@ -21,6 +21,7 @@ module CloseYourIt
         config = @configuration || CloseYourIt.configuration
         return if ignored_name?(name)
         return if duration_ms < config.slow_query_threshold_ms
+        return if excluded_sql?(config, sql)
 
         event = SlowQueryEvent.new(
           { name: name, sql: sql, cached: cached, connection: connection,
@@ -77,6 +78,26 @@ module CloseYourIt
       def ignored_name?(name)
         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:
+      #
+      #   - 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.
+      #
+      # 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.
+      def excluded_sql?(config, sql)
+        return false if sql.nil?
+
+        patterns = config.excluded_query_patterns
+        return false if patterns.empty?
+
+        text = sql.to_s
+        patterns.any? { |pattern| pattern.match?(text) }
+      end
     end
   end
 end

data/lib/closeyourit/transport.rb

@@ -3,6 +3,7 @@
 require "net/http"
 require "json"
 require "uri"
+require "timeout"
 
 module CloseYourIt
   # Spedisce un payload a un path di ingest (errori → /events, metriche → /metrics) via HTTP POST
@@ -14,6 +15,10 @@ module CloseYourIt
     # Ri-POSTiamo a Location preservando metodo + body, così l'evento non si perde in silenzio.
     MAX_REDIRECTS = 2
 
+    # 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).
+    TIMEOUT_ERRORS = [ Net::OpenTimeout, Net::ReadTimeout, Timeout::Error ].freeze
+
     def initialize(configuration)
       @configuration = configuration
     end
@@ -22,19 +27,31 @@ module CloseYourIt
       response = post(payload, path)
       if response.is_a?(Net::HTTPSuccess)
         CloseYourIt.stats.increment(:sent)
+        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.notify_diagnostic(:drop, reason: :response, status: response.code.to_i)
       end
       response
     rescue StandardError => e
       CloseYourIt.stats.increment(:failed)
       CloseYourIt.internal_logger.error("CloseYourIt transport: #{e.class}: #{e.message}")
+      if timeout_error?(e)
+        CloseYourIt.stats.increment(:timeout)
+        CloseYourIt.notify_diagnostic(:timeout, error: e.class.name)
+      else
+        CloseYourIt.notify_diagnostic(:drop, reason: :network, error: e.class.name)
+      end
       nil
     end
 
     private
 
+    def timeout_error?(error)
+      TIMEOUT_ERRORS.any? { |klass| error.is_a?(klass) }
+    end
+
     def post(payload, path)
       body = JSON.generate(payload)
       origin = URI.parse("#{base_url}#{path}")

data/lib/closeyourit/version.rb

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

data/lib/closeyourit-ruby.rb

@@ -17,12 +17,14 @@ require_relative "closeyourit/events/slow_query_event"
 require_relative "closeyourit/events/slow_method_event"
 require_relative "closeyourit/events/log_event"
 require_relative "closeyourit/events/performance_issue_event"
+require_relative "closeyourit/events/job_metric_event"
 require_relative "closeyourit/performance/request_profile"
 require_relative "closeyourit/performance/rollup"
 require_relative "closeyourit/log_device"
 require_relative "closeyourit/log_buffer"
 require_relative "closeyourit/subscribers/slow_query"
 require_relative "closeyourit/subscribers/request_performance"
+require_relative "closeyourit/subscribers/job_performance"
 require_relative "closeyourit/instrumenter"
 require_relative "closeyourit/monitor"
 require_relative "closeyourit/client"
@@ -34,6 +36,7 @@ require_relative "closeyourit/rails/net_http_patch"
 require_relative "closeyourit/rails/active_job_extension"
 require_relative "closeyourit/rails/error_subscriber"
 require_relative "closeyourit/sidekiq/error_handler"
+require_relative "closeyourit/sidekiq/job_metrics_middleware"
 
 # CloseYourIt — client di telemetria (errori + statistiche di query/metodi lenti)
 # che invia gli eventi all'endpoint di ingest di CloseYourIt.
@@ -46,12 +49,27 @@ module CloseYourIt
 
   CAPTURED_FLAG = :@__closeyourit_captured
 
+  # Flag thread-local che segna "sono già dentro l'hook diagnostico": impedisce che una notifica
+  # emessa DENTRO l'hook (o da codice da esso invocato) rientri e riesegua l'hook → niente loop di
+  # auto-monitoraggio (CYRB-12). È per-thread perché le tappe girano su thread diversi (worker pool
+  # per send/timeout, thread chiamante per enqueue/drop).
+  DIAGNOSTIC_GUARD = :__closeyourit_in_diagnostic
+
   class << self
     # Configura il client. Senza token/endpoint → no-op.
+    #
+    # Una re-init SPEGNE prima il client e il log buffer della configurazione precedente (CYRB-10):
+    # azzerarli e basta lascerebbe orfani il thread del worker pool e il TimerTask del buffer, e gli
+    # eventi ancora in coda andrebbero persi o flushati fuori tempo dal timer orfano con la vecchia
+    # credenziale. Riusa la semantica di fine-vita di #shutdown (flush del buffer → drain del worker
+    # con timeout, CYRB-5) — così la coda precedente è svuotata in modo prevedibile con la sua config.
+    # Idempotente: alla prima init (o senza eventi catturati) @client/@log_buffer sono nil → no-op.
     def init
+      shutdown
       @configuration = Configuration.new
       @client = nil
       @log_buffer = nil
+      @shutdown_notified = false # nuova sessione: :shutdown potrà essere notificato di nuovo
       yield(@configuration) if block_given?
       @configuration.validate!
       register_shutdown_flush
@@ -73,12 +91,13 @@ module CloseYourIt
     # Cattura un'eccezione e la spedisce (fire-and-forget). No-op se disabilitato,
     # se l'eccezione è esclusa o già catturata.
     def capture_exception(exception, handled: false, level: "error", contexts: nil)
+      return nil if in_diagnostic?
       return nil unless enabled?
       return nil if ignored_exception?(exception)
       return nil if exception_captured?(exception)
 
       mark_captured(exception)
-      return nil unless sampled?
+      return record_drop(:sampled) unless sampled?
 
       event = ErrorEvent.from_exception(
         exception, configuration: configuration, handled: handled, level: level, contexts: contexts
@@ -88,6 +107,7 @@ module CloseYourIt
 
     # Spedisce un evento già costruito (slow_query/slow_method).
     def capture_event(event)
+      return nil if in_diagnostic?
       return nil unless enabled?
 
       client.capture_event(event)
@@ -96,8 +116,9 @@ module CloseYourIt
     # Invia un messaggio diagnostico esplicito (non un'eccezione). Soggetto a sampling + scope.
     #   CloseYourIt.capture_message("cache miss storm", level: "warning")
     def capture_message(message, level: "info")
+      return nil if in_diagnostic?
       return nil unless enabled?
-      return nil unless sampled?
+      return record_drop(:sampled) unless sampled?
 
       event = MessageEvent.new(message, level: level, configuration: configuration)
       client.capture_event(event)
@@ -181,9 +202,10 @@ module CloseYourIt
     # sorgente) e per impostare la sorgente solo via `.named` (child logger, parità dart/js — CYRB-8).
     # Le app usano `CloseYourIt.log` / `CloseYourIt.logger`.
     def emit_log(level, message, source: nil, attributes: {})
+      return nil if in_diagnostic?
       return nil unless logs_enabled?
       return nil if log_below_min_level?(level)
-      return nil unless logs_sampled?
+      return record_drop(:sampled) unless logs_sampled?
 
       event = LogEvent.new(message, level: level, attributes: attributes,
                                     logger: source, configuration: configuration)
@@ -197,6 +219,37 @@ module CloseYourIt
       logs_enabled?
     end
 
+    # Vero se una riga del broadcast Rails.logger va scartata: nomina un'eccezione già presente in
+    # `excluded_exceptions`, oppure combacia con `excluded_log_patterns`.
+    #
+    # Serve perché un'eccezione esclusa dal canale ERRORI rientrava da quello dei LOG: Rails la
+    # registra con `logger.error`, il broadcast inoltrava la riga senza guardarla, e il rumore che
+    # `excluded_exceptions` aveva appena scartato ricompariva come log-entry. Il 2026-07-30 erano
+    # 48.000 voci su 49.985 nello stream, quasi tutte `ActionController::RoutingError` da favicon
+    # mancanti e scansioni di bot — che è nella lista di default dalla prima riga (CYRB-17).
+    #
+    # `ignored_exception?` non è applicabile: qui la classe arriva come TESTO dentro il messaggio, non
+    # come oggetto con `ancestors` da confrontare. Da cui il match per sottostringa sui matcher String.
+    #
+    # Vale SOLO per il mirror automatico di Rails.logger: un `CloseYourIt.log` scritto di proposito
+    # dallo sviluppatore non si silenzia mai (chi lo scrive ha già deciso che vuole quella riga).
+    def ignored_log_message?(text)
+      text = text.to_s
+      return false if text.empty?
+
+      config = configuration
+      named = config.excluded_exceptions.any? do |matcher|
+        if matcher.is_a?(Regexp)
+          matcher.match?(text)
+        else
+          # Un matcher vuoto combacerebbe con qualunque riga: mai silenziare tutto per una lista sporca.
+          !matcher.empty? && text.include?(matcher)
+        end
+      end
+
+      named || config.excluded_log_patterns.any? { |pattern| pattern.match?(text) }
+    end
+
     # Forza l'invio dei log bufferizzati (chiamato anche allo shutdown del processo).
     def flush_logs
       @log_buffer&.flush
@@ -213,25 +266,112 @@ module CloseYourIt
       # Ordine critico: prima il buffer (accoda l'ultimo batch nel worker), poi il worker (lo drena).
       @log_buffer&.shutdown
       @client&.shutdown
+      # Riepilogo di fine-vita: l'app riceve lo snapshot dei contatori senza log rumorosi. Emesso una
+      # sola volta per sessione (uno shutdown esplicito seguito dall'at_exit non deve duplicarlo; il
+      # flag è azzerato a ogni init). Lo snapshot è best-effort: eventuali invii ancora in volo oltre il
+      # breve timeout di drain possono non esservi riflessi — il drain non blocca l'uscita (CYRB-5).
+      unless @shutdown_notified
+        @shutdown_notified = true
+        notify_diagnostic(:shutdown, stats: stats.to_h)
+      end
+      nil
+    end
+
+    # Ripristina le risorse di invio in un processo figlio dopo un fork. Chiamalo dai worker hook dei
+    # server che forkano (Puma `on_worker_boot`, Sidekiq/Unicorn `after_fork`) per ricreare SUBITO worker
+    # pool e log buffer nel figlio, invece di attendere la rilevazione lazy al primo evento. Opzionale:
+    # la gemma rileva comunque il cambio PID da sé (vedi #ensure_current_process!). Idempotente e sicuro
+    # anche se client/buffer non sono ancora stati materializzati (→ no-op, verranno creati lazy).
+    def after_fork
+      discard_inherited_client!
+      @pid = Process.pid
       nil
     end
 
-    # Contatori diagnostici del client (accodati/scartati/spediti/falliti).
-    #   CloseYourIt.stats.to_h # => { enqueued: …, dropped: …, sent: …, failed: … }
+    # Contatori diagnostici del client (accodati/scartati/spediti/falliti/timeout).
+    #   CloseYourIt.stats.to_h # => { enqueued: …, dropped: …, sent: …, failed: …, timeout: … }
     def stats
       @stats ||= Stats.new
     end
 
+    # Notifica una tappa del ciclo di vita di un evento all'hook `on_diagnostic` (se configurato).
+    # `event` è uno tra :enqueue, :send, :drop, :timeout, :shutdown; `details` un Hash privo di dati
+    # sensibili (es. `{ reason: :queue_full }`, `{ status: 429 }`). Chiamato da Client/Transport/
+    # BackgroundWorker/LogBuffer. Garanzie (CYRB-12):
+    #   * NON invia telemetria: tocca solo l'hook dell'app e i contatori in-memory;
+    #   * NON innesca loop di auto-monitoraggio: durante l'hook il guard è alzato, e finché è alzato
+    #     sono soppressi SIA i `notify_diagnostic` annidati SIA le API di telemetria (`capture_*`/log,
+    #     vedi #in_diagnostic?). Poiché l'accodamento della telemetria è sincrono nel thread dell'hook
+    #     (solo l'invio HTTP è async), sopprimere l'accodamento chiude il loop anche cross-thread;
+    #   * NON solleva: un hook difettoso è isolato (logga su internal_logger) e mai propagato nell'app.
+    # L'hook osserva sempre la configurazione CORRENTE: una notifica in volo che completa dopo una
+    # re-init raggiunge l'hook nuovo (best-effort, coerente col modello fire-and-forget).
+    def notify_diagnostic(event, **details)
+      hook = configuration.on_diagnostic
+      return nil if hook.nil?
+      return nil if Thread.current[DIAGNOSTIC_GUARD]
+
+      Thread.current[DIAGNOSTIC_GUARD] = true
+      begin
+        hook.call(event, details)
+      rescue StandardError => e
+        internal_logger.error("CloseYourIt diagnostic hook: #{e.class}: #{e.message}")
+      ensure
+        Thread.current[DIAGNOSTIC_GUARD] = false
+      end
+      nil
+    end
+
     private
 
+    # Vero se il thread corrente sta eseguendo l'hook diagnostico: le API di telemetria diventano no-op
+    # per impedire che un hook (mal scritto) generi altra telemetria e inneschi auto-monitoraggio.
+    def in_diagnostic?
+      Thread.current[DIAGNOSTIC_GUARD] == true
+    end
+
+    # Registra uno scarto: incrementa il contatore aggregato `dropped` e notifica `:drop` con il motivo
+    # (queue_full/before_send/sampled/error). Un unico punto tiene allineati snapshot e hook.
+    def record_drop(reason, **details)
+      stats.increment(:dropped)
+      notify_diagnostic(:drop, reason: reason, **details)
+      nil
+    end
+
     def client
+      ensure_current_process!
       @client ||= Client.new(configuration)
     end
 
     def log_buffer
+      ensure_current_process!
       @log_buffer ||= LogBuffer.new(client: client, configuration: configuration)
     end
 
+    # Rileva un fork confrontando il PID del processo in cui @client/@log_buffer sono stati materializzati
+    # con quello corrente. In un figlio forkato i due oggetti sono ereditati dal padre, ma i loro thread
+    # — il worker pool di Client e il TimerTask di LogBuffer — vivono solo nel padre (il fork copia il
+    # solo thread chiamante): gli eventi accodati non partirebbero mai, restando affidati a thread che
+    # esistono soltanto nel padre. Al cambio di PID abbandoniamo i riferimenti ereditati SENZA #shutdown
+    # (nessun join possibile sui thread del padre, e un flush del buffer rispedirebbe eventi del padre) →
+    # i getter li ricreano lazy sotto il processo corrente. Nel padre lo stato resta invariato.
+    def ensure_current_process!
+      pid = Process.pid
+      return if @pid == pid
+
+      discard_inherited_client! if @pid # non alla prima materializzazione (@pid nil): nulla da abbandonare
+      @pid = pid
+    end
+
+    # Sgancia i riferimenti a client e log buffer senza drenarli. Usato sia dalla rilevazione lazy del
+    # fork sia da #after_fork: nel figlio i thread sottostanti non esistono, quindi non c'è nulla da
+    # joinare e non si deve flushare (rispedirebbe gli eventi del padre). Il GC raccoglie i vecchi
+    # oggetti; i getter ne creano di nuovi al prossimo accesso.
+    def discard_inherited_client!
+      @client = nil
+      @log_buffer = nil
+    end
+
     # I log seguono il master switch del client + il proprio flag dedicato.
     def logs_enabled?
       enabled? && configuration.logs_enabled

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: closeyourit-ruby
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Alessio Bussolari
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
 description: Gemma client che cattura eccezioni e le statistiche di query e metodi
   lenti e le invia, fire-and-forget, all'endpoint di ingest di CloseYourIt.
 email:
@@ -41,6 +55,7 @@ files:
 - lib/closeyourit/configuration.rb
 - lib/closeyourit/event.rb
 - lib/closeyourit/events/error_event.rb
+- lib/closeyourit/events/job_metric_event.rb
 - lib/closeyourit/events/log_event.rb
 - lib/closeyourit/events/message_event.rb
 - lib/closeyourit/events/performance_issue_event.rb
@@ -65,7 +80,9 @@ files:
 - lib/closeyourit/scope.rb
 - lib/closeyourit/scrubber.rb
 - lib/closeyourit/sidekiq/error_handler.rb
+- lib/closeyourit/sidekiq/job_metrics_middleware.rb
 - lib/closeyourit/stats.rb
+- lib/closeyourit/subscribers/job_performance.rb
 - lib/closeyourit/subscribers/request_performance.rb
 - lib/closeyourit/subscribers/slow_query.rb
 - lib/closeyourit/transport.rb