closeyourit-ruby 0.6.1 → 0.8.0

data/lib/closeyourit-ruby.rb

@@ -5,6 +5,7 @@ require "logger"
 require_relative "closeyourit/version"
 require_relative "closeyourit/configuration"
 require_relative "closeyourit/breadcrumb"
+require_relative "closeyourit/trace_context"
 require_relative "closeyourit/scope"
 require_relative "closeyourit/scrubber"
 require_relative "closeyourit/stats"
@@ -17,12 +18,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 +37,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 +50,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 +92,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 +108,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 +117,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 +203,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 +220,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 +267,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.1
+  version: 0.8.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,9 +80,12 @@ 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/trace_context.rb
 - lib/closeyourit/transport.rb
 - lib/closeyourit/version.rb
 homepage: https://github.com/bussolabs/closeyourit-ruby