allstak 0.1.1 → 0.2.1

data/lib/allstak/integrations/sidekiq.rb

@@ -0,0 +1,183 @@
+require_relative "../sanitizer"
+
+module AllStak
+  module Integrations
+    # Sidekiq integration.
+    #
+    # Provides a Sidekiq *server* middleware that:
+    #   1. Starts a fresh trace per job (so spans/telemetry produced inside the
+    #      job link together and don't bleed across jobs on a reused thread).
+    #   2. Wraps job execution in a "queue.process" span + breadcrumb.
+    #   3. Auto-captures the exception when a job raises, attaching worker
+    #      class, jid, queue, and (sanitized) args as metadata, then re-raises
+    #      so Sidekiq's own retry machinery still runs.
+    #
+    # It also registers a `death_handler` so jobs that exhaust their retries
+    # are captured once more with `mechanism=sidekiq.death` for visibility.
+    #
+    # Installation is guarded: `install!` is a graceful no-op when Sidekiq is
+    # not loaded in the host process, and is idempotent.
+    module Sidekiq
+      def self.install!
+        return if @installed
+        return unless defined?(::Sidekiq)
+
+        ::Sidekiq.configure_server do |sidekiq_config|
+          sidekiq_config.server_middleware do |chain|
+            chain.add(AllStak::Integrations::Sidekiq::Middleware) unless chain.exists?(AllStak::Integrations::Sidekiq::Middleware)
+          end
+
+          # Retries-exhausted handler. The death handler API differs across
+          # Sidekiq majors; both forms accept a (job, exception) callable.
+          if sidekiq_config.respond_to?(:death_handlers)
+            sidekiq_config.death_handlers << lambda do |job, exception|
+              AllStak::Integrations::Sidekiq.capture_death(job, exception)
+            end
+          end
+        end
+
+        @installed = true
+      end
+
+      def self.installed?
+        @installed == true
+      end
+
+      # Capture a job that has exhausted all retries (Sidekiq "death").
+      # Best-effort; never raises into Sidekiq's death-handler loop.
+      def self.capture_death(job, exception)
+        return unless AllStak.initialized?
+        return if exception.nil?
+        client = AllStak.client
+        config = client.config
+        return unless config.capture_unhandled_exceptions
+
+        job = job || {}
+        meta = job_metadata(job).merge(
+          "mechanism" => "sidekiq.death",
+          "handled"   => false
+        )
+        client.errors.capture_exception(exception, metadata: meta)
+      rescue => e
+        begin
+          AllStak.client.config.debug && warn("[AllStak] sidekiq death capture failed: #{e.message}")
+        rescue
+          nil
+        end
+      end
+
+      # Build sanitized job metadata from a Sidekiq job hash.
+      # Args are routed through the Sanitizer (KEY-NAME redaction only) so
+      # secrets in argument hashes are redacted here; value-pattern PII
+      # scrubbing (email/IP/CC/SSN, gated by send_default_pii) is applied
+      # authoritatively on the wire path, so we don't double-scrub free text
+      # at this layer.
+      def self.job_metadata(job)
+        job ||= {}
+        args = job["args"]
+        sanitized_args =
+          begin
+            AllStak::Sanitizer.scrub(args, values: false) if args
+          rescue
+            nil
+          end
+        {
+          "sidekiq.class" => job["class"] || job["wrapped"],
+          "sidekiq.jid"   => job["jid"],
+          "sidekiq.queue" => job["queue"],
+          "sidekiq.retry_count" => job["retry_count"],
+          "sidekiq.args"  => sanitized_args
+        }.reject { |_, v| v.nil? }
+      end
+
+      # Sidekiq server middleware. Sidekiq calls `#call(worker, job, queue)`
+      # and expects the middleware to `yield` to run the job.
+      class Middleware
+        def call(worker, job, queue)
+          unless AllStak.initialized?
+            return yield
+          end
+
+          client = AllStak.client
+          config = client.config
+
+          # Each job is its own trace root unless an upstream producer
+          # propagated a trace id into the job payload.
+          incoming_trace = job.is_a?(Hash) ? (job["allstak_trace_id"] || job["trace_id"]) : nil
+          if incoming_trace && !incoming_trace.to_s.empty?
+            client.tracing.set_trace_id(incoming_trace.to_s)
+          else
+            client.tracing.reset_trace
+          end
+
+          worker_class = worker_class_name(worker, job)
+          job_queue = (job.is_a?(Hash) ? job["queue"] : nil) || queue
+          jid = job.is_a?(Hash) ? job["jid"] : nil
+
+          client.errors.add_breadcrumb(
+            type: "sidekiq",
+            message: "process #{worker_class}",
+            data: { "queue" => job_queue, "jid" => jid }.reject { |_, v| v.nil? }
+          )
+
+          span = client.tracing.start_span(
+            "queue.process",
+            description: worker_class,
+            tags: {
+              "messaging.system"      => "sidekiq",
+              "messaging.destination" => job_queue.to_s,
+              "messaging.message_id"  => jid.to_s
+            }.reject { |_, v| v.to_s.empty? }
+          )
+
+          captured = nil
+          begin
+            yield
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            captured = e
+            raise
+          ensure
+            span.finish(captured ? "error" : "ok") unless span.finished?
+
+            if captured && config.capture_unhandled_exceptions
+              begin
+                meta = AllStak::Integrations::Sidekiq.job_metadata(job_hash(job, worker_class, job_queue, jid)).merge(
+                  "mechanism" => "sidekiq",
+                  "handled"   => false,
+                  "traceId"   => client.tracing.current_trace_id
+                )
+                client.errors.capture_exception(
+                  captured,
+                  trace_id: client.tracing.current_trace_id,
+                  metadata: meta
+                )
+              rescue => err
+                config.debug && warn("[AllStak] sidekiq exception capture failed: #{err.message}")
+              end
+            end
+          end
+        end
+
+        private
+
+        def worker_class_name(worker, job)
+          if job.is_a?(Hash) && (job["wrapped"] || job["class"])
+            return (job["wrapped"] || job["class"]).to_s
+          end
+          worker.respond_to?(:class) ? worker.class.name : worker.to_s
+        end
+
+        # Normalize the job into a Hash for metadata extraction. Sidekiq always
+        # passes a Hash, but we tolerate non-Hash defensively.
+        def job_hash(job, worker_class, queue, jid)
+          return job if job.is_a?(Hash)
+          {
+            "class" => worker_class,
+            "queue" => queue,
+            "jid"   => jid
+          }
+        end
+      end
+    end
+  end
+end

data/lib/allstak/modules/database.rb

@@ -78,7 +78,10 @@ module AllStak
           rescue Transport::AllStakAuthError
             return
           rescue Transport::AllStakTransportError => e
-            @logger.debug("[AllStak] db batch transport error: #{e.message}")
+            # Retries exhausted / outage: persist the (scrubbed) batch for
+            # replay on the next init instead of dropping.
+            @transport.persist_failed(PATH, { queries: chunk })
+            @logger.debug("[AllStak] db batch transport error (spooled): #{e.message}")
           rescue => e
             @logger.debug("[AllStak] db batch unexpected error: #{e.message}")
           end

data/lib/allstak/modules/errors.rb

@@ -1,4 +1,5 @@
 require "json"
+require_relative "../sampling"
 
 module AllStak
   module Modules
@@ -7,13 +8,16 @@ module AllStak
       PATH = "/ingest/v1/errors".freeze
       MAX_BREADCRUMBS = 50
 
-      def initialize(transport, config, logger)
+      def initialize(transport, config, logger, session_id_provider: nil)
         @transport = transport
         @config = config
         @logger = logger
         @current_user = nil
         @breadcrumbs = []
         @breadcrumb_mutex = Mutex.new
+        # 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
       end
 
       def set_user(id: nil, email: nil, ip: nil)
@@ -54,21 +58,42 @@ module AllStak
             level: level,
             environment: @config.environment,
             release: @config.release,
+            # Phase 3 — v2 ingest contract: top-level identity + frames.
+            sdkName:    @config.sdk_name,
+            sdkVersion: @config.sdk_version,
+            platform:   @config.platform,
+            dist:       @config.dist,
+            frames:     extract_structured_frames(exc),
             traceId: trace_id,
+            # Release-health: top-level session id so the backend error
+            # consumer can mark the session errored/crashed server-side.
+            sessionId: current_session_id,
             user: (user || @current_user)&.to_h,
             requestContext: request_context&.to_h,
-            metadata: metadata,
+            metadata: @config.release_tags.merge(metadata || {}),
             breadcrumbs: crumbs
           }.compact
           payload.delete(:user)           if payload[:user]&.empty?
           payload.delete(:requestContext) if payload[:requestContext]&.empty?
 
+          # Sampling first, then before_send, then transport (which scrubs).
+          return nil unless Sampling.sampled?(@config.sample_rate)
+          payload = apply_before_send(payload)
+          return nil if payload.nil?
+
           status, body = @transport.post(PATH, payload)
           return nil unless status == 202
           parsed = JSON.parse(body) rescue nil
           parsed&.dig("data", "id")
         rescue Transport::AllStakAuthError
           nil
+        rescue Transport::AllStakTransportError => e
+          # Retries exhausted / network outage: persist the (scrubbed) error for
+          # replay on the next init instead of dropping. `payload` is in scope
+          # only after it is built; guard so a pre-build failure still no-ops.
+          @transport.persist_failed(PATH, payload) if defined?(payload) && payload
+          @logger.debug("[AllStak] capture_exception transport error (spooled): #{e.message}")
+          nil
         rescue => e
           @logger.debug("[AllStak] capture_exception swallowed: #{e.class}: #{e.message}")
           nil
@@ -86,14 +111,27 @@ module AllStak
             environment: @config.environment,
             release: @config.release,
             traceId: trace_id,
+            sessionId: current_session_id,
             user: (user || @current_user)&.to_h,
             requestContext: request_context&.to_h,
-            metadata: metadata
+            metadata: @config.release_tags.merge(metadata || {})
           }.compact
           payload.delete(:user)           if payload[:user]&.empty?
           payload.delete(:requestContext) if payload[:requestContext]&.empty?
+
+          # Sampling first, then before_send, then transport (which scrubs).
+          return nil unless Sampling.sampled?(@config.sample_rate)
+          payload = apply_before_send(payload)
+          return nil if payload.nil?
+
           status, _ = @transport.post(PATH, payload)
           status == 202 ? exception_class : nil
+        rescue Transport::AllStakAuthError
+          nil
+        rescue Transport::AllStakTransportError => e
+          @transport.persist_failed(PATH, payload) if defined?(payload) && payload
+          @logger.debug("[AllStak] capture_error transport error (spooled): #{e.message}")
+          nil
         rescue => e
           @logger.debug("[AllStak] capture_error swallowed: #{e.class}: #{e.message}")
           nil
@@ -102,10 +140,53 @@ module AllStak
 
       private
 
+      # Resolve the active release-health session id via the injected provider.
+      # Fail-open: any error yields nil so capture is never blocked.
+      def current_session_id
+        return nil unless @session_id_provider.respond_to?(:call)
+        sid = @session_id_provider.call
+        sid.to_s.empty? ? nil : sid
+      rescue StandardError
+        nil
+      end
+
+      # Run the user-supplied before_send hook. Returns the (possibly modified)
+      # event, or nil to drop. Fail-open: if the hook raises, log and return
+      # the ORIGINAL event so telemetry is never lost to a buggy hook.
+      def apply_before_send(payload)
+        hook = @config.before_send
+        return payload unless hook.respond_to?(:call)
+        begin
+          hook.call(payload)
+        rescue => e
+          @logger.warn("[AllStak] before_send raised; sending original event: #{e.class}: #{e.message}")
+          payload
+        end
+      end
+
       def extract_frames(exc)
         return [] unless exc.backtrace.is_a?(Array)
         exc.backtrace.first(50)
       end
+
+      # Phase 3 — v2 structured frames. Ruby's backtrace is "<file>:<line>:in `<fn>'"
+      # — split it into the wire shape so the dashboard can render real
+      # source paths. Falls back to nil when no backtrace is present.
+      def extract_structured_frames(exc)
+        return nil unless exc.backtrace.is_a?(Array)
+        out = []
+        exc.backtrace.first(50).each do |line|
+          if line =~ /^(.*):(\d+):in [`'](.+?)'/
+            out << {
+              filename: $1, absPath: $1,
+              function: $3, lineno: Integer($2),
+              inApp: !$1.include?('/gems/') && !$1.start_with?('<internal:'),
+              platform: 'ruby'
+            }
+          end
+        end
+        out.empty? ? nil : out
+      end
     end
   end
 end

data/lib/allstak/modules/http_monitor.rb

@@ -23,7 +23,8 @@ module AllStak
 
       def record(direction:, method:, host:, path:, status_code:, duration_ms:,
                  request_size: 0, response_size: 0, trace_id: nil, user_id: nil,
-                 error_fingerprint: nil, span_id: nil, parent_span_id: nil)
+                 error_fingerprint: nil, span_id: nil, parent_span_id: nil,
+                 request_id: nil)
         return if @transport.disabled?
         item = {
           direction: direction,
@@ -36,6 +37,7 @@ module AllStak
           responseSize: response_size.to_i,
           timestamp: Time.now.utc.iso8601(3),
           traceId: trace_id || SecureRandom.hex(16),
+          requestId: request_id,
           userId: user_id,
           errorFingerprint: error_fingerprint,
           spanId: span_id,
@@ -68,7 +70,10 @@ module AllStak
           rescue Transport::AllStakAuthError
             return
           rescue Transport::AllStakTransportError => e
-            @logger.debug("[AllStak] http batch transport error: #{e.message}")
+            # Retries exhausted / outage: persist the (scrubbed) batch for
+            # replay on the next init instead of dropping.
+            @transport.persist_failed(PATH, { requests: chunk })
+            @logger.debug("[AllStak] http batch transport error (spooled): #{e.message}")
           rescue => e
             @logger.debug("[AllStak] http batch unexpected error: #{e.message}")
           end

data/lib/allstak/modules/logs.rb

@@ -34,7 +34,7 @@ module AllStak
           requestId: request_id,
           userId: user_id,
           errorId: error_id,
-          metadata: metadata
+          metadata: @config.release_tags.merge(metadata || {})
         }.compact
         @buffer.push(payload)
       end
@@ -68,7 +68,10 @@ module AllStak
           rescue Transport::AllStakAuthError
             return
           rescue Transport::AllStakTransportError => e
-            @logger.debug("[AllStak] log transport error (discarding): #{e.message}")
+            # Retries exhausted / network outage: persist (scrubbed) for replay
+            # on the next init instead of dropping. Fail-open inside transport.
+            @transport.persist_failed(PATH, item)
+            @logger.debug("[AllStak] log transport error (spooled): #{e.message}")
           rescue => e
             @logger.debug("[AllStak] unexpected log error: #{e.message}")
           end

data/lib/allstak/modules/tracing.rb

@@ -1,4 +1,5 @@
 require "securerandom"
+require_relative "../sampling"
 
 module AllStak
   module Modules
@@ -36,10 +37,26 @@ module AllStak
       def reset_trace
         Thread.current[:allstak_trace_id] = nil
         Thread.current[:allstak_span_stack] = nil
+        Thread.current[:allstak_trace_sampled] = nil
+      end
+
+      # Sampling decision for the CURRENT trace. Decided once (at the first
+      # span of the trace) and cached thread-locally so every span and the
+      # propagated traceparent flag agree. When `traces_sample_rate` is nil
+      # (the default), tracing is unsampled-mode-off: everything is kept and
+      # the traceparent sampled flag stays "01" (historical behavior).
+      def current_trace_sampled?
+        decided = Thread.current[:allstak_trace_sampled]
+        return decided unless decided.nil?
+        rate = @config.traces_sample_rate
+        decided = rate.nil? ? true : Sampling.sampled?(rate)
+        Thread.current[:allstak_trace_sampled] = decided
+        decided
       end
 
       def start_span(operation, description: "", tags: nil)
         trace_id = current_trace_id
+        sampled = current_trace_sampled?
         span_id = SecureRandom.hex(8)
         parent = current_span_id || ""
         Thread.current[:allstak_span_stack] ||= []
@@ -56,6 +73,7 @@ module AllStak
           release: (@config.respond_to?(:release) ? @config.release : nil) || "",
           tags: tags || {},
           start_time_millis: (Time.now.to_f * 1000).to_i,
+          sampled: sampled,
           on_finish: method(:on_span_finish)
         )
       end
@@ -88,6 +106,10 @@ module AllStak
       def on_span_finish(span)
         stack = Thread.current[:allstak_span_stack]
         stack&.delete(span.span_id)
+        # 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?
         @buffer.push(span.to_h)
       end
 
@@ -97,7 +119,10 @@ module AllStak
         rescue Transport::AllStakAuthError
           return
         rescue Transport::AllStakTransportError => e
-          @logger.debug("[AllStak] span transport error: #{e.message}")
+          # Retries exhausted / outage: persist the (scrubbed) spans for replay
+          # on the next init instead of dropping.
+          @transport.persist_failed(PATH, { spans: items })
+          @logger.debug("[AllStak] span transport error (spooled): #{e.message}")
         rescue => e
           @logger.debug("[AllStak] span unexpected error: #{e.message}")
         end
@@ -108,7 +133,8 @@ module AllStak
       attr_reader :trace_id, :span_id
 
       def initialize(trace_id:, span_id:, parent_span_id:, operation:, description:,
-                     service:, environment:, tags:, start_time_millis:, on_finish:, release: "")
+                     service:, environment:, tags:, start_time_millis:, on_finish:,
+                     release: "", sampled: true)
         @trace_id = trace_id
         @span_id = span_id
         @parent_span_id = parent_span_id
@@ -122,9 +148,14 @@ module AllStak
         @end_time_millis = nil
         @status = "ok"
         @finished = false
+        @sampled = sampled
         @on_finish = on_finish
       end
 
+      def sampled?
+        @sampled
+      end
+
       def set_tag(key, value)
         @tags[key.to_s] = value.to_s
         self

data/lib/allstak/propagation.rb

@@ -0,0 +1,48 @@
+module AllStak
+  module Propagation
+    module_function
+
+    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?
+      parts << "allstak-span_id=#{span_id}" if span_id && !span_id.to_s.empty?
+      parts.join(",")
+    end
+
+    def merge_baggage(existing, trace_id:, request_id: nil, span_id: nil)
+      preserved = existing.to_s.split(",").map(&:strip).reject do |part|
+        part.empty? || part.downcase.start_with?("allstak-")
+      end
+      (preserved + baggage(trace_id: trace_id, request_id: request_id, span_id: span_id).split(",")).join(",")
+    end
+
+    # W3C traceparent trace-flags: "01" = sampled, "00" = not sampled.
+    # `sampled` defaults to true to preserve historical behavior for callers
+    # that do not pass an explicit sampling decision.
+    def trace_flags(sampled)
+      sampled == false ? "00" : "01"
+    end
+
+    def apply_headers(headers, trace_id:, request_id: nil, span_id: nil, sampled: true)
+      headers["X-AllStak-Trace-Id"] = 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)}"
+      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)
+    end
+
+    def apply_request_headers(req, trace_id:, request_id: nil, span_id: nil, sampled: true)
+      req["X-AllStak-Trace-Id"] ||= 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)}"
+      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)
+    end
+  end
+end

data/lib/allstak/sampling.rb

@@ -0,0 +1,38 @@
+module AllStak
+  # Deterministic head-sampling helper.
+  #
+  # Sampling is "deterministic" in the sense that a rate of 1.0 always keeps
+  # an event and a rate of 0.0 always drops it — no RNG is consulted at the
+  # boundaries. For intermediate rates a single random draw in [0.0, 1.0) is
+  # compared against the rate: kept when `draw < rate`.
+  #
+  # The RNG is a seam: tests inject a deterministic value via {rng=} so the
+  # keep/drop decision is fully controllable without monkeypatching Kernel.
+  module Sampling
+    module_function
+
+    # Override the random source used by {sampled?}. Pass a callable returning
+    # a Float in [0.0, 1.0). Pass nil to restore the default (Kernel#rand).
+    def rng=(callable)
+      @rng = callable
+    end
+
+    def rng
+      @rng || ->(*) { rand }
+    end
+
+    # Returns true when an event should be KEPT under the given rate.
+    #
+    # nil rate is treated as "no sampling configured" → keep.
+    # Rates are clamped to [0.0, 1.0]. 1.0 always keeps; 0.0 always drops.
+    def sampled?(rate)
+      return true if rate.nil?
+      r = rate.to_f
+      r = 0.0 if r < 0.0
+      r = 1.0 if r > 1.0
+      return true  if r >= 1.0
+      return false if r <= 0.0
+      rng.call < r
+    end
+  end
+end