closeyourit-ruby 0.8.0 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1482102089ba9e319a50f2d3822b63fc76ddc9a63c6c629f1d7cdc53022ca362
-  data.tar.gz: f312feb36b22702dca3109c62f623ba4484d25caf82dc9b25c807fe89f2ea2ba
+  metadata.gz: e7fb813ea37f0fb206ed31a5a960f795e364c6b23902d59b9b5d6e56ff4fb295
+  data.tar.gz: 926f4e714781796b43ad8c9eaf0e6bf52d7976599a188d3e3720637df623d2bb
 SHA512:
-  metadata.gz: 4f6a4d467f80966599d057452927a75c17126cb01def6de0d1e365cb0fa5dcbd458122e3b860b05906d35bb307b29eed0d8e9ee9b5afb1b4008170dd3462205d
-  data.tar.gz: 6f4a5ee0fb8dea5b160c1447624d1f409a1a36df63700c46dc66390c9d4fc2ab932e04a1c50c2dacec9c0202f73af7b697250786bfd52f8d6303fdaaebfdbff8
+  metadata.gz: d8d590e358c098c3061383a85f9e1593b0b574a0ee52fcb67bbdd76e215cf44076703d9a1917d52acc99e43dee0ba58113afd9516c44b1adaa807341c22cf3ee
+  data.tar.gz: e492934a7b0329fe0ba887dc45b05fa8c148ac3fb9665d866f95bdfe25b1cd114aa66bf95bca76cb83f3f16a96a34b4b24165152a247971e43888358e69291f9

data/README.md

@@ -8,9 +8,9 @@ installa per inviare a CloseYourIt:
 - **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.
+È il **client primario** di CloseYourIt e copre, senza dipendere dagli SDK Sentry, ciò per cui di
+solito se ne installa uno: request context, user/tag/contesto, breadcrumbs, errori nei background job,
+errori handled, sampling, messaggi.
 
 Caratteristiche:
 - **Contesto ricco** sull'errore: request HTTP (method/url/header), user/tag/contesto custom, breadcrumbs
@@ -24,6 +24,13 @@ Caratteristiche:
 
 > Design e contratto dati in [`PDR.md`](PDR.md).
 
+> **Rispetto agli altri SDK.** Ruby, JavaScript, Dart e Python **non coprono le stesse funzioni**: le
+> metriche dei background job e la telemetria d'uso oggi esistono solo qui, i `pageview` e la session
+> replay solo in JavaScript, la coda offline su disco solo in Dart. Cosa c'è dove — con la versione
+> minima e il sorgente che lo implementa — sta in una tabella sola, `compatibility/sdk-feature-parity.md`
+> nel repo interno [closeyourit-docs](https://github.com/bussolabs/closeyourit-docs/blob/main/compatibility/sdk-feature-parity.md).
+> Questo README descrive ciò che fa la gemma Ruby, non ciò che fanno gli altri SDK.
+
 ## Installazione
 
 Pubblicata su [RubyGems](https://rubygems.org/gems/closeyourit-ruby):
@@ -172,8 +179,8 @@ 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:
+La **sorgente** del log (campo `logger`) si imposta con `.named` — child logger immutabile, come in
+dart/js. Il logger radice resta invariato:
 
 ```ruby
 payments = CloseYourIt.logger.named("payments")   # child con sorgente "payments"
@@ -186,7 +193,7 @@ come sorgente): `CloseYourIt.logger.warn("disco pieno", logger: "/dev/sda1")` me
 
 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
+`error` < `fatal`), con gli stessi nomi di 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

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,7 +41,8 @@ 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, :propagate_trace_context
+                  :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, :trace_propagation_allowlist
@@ -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

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
@@ -104,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/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.8.0"
+  VERSION = "0.9.3"
 end

data/lib/closeyourit-ruby.rb

@@ -23,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"
@@ -70,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!
@@ -264,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
@@ -323,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
@@ -349,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
@@ -371,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.8.0
+  version: 0.9.3
 platform: ruby
 authors:
 - Alessio Bussolari
@@ -87,6 +87,7 @@ files:
 - 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: