allstak 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea16fc5869d09516a29301382b4d59d9e3f33018226516beb208aa1c826a77f3
-  data.tar.gz: 6b73ffb1e1319585c2be4c7398181cf9beae32a4ea17914501df6ae1a5df2a66
+  metadata.gz: 6749cec382749239156fb82d5feb81db7c0c63916d06f037ec6d3fbcea037a53
+  data.tar.gz: ae060d2498ee40e52b6c4ce26dc5fc283bfeff5c9ab0756fff1ecdcccf26ebad
 SHA512:
-  metadata.gz: 1a21a2da36cf561691221369b9cf25fdfc4063300fc3f32452652d6f0987044b9121d719a597db9d6b18d617583e0253e8ee59f08539c8f2ed3c1efe5ffd543a
-  data.tar.gz: 43e2c1d26dd502e77fe498e4850352235a63be28fa33ac5c2d61a4ee7171cafda55bc11285d781de96664cdb962becf4df387c83573ccdfa495de3e80fe05695
+  metadata.gz: 26a946694cf36a20b64023727ca4f9b8c0a8fab9248d6481f527252ad879bb83b9901e5349524b11156bf959ef6eec7cf1b09deb21bfa5f0e57149cba21f0f2a
+  data.tar.gz: c1dbec9f5fb40f38a2aca6ac7f52a5515edd9ce6b87dd8702030fdf6d334b8f3cf3b102ea24260a30bb9d7219b177a7f14a3158e8499cdb6c29ee0ffc020f689

data/CHANGELOG.md

@@ -5,6 +5,13 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ## Unreleased
 
+## [0.3.1] — 2026-06-06
+
+### Fixed
+
+- Treated terminal non-429 4xx ingest responses, including feature-gated `402`
+  responses, as non-retryable so offline replay cannot wedge permanently.
+
 ## [0.3.0] — 2026-05-30
 
 ### Added — Automatic breadcrumbs across all instrumentation

data/lib/allstak/client.rb

@@ -1,3 +1,5 @@
+require_relative "diagnostics"
+
 module AllStak
   # The AllStak SDK client. Create once via {AllStak.configure}.
   class Client
@@ -130,8 +132,49 @@ module AllStak
       @session_tracker&.end rescue nil
     end
 
+    # Privacy-safe SDK diagnostics. Contains counters and queue sizes only.
+    def diagnostics
+      transport_stats =
+        if @transport.respond_to?(:diagnostics)
+          @transport.diagnostics
+        else
+          {}
+        end
+      modules = [@errors, @logs, @http, @tracing, @database]
+      buffer_queue = modules.sum { |m| safe_count(m, :buffer_count) }
+      buffer_drops = modules.sum { |m| safe_count(m, :dropped_count) }
+
+      Diagnostics.new(
+        events_captured: modules.sum { |m| safe_count(m, :captured_count) },
+        events_sent: transport_stats.fetch(:sent, 0),
+        events_failed: transport_stats.fetch(:failed, 0),
+        events_dropped: transport_stats.fetch(:dropped, 0) + buffer_drops,
+        events_persisted: transport_stats.fetch(:persisted, 0),
+        events_replayed: transport_stats.fetch(:replayed, 0),
+        queue_size: transport_stats.fetch(:queue_size, 0) + buffer_queue,
+        retry_attempts: transport_stats.fetch(:retry_attempts, 0),
+        rate_limited_count: transport_stats.fetch(:rate_limited, 0),
+        compressed_payloads: transport_stats.fetch(:compressed, 0),
+        uncompressed_payloads: transport_stats.fetch(:uncompressed, 0),
+        compression_bytes_saved: transport_stats.fetch(:compression_bytes_saved, 0),
+        sanitizer_redaction_count: AllStak::Sanitizer.redaction_count,
+        active_trace_count: safe_count(@tracing, :active_trace_count),
+        active_span_count: safe_count(@tracing, :active_span_count),
+        breadcrumb_count: safe_count(@errors, :breadcrumb_count),
+        session_recovery_count: safe_count(@session_tracker, :recovery_count),
+        disabled: @transport.disabled?
+      )
+    end
+
     private
 
+    def safe_count(target, method_name)
+      return 0 unless target.respond_to?(method_name)
+      target.public_send(method_name).to_i
+    rescue StandardError
+      0
+    end
+
     # Mark the active session errored/crashed based on the captured event's
     # mechanism. An at_exit/unhandled event (handled=false) is a crash;
     # everything else is a handled error. Fail-open — never raises.

data/lib/allstak/diagnostics.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AllStak
+  # Privacy-safe SDK diagnostics snapshot.
+  #
+  # Contains counters and queue sizes only. It intentionally never includes
+  # telemetry payloads, headers, tags, context values, user data, or breadcrumbs.
+  class Diagnostics
+    ATTRIBUTES = [
+      :events_captured,
+      :events_sent,
+      :events_failed,
+      :events_dropped,
+      :events_persisted,
+      :events_replayed,
+      :queue_size,
+      :retry_attempts,
+      :rate_limited_count,
+      :compressed_payloads,
+      :uncompressed_payloads,
+      :compression_bytes_saved,
+      :sanitizer_redaction_count,
+      :active_trace_count,
+      :active_span_count,
+      :breadcrumb_count,
+      :session_recovery_count,
+      :disabled
+    ].freeze
+
+    attr_reader(*ATTRIBUTES)
+
+    def initialize(values = {})
+      ATTRIBUTES.each do |name|
+        default = name == :disabled ? false : 0
+        instance_variable_set("@#{name}", values.fetch(name, default))
+      end
+    end
+
+    def to_h
+      ATTRIBUTES.each_with_object({}) do |name, out|
+        out[name] = public_send(name)
+      end
+    end
+
+    alias to_hash to_h
+  end
+end

data/lib/allstak/integrations/rack.rb

@@ -23,14 +23,16 @@ module AllStak
           start = now_ms
           started_at = Time.now.utc.iso8601(3)
 
-          trace_id = trace_id_from_env(env)
-          parent_span_id = parent_span_id_from_env(env)
+          incoming_trace = trace_context_from_env(env)
+          trace_id = incoming_trace[:trace_id]
+          parent_span_id = incoming_trace[:parent_span_id]
           request_id = env["HTTP_X_REQUEST_ID"] || env["HTTP_X_ALLSTAK_REQUEST_ID"] || SecureRandom.hex(16)
           if trace_id && !trace_id.empty?
             client.tracing.set_trace_id(trace_id)
           else
             client.tracing.reset_trace
           end
+          client.tracing.set_parent_span_id(parent_span_id) if parent_span_id && client.tracing.respond_to?(:set_parent_span_id)
           trace_id = client.tracing.current_trace_id
           span = client.tracing.start_span(
             "http.server",
@@ -154,18 +156,23 @@ module AllStak
           (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
         end
 
-        def trace_id_from_env(env)
-          traceparent = env["HTTP_TRACEPARENT"].to_s
-          parts = traceparent.split("-")
-          return parts[1] if parts.length >= 2 && parts[1].length == 32
-          env["HTTP_X_ALLSTAK_TRACE_ID"] || env["HTTP_X_TRACE_ID"]
+        def trace_context_from_env(env)
+          parsed = AllStak::Propagation.parse_traceparent(env["HTTP_TRACEPARENT"])
+          return parsed if parsed
+
+          trace_id = valid_trace_header(env["HTTP_X_ALLSTAK_TRACE_ID"]) || valid_trace_header(env["HTTP_X_TRACE_ID"])
+          parent_span_id = trace_id ? (valid_span_header(env["HTTP_X_ALLSTAK_SPAN_ID"]) || valid_span_header(env["HTTP_X_SPAN_ID"])) : nil
+          { trace_id: trace_id, parent_span_id: parent_span_id, sampled: nil }
+        end
+
+        def valid_trace_header(value)
+          normalized = value.to_s.downcase
+          AllStak::Propagation.valid_trace_id?(normalized) ? normalized : nil
         end
 
-        def parent_span_id_from_env(env)
-          traceparent = env["HTTP_TRACEPARENT"].to_s
-          parts = traceparent.split("-")
-          return parts[2] if parts.length >= 3 && parts[2].length == 16
-          env["HTTP_X_ALLSTAK_SPAN_ID"] || env["HTTP_X_SPAN_ID"]
+        def valid_span_header(value)
+          normalized = value.to_s.downcase
+          AllStak::Propagation.valid_span_id?(normalized) ? normalized : nil
         end
 
         def extract_user_id(env)

data/lib/allstak/modules/database.rb

@@ -11,6 +11,7 @@ module AllStak
         @transport = transport
         @config = config
         @logger = logger
+        @captured_count = 0
         @buffer = Transport::FlushBuffer.new(
           name: "database",
           max_size: config.buffer_size,
@@ -42,6 +43,7 @@ module AllStak
           spanId: span_id,
           rowsAffected: rows_affected
         }.compact)
+        @captured_count += 1
       end
 
       def flush
@@ -69,6 +71,18 @@ module AllStak
         %w[SELECT INSERT UPDATE DELETE].include?(first) ? first : "OTHER"
       end
 
+      def buffer_count
+        @buffer.count
+      end
+
+      def dropped_count
+        @buffer.dropped_count
+      end
+
+      def captured_count
+        @captured_count
+      end
+
       private
 
       def flush_batch(items)

data/lib/allstak/modules/errors.rb

@@ -23,6 +23,8 @@ module AllStak
         # Optional callable returning the active release-health session id, so
         # the backend's error consumer can mark the session errored/crashed.
         @session_id_provider = session_id_provider
+        @captured_count = 0
+        @dropped_count = 0
       end
 
       def set_user(id: nil, email: nil, ip: nil)
@@ -58,8 +60,12 @@ module AllStak
       end
 
       def capture_exception(exc, level: "error", user: nil, request_context: nil, trace_id: nil, metadata: nil)
-        return nil if @transport.disabled?
+        if @transport.disabled?
+          @dropped_count += 1
+          return nil
+        end
         begin
+          @captured_count += 1
           crumbs = drain_breadcrumbs
 
           payload = {
@@ -90,9 +96,15 @@ module AllStak
           # Sampling first, then pre-hook scrub, before_send, and final
           # transport scrub. Hooks never see raw secrets and cannot reintroduce
           # values that escape the wire-path sanitizer.
-          return nil unless Sampling.sampled?(@config.sample_rate)
+          unless Sampling.sampled?(@config.sample_rate)
+            @dropped_count += 1
+            return nil
+          end
           payload = apply_before_send(payload)
-          return nil if payload.nil?
+          if payload.nil?
+            @dropped_count += 1
+            return nil
+          end
 
           status, body = @transport.post(PATH, payload)
           return nil unless status == 202
@@ -114,8 +126,12 @@ module AllStak
       end
 
       def capture_error(exception_class, message, stack_trace: nil, level: "error", user: nil, request_context: nil, trace_id: nil, metadata: nil)
-        return nil if @transport.disabled?
+        if @transport.disabled?
+          @dropped_count += 1
+          return nil
+        end
         begin
+          @captured_count += 1
           payload = {
             exceptionClass: exception_class,
             message: message,
@@ -134,9 +150,15 @@ module AllStak
 
           # Sampling first, then pre-hook scrub, before_send, and final
           # transport scrub.
-          return nil unless Sampling.sampled?(@config.sample_rate)
+          unless Sampling.sampled?(@config.sample_rate)
+            @dropped_count += 1
+            return nil
+          end
           payload = apply_before_send(payload)
-          return nil if payload.nil?
+          if payload.nil?
+            @dropped_count += 1
+            return nil
+          end
 
           status, _ = @transport.post(PATH, payload)
           status == 202 ? exception_class : nil
@@ -152,6 +174,21 @@ module AllStak
         end
       end
 
+      def breadcrumb_count
+        buffer = Thread.current[BREADCRUMB_TLS_KEY]
+        buffer.respond_to?(:length) ? buffer.length : 0
+      rescue StandardError
+        0
+      end
+
+      def captured_count
+        @captured_count
+      end
+
+      def dropped_count
+        @dropped_count
+      end
+
       private
 
       # The current thread's breadcrumb ring buffer (lazily created).

data/lib/allstak/modules/http_monitor.rb

@@ -12,6 +12,7 @@ module AllStak
         @transport = transport
         @config = config
         @logger = logger
+        @captured_count = 0
         @buffer = Transport::FlushBuffer.new(
           name: "http",
           max_size: config.buffer_size,
@@ -45,6 +46,7 @@ module AllStak
           environment: @config.environment,
           release: @config.release
         }.compact
+        @captured_count += 1
         @buffer.push(item)
       end
 
@@ -56,6 +58,18 @@ module AllStak
         @buffer.shutdown
       end
 
+      def buffer_count
+        @buffer.count
+      end
+
+      def dropped_count
+        @buffer.dropped_count
+      end
+
+      def captured_count
+        @captured_count
+      end
+
       private
 
       def strip_query(path)

data/lib/allstak/modules/logs.rb

@@ -13,6 +13,7 @@ module AllStak
         # entries also surface as breadcrumbs on the next captured exception.
         # Injected by the client; nil keeps Logs standalone (and recursion-free).
         @breadcrumb_sink = breadcrumb_sink
+        @captured_count = 0
         @buffer = Transport::FlushBuffer.new(
           name: "logs",
           max_size: config.buffer_size,
@@ -40,6 +41,7 @@ module AllStak
           errorId: error_id,
           metadata: @config.release_tags.merge(metadata || {})
         }.compact
+        @captured_count += 1
         @buffer.push(payload)
         emit_breadcrumb(level, message, trace_id: trace_id, span_id: span_id)
         nil
@@ -59,6 +61,18 @@ module AllStak
         @buffer.shutdown
       end
 
+      def buffer_count
+        @buffer.count
+      end
+
+      def dropped_count
+        @buffer.dropped_count
+      end
+
+      def captured_count
+        @captured_count
+      end
+
       private
 
       # Bridge an accepted log into a breadcrumb via the injected sink. The

data/lib/allstak/modules/tracing.rb

@@ -1,4 +1,5 @@
 require "securerandom"
+require_relative "../propagation"
 require_relative "../sampling"
 
 module AllStak
@@ -12,6 +13,8 @@ module AllStak
         @transport = transport
         @config = config
         @logger = logger
+        @captured_count = 0
+        @dropped_count = 0
         @buffer = Transport::FlushBuffer.new(
           name: "tracing",
           max_size: config.buffer_size,
@@ -26,7 +29,12 @@ module AllStak
       end
 
       def set_trace_id(trace_id)
-        Thread.current[:allstak_trace_id] = trace_id
+        Thread.current[:allstak_trace_id] = AllStak::Propagation.normalize_trace_id(trace_id)
+      end
+
+      def set_parent_span_id(span_id)
+        return unless AllStak::Propagation.valid_span_id?(span_id)
+        Thread.current[:allstak_span_stack] = [span_id.to_s.downcase]
       end
 
       def current_span_id
@@ -101,6 +109,31 @@ module AllStak
         @buffer.shutdown
       end
 
+      def buffer_count
+        @buffer.count
+      end
+
+      def dropped_count
+        @dropped_count + @buffer.dropped_count
+      end
+
+      def captured_count
+        @captured_count
+      end
+
+      def active_span_count
+        stack = Thread.current[:allstak_span_stack]
+        stack.respond_to?(:length) ? stack.length : 0
+      rescue StandardError
+        0
+      end
+
+      def active_trace_count
+        Thread.current[:allstak_trace_id].nil? ? 0 : 1
+      rescue StandardError
+        0
+      end
+
       private
 
       def on_span_finish(span)
@@ -109,7 +142,11 @@ module AllStak
         # Drop unsampled spans: they were never meant to be sent. The span
         # still ran (timing/finish semantics intact) so block-form `in_span`
         # control flow is unaffected.
-        return unless span.sampled?
+        unless span.sampled?
+          @dropped_count += 1
+          return
+        end
+        @captured_count += 1
         @buffer.push(span.to_h)
       end
 

data/lib/allstak/propagation.rb

@@ -1,7 +1,14 @@
+require "securerandom"
+
 module AllStak
   module Propagation
     module_function
 
+    TRACE_ID_RE = /\A[0-9a-f]{32}\z/.freeze
+    SPAN_ID_RE = /\A[0-9a-f]{16}\z/.freeze
+    ZERO_TRACE_ID_RE = /\A0{32}\z/.freeze
+    ZERO_SPAN_ID_RE = /\A0{16}\z/.freeze
+
     def baggage(trace_id:, request_id: nil, span_id: nil)
       parts = ["allstak-trace_id=#{trace_id}"]
       parts << "allstak-request_id=#{request_id}" if request_id && !request_id.to_s.empty?
@@ -23,26 +30,77 @@ module AllStak
       sampled == false ? "00" : "01"
     end
 
+    def valid_trace_id?(trace_id)
+      value = trace_id.to_s.downcase
+      value.match?(TRACE_ID_RE) && !value.match?(ZERO_TRACE_ID_RE)
+    end
+
+    def valid_span_id?(span_id)
+      value = span_id.to_s.downcase
+      value.match?(SPAN_ID_RE) && !value.match?(ZERO_SPAN_ID_RE)
+    end
+
+    def normalize_trace_id(trace_id)
+      hex = trace_id.to_s.gsub(/[^0-9a-f]/i, "").downcase
+      candidate =
+        if hex.length >= 32
+          hex[0, 32]
+        elsif !hex.empty?
+          hex.ljust(32, "0")
+        end
+      return candidate if candidate && valid_trace_id?(candidate)
+      SecureRandom.hex(16)
+    end
+
+    def normalize_span_id(span_id)
+      hex = span_id.to_s.gsub(/[^0-9a-f]/i, "").downcase
+      candidate =
+        if hex.length >= 16
+          hex[0, 16]
+        elsif !hex.empty?
+          hex.ljust(16, "0")
+        end
+      return candidate if candidate && valid_span_id?(candidate)
+      SecureRandom.hex(8)
+    end
+
+    def parse_traceparent(header)
+      match = /\A00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})\z/i.match(header.to_s.strip)
+      return nil unless match
+      trace_id = match[1].downcase
+      parent_span_id = match[2].downcase
+      return nil unless valid_trace_id?(trace_id) && valid_span_id?(parent_span_id)
+      {
+        trace_id: trace_id,
+        parent_span_id: parent_span_id,
+        sampled: (match[3].to_i(16) & 1) == 1
+      }
+    end
+
     def apply_headers(headers, trace_id:, request_id: nil, span_id: nil, sampled: true)
-      headers["X-AllStak-Trace-Id"] = trace_id
+      wire_trace_id = normalize_trace_id(trace_id)
+      wire_span_id = span_id && !span_id.to_s.empty? ? normalize_span_id(span_id) : nil
+      headers["X-AllStak-Trace-Id"] = wire_trace_id
       headers["X-AllStak-Request-Id"] = request_id if request_id && !request_id.to_s.empty?
-      if span_id && !span_id.to_s.empty?
-        headers["X-AllStak-Span-Id"] = span_id
-        headers["traceparent"] = "00-#{trace_id}-#{span_id[0, 16]}-#{trace_flags(sampled)}"
+      if wire_span_id
+        headers["X-AllStak-Span-Id"] = wire_span_id
+        headers["traceparent"] = "00-#{wire_trace_id}-#{wire_span_id}-#{trace_flags(sampled)}"
       end
-      headers["baggage"] = merge_baggage(headers["baggage"], trace_id: trace_id, request_id: request_id, span_id: span_id)
-      headers["AllStak-Baggage"] = baggage(trace_id: trace_id, request_id: request_id, span_id: span_id)
+      headers["baggage"] = merge_baggage(headers["baggage"], trace_id: wire_trace_id, request_id: request_id, span_id: wire_span_id)
+      headers["AllStak-Baggage"] = baggage(trace_id: wire_trace_id, request_id: request_id, span_id: wire_span_id)
     end
 
     def apply_request_headers(req, trace_id:, request_id: nil, span_id: nil, sampled: true)
-      req["X-AllStak-Trace-Id"] ||= trace_id
+      wire_trace_id = normalize_trace_id(trace_id)
+      wire_span_id = span_id && !span_id.to_s.empty? ? normalize_span_id(span_id) : nil
+      req["X-AllStak-Trace-Id"] ||= wire_trace_id
       req["X-AllStak-Request-Id"] ||= request_id if request_id && !request_id.to_s.empty?
-      if span_id && !span_id.to_s.empty?
-        req["X-AllStak-Span-Id"] ||= span_id
-        req["traceparent"] ||= "00-#{trace_id}-#{span_id[0, 16]}-#{trace_flags(sampled)}"
+      if wire_span_id
+        req["X-AllStak-Span-Id"] ||= wire_span_id
+        req["traceparent"] ||= "00-#{wire_trace_id}-#{wire_span_id}-#{trace_flags(sampled)}"
       end
-      req["baggage"] = merge_baggage(req["baggage"], trace_id: trace_id, request_id: request_id, span_id: span_id)
-      req["AllStak-Baggage"] = baggage(trace_id: trace_id, request_id: request_id, span_id: span_id)
+      req["baggage"] = merge_baggage(req["baggage"], trace_id: wire_trace_id, request_id: request_id, span_id: wire_span_id)
+      req["AllStak-Baggage"] = baggage(trace_id: wire_trace_id, request_id: request_id, span_id: wire_span_id)
     end
   end
 end

data/lib/allstak/sanitizer.rb

@@ -33,6 +33,7 @@
 #   falls back to the key-redacted-but-not-value-scrubbed structure.
 
 require "set"
+require "thread"
 
 module AllStak
   module Sanitizer
@@ -166,6 +167,28 @@ module AllStak
 
     module_function
 
+    @redaction_count = 0
+    @redaction_mutex = Mutex.new
+
+    def redaction_count
+      @redaction_mutex.synchronize { @redaction_count }
+    rescue StandardError
+      0
+    end
+
+    def reset_redaction_count!
+      @redaction_mutex.synchronize { @redaction_count = 0 }
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def record_redaction
+      @redaction_mutex.synchronize { @redaction_count += 1 }
+    rescue StandardError
+      nil
+    end
+
     # Returns a sanitized deep copy of `payload`.
     #
     # @param extra_denylist [Array<String>, nil] additional key terms to redact;
@@ -207,6 +230,7 @@ module AllStak
         value.each_with_object({}) do |(k, v), out|
           out[k] =
             if sensitive?(k, denylist)
+              record_redaction
               REDACTED
             elsif skip_subtree?(k)
               # Explicit user object / stack frames: deep-copy with key-name
@@ -241,7 +265,12 @@ module AllStak
 
         seen.add(value.object_id)
         value.each_with_object({}) do |(k, v), out|
-          out[k] = sensitive?(k, denylist) ? REDACTED : walk_keys_only(v, denylist, seen)
+          if sensitive?(k, denylist)
+            record_redaction
+            out[k] = REDACTED
+          else
+            out[k] = walk_keys_only(v, denylist, seen)
+          end
         end
       when Array
         return REDACTED if seen.include?(value.object_id)
@@ -282,6 +311,7 @@ module AllStak
         out = out.gsub(IPV6_REGEX, REDACTED)
       end
 
+      record_redaction if out != str
       out
     rescue StandardError
       str

data/lib/allstak/session_tracker.rb

@@ -107,6 +107,10 @@ module AllStak
       @mutex.synchronize { (@started && !@ended) ? @session_id : nil }
     end
 
+    def recovery_count
+      0
+    end
+
     # Record a HANDLED error: bump status ok -> errored (never downgrades a
     # terminal crash). No I/O.
     def record_error

data/lib/allstak/transport/flush_buffer.rb

@@ -21,6 +21,7 @@ module AllStak
         @queue = []
         @stopped = false
         @overflow_warned = false
+        @dropped_count = 0
         @flushing_mutex = Mutex.new
         start_timer
       end
@@ -29,6 +30,7 @@ module AllStak
         synchronize do
           if @queue.length >= @max_size
             @queue.shift
+            @dropped_count += 1
             unless @overflow_warned
               @overflow_warned = true
               @logger.warn("[AllStak] Buffer #{@name} full (#{@max_size}); oldest events dropped")
@@ -45,6 +47,10 @@ module AllStak
         synchronize { @queue.length }
       end
 
+      def dropped_count
+        synchronize { @dropped_count }
+      end
+
       def flush
         @flushing_mutex.synchronize do
           drained = synchronize do

data/lib/allstak/transport/http_transport.rb

@@ -1,6 +1,8 @@
 require "net/http"
 require "uri"
 require "json"
+require "thread"
+require "zlib"
 require_relative "../sanitizer"
 require_relative "event_spool"
 
@@ -16,7 +18,7 @@ module AllStak
     #   backoff         = 1s → 2s → 4s → 8s (+ jitter 0-500ms)
     #   max attempts    = 5
     #   401             → disable SDK
-    #   4xx (400/403/404/422) → no retry
+    #   4xx except 429  → no retry
     #   5xx / network   → retry
     class HttpTransport
       NON_RETRYABLE_STATUSES = [400, 401, 403, 404, 422].freeze
@@ -25,6 +27,7 @@ module AllStak
       RETRY_AFTER_STATUSES = [429, 503].freeze
       # Upper bound on any honored Retry-After delay, in seconds.
       MAX_RETRY_AFTER = 300.0
+      COMPRESSION_THRESHOLD_BYTES = 1024
 
       # Session lifecycle calls are best-effort LIVE-only — a replayed stale
       # session would skew durations, so they are NEVER spooled to disk.
@@ -42,6 +45,17 @@ module AllStak
         @api_key = config.api_key
         @disabled = false
         @spool = build_spool(config, logger)
+        @stats_mutex = Mutex.new
+        @sent_count = 0
+        @failed_count = 0
+        @dropped_count = 0
+        @persisted_count = 0
+        @replayed_count = 0
+        @retry_attempt_count = 0
+        @rate_limited_count = 0
+        @compressed_count = 0
+        @uncompressed_count = 0
+        @compression_bytes_saved = 0
       end
 
       # The offline spool, or nil when disabled / unavailable. Exposed for
@@ -68,11 +82,15 @@ module AllStak
             AllStak::Sanitizer.scrub(parsed, **scrub_options)
           rescue StandardError => e
             @logger.debug("[AllStak] spool scrub failed; not persisting: #{e.class}: #{e.message}") if @config.debug
+            increment(:@dropped_count)
             return false
           end
-        @spool.persist(path, scrubbed)
+        persisted = @spool.persist(path, scrubbed)
+        increment(persisted ? :@persisted_count : :@dropped_count)
+        persisted
       rescue StandardError => e
         @logger.debug("[AllStak] persist_failed swallowed: #{e.class}: #{e.message}") if @config.debug
+        increment(:@dropped_count)
         false
       end
 
@@ -89,6 +107,8 @@ module AllStak
             status, _ = post(path, payload)
             # post() returns for 2xx and non-retryable 4xx; raises otherwise.
             if status && (status < 400 || (status >= 400 && status != 429))
+              increment(:@replayed_count) if status < 400
+              increment(:@dropped_count) if status >= 400
               @spool.remove(handle)
             end
           rescue AllStakAuthError
@@ -113,9 +133,26 @@ module AllStak
       end
 
       def post(path, payload)
-        raise AllStakAuthError, "SDK disabled" if @disabled
+        if @disabled
+          increment(:@dropped_count)
+          raise AllStakAuthError, "SDK disabled"
+        end
 
-        wire_payload = serialize_payload(payload)
+        wire_payload =
+          begin
+            serialize_payload(payload)
+          rescue AllStakTransportError
+            increment(:@failed_count)
+            increment(:@dropped_count)
+            raise
+          end
+        wire_body, compressed, bytes_saved = prepare_body(wire_payload)
+        if compressed
+          increment(:@compressed_count)
+          increment(:@compression_bytes_saved, bytes_saved)
+        else
+          increment(:@uncompressed_count)
+        end
 
         uri = URI.parse("#{@base_url}#{path}")
         http = Net::HTTP.new(uri.host, uri.port)
@@ -136,7 +173,8 @@ module AllStak
               "X-AllStak-Key"  => @api_key,
               "User-Agent"     => "allstak-ruby/#{AllStak::VERSION}"
             })
-            req.body = wire_payload
+            req["Content-Encoding"] = "gzip" if compressed
+            req.body = wire_body
             @logger.debug("[AllStak] POST #{path} attempt=#{attempt}") if @config.debug
 
             resp = http.request(req)
@@ -145,15 +183,25 @@ module AllStak
 
             if last_status == 401
               @disabled = true
+              increment(:@failed_count)
+              increment(:@dropped_count)
               @logger.warn("[AllStak] SDK disabled: invalid API key (401). No further events will be sent.")
               raise AllStakAuthError, "Invalid API key"
             end
 
-            return [last_status, body] if NON_RETRYABLE_STATUSES.include?(last_status)
-            return [last_status, body] if last_status < 400
+            if NON_RETRYABLE_STATUSES.include?(last_status) ||
+               (last_status >= 400 && last_status < 500 && last_status != 429)
+              increment(:@dropped_count) if last_status >= 400
+              return [last_status, body]
+            end
+            if last_status < 400
+              increment(:@sent_count)
+              return [last_status, body]
+            end
 
             # 429 (rate limited) / 503 (unavailable) → honor Retry-After when present.
             if RETRY_AFTER_STATUSES.include?(last_status)
+              increment(:@rate_limited_count) if last_status == 429
               parsed = parse_retry_after(resp["Retry-After"])
               retry_after_delay = parsed if parsed > 0
             end
@@ -171,6 +219,7 @@ module AllStak
           end
 
           if attempt < max_attempts
+            increment(:@retry_attempt_count)
             if retry_after_delay
               # Server told us how long to wait; honor it (already clamped).
               sleep(retry_after_delay)
@@ -182,10 +231,38 @@ module AllStak
           end
         end
 
+        increment(:@failed_count)
         raise AllStakTransportError,
               "All #{max_attempts} attempts failed for POST #{path}. last_status=#{last_status} last_error=#{last_exc&.message}"
       end
 
+      def diagnostics
+        snapshot = @stats_mutex.synchronize do
+          {
+            sent: @sent_count,
+            failed: @failed_count,
+            dropped: @dropped_count,
+            persisted: @persisted_count,
+            replayed: @replayed_count,
+            retry_attempts: @retry_attempt_count,
+            rate_limited: @rate_limited_count,
+            compressed: @compressed_count,
+            uncompressed: @uncompressed_count,
+            compression_bytes_saved: @compression_bytes_saved
+          }
+        end
+        snapshot[:queue_size] = @spool&.size.to_i
+        snapshot[:disabled] = disabled?
+        snapshot
+      rescue StandardError
+        {
+          sent: 0, failed: 0, dropped: 0, persisted: 0, replayed: 0,
+          retry_attempts: 0, rate_limited: 0, queue_size: 0,
+          compressed: 0, uncompressed: 0, compression_bytes_saved: 0,
+          disabled: disabled?
+        }
+      end
+
       def serialize_payload(payload)
         parsed = payload.is_a?(String) ? JSON.parse(payload) : payload
         JSON.generate(AllStak::Sanitizer.scrub(parsed, **scrub_options))
@@ -238,6 +315,26 @@ module AllStak
 
       private
 
+      def prepare_body(wire_payload)
+        return [wire_payload, false, 0] if wire_payload.bytesize < COMPRESSION_THRESHOLD_BYTES
+
+        compressed = Zlib.gzip(wire_payload)
+        return [wire_payload, false, 0] if compressed.bytesize >= wire_payload.bytesize
+
+        [compressed, true, wire_payload.bytesize - compressed.bytesize]
+      rescue StandardError
+        [wire_payload, false, 0]
+      end
+
+      def increment(counter, by = 1)
+        @stats_mutex.synchronize do
+          value = instance_variable_get(counter).to_i
+          instance_variable_set(counter, value + by.to_i)
+        end
+      rescue StandardError
+        nil
+      end
+
       # Build the offline spool from config, or nil when opted out. The spool
       # itself fails open (an unwritable dir leaves it `available? == false`),
       # so a non-nil-but-unavailable spool is fine — every public method guards

data/lib/allstak/version.rb

@@ -1,3 +1,3 @@
 module AllStak
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/lib/allstak.rb

@@ -3,6 +3,7 @@ require "time"
 
 require_relative "allstak/version"
 require_relative "allstak/config"
+require_relative "allstak/diagnostics"
 require_relative "allstak/transport/http_transport"
 require_relative "allstak/transport/flush_buffer"
 require_relative "allstak/models/user_context"
@@ -228,6 +229,14 @@ module AllStak
       @client&.shutdown
     end
 
+    # Privacy-safe SDK diagnostics for the active client. Returns a disabled
+    # zero snapshot before configure or when configuration is invalid.
+    def get_diagnostics
+      @client&.diagnostics || Diagnostics.new(disabled: true)
+    end
+
+    alias diagnostics get_diagnostics
+
     # Test helper.
     def reset!
       @mutex.synchronize do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: allstak
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - AllStak
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-30 00:00:00.000000000 Z
+date: 2026-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -68,6 +68,7 @@ files:
 - lib/allstak.rb
 - lib/allstak/client.rb
 - lib/allstak/config.rb
+- lib/allstak/diagnostics.rb
 - lib/allstak/global_handler.rb
 - lib/allstak/integrations/active_record.rb
 - lib/allstak/integrations/logger.rb