closeyourit-ruby 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d841fba2147566f662dce067e2d41c44d44cf6d402fb929fc3c73eb9a6af4a1
+  data.tar.gz: cf7b435c2c9a336f107930ded5fc2ad197032a5d62eeca07f25594775a111bcc
+SHA512:
+  metadata.gz: a5172771940399ca5f3f2706e35d3c72d16942b79e0b2bbb89f0dfa184e4a66d45f7644704d45b6fb8f62f645b01bc84e75d7abe1d8a08ae0fced77e87781dcf
+  data.tar.gz: dc9b5cc1387ecfb81b70a58815c0f79f7e68f1aeda98c2d3af14d0862f2dd28878a6803a1193e2737c4d8990b833c2aadf0d4461b393a26810957a1b6f0749d0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alessio Bussolari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,177 @@
+# closeyourit-ruby
+
+Client di telemetria per [CloseYourIt](../closeyourit-rails). Una gemma che il tuo progetto Rails
+installa per inviare a CloseYourIt:
+
+- **Eccezioni** → in **formato evento Sentry**, sul path Bearer `/api/v1/projects/:id/events`. Finiscono
+  nel error-tracker (raggruppate, triage, promote-to-ticket) come quelle di un SDK Sentry.
+- **Query/metodi lenti** → sul path `/api/v1/projects/:id/metrics` (pipeline metriche dedicata,
+  raggruppate per signature con aggregati di durata) — ciò che Sentry/GlitchTip non danno bene.
+
+È il **client primario** di CloseYourIt: replica e migliora ciò che fa un SDK Sentry (request context,
+user/tag/contesto, breadcrumbs, errori nei background job, errori handled, sampling, messaggi) senza
+dipendere dagli SDK Sentry.
+
+Caratteristiche:
+- **Contesto ricco** sull'errore: request HTTP (method/url/header), user/tag/contesto custom, breadcrumbs
+  (cronologia query offuscate prima del crash).
+- Cattura **automatica** di: eccezioni non gestite (Rack), errori in **ActiveJob/Sidekiq** (oggi persi),
+  errori **handled** (`Rails.error.report`), query/metodi lenti.
+- `capture_message`, **sampling** (`sample_rate`), ignore per **Regexp**, release detection automatica.
+- Invio **fire-and-forget**: thread pool in background, non blocca la request, **non crasha mai** l'app.
+- **No-op** se non configurata (sicura in sviluppo/test).
+- **Privacy-by-default**: niente PII a meno di abilitarla esplicitamente.
+
+> Design e contratto dati in [`PDR.md`](PDR.md).
+
+## Installazione
+
+Uso interno → install via git o path (no RubyGems):
+
+```ruby
+# Gemfile del progetto da monitorare
+gem "closeyourit-ruby", git: "https://github.com/bussolabs/closeyourit-ruby"
+# in sviluppo locale:
+# gem "closeyourit-ruby", path: "../closeyourit-ruby"
+```
+
+## Ottenere credenziali
+
+In CloseYourIt, area **Member → Project → tokens**, crea un token: ottieni il **Bearer secret**
+(mostrato una volta) e l'**UUID del progetto**. Servono entrambi alla gemma.
+
+## Configurazione
+
+```ruby
+# config/initializers/closeyourit.rb
+CloseYourIt.init do |c|
+  c.endpoint_url = ENV["CLOSEYOURIT_ENDPOINT_URL"]   # es. https://closeyour.it
+  c.token        = ENV["CLOSEYOURIT_TOKEN"]          # Bearer secret del Projects::Token
+  c.project_id   = ENV["CLOSEYOURIT_PROJECT_ID"]     # UUID del progetto su CloseYourIt
+  c.environment  = Rails.env
+end
+```
+
+**Senza `endpoint_url` / `token` / `project_id` la gemma è no-op** (nessun invio, nessun overhead). In
+`production` un `endpoint_url` `http://` viene rifiutato (no-op + warning): il token viaggerebbe in chiaro.
+
+### Opzioni
+
+| Opzione | Default | Descrizione |
+|---|---|---|
+| `endpoint_url` | `ENV["CLOSEYOURIT_ENDPOINT_URL"]` | URL base (la gemma appende i path per-progetto) |
+| `token` | `ENV["CLOSEYOURIT_TOKEN"]` | Bearer secret del progetto |
+| `project_id` | `ENV["CLOSEYOURIT_PROJECT_ID"]` | UUID progetto (nel path di ingest) |
+| `release` | `ENV["CLOSEYOURIT_RELEASE"]` | Versione riportata negli errori (opzionale) |
+| `environment` | `Rails.env` / `RACK_ENV` / `"development"` | Ambiente riportato negli eventi |
+| `excluded_exceptions` | `RoutingError`, `RecordNotFound` | Eccezioni da NON inviare — **String** (nome classe) o **Regexp** (match su nome/messaggio) |
+| `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) |
+| `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) |
+| `request_header_allowlist` | `Accept`, `Content-Type`, `User-Agent`, `Referer` | Header inviati (mai Authorization/Cookie) |
+| `breadcrumbs_enabled` | `true` | Cronologia (query offuscate + `add_breadcrumb`) allegata all'errore |
+| `max_breadcrumbs` | `100` | Dimensione max del ring buffer breadcrumbs |
+| `capture_handled_errors` | `true` | Cattura gli errori riportati via `Rails.error.report` |
+| `report_active_job_errors` | `true` | Cattura gli errori dei job ActiveJob/Solid Queue/Sidekiq |
+| `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 |
+
+## Cosa cattura
+
+### Eccezioni (automatico, con Rails) → error-tracker
+
+Il Railtie inserisce un Rack middleware che cattura le eccezioni non gestite, le invia come **evento
+Sentry** (`exception.values[]`, `level`, `event_id`, stacktrace) e le **ri-solleva** (l'app continua a
+gestirle come prima). Cattura manuale ovunque:
+
+```ruby
+begin
+  rischioso!
+rescue => e
+  CloseYourIt.capture_exception(e)
+  raise
+end
+```
+
+### Request context (automatico, con Rails)
+
+Un Rack middleware allega a ogni evento il contesto HTTP della richiesta: **method**, **url** (senza
+query string) e gli **header dell'allowlist** (`request_header_allowlist`, mai Authorization/Cookie).
+Query string e IP solo con `send_pii`. Lo scope è resettato a fine richiesta (niente bleed tra request).
+
+### Background job + errori handled (automatico, con Rails)
+
+- **ActiveJob / Solid Queue / Sidekiq**: gli errori dei job (prima persi) vengono catturati con tag
+  `job.class`/`job.queue` e contesto del job, poi ri-sollevati.
+- **`Rails.error.report`** (ActiveSupport ErrorReporter): gli errori *handled* vengono inviati con
+  `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).
+
+### Contesto, breadcrumbs e messaggi (manuale)
+
+```ruby
+CloseYourIt.set_user(id: account.id)              # solo id; email/ip solo se send_pii
+CloseYourIt.set_tag(:tenant, current_tenant.slug)
+CloseYourIt.set_context(:billing, { plan: "pro" })
+CloseYourIt.set_extra(:cart_size, cart.size)
+CloseYourIt.configure_scope { |s| s.set_tag(:area, "checkout") }
+
+CloseYourIt.add_breadcrumb(message: "coupon applicato", category: "ui")  # cronologia pre-crash
+CloseYourIt.capture_message("cache miss storm", level: "warning")        # messaggio diagnostico
+```
+
+Lo scope (user/tag/contesto/breadcrumbs) è **per-richiesta/job** e viene allegato automaticamente
+all'evento d'errore catturato nello stesso contesto di esecuzione.
+
+### Query lente (automatico, con Rails) → metriche
+
+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).
+
+### Metodi lenti → metriche
+
+```ruby
+# Blocco ad-hoc
+CloseYourIt.measure("checkout.total") do
+  calcolo_pesante
+end
+
+# Macro su un metodo (wrap automatico, firma e valore di ritorno invariati)
+class Report
+  include CloseYourIt::Monitor
+  def generate(...) = ...
+  monitor :generate
+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).
+
+## Privacy & PII
+
+Privacy-by-default (`send_pii = false`). In sintesi:
+
+- **SQL**: inviato il template, **mai** i bind values; `obfuscate_sql` maschera anche i literal inline.
+- **Chiavi sensibili** (`password`, `token`, `authorization`, `cookie`, `secret`, `api_key`, `csrf`,
+  `credit_card`, `cvv`, `ssn`, `iban`, …) → `[FILTERED]`; estendibili con `filter_parameters`.
+- **Messaggi d'eccezione**: inviati per il debug, ma redigibili con `scrub_message_patterns` /
+  `before_send`.
+- **Mai inviati**: variabili locali dei frame, argomenti dei metodi, IP/cookie/Authorization, token (che
+  viaggia solo nell'header su HTTPS).
+
+> Rischio residuo: `exception.value` e i nomi tabella/colonna nello SQL possono contenere dati di
+> dominio. Usa `before_send`/`scrub_message_patterns` per azzerarli. Dettaglio in [`PDR.md` §9](PDR.md).
+
+## Sviluppo
+
+```bash
+bundle install
+bundle exec rspec        # test (WebMock, niente rete reale)
+bundle exec rubocop      # lint (omakase)
+COVERAGE_ENFORCE=1 bundle exec rspec   # gate coverage ≥90% line
+```

data/lib/closeyourit/background_worker.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module CloseYourIt
+  # Esegue l'invio fire-and-forget. Con `threads == 0` esegue sincrono (test/dev);
+  # altrimenti usa una thread-pool con coda bounded e `fallback_policy: :discard`
+  # (se la coda è piena l'evento si perde, mai backpressure sulla request).
+  class BackgroundWorker
+    attr_reader :executor
+
+    def initialize(threads:, max_queue: 30)
+      @executor = build_executor(threads.to_i, max_queue)
+    end
+
+    def perform(&block)
+      @executor.post do
+        block.call
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        # Mai propagare: la telemetria non deve poter crashare l'app ospite.
+        CloseYourIt.logger.error("CloseYourIt background worker: #{e.class}: #{e.message}")
+      end
+    end
+
+    def shutdown(timeout = 1)
+      return unless @executor.respond_to?(:shutdown)
+
+      @executor.shutdown
+      @executor.wait_for_termination(timeout)
+    end
+
+    private
+
+    def build_executor(threads, max_queue)
+      return Concurrent::ImmediateExecutor.new if threads <= 0
+
+      Concurrent::ThreadPoolExecutor.new(
+        min_threads: 0,
+        max_threads: threads,
+        max_queue: max_queue,
+        fallback_policy: :discard
+      )
+    end
+  end
+end

data/lib/closeyourit/breadcrumb.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "time"
+
+module CloseYourIt
+  # Singola briciola di contesto (query, navigazione, evento custom) precedente a un errore.
+  # Forma evento Sentry (`breadcrumbs.values[]`). Il `data` è già scrubato a monte (module API).
+  class Breadcrumb
+    def initialize(message: nil, category: nil, type: "default", level: "info", data: {}, timestamp: nil)
+      @timestamp = timestamp || Time.now.utc.iso8601
+      @type      = type
+      @category  = category
+      @level     = level
+      @message   = message
+      @data      = data
+    end
+
+    def to_h
+      {
+        "timestamp" => @timestamp,
+        "type"      => @type,
+        "category"  => @category,
+        "level"     => @level,
+        "message"   => @message,
+        "data"      => presence(@data)
+      }.reject { |_key, value| value.nil? }
+    end
+
+    private
+
+    def presence(value)
+      value.nil? || value.empty? ? nil : value
+    end
+  end
+end

data/lib/closeyourit/breadcrumb_buffer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CloseYourIt
+  # Ring buffer limitato di breadcrumb. Vive nello Scope (un buffer per execution-context),
+  # scritto solo dal thread proprietario → niente mutex. Oltre `max_size` droppa il più vecchio.
+  class BreadcrumbBuffer
+    def initialize(max_size)
+      @max_size = max_size.to_i
+      @items = []
+    end
+
+    def add(breadcrumb)
+      return self unless @max_size.positive?
+
+      @items.shift while @items.size >= @max_size
+      @items << breadcrumb
+      self
+    end
+
+    def to_a
+      @items.map(&:to_h)
+    end
+
+    def empty?
+      @items.empty?
+    end
+
+    def size
+      @items.size
+    end
+  end
+end

data/lib/closeyourit/client.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CloseYourIt
+  # Compone Transport + BackgroundWorker: applica `before_send` e dispatcha
+  # l'invio in modo fire-and-forget.
+  class Client
+    def initialize(configuration)
+      @configuration = configuration
+      @transport = Transport.new(configuration)
+      @worker = BackgroundWorker.new(
+        threads: configuration.async_threads,
+        max_queue: configuration.background_worker_max_queue
+      )
+    end
+
+    def capture_event(event)
+      payload = event.to_h
+      payload = @configuration.before_send.call(payload) if @configuration.before_send
+      return nil if payload.nil?
+
+      path = event.ingest_path(@configuration.project_id)
+      @worker.perform { @transport.send_event(payload, path: path) }
+      payload
+    end
+
+    def shutdown
+      @worker.shutdown
+    end
+  end
+end

data/lib/closeyourit/configuration.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "uri"
+require "concurrent"
+
+module CloseYourIt
+  # Tiene tutte le opzioni del client. Costruita da `CloseYourIt.init { |c| ... }`.
+  # Senza `endpoint_url`/`token`/`project_id` (o con `http://` in produzione) il client è no-op.
+  class Configuration
+    DEFAULT_EXCLUDED_EXCEPTIONS = %w[
+      ActionController::RoutingError
+      ActiveRecord::RecordNotFound
+    ].freeze
+
+    # 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,
+                  :async_threads, :background_worker_max_queue,
+                  :slow_query_threshold_ms, :slow_method_threshold_ms,
+                  :send_pii, :obfuscate_sql, :send_server_name,
+                  :capture_query_bindings, :capture_method_arguments,
+                  :capture_request, :request_header_allowlist,
+                  :breadcrumbs_enabled, :max_breadcrumbs, :sample_rate,
+                  :capture_handled_errors, :report_active_job_errors
+    attr_writer :release
+    attr_reader :excluded_exceptions, :filter_parameters, :scrub_message_patterns
+
+    def initialize
+      @endpoint_url = ENV.fetch("CLOSEYOURIT_ENDPOINT_URL", nil)
+      @token        = ENV.fetch("CLOSEYOURIT_TOKEN", nil)
+      @project_id   = ENV.fetch("CLOSEYOURIT_PROJECT_ID", nil)
+      @release      = ENV.fetch("CLOSEYOURIT_RELEASE", nil)
+      @environment  = ENV.fetch("CLOSEYOURIT_ENVIRONMENT") { detect_environment }
+
+      @excluded_exceptions = DEFAULT_EXCLUDED_EXCEPTIONS.dup
+      @before_send         = nil
+
+      @async_threads               = default_threads
+      @background_worker_max_queue  = 30
+
+      @slow_query_threshold_ms  = 100
+      @slow_method_threshold_ms = 200
+
+      @send_pii         = false
+      @obfuscate_sql    = true
+      @send_server_name = true
+
+      # Contesto HTTP della richiesta (method/url/header allowlist). Body/query/IP solo con send_pii.
+      @capture_request          = true
+      @request_header_allowlist = DEFAULT_REQUEST_HEADER_ALLOWLIST.dup
+
+      # Breadcrumbs: cronologia (query offuscate, eventi custom) allegata all'errore.
+      @breadcrumbs_enabled = true
+      @max_breadcrumbs     = 100
+
+      # Sampling probabilistico di errori/messaggi (1.0 = invia tutto, 0.0 = niente).
+      @sample_rate = 1.0
+
+      # Cattura errori handled (Rails.error.report) e degli ActiveJob/Sidekiq (oggi persi).
+      @capture_handled_errors   = true
+      @report_active_job_errors = true
+
+      # Cattura valori dei parametri — opt-in, default OFF (privacy). I bind/argomenti possono contenere PII.
+      @capture_query_bindings   = false
+      @capture_method_arguments = false
+
+      @filter_parameters      = []
+      @scrub_message_patterns = []
+    end
+
+    # Classi/stringhe → nome (String); i Regexp restano Regexp (match per pattern su nome/messaggio).
+    def excluded_exceptions=(list)
+      @excluded_exceptions = Array(list).map { |item| item.is_a?(Regexp) ? item : item.to_s }
+    end
+
+    def filter_parameters=(list)
+      @filter_parameters = Array(list)
+    end
+
+    def scrub_message_patterns=(list)
+      @scrub_message_patterns = Array(list)
+    end
+
+    def production?
+      environment.to_s == "production"
+    end
+
+    # Il client invia solo con credenziali complete (endpoint + token + project_id) e trasporto
+    # sicuro (http:// ammesso fuori produzione).
+    def enabled?
+      return false if blank?(endpoint_url) || blank?(token) || blank?(project_id)
+      return false if insecure_endpoint? && production?
+
+      true
+    end
+
+    # Logga i warning di configurazione (es. endpoint http://). Chiamata da `CloseYourIt.init`.
+    def validate!
+      CloseYourIt.logger.warn(insecure_endpoint_message) if insecure_endpoint?
+      self
+    end
+
+    # Release effettiva: quella impostata, altrimenti auto-rilevata (ENV di deploy/CI o git).
+    def release
+      return @release unless @release.nil?
+
+      @release = detect_release
+    end
+
+    # Auto-rilevamento release dalle env di deploy/CI o dal git short SHA. Mai solleva.
+    def detect_release
+      ENV["KAMAL_VERSION"] ||
+        ENV["GIT_SHA"] ||
+        ENV["GIT_REVISION"] ||
+        ENV["SOURCE_VERSION"] ||
+        ENV["HEROKU_SLUG_COMMIT"] ||
+        git_revision
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    # `.git` è una directory in un checkout normale, un file in un worktree → File.directory?
+    # è false nei worktree, così i test non lanciano subprocess git (deterministico).
+    def git_revision
+      return nil unless File.directory?(".git")
+
+      sha = `git rev-parse --short HEAD 2>/dev/null`.strip
+      sha.empty? ? nil : sha
+    rescue StandardError
+      nil
+    end
+
+    def insecure_endpoint?
+      uri = parsed_endpoint
+      !uri.nil? && uri.scheme != "https"
+    end
+
+    def insecure_endpoint_message
+      tail = production? ? "Telemetria DISABILITATA in production." : "Consentito solo in sviluppo."
+      "CloseYourIt: endpoint_url usa http:// non sicuro (#{endpoint_url}) — il token viaggerebbe in chiaro. #{tail}"
+    end
+
+    def parsed_endpoint
+      return nil if blank?(endpoint_url)
+
+      URI.parse(endpoint_url)
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def detect_environment
+      return ::Rails.env.to_s if defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env
+
+      ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+    end
+
+    def default_threads
+      [ (Concurrent.processor_count / 2.0).ceil, 1 ].max
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/closeyourit/event.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "time"
+require "socket"
+
+module CloseYourIt
+  # Base degli eventi di telemetria. Le sottoclassi implementano `#to_h` e `#ingest_path`
+  # (il path API a cui l'evento va spedito: errori → /events, metriche → /metrics).
+  class Event
+    def initialize(configuration)
+      @configuration = configuration
+      @occurred_at = Time.now.utc.iso8601
+    end
+
+    def to_h
+      raise NotImplementedError, "#{self.class} deve implementare #to_h"
+    end
+
+    def ingest_path(_project_id)
+      raise NotImplementedError, "#{self.class} deve implementare #ingest_path"
+    end
+
+    private
+
+    def environment
+      @configuration.environment
+    end
+
+    def sdk
+      { "name" => "closeyourit-ruby", "version" => VERSION }
+    end
+
+    def server_name
+      return nil unless @configuration.send_server_name
+
+      Socket.gethostname
+    rescue StandardError
+      nil
+    end
+
+    def compact(hash)
+      hash.reject { |_key, value| value.nil? }
+    end
+
+    # Fusione ricorsiva: gli Hash annidati vengono fusi (es. `contexts.runtime` preservato
+    # mentre lo scope aggiunge `contexts.active_job`), gli scalari sovrascritti.
+    def deep_merge(base, override)
+      base.merge(override) do |_key, old_value, new_value|
+        if old_value.is_a?(Hash) && new_value.is_a?(Hash)
+          deep_merge(old_value, new_value)
+        else
+          new_value
+        end
+      end
+    end
+  end
+end

data/lib/closeyourit/events/error_event.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "socket"
+require_relative "../event"
+require_relative "../scrubber"
+
+module CloseYourIt
+  # Trasforma un'eccezione Ruby nel **payload evento Sentry** che il backend CloseYourIt ingerisce
+  # (Errors::Ingest::Normalize). Usa `backtrace_locations` (niente regex) e mette la cause-chain in
+  # `exception.values` ordinata dall'esterna alla principale (Sentry: values.last = il crash).
+  class ErrorEvent < Event
+    def self.from_exception(exception, configuration:, handled: false, level: "error", contexts: nil)
+      new(exception, configuration, handled: handled, level: level, contexts: contexts)
+    end
+
+    def initialize(exception, configuration, handled: false, level: "error", contexts: nil)
+      super(configuration)
+      @exception = exception
+      @handled = handled
+      @level = level
+      @contexts = contexts
+      @scrubber = Scrubber.new(configuration)
+    end
+
+    def to_h
+      base = compact(
+        "event_id" => SecureRandom.uuid.delete("-"),
+        "timestamp" => @occurred_at,
+        "platform" => "ruby",
+        "level" => @level,
+        "environment" => environment,
+        "release" => @configuration.release,
+        "server_name" => server_name,
+        "exception" => { "values" => exception_values },
+        "contexts" => { "runtime" => { "name" => "ruby", "version" => RUBY_VERSION } },
+        "sdk" => sdk
+      )
+      # Fonde il contesto per-richiesta/job (user/tags/extra/contexts/request) raccolto nello Scope.
+      merged = deep_merge(base, CloseYourIt::Scope.current.to_event_hash)
+      # Context extra passato esplicitamente (es. rails_error dall'ErrorReporter).
+      @contexts ? deep_merge(merged, { "contexts" => @contexts }) : merged
+    end
+
+    def ingest_path(project_id)
+      "/api/v1/projects/#{project_id}/events"
+    end
+
+    private
+
+    # Cause-chain → array Sentry: causa più esterna prima, eccezione principale ULTIMA.
+    def exception_values
+      chain = []
+      seen = []
+      current = @exception
+      while current && !seen.include?(current)
+        chain << single_exception(current)
+        seen << current
+        current = current.cause
+      end
+      chain.reverse
+    end
+
+    def single_exception(exception)
+      {
+        "type" => exception.class.name,
+        "value" => @scrubber.scrub_message(exception.message),
+        "stacktrace" => { "frames" => frames(exception.backtrace_locations) },
+        "mechanism" => { "type" => "ruby", "handled" => @handled }
+      }
+    end
+
+    # Sentry-style: frame più recente per ultimo; chiavi filename/function/lineno/in_app/abs_path.
+    def frames(locations)
+      return [] if locations.nil?
+
+      locations.reverse.map do |loc|
+        {
+          "filename" => loc.path,
+          "abs_path" => loc.path,
+          "function" => loc.label,
+          "lineno" => loc.lineno,
+          "in_app" => in_app?(loc.path)
+        }
+      end
+    end
+
+    def in_app?(path)
+      return false if path.nil?
+
+      !path.include?("/gems/") && !path.include?(RbConfig::CONFIG["rubylibdir"].to_s)
+    end
+  end
+end