closeyourit-ruby 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8d2868773842804dc2c90f163ea4766ea748c59edf8adaa956f257827391e8c
-  data.tar.gz: 7fe183c1a6c64226f341b09c7da4cd37bf58bb75409b9afc20c223efc55ffe1f
+  metadata.gz: c80dd7130394211bc1c0ebbf7a13bbe9906951b667734380bdf38aac53f194ae
+  data.tar.gz: 9adde552df65cee4cd32d47161bdd84fbe5a69c06698b9fc5c9cfd5a1a2a1088
 SHA512:
-  metadata.gz: fc0267a4f038cd2ab3f6e0af119cacbdb368cdce3f4d07d2a01ea1b8b5f2d2c4f4753fed6d5dcc0b71c5826868c7557eab614d7b0f37f953fd586aff01147c1b
-  data.tar.gz: 0b6e57599d21d07d4d2552331aa14d17bed514c7ed0733881d4a7ebd850051ca1271137fac7147f1e2d12c74c69e6e5e265017b256c36abf06ffd6342b458350
+  metadata.gz: 1f7cc16b574bfc124e9f9f49037a7045dc30a7125da890f78ae6c7c36712a418da61dbd2170a12a8d34be35ea5fc8fb96568dc58e1e573677fe67afb902c071e
+  data.tar.gz: aa9871930fa03617485c993e2f84db54aeb23ecd092c8a2a15a463e9dcda75c710d3cadef95f14081bbe3844cca50f4215ef0c5b40cb149e205ff1d6e701a575

data/README.md

@@ -72,6 +72,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) |
+| `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 |
 | `slow_method_threshold_ms` | `200` | Soglia metodi lenti |
 | `capture_request` | `true` | Cattura il contesto HTTP della richiesta (method/url/header allowlist) |
@@ -83,7 +84,21 @@ end
 | `send_pii` | `false` | Master switch PII |
 | `obfuscate_sql` | `true` | Maschera i literal nello SQL |
 | `filter_parameters` | `[]` | Chiavi extra da redarre (mergiate con quelle di Rails) |
-| `scrub_message_patterns` | `[]` | Regexp da redarre dai messaggi d'eccezione |
+| `scrub_message_patterns` | `[]` | Regexp da redarre da messaggi d'eccezione **e da `message` dei log** |
+| `logs_enabled` | `true` | Master switch dello stream di log strutturato |
+| `logs_min_level` | `:info` | Soglia minima: i log sotto (es. `debug`) non vengono inviati |
+| `logs_sample_rate` | `1.0` | Frazione di log inviata (`1.0` tutto, `0.0` niente) |
+| `logs_batch_size` | `50` | Log accumulati nel buffer prima di un flush a batch verso `/logs` |
+| `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 |
+| `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` |
+| `query_time_threshold_ms` | `500` | Tempo DB totale per richiesta (ms) oltre cui = `high_query_count` |
+| `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`) |
 
 ## Cosa cattura
 
@@ -116,6 +131,55 @@ Query string e IP solo con `send_pii`. Lo scope è resettato a fine richiesta (n
   `mechanism.handled = true` e il `level` mappato dalla severity. La dedup garantisce un solo invio anche
   se la stessa eccezione passa da più punti (Rack + job + reporter).
 
+### Log strutturati (manuale/automatico) → stream log
+
+Stream di log strutturati (`level`/`message`/`attributes`/`logger`) separato dagli errori, correlato via
+`trace_id` (stesso della richiesta). Bufferizzato e spedito a batch a `/logs`. `message` **e**
+`attributes` passano dallo scrubber (denylist chiavi + `scrub_message_patterns`) come gli errori.
+
+```ruby
+# API esplicita — il keyword `logger:` è la sorgente del log; ogni altra keyword è un attributo
+CloseYourIt.log(:info, "ordine creato", order_id: order.id, amount: order.amount)
+CloseYourIt.log(:warning, "retry pagamento", attempt: 2)
+
+# Interfaccia ::Logger-like (level via metodo)
+CloseYourIt.logger.warn("cache miss", key: cache_key)
+CloseYourIt.logger.error("job fallito", job: self.class.name)
+```
+
+La **sorgente** del log (campo `logger`) si imposta con `.named` — child logger immutabile, stesso
+idioma di dart/js. Il logger radice resta invariato:
+
+```ruby
+payments = CloseYourIt.logger.named("payments")   # child con sorgente "payments"
+payments.warn("retry", attempt: 3)                # logger="payments", attributes={attempt: 3}
+```
+
+Sull'interfaccia `.logger` una chiave `logger:` è **sempre un attributo dati** (non viene hijackata
+come sorgente): `CloseYourIt.logger.warn("disco pieno", logger: "/dev/sda1")` mette `logger` negli
+`attributes`. Sorgente (`.named`) e attributo `logger` possono coesistere senza collidere.
+
+Ogni log sotto `logs_min_level` (default `:info`) è **scartato** prima di essere costruito o spedito —
+`CloseYourIt.log` e `CloseYourIt.logger.*` usano la mappa di livelli (`debug` < `info` < `warning` <
+`error` < `fatal`), identica agli SDK dart/js. Un `CloseYourIt.logger.debug(...)` in un loop caldo con
+la soglia di default non produce alcun invio.
+
+Con Rails, `capture_rails_logs = true` inoltra anche `Rails.logger` allo stream, ma con una soglia
+**dedicata** `capture_rails_logs_min_level` (default `:warn`, distinta da `logs_min_level`): in
+produzione ad alto traffico Rails logga a `:info` ogni richiesta (`Started GET`, `Rendered`, ...) e un
+default a `:info` inonderebbe lo stream col rumore del framework — la soglia conservativa lo evita.
+Abbassala esplicitamente (es. `config.capture_rails_logs_min_level = :info`) solo se vuoi anche gli
+`info` del framework. I log dei background job ereditano il `trace_id = job_id`, così log ed errore
+dello stesso job si correlano.
+
+#### Flush di fine-vita
+
+Il buffer log viene svuotato automaticamente allo **shutdown del processo**: `CloseYourIt.init` registra
+un `at_exit` che drena anche il worker asincrono (attende gli invii in volo, non solo il flush del
+buffer), così i log sotto-batch di rake/CLI non vanno persi all'uscita. `SIGTERM` (deploy/Kamal)
+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.
+
 ### Contesto, breadcrumbs e messaggi (manuale)
 
 ```ruby
@@ -156,6 +220,43 @@ end
 Viene inviato un `slow_method` solo se la durata supera `slow_method_threshold_ms`. **Gli argomenti
 del metodo non vengono mai inviati** (solo label, durata, file:riga).
 
+## Performance issues (opt-in)
+
+`slow_query` e `slow_method` sono metriche **puntuali** (una query/un metodo lenti). Oltre a queste,
+con **`detect_performance_issues = true`** la gemma profila **ogni query della richiesta**
+(fingerprint + call-site) e, a fine richiesta, emette 0..N **verdetti** `performance_issue` sulla
+pipeline metriche (`/api/v1/projects/:id/metrics`). Un verdetto non è una singola query lenta: è un
+**pattern dell'intera richiesta**, aggregato e correlato a log/errori via `trace_id`. I quattro
+`subtype`:
+
+- **`n_plus_one`** — lo stesso `[fingerprint SQL, call-site]` eseguito più di `n_plus_one_threshold`
+  volte (default 10) nella stessa richiesta: il classico N+1. Un verdetto per gruppo, con lo SQL già
+  offuscato e il `source` (`file:riga`) che lo ha originato.
+- **`high_query_count`** — troppe query in una richiesta: numero totale oltre `query_count_threshold`
+  (default 100) **oppure** tempo DB totale oltre `query_time_threshold_ms` (default 500 ms).
+- **`slow_request`** — durata totale della richiesta oltre `slow_request_threshold_ms` (default
+  1000 ms), con `route`, `query_count` e tempo DB come contesto.
+- **`slow_external_http`** — una singola chiamata HTTP esterna (`Net::HTTP`) oltre
+  `slow_external_threshold_ms` (default 1000 ms). Richiede `capture_external_http` (default `true`, che
+  strumenta `Net::HTTP` **solo** quando la detection è attiva); host e path templatizzato, mai la query string.
+
+```ruby
+CloseYourIt.init do |c|
+  # …endpoint_url / token / project_id…
+  c.detect_performance_issues = true
+end
+```
+
+Con Rails il wiring è **automatico** (il Railtie si iscrive a `process_action.action_controller`):
+attivato il master switch, non serve altro codice. Le soglie sopra sono conservative (poco rumore) e
+tutte ritoccabili.
+
+> **Overhead — perché è opt-in (default OFF).** Per aggregare i verdetti la detection profila **ogni**
+> query della richiesta (fingerprint + call-site): un costo non trascurabile, da attivare
+> consapevolmente per-app. `slow_query`/`slow_method` restano attive e **indipendenti** da questo
+> 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.)
+
 ## Privacy & PII
 
 Privacy-by-default (`send_pii = false`). In sintesi:

data/lib/closeyourit/client.rb

@@ -27,6 +27,13 @@ module CloseYourIt
       accepted = @worker.perform { @transport.send_event(payload, path: path) }
       CloseYourIt.stats.increment(:enqueued) if accepted
       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.
+      CloseYourIt.internal_logger.error("CloseYourIt client: #{e.class}: #{e.message}")
+      nil
     end
 
     # Invia un batch di log come ARRAY a /logs (l'endpoint accetta singolo o array). before_send è
@@ -43,7 +50,8 @@ module CloseYourIt
 
       path = events.first.ingest_path(@configuration.project_id)
       payloads.each_slice(LOGS_MAX_BATCH) do |chunk|
-        @worker.perform { @transport.send_event(chunk, path: path) }
+        accepted = @worker.perform { @transport.send_event(chunk, path: path) }
+        CloseYourIt.stats.increment(:enqueued) if accepted
       end
       payloads
     end

data/lib/closeyourit/configuration.rb

@@ -25,11 +25,11 @@ module CloseYourIt
                   :breadcrumbs_enabled, :max_breadcrumbs, :sample_rate,
                   :capture_handled_errors, :report_active_job_errors,
                   :logs_enabled, :logs_sample_rate, :logs_batch_size, :logs_flush_interval,
-                  :capture_rails_logs, :logs_min_level,
+                  :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
-    attr_writer :release
+                  :capture_external_http, :trap_signals
+    attr_writer :release, :project_root
     attr_reader :excluded_exceptions, :filter_parameters, :scrub_message_patterns
 
     def initialize
@@ -45,6 +45,11 @@ module CloseYourIt
       @async_threads               = default_threads
       @background_worker_max_queue  = 30
 
+      # Intercetta SIGTERM per garantire il flush di fine-vita (deploy/Kamal): SIGTERM di default
+      # termina il processo SENZA eseguire gli at_exit. OPT-IN perché sovrascrive un eventuale handler
+      # TERM dell'app ospite. Vedi CloseYourIt.shutdown / register_shutdown_flush (CYRB-5).
+      @trap_signals = false
+
       @slow_query_threshold_ms  = 100
       @slow_method_threshold_ms = 200
 
@@ -87,6 +92,12 @@ module CloseYourIt
       # Broadcast opt-in di Rails.logger → CloseYourIt.log (default OFF; spedisce solo ≥ soglia).
       @capture_rails_logs = false
       @logs_min_level     = :info
+      # Soglia DEDICATA del broadcast Rails.logger, distinta da logs_min_level (che governa
+      # CloseYourIt.log/.logger, dove è il dev a scegliere cosa loggare). Default :warn — conservativo:
+      # senza, in produzione ad alto traffico OGNI riga info del framework (Started GET, Rendered, ...)
+      # 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
 
       # 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
@@ -99,6 +110,10 @@ module CloseYourIt
       @slow_external_threshold_ms = 1000     # singola chiamata HTTP esterna
       @capture_external_http     = true      # strumenta Net::HTTP (solo se detect_performance_issues)
 
+      # 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
+
       @filter_parameters      = []
       @scrub_message_patterns = []
     end
@@ -145,6 +160,23 @@ module CloseYourIt
       @release = detect_release
     end
 
+    # Radice del progetto effettiva: quella impostata, altrimenti auto-rilevata (Rails.root o Dir.pwd).
+    # Usata per rendere `frame.filename` relativo (culprit confrontabile cross-SDK — CYRB-4).
+    def project_root
+      return @project_root unless @project_root.nil?
+
+      @project_root = detect_project_root
+    end
+
+    # Rails.root quando l'app gira sotto Rails, altrimenti la working directory. Mai solleva.
+    def detect_project_root
+      return ::Rails.root.to_s if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+
+      Dir.pwd
+    rescue StandardError
+      Dir.pwd
+    end
+
     # Auto-rilevamento release dalle env di deploy/CI o dal git short SHA. Mai solleva.
     def detect_release
       ENV["KAMAL_VERSION"] ||

data/lib/closeyourit/events/error_event.rb

@@ -75,13 +75,15 @@ module CloseYourIt
 
     # Sentry-style: frame più recente per ultimo; chiavi filename/function/lineno/in_app/abs_path
     # + snippet di sorgente (pre_context/context_line/post_context) quando il file è leggibile.
+    # `filename` è relativo/basename (culprit confrontabile cross-SDK — CYRB-4); `abs_path` è il
+    # path assoluto per il dettaglio e per leggere il sorgente delle context lines.
     def frames(locations)
       return [] if locations.nil?
 
       context_lines = @configuration.context_lines.to_i
       locations.reverse.map do |loc|
         frame = {
-          "filename" => loc.path,
+          "filename" => relative_filename(loc.path),
           "abs_path" => loc.path,
           "function" => loc.label,
           "lineno" => loc.lineno,
@@ -92,6 +94,21 @@ module CloseYourIt
       end
     end
 
+    # Path da mostrare (Sentry `filename`): relativo alla project_root se il file è dentro l'app
+    # (es. "app/models/user.rb"), altrimenti il basename (gem/stdlib/path esterni → "base.rb").
+    # Allinea Ruby agli altri SDK (Dart/JS mandano basename/relativo), così il culprit
+    # "filename in function" è confrontabile a colpo d'occhio su progetti poliglotti. Vedi CYRB-4.
+    def relative_filename(path)
+      return path if path.nil?
+
+      root = @configuration.project_root.to_s
+      prefix = root.empty? ? nil : File.join(root, "") # root con separatore finale, portabile
+      return File.basename(path) unless prefix && path.start_with?(prefix)
+
+      relative = path[prefix.length..]
+      relative.nil? || relative.empty? ? File.basename(path) : relative
+    end
+
     def add_context!(frame, path, lineno, count)
       lines = LineCache.lines(path)
       return if lines.nil? || lineno.nil? || lineno < 1 || lineno > lines.size

data/lib/closeyourit/events/log_event.rb

@@ -1,23 +1,47 @@
 # frozen_string_literal: true
 
 require "securerandom"
+require_relative "../scrubber"
 
 module CloseYourIt
   # Voce di log strutturata spedita all'ingest /logs (NON formato Sentry: i log sono uno stream con
-  # message/level/attributes/logger). Gli `attributes` passano dallo Scrubber (denylist). `trace_id`
-  # è preso dallo Scope corrente (popolato per richiesta) → correlazione log↔errori della stessa request.
+  # message/level/attributes/logger). `message` E `attributes` passano dallo Scrubber (denylist +
+  # pattern) come ErrorEvent — un log può contenere PII/segreti quanto un errore. `trace_id` è
+  # congelato alla COSTRUZIONE (thread della richiesta) → correlazione log↔errori della stessa request
+  # anche quando il flush avviene su un thread timer diverso.
   class LogEvent < Event
     # Livelli canonici del backend (enum) + alias dei nomi stile ::Logger. Normalizzati QUI (fonte
     # unica) così ogni costruzione — via CloseYourIt.log, .logger o diretta — produce un livello valido.
+    # L'indice in LEVELS è anche la severità numerica del livello (debug=0 … fatal=4): la STESSA mappa
+    # di dart/js, così il gating per soglia (`logs_min_level`) filtra identico cross-SDK (CYRB-6).
     LEVELS = %w[debug info warning error fatal].freeze
     LEVEL_ALIASES = { "warn" => "warning", "err" => "error", "unknown" => "fatal" }.freeze
 
+    # Normalizza qualsiasi livello (simbolo/stringa, maiuscole, alias) al nome canonico del backend.
+    # Ignoto → "info". Metodo di classe: fonte unica riusata da `CloseYourIt.log` per il gating.
+    def self.normalize_level(level)
+      value = level.to_s.downcase
+      value = LEVEL_ALIASES.fetch(value, value)
+      LEVELS.include?(value) ? value : "info"
+    end
+
+    # Severità numerica del livello (indice in LEVELS), identica alla mappa cross-SDK. Usata per il
+    # confronto con `logs_min_level` prima di costruire/spedire il log.
+    def self.severity(level)
+      LEVELS.index(normalize_level(level))
+    end
+
     def initialize(message, level:, attributes:, configuration:, logger: nil)
       super(configuration)
       @message = message
-      @level = normalize_level(level)
+      @level = self.class.normalize_level(level)
       @attributes = attributes || {}
       @logger = logger
+      @scrubber = Scrubber.new(configuration)
+      # trace_id catturato QUI, sul thread della richiesta: il LogEvent viene bufferizzato e flushato
+      # su un thread timer diverso, dove lo Scope corrente è di un'ALTRA richiesta (o vuoto) → leggerlo
+      # lazy in to_h romperebbe la correlazione log↔errore. Lo congeliamo alla costruzione.
+      @trace_id = CloseYourIt::Scope.current.trace_id
     end
 
     def to_h
@@ -25,10 +49,10 @@ module CloseYourIt
         "event_id" => SecureRandom.uuid.delete("-"),
         "timestamp" => @occurred_at,
         "level" => @level,
-        "message" => @message.to_s,
+        "message" => @scrubber.scrub_message(@message.to_s),
         "attributes" => scrubbed_attributes,
         "logger" => @logger,
-        "trace_id" => CloseYourIt::Scope.current.trace_id,
+        "trace_id" => @trace_id,
         "environment" => environment,
         "release" => @configuration.release,
         "sdk" => sdk
@@ -41,16 +65,10 @@ module CloseYourIt
 
     private
 
-    def normalize_level(level)
-      value = level.to_s.downcase
-      value = LEVEL_ALIASES.fetch(value, value)
-      LEVELS.include?(value) ? value : "info"
-    end
-
     def scrubbed_attributes
       return {} if @attributes.nil? || @attributes.empty?
 
-      Scrubber.new(@configuration).filter_params(deep_stringify_keys(@attributes))
+      @scrubber.filter_params(deep_stringify_keys(@attributes))
     end
 
     # Chiavi sempre stringa (anche annidate): coerenza col payload JSON e con la denylist dello Scrubber.

data/lib/closeyourit/events/message_event.rb

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
 require "securerandom"
+require_relative "../scrubber"
 
 module CloseYourIt
   # Messaggio diagnostico esplicito (`CloseYourIt.capture_message`) nel formato evento Sentry
-  # (`message.formatted` + level). Fonde lo Scope corrente come ErrorEvent.
+  # (`message.formatted` + level). Fonde lo Scope corrente come ErrorEvent. Il messaggio passa dallo
+  # Scrubber (pattern) come `exception.message` di ErrorEvent — parità PII cross-evento.
   class MessageEvent < Event
     def initialize(message, level:, configuration:)
       super(configuration)
       @message = message
       @level = level
+      @scrubber = Scrubber.new(configuration)
     end
 
     def to_h
@@ -18,10 +21,12 @@ module CloseYourIt
         "timestamp" => @occurred_at,
         "platform" => "ruby",
         "level" => @level,
+        # Correlazione log↔errori: stesso trace_id dei log della medesima richiesta (parità con ErrorEvent).
+        "trace_id" => CloseYourIt::Scope.current.trace_id,
         "environment" => environment,
         "release" => @configuration.release,
         "server_name" => server_name,
-        "message" => { "formatted" => @message },
+        "message" => { "formatted" => @scrubber.scrub_message(@message.to_s) },
         "contexts" => { "runtime" => { "name" => "ruby", "version" => RUBY_VERSION } },
         "sdk" => sdk
       )

data/lib/closeyourit/log_buffer.rb

@@ -32,6 +32,11 @@ module CloseYourIt
       return if batch.empty?
 
       @client.flush_logs(batch)
+    rescue StandardError => e
+      # Il flush gira sia sul thread della richiesta (batch pieno) sia sul thread timer: un to_h /
+      # 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}")
     end
 
     def shutdown

data/lib/closeyourit/log_device.rb

@@ -2,13 +2,32 @@
 
 module CloseYourIt
   # Oggetto Logger-compatibile esposto come `CloseYourIt.logger`: ogni chiamata inoltra a
-  # `CloseYourIt.log` (→ ingest /logs). Usabile come logger esplicito dell'app, anche con attributes:
+  # `CloseYourIt.emit_log` (→ ingest /logs). Usabile come logger esplicito dell'app, anche con attributes:
   #   CloseYourIt.logger.warn("disco quasi pieno", disk: "sda1")
   # `warn` mappa sul livello `warning` (enum backend); supporta block e `::Logger#add` per drop-in.
+  #
+  # La sorgente del log (campo `logger` del payload) si imposta SOLO via `.named` (child logger, parità
+  # dart/js) o via costruttore — MAI da una keyword dei metodi: così una chiave `logger` passata a un
+  # metodo resta un attributo dati e non viene hijackata come sorgente (CYRB-8).
+  #   payments = CloseYourIt.logger.named("payments") # child con sorgente "payments"
+  #   payments.warn("retry", attempt: 3)              # logger=payments, attributes={attempt:3}
+  #   CloseYourIt.logger.warn("disco pieno", logger: "/dev/sda1") # attributes={logger:"/dev/sda1"}
   class LogDevice
     # Severità numeriche ::Logger → livelli CloseYourIt (UNKNOWN→fatal).
     SEVERITY_LEVELS = { 0 => "debug", 1 => "info", 2 => "warning", 3 => "error", 4 => "fatal", 5 => "fatal" }.freeze
 
+    # `source` = nome della sorgente del log (campo `logger` del payload). Preferire `.named` in app.
+    def initialize(source = nil)
+      @source = normalize_source(source)
+    end
+
+    # Child logger con sorgente esplicita (parità dart/js). Ritorna un NUOVO LogDevice: il logger su
+    # cui è chiamato resta invariato (immutabile), come i child logger cross-SDK.
+    #   CloseYourIt.logger.named("payments").info("retry", attempt: 3)
+    def named(source)
+      self.class.new(source)
+    end
+
     def debug(message = nil, **attributes, &block) = write("debug", message, attributes, &block)
     def info(message = nil, **attributes, &block)  = write("info", message, attributes, &block)
     def warn(message = nil, **attributes, &block)  = write("warning", message, attributes, &block)
@@ -33,7 +52,17 @@ module CloseYourIt
       return unless CloseYourIt.logs_active?
 
       message = block.call if block
-      CloseYourIt.log(level, message, **attributes)
+      # Sorgente e attributes separati: gli `attributes` (inclusa un'eventuale chiave `logger`) restano
+      # dati; la sorgente è SOLO `@source` (via `.named`/costruttore) → nessuna collisione (CYRB-8).
+      CloseYourIt.emit_log(level, message, source: @source, attributes: attributes)
+    end
+
+    # Sorgente vuota/blank → nessuna sorgente (nil); altrimenti stringa (il campo `logger` è testuale).
+    def normalize_source(source)
+      return nil if source.nil?
+
+      value = source.to_s.strip
+      value.empty? ? nil : value
     end
   end
 end

data/lib/closeyourit/rails/active_job_extension.rb

@@ -36,6 +36,10 @@ module CloseYourIt
         context["job_id"] = job.job_id if job.respond_to?(:job_id)
         context["executions"] = job.executions if job.respond_to?(:executions)
         CloseYourIt.set_context("active_job", context) unless context.empty?
+
+        # Un trace_id stabile per esecuzione (job_id è unico per run ActiveJob): log ed errore dello
+        # stesso job condividono il trace_id → correlazione log↔errore anche fuori dal ciclo richiesta.
+        CloseYourIt::Scope.current.trace_id = job.job_id if job.respond_to?(:job_id)
       end
     end
   end

data/lib/closeyourit/rails/log_broadcast.rb

@@ -5,15 +5,17 @@ require "logger"
 module CloseYourIt
   module Rails
     # Sink Logger-compatibile agganciato a Rails.logger (broadcast opt-in, `config.capture_rails_logs`):
-    # ogni log dell'app ≥ soglia (`logs_min_level`) viene re-inoltrato a CloseYourIt.log → ingest /logs.
-    # Sotto soglia: no-op (nessun invio). Non scrive su alcun device (inoltra soltanto).
+    # ogni log dell'app ≥ soglia (`capture_rails_logs_min_level`, default :warn) viene re-inoltrato a
+    # CloseYourIt.log → ingest /logs. Sotto soglia: no-op (nessun invio). Il default è conservativo
+    # (:warn) per non inondare lo stream col rumore info del framework (CYRB-7). Non scrive su alcun
+    # device (inoltra soltanto).
     class LogBroadcast < ::Logger
       SEVERITY_LEVELS = { 0 => "debug", 1 => "info", 2 => "warning", 3 => "error", 4 => "fatal", 5 => "fatal" }.freeze
       LEVEL_BY_SYMBOL = { debug: 0, info: 1, warn: 2, warning: 2, error: 3, fatal: 4 }.freeze
 
-      def initialize(min_level = :info)
+      def initialize(min_level = :warn)
         super(nil) # nessun device: inoltra soltanto
-        self.level = LEVEL_BY_SYMBOL.fetch(min_level.to_sym, 1)
+        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.

data/lib/closeyourit/rails/railtie.rb

@@ -95,7 +95,10 @@ module CloseYourIt
       end
 
       # Broadcast opt-in di Rails.logger → CloseYourIt.log (config.capture_rails_logs, default OFF).
-      # Spedisce solo i log dell'app ≥ logs_min_level. Richiede BroadcastLogger (Rails 7.1+).
+      # Spedisce solo i log dell'app ≥ capture_rails_logs_min_level: soglia DEDICATA (default :warn),
+      # distinta da logs_min_level, così il broadcast non inonda lo stream col rumore info del framework
+      # (Started GET, Rendered, ... — una riga per richiesta ad alto traffico, CYRB-7). Richiede
+      # BroadcastLogger (Rails 7.1+).
       # `after: :load_config_initializers`: config.capture_rails_logs è impostato in
       # config/initializers/closeyourit.rb (CloseYourIt.init), che gira DOPO gli initializer dei
       # railtie. Senza questo `after:` il check leggerebbe il default (false) e il broadcast non
@@ -103,7 +106,7 @@ module CloseYourIt
       initializer "closeyourit.capture_rails_logs", after: :load_config_initializers do
         config = CloseYourIt.configuration
         if config.capture_rails_logs && ::Rails.logger.respond_to?(:broadcast_to)
-          ::Rails.logger.broadcast_to(CloseYourIt::Rails::LogBroadcast.new(config.logs_min_level))
+          ::Rails.logger.broadcast_to(CloseYourIt::Rails::LogBroadcast.new(config.capture_rails_logs_min_level))
         end
       end
 

data/lib/closeyourit/rails/request_context.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "securerandom"
+require "rack/utils"
 
 module CloseYourIt
   module Rails
@@ -12,6 +13,10 @@ module CloseYourIt
       # Header con prefisso non-HTTP_ in env Rack.
       RAW_HEADERS = %w[CONTENT_TYPE CONTENT_LENGTH].freeze
 
+      # Cookie di correlazione scritto dal browser SDK (session replay): id opaco della
+      # sessione di replay, trasportato da ogni richiesta same-origin.
+      REPLAY_COOKIE = "cyi_replay"
+
       def initialize(app)
         @app = app
       end
@@ -20,6 +25,9 @@ module CloseYourIt
         if enabled?
           # trace_id sempre (correlazione log↔errori), anche con capture_request OFF.
           CloseYourIt::Scope.current.trace_id = trace_id_for(env)
+          # Correlazione errore server ↔ session replay: l'id dal cookie finisce sullo scope
+          # → contexts.replay.replay_id dell'evento (stesso punto del percorso JS).
+          CloseYourIt::Scope.current.replay_session_id = replay_session_id_for(env)
           if CloseYourIt.configuration.capture_request
             CloseYourIt::Scope.current.request = build_request(env)
             # Riferimento all'env per l'estrazione LAZY del body (request.data) a evento costruito.
@@ -47,6 +55,14 @@ module CloseYourIt
           SecureRandom.uuid
       end
 
+      # Estrae `cyi_replay` dal cookie della richiesta (nil se assente). Rack puro.
+      def replay_session_id_for(env)
+        cookie = env["HTTP_COOKIE"]
+        return nil if cookie.nil? || cookie.empty?
+
+        Rack::Utils.parse_cookies_header(cookie)[REPLAY_COOKIE].to_s.then { |id| id.empty? ? nil : id }
+      end
+
       # Forma `request` Sentry. URL senza query string; header solo dall'allowlist (mai
       # Authorization/Cookie). query_string + IP solo con send_pii (opt-in).
       def build_request(env)

data/lib/closeyourit/scope.rb

@@ -35,7 +35,7 @@ module CloseYourIt
       end
     end
 
-    attr_accessor :request, :trace_id, :rack_env
+    attr_accessor :request, :trace_id, :rack_env, :replay_session_id
     attr_reader :user, :tags, :extra, :contexts, :breadcrumbs
 
     def initialize
@@ -80,6 +80,7 @@ module CloseYourIt
       @request     = nil
       @rack_env    = nil
       @trace_id    = nil
+      @replay_session_id = nil
       @breadcrumbs = BreadcrumbBuffer.new(CloseYourIt.configuration.max_breadcrumbs)
       @performance_profile = nil
     end
@@ -93,7 +94,7 @@ module CloseYourIt
         "user"        => serialize_user,
         "tags"        => scrub(presence(@tags)),
         "extra"       => scrub(presence(@extra)),
-        "contexts"    => scrub(presence(@contexts)),
+        "contexts"    => contexts_payload,
         "request"     => request_payload,
         "breadcrumbs" => breadcrumbs_payload
       }.reject { |_key, value| value.nil? }
@@ -101,6 +102,15 @@ module CloseYourIt
 
     private
 
+    # contexts utente + `replay.replay_id` (session replay) quando presente sullo scope: il
+    # backend legge contexts.replay.replay_id per legare l'errore server al video (stesso punto
+    # del percorso JS). replay/replay_id non sono chiavi sensibili → sopravvivono allo Scrubber.
+    def contexts_payload
+      merged = @contexts.dup
+      merged["replay"] = { "replay_id" => @replay_session_id } if @replay_session_id
+      scrub(presence(merged))
+    end
+
     # Redige i valori delle chiavi sensibili preservando la struttura (es. contexts.runtime resta
     # intatto, solo i valori sotto chiavi sensibili diventano [FILTERED]). Riusa lo Scrubber della
     # configurazione, lo stesso percorso di breadcrumb.data e degli attributi di log.

data/lib/closeyourit/scrubber.rb

@@ -6,14 +6,21 @@ module CloseYourIt
   class Scrubber
     FILTERED = "[FILTERED]"
 
-    # Token di chiavi sempre redatti (match per sottostringa, normalizzato). Allineato 1:1 al regex
-    # di backend e client Dart (parità client-side) — vedi Errors/Logs::Ingest::Normalize::SENSITIVE_KEY:
-    #   /pass|secret|token|api[_-]?key|apikey|authorization|cookie|csrf|credit|card|cvv|ssn|iban/i
+    # Token di chiavi sempre redatti (match per sottostringa, normalizzato). Allineato al regex
+    # SENSITIVE_KEY di backend e client Dart (parità client-side) — vedi
+    # Errors/Logs::Ingest::Normalize::SENSITIVE_KEY. Copre credenziali/segreti e PII:
+    #   /pass|secret|token|api[_-]?key|apikey|authorization|cookie|csrf|credit|card|cvv|ssn|iban|
+    #    email|phone|telephone|mobile|dob|birth|passport|bearer|session|pin|pan/i
     # `pass` copre password/passwd/pass_code/passkey/passphrase; `cookie` copre set-cookie;
-    # `credit`+`card` coprono credit_card. La lista letterale precedente ometteva i `pass*` bare → leak.
+    # `credit`+`card` coprono credit_card; `phone` copre telephone/smartphone; `birth` copre
+    # date_of_birth. Match per sottostringa → privilegia l'over-redaction (privacy-by-default):
+    # p.es. `company_name` (contiene `pan`) o `shipping` (contiene `pin`) vengono redatti — è
+    # accettabile, meglio redigere troppo che perdere PII.
+    # CYRB-3: la lista ometteva email/phone/dob → i bind delle query lente li leakavano nel pannello.
     DENYLIST = %w[
       pass secret token api_key apikey authorization
       cookie csrf credit card cvv ssn iban
+      email phone telephone mobile dob birth passport bearer session pin pan
     ].freeze
 
     STRING_LITERAL = /'(?:[^']|'')*'/

data/lib/closeyourit/subscribers/slow_query.rb

@@ -29,6 +29,9 @@ module CloseYourIt
           config
         )
         CloseYourIt.capture_event(event)
+      rescue StandardError
+        # La telemetria non deve mai disturbare la query ospite.
+        nil
       end
 
       # Breadcrumb per OGNI query non di sistema (non solo lente): SQL offuscato, niente bind.
@@ -44,6 +47,9 @@ module CloseYourIt
           message: scrubber(config).obfuscate_sql(sql),
           data: { "name" => name, "duration_ms" => duration_ms.to_f.round(2), "cached" => cached }
         )
+      rescue StandardError
+        # La telemetria non deve mai disturbare la query ospite.
+        nil
       end
 
       # Spinge OGNI query non di sistema nel RequestProfile dello Scope (per la detection N+1 a fine

data/lib/closeyourit/transport.rb

@@ -24,7 +24,7 @@ module CloseYourIt
         CloseYourIt.stats.increment(:sent)
       else
         CloseYourIt.stats.increment(:failed)
-        CloseYourIt.internal_logger.warn("CloseYourIt transport: HTTP #{response.code} su #{path}")
+        CloseYourIt.internal_logger.warn("CloseYourIt transport: HTTP #{response.code}#{error_detail(response)} su #{path}")
       end
       response
     rescue StandardError => e
@@ -37,11 +37,12 @@ module CloseYourIt
 
     def post(payload, path)
       body = JSON.generate(payload)
-      uri = URI.parse("#{base_url}#{path}")
+      origin = URI.parse("#{base_url}#{path}")
+      uri = origin
       redirects = 0
 
       loop do
-        response = post_once(uri, body)
+        response = post_once(uri, body, authorize: same_authority?(origin, uri))
         location = response["location"] if response.is_a?(Net::HTTPRedirection)
         return response unless location && redirects < MAX_REDIRECTS
 
@@ -50,14 +51,16 @@ module CloseYourIt
       end
     end
 
-    def post_once(uri, body)
+    def post_once(uri, body, authorize:)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == "https"
       http.open_timeout = OPEN_TIMEOUT
       http.read_timeout = READ_TIMEOUT
 
       request = Net::HTTP::Post.new(uri.request_uri)
-      request["Authorization"] = "Bearer #{@configuration.token}"
+      # Il Bearer è un segreto d'ingest: non ri-inviarlo dopo un redirect verso un host diverso
+      # (o un downgrade https→http), per non consegnarlo a un endpoint non fidato.
+      request["Authorization"] = "Bearer #{@configuration.token}" if authorize
       request["Content-Type"] = "application/json"
       request["User-Agent"] = "closeyourit-ruby/#{VERSION}"
       request.body = body
@@ -71,6 +74,27 @@ module CloseYourIt
       target.relative? ? current + target : target
     end
 
+    # Il Bearer va ri-inviato solo se il redirect resta sullo stesso host (o la sua variante www) e
+    # senza downgrade https→http: evita di consegnare il segreto d'ingest a un host non fidato.
+    def same_authority?(origin, target)
+      return false if origin.scheme == "https" && target.scheme != "https"
+
+      origin.host.to_s.sub(/\Awww\./, "") == target.host.to_s.sub(/\Awww\./, "")
+    end
+
+    # Estrae " R…: messaggio" dall'envelope d'errore del backend, così il dev vede il codice d'errore
+    # nel log diagnostico (non solo lo status HTTP). Silenzioso se il body non è l'envelope atteso.
+    def error_detail(response)
+      body = JSON.parse(response.body.to_s)
+      error = body["error"]
+      return "" unless error.is_a?(Hash)
+
+      detail = [ error["code"], error["message"] ].compact.join(": ")
+      detail.empty? ? "" : " #{detail}"
+    rescue StandardError
+      ""
+    end
+
     def base_url
       @configuration.endpoint_url.to_s.chomp("/")
     end

data/lib/closeyourit/version.rb

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

data/lib/closeyourit-ruby.rb

@@ -165,17 +165,28 @@ module CloseYourIt
       @app_logger ||= LogDevice.new
     end
 
-    # Costruisce e bufferizza una voce di log strutturata (batch verso /logs, fire-and-forget). Il
-    # `level` è normalizzato ai livelli canonici (`:warn`→`warning`, downcase; ignoto→`info`). `logger`
-    # opzionale = nome della sorgente del log.
+    # API esplicita: costruisce e bufferizza una voce di log strutturata (batch verso /logs,
+    # fire-and-forget). Il `level` è normalizzato ai livelli canonici (`:warn`→`warning`, downcase;
+    # ignoto→`info`). Il keyword `logger:` = nome della sorgente del log; ogni altra keyword è un
+    # attributo dati. I log sotto `logs_min_level` sono scartati con la stessa mappa numerica di
+    # dart/js (regola standardize, not adapt — CYRB-6): niente costruzione né invio.
     #   CloseYourIt.log(:info, "ordine creato", order_id: 1)
     #   CloseYourIt.log(:warn, "retry", logger: "payments", attempt: 3)
     def log(level, message, logger: nil, **attributes)
+      emit_log(level, message, source: logger, attributes: attributes)
+    end
+
+    # Percorso a basso livello (gating + costruzione + buffer) con sorgente e attributes SEPARATI e
+    # non-ambigui: usato da `LogDevice` per trattare una chiave `logger` come attributo dati (mai come
+    # 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 unless logs_enabled?
+      return nil if log_below_min_level?(level)
       return nil unless logs_sampled?
 
       event = LogEvent.new(message, level: level, attributes: attributes,
-                                    logger: logger, configuration: configuration)
+                                    logger: source, configuration: configuration)
       log_buffer.add(event)
       nil
     end
@@ -192,6 +203,19 @@ module CloseYourIt
       nil
     end
 
+    # Flush di fine-vita: svuota i log bufferizzati E drena il worker asincrono, attendendo (fino a un
+    # timeout breve) che gli invii in volo verso l'ingest completino. Solo flushare il buffer li
+    # accoderebbe nel worker che verrebbe poi ucciso alla terminazione → log persi (CYRB-5). Drena
+    # TUTTO il worker (log + errori + metriche fire-and-forget), non solo i log. Registrato su at_exit
+    # da CloseYourIt.init; con `config.trap_signals` viene raggiunto anche su SIGTERM. Idempotente:
+    # richiamarlo è sicuro (buffer già vuoto, worker già fermo → no-op).
+    def shutdown
+      # Ordine critico: prima il buffer (accoda l'ultimo batch nel worker), poi il worker (lo drena).
+      @log_buffer&.shutdown
+      @client&.shutdown
+      nil
+    end
+
     # Contatori diagnostici del client (accodati/scartati/spediti/falliti).
     #   CloseYourIt.stats.to_h # => { enqueued: …, dropped: …, sent: …, failed: … }
     def stats
@@ -213,6 +237,12 @@ module CloseYourIt
       enabled? && configuration.logs_enabled
     end
 
+    # Gating per soglia: il log è scartato se la sua severità è sotto `logs_min_level`. La severità è
+    # la mappa numerica di LogEvent (debug=0 … fatal=4), identica cross-SDK → filtra come dart/js.
+    def log_below_min_level?(level)
+      LogEvent.severity(level) < LogEvent.severity(configuration.logs_min_level)
+    end
+
     # Sampling indipendente dei log (1.0 = tutti, 0.0 = nessuno).
     def logs_sampled?
       rate = configuration.logs_sample_rate.to_f
@@ -222,13 +252,36 @@ module CloseYourIt
       Random.rand < rate
     end
 
-    # Allo shutdown del processo svuota i log bufferizzati e ferma il timer (una sola registrazione).
-    # Senza, i log sotto-batch dei processi brevi (rake/CLI) andrebbero persi all'uscita.
+    # Allo shutdown del processo svuota i log bufferizzati e drena il worker asincrono. Senza, i log
+    # sotto-batch dei processi brevi (rake/CLI) e gli ultimi eventi accodati andrebbero persi all'uscita.
+    # Con `config.trap_signals` intercetta anche SIGTERM, che di default salta gli at_exit (deploy/Kamal
+    # perderebbero il flush). Vedi #shutdown (CYRB-5).
+    #
+    # L'at_exit si registra una sola volta per processo (@shutdown_registered evita N flush da init
+    # multiple), ma il trap SIGTERM è valutato PRIMA del guard e a OGNI init: deve seguire la config
+    # CORRENTE, altrimenti una init che attiva `trap_signals` dopo una prima con la flag OFF non lo
+    # installerebbe mai (il guard di idempotenza ritornerebbe prima). `Signal.trap` è idempotente →
+    # reinstallare lo stesso handler è innocuo.
     def register_shutdown_flush
+      install_term_trap if configuration.trap_signals
+
       return if @shutdown_registered
 
       @shutdown_registered = true
-      at_exit { @log_buffer&.shutdown }
+      at_exit { shutdown }
+    end
+
+    # SIGTERM termina il processo SENZA eseguire gli at_exit → il flush di fine-vita non girerebbe.
+    # Convertiamo TERM in un exit pulito: `exit` solleva SystemExit sul thread principale, che ESEGUE
+    # gli at_exit (incluso #shutdown) in contesto normale — niente lavoro pesante nel trap handler
+    # (Mutex/wait_for_termination in trap context solleverebbero ThreadError). Opt-in: sovrascrive un
+    # eventuale handler TERM dell'app ospite.
+    def install_term_trap
+      Signal.trap("TERM") { exit }
+    rescue ArgumentError, RuntimeError => e
+      # Contesti dove TERM non è trap-abile (piattaforma senza TERM, thread non-main): non fatale,
+      # resta comunque l'at_exit per le uscite normali.
+      internal_logger.warn("CloseYourIt: trap SIGTERM non installato (#{e.class}: #{e.message})")
     end
 
     def ignored_exception?(exception)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: closeyourit-ruby
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Alessio Bussolari