closeyourit-ruby 0.2.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b015462d6b0e563ef202410b5f2bc33b11ee10f985d984ac84a874836f67c82e
-  data.tar.gz: 41f3e3ca878dbfbfd818cd4963b238d1d78400344e0e8bbb95cfd025853ebf82
+  metadata.gz: 0e319cd48ab53d0933f14344dc8ea2ac503ed7537b8111789fd540cf6bc3d65f
+  data.tar.gz: 2f7d6223045d8c9aea2ad4d1b9b6bac4cd1420cbc8abe2bd91622855cb45dfae
 SHA512:
-  metadata.gz: 16d70f8ef7436397d881a8f67664f24aaabfe3ae976d5b23276149242bf8f539d1c5dc1d27f9d7c8a2c72a080ab42b2b56c11ec8af1e0fae108e06f5bf8cfbdc
-  data.tar.gz: '02853ab18aad59772dd4aa0cc497c32983e4e49f2926d2b42d28654552dabad1c0f9dacd589fc0423c920cbb1ea903457a35767365130777dc4d0317282e7225'
+  metadata.gz: 4d37a064316618dcbee1b2a82626f950dc62e20dc22db3f7b8c6d14373ae1d307a20570ead272959536a1a337cceb3a13375e87edb5c2af23c1eeceae14fbee1
+  data.tar.gz: 937873c344d55dd765cedae07d1b7d05fb531012c22b616f4e22d6a8130fd26059a65cc8e949a1336b3ab97788d8e930118e451a13e1a51c2e4c6bccdcdb0efb

data/README.md

@@ -171,6 +171,23 @@ Privacy-by-default (`send_pii = false`). In sintesi:
 > 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).
 
+## Diagnostica
+
+Il trasporto è fire-and-forget: non solleva mai e non blocca la request. Per non lasciare
+fallimenti silenziosi, ogni risposta HTTP non-2xx (es. `401` token errato, `404` progetto
+inesistente) viene loggata a `warn`, così come gli eventi scartati a coda piena. I contatori
+sono ispezionabili a runtime:
+
+```ruby
+CloseYourIt.stats.to_h
+# => { enqueued: 128, dropped: 0, sent: 126, failed: 2 }
+```
+
+- `enqueued` — eventi accettati per l'invio
+- `dropped` — scartati perché la coda async era piena (mai backpressure)
+- `sent` — risposta HTTP 2xx
+- `failed` — errore di rete o status non-2xx (vedi i log a `warn`)
+
 ## Sviluppo
 
 ```bash

data/lib/closeyourit/background_worker.rb

@@ -13,13 +13,22 @@ module CloseYourIt
       @executor = build_executor(threads.to_i, max_queue)
     end
 
+    # Ritorna true se l'evento è stato accettato (o eseguito sincrono), false se scartato
+    # perché la coda era piena (`fallback_policy: :discard`). Mai backpressure sulla request.
     def perform(&block)
-      @executor.post do
+      accepted = @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}")
+        CloseYourIt.internal_logger.error("CloseYourIt background worker: #{e.class}: #{e.message}")
       end
+
+      unless accepted
+        CloseYourIt.stats.increment(:dropped)
+        CloseYourIt.internal_logger.warn("CloseYourIt background worker: coda piena, evento scartato")
+      end
+
+      accepted
     end
 
     def shutdown(timeout = 1)

data/lib/closeyourit/client.rb

@@ -19,10 +19,25 @@ module CloseYourIt
       return nil if payload.nil?
 
       path = event.ingest_path(@configuration.project_id)
-      @worker.perform { @transport.send_event(payload, path: path) }
+      accepted = @worker.perform { @transport.send_event(payload, path: path) }
+      CloseYourIt.stats.increment(:enqueued) if accepted
       payload
     end
 
+    # Invia un batch di log come ARRAY a /logs (l'endpoint accetta singolo o array). before_send è
+    # applicato a ciascun payload; quelli scartati (nil) non vengono inviati.
+    def flush_logs(events)
+      return nil if events.nil? || events.empty?
+
+      payloads = events.map(&:to_h)
+      payloads = payloads.filter_map { |payload| @configuration.before_send.call(payload) } if @configuration.before_send
+      return nil if payloads.empty?
+
+      path = events.first.ingest_path(@configuration.project_id)
+      @worker.perform { @transport.send_event(payloads, path: path) }
+      payloads
+    end
+
     def shutdown
       @worker.shutdown
     end

data/lib/closeyourit/configuration.rb

@@ -22,7 +22,9 @@ module CloseYourIt
                   :capture_query_bindings, :capture_method_arguments,
                   :capture_request, :request_header_allowlist,
                   :breadcrumbs_enabled, :max_breadcrumbs, :sample_rate,
-                  :capture_handled_errors, :report_active_job_errors
+                  :capture_handled_errors, :report_active_job_errors,
+                  :logs_enabled, :logs_sample_rate, :logs_batch_size, :logs_flush_interval,
+                  :capture_rails_logs, :logs_min_level
     attr_writer :release
     attr_reader :excluded_exceptions, :filter_parameters, :scrub_message_patterns
 
@@ -65,6 +67,15 @@ module CloseYourIt
       @capture_query_bindings   = false
       @capture_method_arguments = false
 
+      # Log strutturati (CloseYourIt.log / .logger). Master switch + sampling + batching dedicati.
+      @logs_enabled        = true
+      @logs_sample_rate    = 1.0
+      @logs_batch_size     = 50
+      @logs_flush_interval = 5
+      # Broadcast opt-in di Rails.logger → CloseYourIt.log (default OFF; spedisce solo ≥ soglia).
+      @capture_rails_logs = false
+      @logs_min_level     = :info
+
       @filter_parameters      = []
       @scrub_message_patterns = []
     end
@@ -95,9 +106,12 @@ module CloseYourIt
       true
     end
 
-    # Logga i warning di configurazione (es. endpoint http://). Chiamata da `CloseYourIt.init`.
+    # Logga i warning di configurazione (es. endpoint http://, project_id/endpoint malformati).
+    # Non solleva mai: coerente con la filosofia no-op del client. Chiamata da `CloseYourIt.init`.
     def validate!
-      CloseYourIt.logger.warn(insecure_endpoint_message) if insecure_endpoint?
+      CloseYourIt.internal_logger.warn(insecure_endpoint_message) if insecure_endpoint?
+      CloseYourIt.internal_logger.warn(malformed_project_id_message) if malformed_project_id?
+      CloseYourIt.internal_logger.warn(malformed_endpoint_message) if malformed_endpoint?
       self
     end
 
@@ -133,11 +147,35 @@ module CloseYourIt
       nil
     end
 
+    UUID_FORMAT = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
     def insecure_endpoint?
       uri = parsed_endpoint
       !uri.nil? && uri.scheme != "https"
     end
 
+    # Avvisa se il project_id è valorizzato ma non sembra uno UUID (l'errore tipico è incollare
+    # uno slug/nome al posto dell'id). Non blocca: il server è l'autorità sulla validità.
+    def malformed_project_id?
+      !blank?(project_id) && !UUID_FORMAT.match?(project_id.to_s)
+    end
+
+    def malformed_project_id_message
+      "CloseYourIt: project_id (#{project_id}) non ha forma UUID — verifica di aver copiato l'id corretto."
+    end
+
+    # Avvisa se endpoint_url è valorizzato ma non parsabile o privo di host.
+    def malformed_endpoint?
+      return false if blank?(endpoint_url)
+
+      uri = parsed_endpoint
+      uri.nil? || blank?(uri.host)
+    end
+
+    def malformed_endpoint_message
+      "CloseYourIt: endpoint_url (#{endpoint_url}) non è un URL valido (host mancante)."
+    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}"

data/lib/closeyourit/events/error_event.rb

@@ -29,6 +29,8 @@ module CloseYourIt
         "timestamp" => @occurred_at,
         "platform" => "ruby",
         "level" => @level,
+        # Correlazione log↔errori: stesso trace_id dei log della medesima richiesta (popolato dallo Scope).
+        "trace_id" => CloseYourIt::Scope.current.trace_id,
         "environment" => environment,
         "release" => @configuration.release,
         "server_name" => server_name,

data/lib/closeyourit/events/log_event.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+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.
+  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.
+    LEVELS = %w[debug info warning error fatal].freeze
+    LEVEL_ALIASES = { "warn" => "warning", "err" => "error", "unknown" => "fatal" }.freeze
+
+    def initialize(message, level:, attributes:, configuration:, logger: nil)
+      super(configuration)
+      @message = message
+      @level = normalize_level(level)
+      @attributes = attributes || {}
+      @logger = logger
+    end
+
+    def to_h
+      compact(
+        "event_id" => SecureRandom.uuid.delete("-"),
+        "timestamp" => @occurred_at,
+        "level" => @level,
+        "message" => @message.to_s,
+        "attributes" => scrubbed_attributes,
+        "logger" => @logger,
+        "trace_id" => CloseYourIt::Scope.current.trace_id,
+        "environment" => environment,
+        "release" => @configuration.release,
+        "sdk" => sdk
+      )
+    end
+
+    def ingest_path(project_id)
+      "/api/v1/projects/#{project_id}/logs"
+    end
+
+    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))
+    end
+
+    # Chiavi sempre stringa (anche annidate): coerenza col payload JSON e con la denylist dello Scrubber.
+    def deep_stringify_keys(value)
+      case value
+      when Hash  then value.each_with_object({}) { |(key, val), acc| acc[key.to_s] = deep_stringify_keys(val) }
+      when Array then value.map { |item| deep_stringify_keys(item) }
+      else value
+      end
+    end
+  end
+end

data/lib/closeyourit/log_buffer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module CloseYourIt
+  # Buffer in-memory thread-safe dei log: accumula i LogEvent e li flusha in batch verso /logs quando
+  # raggiungono `logs_batch_size`, allo scadere di `logs_flush_interval` (timer), o allo shutdown.
+  # Riduce le richieste HTTP — i log sono alto-volume, a differenza di errori/metriche uno-a-uno.
+  class LogBuffer
+    attr_reader :timer # esposto per i test (verifica dell'intervallo configurato)
+
+    def initialize(client:, configuration:)
+      @client = client
+      @configuration = configuration
+      @mutex = Mutex.new
+      @events = []
+      @timer = nil
+    end
+
+    def add(event)
+      reached_batch = false
+      @mutex.synchronize do
+        @events << event
+        ensure_timer
+        reached_batch = @events.size >= @configuration.logs_batch_size.to_i
+      end
+      flush if reached_batch
+    end
+
+    def flush
+      batch = drain
+      return if batch.empty?
+
+      @client.flush_logs(batch)
+    end
+
+    def shutdown
+      @timer&.shutdown
+      flush
+    end
+
+    private
+
+    def drain
+      @mutex.synchronize do
+        events = @events
+        @events = []
+        events
+      end
+    end
+
+    # Avvia il timer di flush periodico alla prima voce (una sola volta).
+    def ensure_timer
+      return if @timer
+
+      interval = @configuration.logs_flush_interval.to_f
+      return if interval <= 0
+
+      @timer = Concurrent::TimerTask.new(execution_interval: interval) { flush }
+      @timer.execute
+    end
+  end
+end

data/lib/closeyourit/log_device.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+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.logger.warn("disco quasi pieno", disk: "sda1")
+  # `warn` mappa sul livello `warning` (enum backend); supporta block e `::Logger#add` per drop-in.
+  class LogDevice
+    # Severità numeriche ::Logger → livelli CloseYourIt (UNKNOWN→fatal).
+    SEVERITY_LEVELS = { 0 => "debug", 1 => "info", 2 => "warning", 3 => "error", 4 => "fatal", 5 => "fatal" }.freeze
+
+    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)
+    def error(message = nil, **attributes, &block) = write("error", message, attributes, &block)
+    def fatal(message = nil, **attributes, &block) = write("fatal", message, attributes, &block)
+
+    def <<(message)
+      write("info", message, {})
+      message
+    end
+
+    # Compat con ::Logger#add(severity, message = nil, progname = nil).
+    def add(severity, message = nil, progname = nil, &block)
+      write(SEVERITY_LEVELS.fetch(severity.to_i, "info"), message || progname, {}, &block)
+    end
+    alias log add
+
+    private
+
+    def write(level, message, attributes, &block)
+      # Gate PRIMA del block: `logger.debug { dump_costoso }` non valuta il block se i log sono spenti.
+      return unless CloseYourIt.logs_active?
+
+      message = block.call if block
+      CloseYourIt.log(level, message, **attributes)
+    end
+  end
+end

data/lib/closeyourit/rails/log_broadcast.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+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).
+    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)
+        super(nil) # nessun device: inoltra soltanto
+        self.level = LEVEL_BY_SYMBOL.fetch(min_level.to_sym, 1)
+      end
+
+      # Sovrascrive il punto unico di ::Logger: filtra per soglia e re-inoltra a CloseYourIt.log.
+      def add(severity, message = nil, progname = nil)
+        severity ||= ::Logger::UNKNOWN
+        return true if severity < level
+
+        text = message || (block_given? ? yield : nil) || progname
+        CloseYourIt.log(SEVERITY_LEVELS.fetch(severity, "info"), text) unless text.nil?
+        true
+      end
+    end
+  end
+end

data/lib/closeyourit/rails/railtie.rb

@@ -6,6 +6,7 @@ require_relative "active_job_extension"
 require_relative "error_subscriber"
 require_relative "../sidekiq/error_handler"
 require_relative "query_source"
+require_relative "log_broadcast"
 require_relative "../subscribers/slow_query"
 
 module CloseYourIt
@@ -61,6 +62,15 @@ module CloseYourIt
         end
       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+).
+      initializer "closeyourit.capture_rails_logs" 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))
+        end
+      end
+
       # Cattura gli errori dei job Sidekiq (solo se Sidekiq è presente).
       initializer "closeyourit.sidekiq" do
         if defined?(::Sidekiq) && ::Sidekiq.respond_to?(:configure_server)

data/lib/closeyourit/rails/request_context.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module CloseYourIt
   module Rails
     # Rack middleware: popola lo Scope con il contesto HTTP della richiesta (method/url/header)
@@ -15,7 +17,11 @@ module CloseYourIt
       end
 
       def call(env)
-        CloseYourIt::Scope.current.request = build_request(env) if active?
+        if enabled?
+          # trace_id sempre (correlazione log↔errori), anche con capture_request OFF.
+          CloseYourIt::Scope.current.trace_id = trace_id_for(env)
+          CloseYourIt::Scope.current.request = build_request(env) if CloseYourIt.configuration.capture_request
+        end
         @app.call(env)
       ensure
         CloseYourIt::Scope.reset!
@@ -23,12 +29,20 @@ module CloseYourIt
 
       private
 
-      def active?
-        CloseYourIt.enabled? && CloseYourIt.configuration.capture_request
+      def enabled?
+        CloseYourIt.enabled?
       rescue StandardError
         false
       end
 
+      # Riusa il request id di Rails/Rack se presente (stessa correlazione dei log applicativi),
+      # altrimenti ne genera uno.
+      def trace_id_for(env)
+        env["action_dispatch.request_id"] ||
+          env["HTTP_X_REQUEST_ID"].to_s.split(",").first&.strip.then { |id| id&.empty? ? nil : id } ||
+          SecureRandom.uuid
+      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

@@ -34,7 +34,7 @@ module CloseYourIt
       end
     end
 
-    attr_accessor :request
+    attr_accessor :request, :trace_id
     attr_reader :user, :tags, :extra, :contexts, :breadcrumbs
 
     def initialize
@@ -71,6 +71,7 @@ module CloseYourIt
       @extra       = {}
       @contexts    = {}
       @request     = nil
+      @trace_id    = nil
       @breadcrumbs = BreadcrumbBuffer.new(CloseYourIt.configuration.max_breadcrumbs)
     end
 

data/lib/closeyourit/stats.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module CloseYourIt
+  # Contatori diagnostici thread-safe del client: quanti eventi sono stati accodati,
+  # scartati (coda piena), spediti con successo o falliti (rete o status non-2xx).
+  # Servono a rendere visibili i fallimenti silenziosi del trasporto fire-and-forget.
+  #
+  #   CloseYourIt.stats.to_h # => { enqueued: 12, dropped: 0, sent: 11, failed: 1 }
+  class Stats
+    COUNTERS = %i[enqueued dropped sent failed].freeze
+
+    def initialize
+      @counters = COUNTERS.to_h { |name| [ name, Concurrent::AtomicFixnum.new(0) ] }
+    end
+
+    def increment(name)
+      counter = @counters.fetch(name)
+      counter.increment
+      counter.value
+    end
+
+    def [](name)
+      @counters.fetch(name).value
+    end
+
+    def to_h
+      @counters.transform_values(&:value)
+    end
+
+    def reset!
+      @counters.each_value { |counter| counter.value = 0 }
+      self
+    end
+  end
+end

data/lib/closeyourit/transport.rb

@@ -10,8 +10,8 @@ module CloseYourIt
   class Transport
     OPEN_TIMEOUT = 2
     READ_TIMEOUT = 3
-    # Net::HTTP non segue i redirect da solo. L'host canonico può rispondere 301 (es. apex → www):
-    # ri-POSTiamo a Location preservando metodo + body, così l'evento non si perde in silenzio.
+    # Net::HTTP non segue i redirect: l'host canonico può rispondere 301 (es. apex → www).
+    # Ri-POSTiamo a Location preservando metodo + body, così l'evento non si perde in silenzio.
     MAX_REDIRECTS = 2
 
     def initialize(configuration)
@@ -19,9 +19,17 @@ module CloseYourIt
     end
 
     def send_event(payload, path:)
-      post(payload, path)
+      response = post(payload, path)
+      if response.is_a?(Net::HTTPSuccess)
+        CloseYourIt.stats.increment(:sent)
+      else
+        CloseYourIt.stats.increment(:failed)
+        CloseYourIt.internal_logger.warn("CloseYourIt transport: HTTP #{response.code} su #{path}")
+      end
+      response
     rescue StandardError => e
-      CloseYourIt.logger.error("CloseYourIt transport: #{e.class}: #{e.message}")
+      CloseYourIt.stats.increment(:failed)
+      CloseYourIt.internal_logger.error("CloseYourIt transport: #{e.class}: #{e.message}")
       nil
     end
 

data/lib/closeyourit/version.rb

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

data/lib/closeyourit-ruby.rb

@@ -7,6 +7,7 @@ require_relative "closeyourit/configuration"
 require_relative "closeyourit/breadcrumb"
 require_relative "closeyourit/scope"
 require_relative "closeyourit/scrubber"
+require_relative "closeyourit/stats"
 require_relative "closeyourit/background_worker"
 require_relative "closeyourit/transport"
 require_relative "closeyourit/event"
@@ -14,12 +15,16 @@ require_relative "closeyourit/events/error_event"
 require_relative "closeyourit/events/message_event"
 require_relative "closeyourit/events/slow_query_event"
 require_relative "closeyourit/events/slow_method_event"
+require_relative "closeyourit/events/log_event"
+require_relative "closeyourit/log_device"
+require_relative "closeyourit/log_buffer"
 require_relative "closeyourit/subscribers/slow_query"
 require_relative "closeyourit/instrumenter"
 require_relative "closeyourit/monitor"
 require_relative "closeyourit/client"
 require_relative "closeyourit/rails/capture_exceptions"
 require_relative "closeyourit/rails/request_context"
+require_relative "closeyourit/rails/log_broadcast"
 require_relative "closeyourit/rails/active_job_extension"
 require_relative "closeyourit/rails/error_subscriber"
 require_relative "closeyourit/sidekiq/error_handler"
@@ -40,8 +45,10 @@ module CloseYourIt
     def init
       @configuration = Configuration.new
       @client = nil
+      @log_buffer = nil
       yield(@configuration) if block_given?
       @configuration.validate!
+      register_shutdown_flush
       @configuration
     end
 
@@ -138,11 +145,52 @@ module CloseYourIt
       )
     end
 
+    # Logger interno della gemma (warning/errori diagnostici su stdout). NON è il logging applicativo:
+    # per spedire log strutturati a CloseYourIt usa `CloseYourIt.log` / `CloseYourIt.logger`.
+    def internal_logger
+      @internal_logger ||= default_internal_logger
+    end
+
+    attr_writer :internal_logger
+
+    # Logger applicativo Logger-compatibile: inoltra ogni messaggio a `CloseYourIt.log` (→ ingest /logs).
+    #   CloseYourIt.logger.info("ordine creato", order_id: 1)
     def logger
-      @logger ||= default_logger
+      @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.
+    #   CloseYourIt.log(:info, "ordine creato", order_id: 1)
+    #   CloseYourIt.log(:warn, "retry", logger: "payments", attempt: 3)
+    def log(level, message, logger: nil, **attributes)
+      return nil unless logs_enabled?
+      return nil unless logs_sampled?
+
+      event = LogEvent.new(message, level: level, attributes: attributes,
+                                    logger: logger, configuration: configuration)
+      log_buffer.add(event)
+      nil
+    end
+
+    # Vero se i log sono attivi (master switch + flag): usato da LogDevice per NON valutare i block
+    # costosi (`logger.debug { dump }`) quando il logging è spento.
+    def logs_active?
+      logs_enabled?
+    end
+
+    # Forza l'invio dei log bufferizzati (chiamato anche allo shutdown del processo).
+    def flush_logs
+      @log_buffer&.flush
+      nil
     end
 
-    attr_writer :logger
+    # Contatori diagnostici del client (accodati/scartati/spediti/falliti).
+    #   CloseYourIt.stats.to_h # => { enqueued: …, dropped: …, sent: …, failed: … }
+    def stats
+      @stats ||= Stats.new
+    end
 
     private
 
@@ -150,6 +198,33 @@ module CloseYourIt
       @client ||= Client.new(configuration)
     end
 
+    def log_buffer
+      @log_buffer ||= LogBuffer.new(client: client, configuration: configuration)
+    end
+
+    # I log seguono il master switch del client + il proprio flag dedicato.
+    def logs_enabled?
+      enabled? && configuration.logs_enabled
+    end
+
+    # Sampling indipendente dei log (1.0 = tutti, 0.0 = nessuno).
+    def logs_sampled?
+      rate = configuration.logs_sample_rate.to_f
+      return true if rate >= 1.0
+      return false if rate <= 0.0
+
+      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.
+    def register_shutdown_flush
+      return if @shutdown_registered
+
+      @shutdown_registered = true
+      at_exit { @log_buffer&.shutdown }
+    end
+
     def ignored_exception?(exception)
       return true if exception.is_a?(CloseYourIt::Error)
 
@@ -180,7 +255,7 @@ module CloseYourIt
       exception.instance_variable_set(CAPTURED_FLAG, true)
     end
 
-    def default_logger
+    def default_internal_logger
       ::Logger.new($stdout).tap do |l|
         l.level = ::Logger::WARN
         l.progname = "CloseYourIt"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: closeyourit-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Alessio Bussolari
@@ -41,20 +41,25 @@ files:
 - lib/closeyourit/configuration.rb
 - lib/closeyourit/event.rb
 - lib/closeyourit/events/error_event.rb
+- lib/closeyourit/events/log_event.rb
 - lib/closeyourit/events/message_event.rb
 - lib/closeyourit/events/slow_method_event.rb
 - lib/closeyourit/events/slow_query_event.rb
 - lib/closeyourit/instrumenter.rb
+- lib/closeyourit/log_buffer.rb
+- lib/closeyourit/log_device.rb
 - lib/closeyourit/monitor.rb
 - lib/closeyourit/rails/active_job_extension.rb
 - lib/closeyourit/rails/capture_exceptions.rb
 - lib/closeyourit/rails/error_subscriber.rb
+- lib/closeyourit/rails/log_broadcast.rb
 - lib/closeyourit/rails/query_source.rb
 - lib/closeyourit/rails/railtie.rb
 - lib/closeyourit/rails/request_context.rb
 - lib/closeyourit/scope.rb
 - lib/closeyourit/scrubber.rb
 - lib/closeyourit/sidekiq/error_handler.rb
+- lib/closeyourit/stats.rb
 - lib/closeyourit/subscribers/slow_query.rb
 - lib/closeyourit/transport.rb
 - lib/closeyourit/version.rb