allstak 0.1.1 → 0.3.0

data/lib/allstak/modules/errors.rb

@@ -1,4 +1,6 @@
 require "json"
+require_relative "../sampling"
+require_relative "../sanitizer"
 
 module AllStak
   module Modules
@@ -7,13 +9,20 @@ module AllStak
       PATH = "/ingest/v1/errors".freeze
       MAX_BREADCRUMBS = 50
 
-      def initialize(transport, config, logger)
+      # Thread-local key for the per-thread breadcrumb ring buffer. Each
+      # request/job runs on its own thread, so a per-thread buffer keeps one
+      # thread's breadcrumb trail from bleeding into another concurrent
+      # request's captured exception.
+      BREADCRUMB_TLS_KEY = :allstak_breadcrumbs
+
+      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)
@@ -24,28 +33,34 @@ module AllStak
         @current_user = nil
       end
 
-      def add_breadcrumb(type:, message:, level: "info", data: nil)
-        @breadcrumb_mutex.synchronize do
-          @breadcrumbs.shift if @breadcrumbs.length >= MAX_BREADCRUMBS
-          @breadcrumbs << {
-            timestamp: Time.now.utc.iso8601(6),
-            type: type,
-            message: message,
-            level: level,
-            data: data
-          }.compact
-        end
+      # Append a breadcrumb to the current thread's ring buffer.
+      #
+      # `auto: true` marks the crumb as produced by an auto-instrumentation
+      # layer (Rack/Net::HTTP/ActiveRecord/log bridge); those are suppressed
+      # when `config.enable_auto_breadcrumbs` is false. Manual breadcrumbs
+      # (`auto: false`, the default) are always recorded so existing callers
+      # (e.g. the Sidekiq middleware) keep working unchanged. Fail-open: a
+      # malformed crumb never raises into the host.
+      def add_breadcrumb(type:, message:, level: "info", data: nil, auto: false)
+        return if auto && !auto_breadcrumbs_enabled?
+        buffer = thread_breadcrumbs
+        buffer.shift if buffer.length >= MAX_BREADCRUMBS
+        buffer << {
+          timestamp: Time.now.utc.iso8601(6),
+          type: type,
+          message: message,
+          level: level,
+          data: data
+        }.compact
+        nil
+      rescue StandardError
+        nil
       end
 
       def capture_exception(exc, level: "error", user: nil, request_context: nil, trace_id: nil, metadata: nil)
         return nil if @transport.disabled?
         begin
-          crumbs = @breadcrumb_mutex.synchronize do
-            next nil if @breadcrumbs.empty?
-            out = @breadcrumbs.dup
-            @breadcrumbs.clear
-            out
-          end
+          crumbs = drain_breadcrumbs
 
           payload = {
             exceptionClass: exc.class.name,
@@ -54,21 +69,44 @@ 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 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)
+          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 +124,28 @@ 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 pre-hook scrub, before_send, and final
+          # transport scrub.
+          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 +154,100 @@ module AllStak
 
       private
 
+      # The current thread's breadcrumb ring buffer (lazily created).
+      def thread_breadcrumbs
+        Thread.current[BREADCRUMB_TLS_KEY] ||= []
+      end
+
+      # Snapshot + clear the current thread's breadcrumbs for attachment to an
+      # outgoing event. Returns nil when empty so the payload omits the key.
+      def drain_breadcrumbs
+        buffer = Thread.current[BREADCRUMB_TLS_KEY]
+        return nil if buffer.nil? || buffer.empty?
+        out = buffer.dup
+        buffer.clear
+        out
+      end
+
+      # Whether auto-emitted breadcrumbs are enabled. Defaults to true if the
+      # (possibly older/stubbed) config doesn't expose the flag.
+      def auto_breadcrumbs_enabled?
+        return true unless @config.respond_to?(:enable_auto_breadcrumbs)
+        @config.enable_auto_breadcrumbs != false
+      end
+
+      # 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. The hook receives a sanitized copy and the
+      # transport sanitizes again after the hook. Fail-open: if the hook raises,
+      # log and return the sanitized event so telemetry is never lost to a buggy
+      # hook and raw secrets are not exposed.
+      def apply_before_send(payload)
+        hook = @config.before_send
+        sanitized = sanitize_before_send(payload)
+        return sanitized unless hook.respond_to?(:call)
+        begin
+          hook.call(sanitized)
+        rescue => e
+          @logger.warn("[AllStak] before_send raised; sending sanitized event: #{e.class}: #{e.message}")
+          sanitized
+        end
+      end
+
+      def sanitize_before_send(payload)
+        AllStak::Sanitizer.scrub(payload, **sanitizer_options)
+      rescue => e
+        @logger.warn("[AllStak] pre-before_send sanitizer failed; sending redacted event: #{e.class}: #{e.message}")
+        redacted_payload(payload)
+      end
+
+      def sanitizer_options
+        {
+          extra_denylist: @config.respond_to?(:extra_denylist) ? @config.extra_denylist : nil,
+          send_default_pii: @config.respond_to?(:send_default_pii?) ? @config.send_default_pii? : false
+        }
+      end
+
+      def redacted_payload(payload)
+        out = payload.dup
+        out[:message] = AllStak::Sanitizer::REDACTED
+        out[:metadata] = { "redacted" => true }
+        out.delete(:breadcrumbs)
+        out
+      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

@@ -5,10 +5,14 @@ module AllStak
       PATH = "/ingest/v1/logs".freeze
       VALID_LEVELS = %w[debug info warn error fatal].freeze
 
-      def initialize(transport, config, logger)
+      def initialize(transport, config, logger, breadcrumb_sink: nil)
         @transport = transport
         @config = config
         @logger = logger
+        # Optional callable invoked for each accepted log so AllStak.log.*
+        # 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
         @buffer = Transport::FlushBuffer.new(
           name: "logs",
           max_size: config.buffer_size,
@@ -34,9 +38,11 @@ module AllStak
           requestId: request_id,
           userId: user_id,
           errorId: error_id,
-          metadata: metadata
+          metadata: @config.release_tags.merge(metadata || {})
         }.compact
         @buffer.push(payload)
+        emit_breadcrumb(level, message, trace_id: trace_id, span_id: span_id)
+        nil
       end
 
       def debug(msg, **kw); log("debug", msg, **kw); end
@@ -55,6 +61,22 @@ module AllStak
 
       private
 
+      # Bridge an accepted log into a breadcrumb via the injected sink. The
+      # sink is the errors module's add_breadcrumb (auto-gated), so this is a
+      # no-op when breadcrumbs are disabled or no sink was wired. Fail-open.
+      def emit_breadcrumb(level, message, trace_id: nil, span_id: nil)
+        sink = @breadcrumb_sink
+        return unless sink.respond_to?(:call)
+        sink.call(
+          type: "log",
+          message: message.to_s,
+          level: level,
+          data: { "traceId" => trace_id, "spanId" => span_id }.reject { |_, v| v.nil? }
+        )
+      rescue StandardError
+        nil
+      end
+
       def normalize_level(level)
         lv = level.to_s.downcase
         lv = "warn" if lv == "warning"
@@ -68,7 +90,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