closeyourit-ruby 0.7.0 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '083ced8226884d6ceed86ae4da2a17cb7f9bfdfa5f3cd6073ac09268c4545d6e'
-  data.tar.gz: 75b18abef8b8c45ae14647c4bc102276286a2c71c1056d37274d0fe350f20555
+  metadata.gz: a23acf258deb222638d8d9bd85f57ffc6fbf36429f9c87b50896814b0245e2e3
+  data.tar.gz: 7e0cb657fde07728331a131932242fb58685929af5ac88ffc7bfdf707ba3e301
 SHA512:
-  metadata.gz: c9285e453091b8f89bc360e1a274fc72fa7b312cd2fd2ac7f8dddb0636a7a49e6f7782f0af5b8e2cb20275e841566731fe48174dddf6f502cb9eb92646bae216
-  data.tar.gz: 1bcd7478c0d2d5572c0fa761e0b16a6bacffef89bd227a36fae117cea468fdd538bf9f011d839fa378a29871a1b2e8efdfc3ef2c467df684096eff585206a7d3
+  metadata.gz: 964551d2a915c4c150dd586362dd110255f361bf8c93e20f8060de7f7c253f737d25d48f1776108f5556f6739e2c909af83dc71c4f1e568ad09797a99a1a755e
+  data.tar.gz: b371074aed62189a65b68f8ce3ad9725f96650b6f11fd871bfd228efdf30c3c2c6331fb93990869230c7e211d3191c3690f609f5873503cf1736a44e37bcc28c

data/README.md

@@ -105,6 +105,25 @@ end
 | `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) |
+| `propagate_trace_context` | `false` | Propaga il **trace context W3C** (`traceparent`/`tracestate`) alle chiamate `Net::HTTP` e mappa il `trace_id` degli eventi sul trace-id W3C entrante (vedi [Propagazione W3C](#propagazione-w3c-opt-in)) |
+| `trace_propagation_allowlist` | `[]` | Host autorizzati a ricevere gli header W3C — **String** (host esatto, case-insensitive) o **Regexp** (sottodomini). Vuoto = nessuna destinazione |
+
+## Propagazione W3C (opt-in)
+
+Correla le richieste Ruby e le chiamate in uscita con lo standard **[W3C Trace Context](https://www.w3.org/TR/trace-context/)**
+(`traceparent`/`tracestate`) — nessun formato proprietario. È un *propagation bridge*, non un tracer
+completo: adotta il contesto entrante o ne genera uno root, e lo inoltra alle chiamate `Net::HTTP`.
+
+```ruby
+CloseYourIt.init do |c|
+  c.propagate_trace_context     = true
+  c.trace_propagation_allowlist = [ "api.interno.example", /\.svc\.internal\z/ ]
+end
+```
+
+- **Ingresso**: un `traceparent` entrante valido diventa il `trace_id` degli eventi CloseYourIt → l'errore/metrica della richiesta si allinea alla traccia distribuita. Un header malformato viene ignorato (si genera un root); un servizio d'origine (senza header) parte comunque con un contesto W3C.
+- **Uscita**: gli header vengono iniettati **solo** verso gli host della `trace_propagation_allowlist` (limitata per destinazione) e mai verso l'endpoint CloseYourIt stesso. Un redirect verso un host non elencato non riceve nulla.
+- **Privacy**: verso host non autorizzati non parte alcun header; l'header `baggage` (che può portare contesto interno/PII) **non viene mai** emesso.
 
 ## Cosa cattura
 

data/lib/closeyourit/client.rb

@@ -78,6 +78,22 @@ module CloseYourIt
       payloads
     end
 
+    # CYSK-29 — il flush della telemetria d'uso: UNA POST per finestra, payload privo di dati utente
+    # per costruzione (route = Controller#action). Fire-and-forget via worker, come tutto il resto.
+    def flush_usage(symbols:, truncated:, window_started_at:, window_ended_at:)
+      payload = {
+        environment: @configuration.environment.to_s,
+        release: @configuration.release,
+        sdk: { name: "closeyourit-ruby", version: CloseYourIt::VERSION },
+        window_started_at: window_started_at, window_ended_at: window_ended_at,
+        truncated: truncated, symbols: symbols
+      }
+      path = "/api/v1/projects/#{@configuration.project_id}/usages"
+      accepted = @worker.perform { @transport.send_event(payload, path: path) }
+      CloseYourIt.notify_diagnostic(:enqueue, path: path, batch: symbols.size) if accepted
+      payload
+    end
+
     def shutdown
       @worker.shutdown
     end

data/lib/closeyourit/configuration.rb

@@ -41,10 +41,11 @@ module CloseYourIt
                   :query_time_threshold_ms, :slow_request_threshold_ms, :slow_external_threshold_ms,
                   :capture_external_http, :trap_signals,
                   :monitor_jobs, :slow_job_threshold_ms, :job_queue_latency_threshold_ms,
-                  :jobs_sample_rate
+                  :jobs_sample_rate, :propagate_trace_context,
+                  :usage_enabled, :usage_flush_interval, :usage_max_symbols
     attr_writer :release, :project_root
     attr_reader :excluded_exceptions, :excluded_log_patterns, :excluded_query_patterns,
-                :filter_parameters, :scrub_message_patterns
+                :filter_parameters, :scrub_message_patterns, :trace_propagation_allowlist
 
     def initialize
       @endpoint_url = ENV.fetch("CLOSEYOURIT_ENDPOINT_URL", nil)
@@ -112,6 +113,14 @@ module CloseYourIt
       @logs_sample_rate    = 1.0
       @logs_batch_size     = 50
       @logs_flush_interval = 5
+
+      # CYSK-29 — telemetria d'uso: quali rotte/job/chiavi girano davvero. Il payload è privo di
+      # dati utente per costruzione (route = Controller#action, mai l'URL), quindi il default è ON:
+      # trenta giorni di raccolta facoltativa hanno insegnato che facoltativo significa mai.
+      # Il registro si svuota a ogni flush: il tetto limita i simboli DISTINTI per finestra.
+      @usage_enabled        = true
+      @usage_flush_interval = 300
+      @usage_max_symbols    = 2000
       # Broadcast opt-in di Rails.logger → CloseYourIt.log (default OFF; spedisce solo ≥ soglia).
       @capture_rails_logs = false
       @logs_min_level     = :info
@@ -148,6 +157,15 @@ module CloseYourIt
       @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
 
+      # Propagazione W3C trace context (traceparent/tracestate) verso i servizi esterni chiamati via
+      # Net::HTTP. OPT-IN, default OFF: iniettare header d'uscita attraversa un trust boundary e va deciso
+      # per-app. È limitata PER DESTINAZIONE dalla allowlist (host esatti, case-insensitive, o Regexp per i
+      # sottodomini); lista vuota = nessuna destinazione. Mai verso host non elencati, mai come `baggage`
+      # (che può portare PII). In ingresso un traceparent valido diventa il trace_id degli eventi
+      # CloseYourIt → gli errori/metriche della richiesta si correlano alla traccia distribuita (CYRB-15).
+      @propagate_trace_context     = false
+      @trace_propagation_allowlist = []
+
       # 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
@@ -177,6 +195,12 @@ module CloseYourIt
       @filter_parameters = Array(list)
     end
 
+    # Destinazioni autorizzate a ricevere gli header di trace W3C. String = host esatto (match
+    # case-insensitive), Regexp = pattern (per sottodomini/famiglie di host). Lista vuota = nessuno.
+    def trace_propagation_allowlist=(list)
+      @trace_propagation_allowlist = Array(list)
+    end
+
     def scrub_message_patterns=(list)
       @scrub_message_patterns = Array(list)
     end

data/lib/closeyourit/rails/active_job_extension.rb

@@ -3,17 +3,45 @@
 module CloseYourIt
   module Rails
     # Incluso in ActiveJob::Base (via railtie `on_load(:active_job)`): cattura gli errori dei job
-    # (oggi persi) con il contesto del job, poi ri-solleva. La logica vive in `.monitor` per essere
+    # (oggi persi) con il contesto del job. La logica vive in `.monitor`/`.report_discarded` per essere
     # testabile senza ActiveSupport/ActiveJob.
+    #
+    # CYRB-19: `around_perform` gira DENTRO `perform_now`, mentre `retry_on`/`discard_on` (rescue_from)
+    # sono valutati FUORI, dopo i callback. Catturare nell'around_perform significa quindi segnalare
+    # OGNI tentativo — anche quelli che verranno ritentati con successo — perché il reporter vede
+    # l'errore prima che il retry possa zittirlo, e ogni tentativo solleva una nuova istanza (la
+    # deduplica interna, per-istanza, non interviene). Su ActiveJob 7.1+ deleghiamo la segnalazione ad
+    # `after_discard`, che Rails invoca al fallimento definitivo (retry_on esauriti o eccezione non
+    # gestita), mai sui tentativi che `retry_on` ritenta → una sola occorrenza per job.
+    #
+    # Limiti noti (per costruzione di ActiveJob, non del client):
+    # - `after_discard` NON scatta per gli errori intercettati da un `rescue_from` custom: sono gestiti
+    #   dall'app, quindi non li segnaliamo più come "non gestiti" (prima lo facevamo, impropriamente).
+    # - I retry a livello di ADAPTER (es. Sidekiq) SENZA `retry_on` risollevano l'errore non gestito:
+    #   `after_discard` scatta a ogni esecuzione, quindi lì la de-duplicazione per tentativo non si
+    #   applica (comportamento invariato rispetto a prima).
+    # Sulle versioni prive di `after_discard` restiamo al fallback legacy (cattura nell'around_perform).
     module ActiveJobExtension
+      # Scope arricchito durante il `perform` tramandato ad `after_discard`. Legato all'ISTANZA del job
+      # (ogni retry ne crea una nuova, deserializzata) → vive esattamente quanto serve, niente bleed tra
+      # job o thread; il reset di fine `perform` lo sgancia solo dallo storage, non muta l'oggetto.
+      STASHED_SCOPE_IVAR = :@__closeyourit_stashed_scope
+
       def self.included(base)
         base.around_perform do |job, block|
           CloseYourIt::Rails::ActiveJobExtension.monitor(job) { block.call }
         end
+
+        return unless base.respond_to?(:after_discard)
+
+        base.after_discard do |job, exception|
+          CloseYourIt::Rails::ActiveJobExtension.report_discarded(job, exception)
+        end
       end
 
-      # Esegue il job arricchendo lo scope con tag/context; cattura l'errore (handled:false) e
-      # ri-solleva; resetta lo scope a fine job (no bleed tra job sullo stesso thread).
+      # Esegue il job arricchendo lo scope con tag/context; resetta lo scope a fine job (no bleed tra
+      # job sullo stesso thread). Su ActiveJob 7.1+ NON cattura l'errore (lo fa `after_discard` solo al
+      # fallimento definitivo): qui tramanda lo scope al job e ri-solleva. Sul fallback legacy cattura.
       def self.monitor(job)
         return yield unless CloseYourIt.configuration.report_active_job_errors
 
@@ -21,13 +49,41 @@ module CloseYourIt
           apply_job_scope(job)
           yield
         rescue Exception => e # rubocop:disable Lint/RescueException
-          CloseYourIt.capture_exception(e, handled: false)
+          if report_on_discard?(job)
+            job.instance_variable_set(STASHED_SCOPE_IVAR, CloseYourIt::Scope.current)
+          else
+            CloseYourIt.capture_exception(e, handled: false)
+          end
           raise
         ensure
           CloseYourIt::Scope.reset!
         end
       end
 
+      # Aggancio `after_discard` (ActiveJob 7.1+): il job è definitivamente fallito, quindi segnaliamo
+      # l'errore UNA sola volta (handled:false). Riprendiamo lo scope arricchito durante il `perform`
+      # (tramandato da `monitor`) così il report conserva breadcrumb/tag/contesti raccolti nel job;
+      # `apply_job_scope` rinfresca i campi standard con `executions` finale senza perdere i custom.
+      def self.report_discarded(job, exception)
+        return unless CloseYourIt.configuration.report_active_job_errors
+
+        begin
+          stashed = job.instance_variable_get(STASHED_SCOPE_IVAR)
+          CloseYourIt::Scope.current = stashed if stashed
+          apply_job_scope(job)
+          CloseYourIt.capture_exception(exception, handled: false)
+        ensure
+          job.remove_instance_variable(STASHED_SCOPE_IVAR) if job.instance_variable_defined?(STASHED_SCOPE_IVAR)
+          CloseYourIt::Scope.reset!
+        end
+      end
+
+      # true quando ActiveJob espone `after_discard` (7.1+): la segnalazione è delegata lì, così
+      # `monitor` non cattura i tentativi intermedi. false → fallback legacy (cattura nell'around_perform).
+      def self.report_on_discard?(job)
+        job.class.respond_to?(:after_discard)
+      end
+
       def self.apply_job_scope(job)
         CloseYourIt.set_tag("job.class", job.class.name)
         CloseYourIt.set_tag("job.queue", job.queue_name) if job.respond_to?(:queue_name)

data/lib/closeyourit/rails/net_http_patch.rb

@@ -12,6 +12,9 @@ module CloseYourIt
     module NetHTTPPatch
       def request(req, body = nil, &block)
         config = CloseYourIt.configuration
+        # Propagazione W3C: indipendente dal profiling (ha il suo opt-in), va fatta PRIMA del round-trip
+        # perché aggiunge header alla richiesta in uscita.
+        inject_trace_context(config, req)
         return super unless config.detect_performance_issues && config.capture_external_http
 
         started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -25,6 +28,53 @@ module CloseYourIt
 
       private
 
+      # Gestisce gli header di trace W3C sulla richiesta in uscita (solo con la propagazione opt-in ON).
+      # Verso una destinazione autorizzata inietta traceparent/tracestate; verso qualsiasi altra li
+      # RIMUOVE. La rimozione è la difesa contro il leak su redirect cross-host: se lo stesso oggetto
+      # request viene riusato per seguire un redirect verso un host non in allowlist, gli header della
+      # chiamata precedente non devono sopravvivere ("host esterni non ricevono header interni" — CYRB-15).
+      # baggage non viene mai né letto né emesso. Difensivo: mai solleva per colpa della propagazione.
+      def inject_trace_context(config, req)
+        return unless config.propagate_trace_context
+
+        context = deliverable_context(config)
+        if context.nil?
+          strip_trace_headers(req)
+        else
+          context.headers.each { |name, value| req[name] = value }
+        end
+      rescue StandardError
+        nil
+      end
+
+      # Il trace context da consegnare a QUESTA destinazione, o nil se non va propagato nulla: host
+      # assente, endpoint CloseYourIt stesso (niente auto-propagazione), destinazione fuori allowlist,
+      # o scope privo di contesto.
+      def deliverable_context(config)
+        host = address
+        return nil if host.nil? || own_endpoint?(config, host)
+        return nil unless destination_allowed?(config, host)
+
+        CloseYourIt::Scope.current.trace_context
+      end
+
+      # La destinazione è autorizzata a ricevere il trace context? String = host esatto (case-insensitive),
+      # Regexp = pattern (sottodomini/famiglie). Lista vuota → sempre false (nessuna destinazione).
+      def destination_allowed?(config, host)
+        config.trace_propagation_allowlist.any? do |pattern|
+          pattern.is_a?(Regexp) ? pattern.match?(host) : pattern.to_s.casecmp?(host)
+        end
+      end
+
+      # Rimuove gli header di trace W3C che una chiamata precedente sullo stesso oggetto request possa
+      # aver lasciato. Solo i nostri header, mai altro; no-op se il request non li supporta.
+      def strip_trace_headers(req)
+        return unless req.respond_to?(:delete)
+
+        req.delete("traceparent")
+        req.delete("tracestate")
+      end
+
       def record_external(config, req, duration_ms)
         host = address
         return if host.nil? || own_endpoint?(config, host)

data/lib/closeyourit/rails/railtie.rb

@@ -68,6 +68,9 @@ module CloseYourIt
         ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
           event = ActiveSupport::Notifications::Event.new(*args)
           payload = event.payload
+          # CYSK-29 — telemetria d'uso: la rotta è `Controller#action`, MAI l'URL. Il registro fa
+          # una lookup e un increment; il gate usage_enabled sta dentro #record.
+          CloseYourIt.usage_registry.record("route", "#{payload[:controller]}##{payload[:action]}") if CloseYourIt.enabled?
           perf.record(
             route: "#{payload[:controller]}##{payload[:action]}",
             duration_ms: event.duration
@@ -75,8 +78,9 @@ module CloseYourIt
         end
       end
 
-      # Strumenta le chiamate HTTP esterne (Net::HTTP) per rilevare quelle lente nella finestra della
-      # richiesta. Il patch è no-op (chiama super) se la detection è OFF → overhead trascurabile.
+      # Strumenta Net::HTTP: rileva le chiamate esterne lente (solo con detect_performance_issues) e
+      # propaga il trace context W3C (solo con propagate_trace_context). Prepend incondizionato — i due
+      # opt-in sono valutati per-chiamata nel patch; con entrambi OFF è di fatto no-op (chiama super).
       initializer "closeyourit.instrument_net_http" do
         require "net/http"
         ::Net::HTTP.prepend(CloseYourIt::Rails::NetHTTPPatch) unless ::Net::HTTP.ancestors.include?(CloseYourIt::Rails::NetHTTPPatch)
@@ -103,6 +107,8 @@ module CloseYourIt
         ActiveSupport::Notifications.subscribe("perform.active_job") do |*args|
           event = ActiveSupport::Notifications::Event.new(*args)
           job = event.payload[:job]
+          # CYSK-29 — anche i job dichiarano di essere girati: kind `job`, simbolo = la classe.
+          CloseYourIt.usage_registry.record("job", job.class.name) if job && CloseYourIt.enabled?
           jobs.active_job_performed(job, event.duration) if job
         end
       end

data/lib/closeyourit/rails/request_context.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "securerandom"
+require_relative "../trace_context"
 
 module CloseYourIt
   module Rails
@@ -22,8 +23,13 @@ module CloseYourIt
 
       def call(env)
         if enabled?
-          # trace_id sempre (correlazione log↔errori), anche con capture_request OFF.
-          CloseYourIt::Scope.current.trace_id = trace_id_for(env)
+          # Contesto di trace W3C (solo con propagazione opt-in): adottato dall'header entrante o generato.
+          context = trace_context_for(env)
+          CloseYourIt::Scope.current.trace_context = context
+          # trace_id sempre (correlazione log↔errori), anche con capture_request OFF. Con un trace context
+          # W3C il trace_id degli eventi È il trace-id W3C → l'errore/metrica si allinea alla traccia
+          # distribuita propagata a valle (mapping trace_id, CYRB-15); altrimenti request_id come prima.
+          CloseYourIt::Scope.current.trace_id = context ? context.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)
@@ -46,6 +52,17 @@ module CloseYourIt
         false
       end
 
+      # Contesto di trace W3C della richiesta, SOLO con la propagazione opt-in attiva (altrimenti nil →
+      # comportamento storico invariato). Adotta un traceparent/tracestate entrante valido (correlazione
+      # distribuita), altrimenti genera un root: così anche i servizi che ORIGINANO traffico partono con
+      # un trace-id W3C propagabile a valle. Un traceparent malformato è ignorato → si genera un root.
+      def trace_context_for(env)
+        return nil unless CloseYourIt.configuration.propagate_trace_context
+
+        CloseYourIt::TraceContext.parse(env["HTTP_TRACEPARENT"], env["HTTP_TRACESTATE"]) ||
+          CloseYourIt::TraceContext.generate
+      end
+
       # Riusa il request id di Rails/Rack se presente (stessa correlazione dei log applicativi),
       # altrimenti ne genera uno.
       def trace_id_for(env)

data/lib/closeyourit/scope.rb

@@ -18,6 +18,13 @@ module CloseYourIt
         store[STORAGE_KEY] ||= new
       end
 
+      # Re-installa uno scope salvato in precedenza. Serve a `after_discard` (ActiveJob 7.1+) per
+      # riprendere lo scope arricchito durante il `perform` — tag/contesti/breadcrumb, incluse le query —
+      # dopo che il reset di fine `perform` l'ha sganciato dallo storage (CYRB-19). Simmetrico a `reset!`.
+      def current=(scope)
+        store[STORAGE_KEY] = scope
+      end
+
       # Azzera lo scope corrente — chiamato in `ensure` da middleware e job (su Puma il
       # thread è riusato: senza reset lo scope colerebbe nella richiesta successiva).
       def reset!
@@ -35,7 +42,7 @@ module CloseYourIt
       end
     end
 
-    attr_accessor :request, :trace_id, :rack_env, :replay_session_id
+    attr_accessor :request, :trace_id, :rack_env, :replay_session_id, :trace_context
     attr_reader :user, :tags, :extra, :contexts, :breadcrumbs
 
     def initialize
@@ -81,6 +88,9 @@ module CloseYourIt
       @rack_env    = nil
       @trace_id    = nil
       @replay_session_id = nil
+      # Contesto di trace W3C della richiesta (CloseYourIt::TraceContext): popolato solo con la
+      # propagazione opt-in attiva, consumato dal patch Net::HTTP per gli header d'uscita.
+      @trace_context = nil
       @breadcrumbs = BreadcrumbBuffer.new(CloseYourIt.configuration.max_breadcrumbs)
       @performance_profile = nil
     end

data/lib/closeyourit/trace_context.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module CloseYourIt
+  # Contesto di trace W3C (`traceparent`/`tracestate`, https://www.w3.org/TR/trace-context/).
+  # NON è un tracer: non apre span né misura tempi. È un "propagation bridge" minimale (il ticket:
+  # "Non costruire tracing custom completo") — adotta un contesto entrante valido facendo pass-through
+  # di trace-id/parent-id/flag, oppure ne genera uno root, e sa serializzarsi negli header d'uscita.
+  # Volutamente separato dai formati proprietari: sullo standard, senza dipendere da un vendor.
+  class TraceContext
+    # traceparent = version "-" trace-id "-" parent-id "-" trace-flags (55 char per la versione 00).
+    # `rest` cattura eventuali campi futuri: ammessi solo da versioni > 00 (forward-compat), vietati su 00.
+    TRACEPARENT = /
+      \A
+      (?<version>[0-9a-f]{2})-
+      (?<trace_id>[0-9a-f]{32})-
+      (?<parent_id>[0-9a-f]{16})-
+      (?<flags>[0-9a-f]{2})
+      (?<rest>-.*)?
+      \z
+    /x
+
+    FORBIDDEN_VERSION = "ff"
+    CURRENT_VERSION   = "00"
+    ZERO_TRACE_ID     = ("0" * 32).freeze
+    ZERO_PARENT_ID    = ("0" * 16).freeze
+    FLAG_SAMPLED      = 0x01
+
+    # tracestate: lista di membri `key=value` separati da virgola, max 32 (W3C §3.3.1).
+    TRACESTATE_MAX_MEMBERS = 32
+    # key: lowercase alnum iniziale + set ristretto (incluso `@`/`/` per le chiavi tenant@vendor).
+    # value: caratteri stampabili 0x20–0x7E esclusi `,` (0x2C) e `=` (0x3D).
+    TRACESTATE_MEMBER = %r{\A[a-z0-9][a-z0-9_\-*/@]*=[\x20-\x2b\x2d-\x3c\x3e-\x7e]+\z}
+
+    attr_reader :trace_id, :parent_id, :flags, :tracestate
+
+    def initialize(trace_id:, parent_id:, flags:, tracestate: nil)
+      @trace_id   = trace_id
+      @parent_id  = parent_id
+      @flags      = flags
+      @tracestate = tracestate
+    end
+
+    class << self
+      # Adotta un traceparent entrante. Ritorna nil se malformato (→ il chiamante genera un root o
+      # lascia il contesto assente). Pass-through: mantiene trace-id/parent-id/flag verbatim così il
+      # bridge non inventa span. Il tracestate viene sanificato (membri invalidi scartati, cap a 32).
+      def parse(traceparent, tracestate = nil)
+        match = TRACEPARENT.match(traceparent.to_s.strip)
+        return nil unless match
+        return nil if match[:version] == FORBIDDEN_VERSION
+        return nil if match[:version] == CURRENT_VERSION && match[:rest]
+        return nil if match[:trace_id] == ZERO_TRACE_ID
+        return nil if match[:parent_id] == ZERO_PARENT_ID
+
+        new(
+          trace_id:   match[:trace_id],
+          parent_id:  match[:parent_id],
+          flags:      match[:flags].to_i(16),
+          tracestate: sanitize_tracestate(tracestate)
+        )
+      end
+
+      # Nuovo contesto root (nessun traceparent entrante valido). Genera trace-id (16 byte) e parent-id
+      # (8 byte) casuali — SecureRandom è fork-safe, così un worker forkato non riusa gli id del padre.
+      # `sampled` fissa il flag: un root che apriamo noi traccia di default.
+      def generate(sampled: true)
+        new(
+          trace_id:   SecureRandom.hex(16),
+          parent_id:  SecureRandom.hex(8),
+          flags:      sampled ? FLAG_SAMPLED : 0,
+          tracestate: nil
+        )
+      end
+
+      private
+
+      # Trattiene solo i membri ben formati, nell'ordine originale, fino a 32. Ritorna nil se non ne
+      # resta nessuno → così non propaghiamo mai un tracestate spazzatura o sovradimensionato.
+      def sanitize_tracestate(tracestate)
+        return nil if tracestate.nil?
+
+        valid = tracestate.to_s.split(",").map(&:strip)
+                          .select { |member| TRACESTATE_MEMBER.match?(member) }
+                          .first(TRACESTATE_MAX_MEMBERS)
+        valid.empty? ? nil : valid.join(",")
+      end
+    end
+
+    def sampled?
+      (flags & FLAG_SAMPLED) != 0
+    end
+
+    # traceparent d'uscita, sempre versione 00 (l'unica che sappiamo emettere). I flag sono ri-emessi
+    # per intero (i bit riservati vanno propagati as-is), formattati su due cifre esadecimali.
+    def traceparent
+      format("%s-%s-%s-%02x", CURRENT_VERSION, trace_id, parent_id, flags & 0xff)
+    end
+
+    # Header di propagazione W3C: traceparent (+ tracestate se presente). MAI `baggage`: può contenere
+    # contesto interno/PII e non deve varcare il confine (ticket: "baggage sensibile non riceve header").
+    def headers
+      result = { "traceparent" => traceparent }
+      result["tracestate"] = tracestate if tracestate && !tracestate.empty?
+      result
+    end
+  end
+end

data/lib/closeyourit/usage_registry.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module CloseYourIt
+  # CYSK-29 — la telemetria d'uso: registra QUALI simboli girano davvero (route come
+  # `Controller#action`, job, chiavi custom letterali) e li flusha in una POST ogni
+  # `usage_flush_interval` secondi per processo. Sul percorso caldo: una lookup e un increment.
+  #
+  # Le regole che rendono il sistema immune alle perdite:
+  # - i conteggi sono INDICATIVI, solo `last_seen_at` è portante: un flush perso costa una finestra
+  #   su un simbolo che si rivede subito dopo;
+  # - il registro SI SVUOTA a ogni flush: il tetto (`usage_max_symbols`) limita i simboli distinti
+  #   visti in una finestra — una grandezza legata al traffico, non alla dimensione del codice;
+  # - oltre il tetto il flush porta `truncated: true`, e lato scanner quel flag SQUALIFICA il kind;
+  # - nessun sampling, mai: un campionamento su una rotta chiamata 3 volte al mese fabbrica
+  #   esattamente il falso «mai vista» che il sistema esiste per evitare;
+  # - `route` è `Controller#action`, MAI l'URL: niente path, parametri, user, IP.
+  class UsageRegistry
+    # I simboli vengono da payload di framework o da stringhe letterali: il pattern è il contratto.
+    SYMBOL_FORMAT = %r{\A[A-Za-z0-9_:#./-]{1,200}\z}
+    KINDS = %w[route job custom].freeze
+
+    attr_reader :timer # esposto per i test (verifica dell'intervallo configurato)
+
+    def initialize(client:, configuration:)
+      @client = client
+      @configuration = configuration
+      @mutex = Mutex.new
+      @symbols = {}
+      @truncated = false
+      @window_started_at = Time.now.utc
+      @timer = nil
+    end
+
+    def record(kind, symbol)
+      return unless @configuration.usage_enabled
+
+      kind = kind.to_s
+      symbol = symbol.to_s
+      return unless KINDS.include?(kind) && symbol.match?(SYMBOL_FORMAT)
+
+      @mutex.synchronize do
+        key = [ kind, symbol ]
+        entry = @symbols[key]
+        if entry
+          entry[:count] += 1
+          entry[:last_seen_at] = Time.now.utc
+        elsif @symbols.size >= @configuration.usage_max_symbols.to_i
+          @truncated = true
+        else
+          @symbols[key] = { count: 1, last_seen_at: Time.now.utc }
+        end
+        ensure_timer
+      end
+    end
+
+    def flush
+      payload = drain
+      return if payload[:symbols].empty? && !payload[:truncated]
+
+      @client.flush_usage(**payload)
+    rescue StandardError => e
+      # Il flush gira sul thread timer: un errore non deve propagare nell'app né uccidere il
+      # TimerTask. La semantica portante è last_seen_at: una finestra persa non falsifica niente.
+      CloseYourIt.internal_logger.error("CloseYourIt usage registry: #{e.class}: #{e.message}")
+    end
+
+    def shutdown
+      @timer&.shutdown
+      flush
+    end
+
+    private
+
+    def drain
+      @mutex.synchronize do
+        symbols = @symbols.map do |(kind, symbol), entry|
+          { kind: kind, symbol: symbol, count: entry[:count], last_seen_at: entry[:last_seen_at].iso8601 }
+        end
+        payload = { symbols: symbols, truncated: @truncated,
+                    window_started_at: @window_started_at.iso8601, window_ended_at: Time.now.utc.iso8601 }
+        @symbols = {}
+        @truncated = false
+        @window_started_at = Time.now.utc
+        payload
+      end
+    end
+
+    def ensure_timer
+      return if @timer
+
+      interval = @configuration.usage_flush_interval.to_i
+      interval = 300 if interval <= 0
+      @timer = Concurrent::TimerTask.new(execution_interval: interval) { flush }
+      @timer.execute
+    end
+  end
+end

data/lib/closeyourit/version.rb

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

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"
@@ -22,6 +23,7 @@ require_relative "closeyourit/performance/request_profile"
 require_relative "closeyourit/performance/rollup"
 require_relative "closeyourit/log_device"
 require_relative "closeyourit/log_buffer"
+require_relative "closeyourit/usage_registry"
 require_relative "closeyourit/subscribers/slow_query"
 require_relative "closeyourit/subscribers/request_performance"
 require_relative "closeyourit/subscribers/job_performance"
@@ -69,6 +71,7 @@ module CloseYourIt
       @configuration = Configuration.new
       @client = nil
       @log_buffer = nil
+      @usage_registry = nil
       @shutdown_notified = false # nuova sessione: :shutdown potrà essere notificato di nuovo
       yield(@configuration) if block_given?
       @configuration.validate!
@@ -263,7 +266,8 @@ module CloseYourIt
     # 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).
+      # Ordine critico: prima i buffer (accodano l'ultimo batch nel worker), poi il worker (li drena).
+      @usage_registry&.shutdown
       @log_buffer&.shutdown
       @client&.shutdown
       # Riepilogo di fine-vita: l'app riceve lo snapshot dei contatori senza log rumorosi. Emesso una
@@ -322,6 +326,22 @@ module CloseYourIt
       nil
     end
 
+    # CYSK-29 — il registro della telemetria d'uso (una lookup + increment sul percorso caldo).
+    def usage_registry
+      ensure_current_process!
+      @usage_registry ||= UsageRegistry.new(client: client, configuration: configuration)
+    end
+
+    # CYSK-29 — dichiara che un pezzo di codice è stato ESEGUITO. `key` deve essere una stringa
+    # LETTERALE (mai interpolata con dati): è l'unico modo onesto di rispondere a «questo ramo viene
+    # mai preso?». No-op se la gemma non è configurata o usage_enabled è OFF.
+    def used(key)
+      return nil unless configured? && enabled?
+
+      usage_registry.record("custom", key)
+      nil
+    end
+
     private
 
     # Vero se il thread corrente sta eseguendo l'hook diagnostico: le API di telemetria diventano no-op
@@ -348,6 +368,7 @@ module CloseYourIt
       @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
@@ -370,6 +391,7 @@ module CloseYourIt
     def discard_inherited_client!
       @client = nil
       @log_buffer = nil
+      @usage_registry = nil
     end
 
     # I log seguono il master switch del client + il proprio flag dedicato.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: closeyourit-ruby
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.2
 platform: ruby
 authors:
 - Alessio Bussolari
@@ -85,7 +85,9 @@ files:
 - 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/usage_registry.rb
 - lib/closeyourit/version.rb
 homepage: https://github.com/bussolabs/closeyourit-ruby
 licenses: