allstak 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2487acc9b1a4a0491b0a86d246b62ffcdb3a02499d728c8eaf01af50c9779d3
-  data.tar.gz: 411db967c468cb7c1793ade463b314cb44169b19071a3ed1d90fdf5bc3a582dc
+  metadata.gz: ea16fc5869d09516a29301382b4d59d9e3f33018226516beb208aa1c826a77f3
+  data.tar.gz: 6b73ffb1e1319585c2be4c7398181cf9beae32a4ea17914501df6ae1a5df2a66
 SHA512:
-  metadata.gz: 9c91a85d0c9208021a2ed16ad0c3fa9a8d701b313d3dcd7e127b3d3a87c7d454cdd007dc65e948dec85fdf2f1a4cffaa4fc62367d13a23553df7cb7770566f55
-  data.tar.gz: 6e597806d72c3da0692ff4c14eea6aef1a09d7c6c83bbc917015fa925e9e55e82e9eebc5e91b6a9c232f0c40ce64f4b603870da485ec8526876710b34f0f938d
+  metadata.gz: 1a21a2da36cf561691221369b9cf25fdfc4063300fc3f32452652d6f0987044b9121d719a597db9d6b18d617583e0253e8ee59f08539c8f2ed3c1efe5ffd543a
+  data.tar.gz: 43e2c1d26dd502e77fe498e4850352235a63be28fa33ac5c2d61a4ee7171cafda55bc11285d781de96664cdb962becf4df387c83573ccdfa495de3e80fe05695

data/CHANGELOG.md

@@ -5,11 +5,43 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ## Unreleased
 
+## [0.3.0] — 2026-05-30
+
+### Added — Automatic breadcrumbs across all instrumentation
+- Breadcrumbs are now collected automatically from every auto-instrumentation
+  layer, not just Sidekiq. The inbound Rack middleware (request method/path/
+  status/duration), the outbound `Net::HTTP` patch (method/host/path/status/
+  duration), and the ActiveRecord subscriber (truncated SQL/duration/status)
+  each emit a breadcrumb, and every `AllStak.log.*` call is bridged into a
+  `log` breadcrumb. The trail is attached to the next captured exception with
+  no per-call developer code.
+- The breadcrumb ring buffer is now **per-thread** (50 entries), so one
+  request/job's trail never leaks into a concurrent request's captured
+  exception. Breadcrumb collection is drained on capture as before.
+- New `config.enable_auto_breadcrumbs` (default `true`; env
+  `ALLSTAK_AUTO_BREADCRUMBS=0/false` to disable) gates only the automatic
+  layers. New top-level `AllStak.add_breadcrumb(...)` records a manual
+  breadcrumb and always works regardless of the toggle.
+
+### Added — Optional structured-log adapter
+- `AllStak::Integrations::Logger` — a `::Logger`-compatible sink that forwards
+  records to `/ingest/v1/logs` via `AllStak.log`. Compose it alongside your
+  existing logger (`AllStak::Integrations::Logger.attach_to_rails!` on Rails
+  7.1+ BroadcastLogger, or `AllStak::Integrations::Logger.broadcast(logger)`)
+  so existing log destinations are preserved and app logs ship automatically.
+- ERROR PROMOTION: records at/above `ERROR` (configurable via
+  `error_promotion_level:`) are additionally captured as message error-group
+  entries so they surface in the Errors list. Opt out with
+  `error_promotion: false`. Opt-in by design and fully fail-open — the adapter
+  never raises into the host's logging path and is a no-op until the SDK is
+  configured. Defined on require but never auto-attached, so default logging
+  behavior is unchanged.
+
 ## [0.2.0] — 2026-05-29
 
 ### Added — Release-health session tracking
 - `AllStak::SessionTracker` — server-mode single-session release-health
-  lifecycle that mirrors the AllStak Java SDK. On boot it POSTs
+  lifecycle that mirrors the AllStak SDKs. On boot it POSTs
   `/ingest/v1/sessions/start` (off the hot path, on a daemon thread) with a
   per-process `sessionId`, the resolved release, environment, and SDK identity;
   on shutdown it POSTs `/ingest/v1/sessions/end` (synchronous, best-effort)
@@ -46,11 +78,11 @@ This project follows [Semantic Versioning](https://semver.org/).
 ### Added — Value-pattern PII scrubbing + sendDefaultPii
 - `AllStak::Sanitizer` gains a second scrubbing layer alongside the existing
   key-name denylist: VALUE-PATTERN redaction that scans free-text string values
-  for PII regardless of key name (Sentry data-scrubbing parity). Tier A is
+  for PII regardless of key name (AllStak data-scrubbing). Tier A is
   ALWAYS scrubbed — Luhn-validated credit-card numbers (13–19 digits, optional
   space/hyphen separators) and hyphenated US SSNs. Tier B — email addresses and
   IPv4/IPv6 — is scrubbed UNLESS `send_default_pii` is enabled.
-- `config.send_default_pii` (default `false`, Sentry parity; env
+- `config.send_default_pii` (default `false`, ; env
   `ALLSTAK_SEND_DEFAULT_PII`) opts into shipping email/IP values. The
   always-on financial/identity scrubbers are not affected by this flag.
 - Structural exemptions prevent over-redaction: the explicit `user` object and
@@ -128,8 +160,8 @@ This project follows [Semantic Versioning](https://semver.org/).
   logs at Warning level and sends raw — telemetry is never blocked.
 
 ### Live canary E2E
-- Event `03188061-8054-439a-8784-a3b52436549e` against `api.allstak.sa`.
-- ClickHouse confirmed `leak_pos = 0` across `metadata`, `stack_trace`,
+- Verified end-to-end against the AllStak ingest API at `api.allstak.sa`.
+- Ingested event confirmed `leak_pos = 0` across `metadata`, `stack_trace`,
   `breadcrumbs`, `message`. Canary `should_not_leak_ruby` planted in
   `password`, `authorization`, `cookie`, `Bearer`, `api_key`, request
   headers / body, `credit_card`, `ssn`, and a 3-level-nested `token`.

data/README.md

@@ -76,6 +76,50 @@ AllStak.tracing.in_span("checkout.authorize") do
 end
 ```
 
+## Breadcrumbs
+
+Breadcrumbs are collected **automatically** — no per-call code. After
+`AllStak.configure`, the SDK records a trail of recent events on a 50-entry
+**per-thread** ring buffer and attaches it to the next captured exception on
+that thread. Auto breadcrumbs come from:
+
+- inbound Rack requests (method, path, status, duration),
+- outbound `Net::HTTP` calls (method, host, path, status, duration),
+- ActiveRecord queries (truncated SQL, duration, status),
+- Sidekiq job processing,
+- and every `AllStak.log.*` call.
+
+Because the buffer is per-thread, one request's trail never bleeds into a
+concurrent request's exception. You can also add your own:
+
+```ruby
+AllStak.add_breadcrumb(type: "auth", message: "password reset requested",
+                       data: { "userId" => current_user.id })
+```
+
+Disable automatic collection (manual `add_breadcrumb` still works) with
+`enable_auto_breadcrumbs = false` or `ALLSTAK_AUTO_BREADCRUMBS=0`.
+
+## Structured logs (optional)
+
+Ship your application logs to AllStak by composing the optional log adapter
+with your existing logger — existing log destinations are preserved:
+
+```ruby
+# Rails 7.1+ (broadcast alongside the current logger):
+AllStak::Integrations::Logger.attach_to_rails!
+
+# Any Ruby logger:
+logger = AllStak::Integrations::Logger.broadcast(logger)
+```
+
+Once attached, `logger.info / .warn / .error` ship to `/ingest/v1/logs`
+automatically. Records at `ERROR`/`FATAL` are additionally promoted to error
+entries so they surface in the Errors list. Disable promotion with
+`AllStak::Integrations::Logger.new(error_promotion: false)`, or change the
+threshold with `error_promotion_level:`. The adapter is opt-in and fail-open —
+it never raises into your logging path.
+
 ## Configuration
 
 | Option | Description |
@@ -86,6 +130,7 @@ end
 | `service_name` | Logical service name. |
 | `flush_interval_ms` | Background flush interval. |
 | `buffer_size` | Max buffered events. |
+| `enable_auto_breadcrumbs` | Collect breadcrumbs automatically from the Rack/Net::HTTP/ActiveRecord/Sidekiq instrumentation and the `AllStak.log.*` bridge (default `true`; env `ALLSTAK_AUTO_BREADCRUMBS=0` to disable). Manual `AllStak.add_breadcrumb` is unaffected. |
 | `install_at_exit_handler` | Install a process-wide `at_exit` hook that captures the exception terminating the process as an unhandled event (default `true`). |
 | `before_send` | Callable invoked with the event hash just before transport. Return a modified hash, or `nil` to drop the event. Fails open (sends the original) if it raises. |
 | `sample_rate` | Float in `[0.0, 1.0]` head-sampling rate for error/message events (default `1.0` = keep all). |

data/lib/allstak/client.rb

@@ -14,7 +14,14 @@ module AllStak
 
       @errors   = Modules::Errors.new(@transport, config, logger,
                                       session_id_provider: -> { @session_tracker&.current_session_id })
-      @logs     = Modules::Logs.new(@transport, config, logger)
+      # Bridge AllStak.log.* into auto breadcrumbs (gated by the errors module
+      # on config.enable_auto_breadcrumbs). `auto: true` so it respects the
+      # toggle and never duplicates a manually-added breadcrumb.
+      errors = @errors
+      @logs     = Modules::Logs.new(@transport, config, logger,
+                                    breadcrumb_sink: lambda do |**kw|
+                                      errors.add_breadcrumb(**kw, auto: true)
+                                    end)
       @http     = Modules::HttpMonitor.new(@transport, config, logger)
       @tracing  = Modules::Tracing.new(@transport, config, logger)
       @database = Modules::Database.new(@transport, config, logger)

data/lib/allstak/config.rb

@@ -73,15 +73,25 @@ module AllStak
                   :connect_timeout, :read_timeout, :max_retries,
                   :capture_unhandled_exceptions, :capture_http_requests,
                   :capture_user_context, :capture_sql,
+                  # When true (default), the auto-instrumentation layers
+                  # (inbound Rack requests, outbound Net::HTTP calls,
+                  # ActiveRecord queries) and the AllStak.log.* bridge emit
+                  # breadcrumbs into a 50-entry per-thread ring buffer that is
+                  # attached to the next captured exception. Set false to
+                  # disable automatic breadcrumb collection entirely (manual
+                  # AllStak.add_breadcrumb still works). Honors
+                  # ALLSTAK_AUTO_BREADCRUMBS=0/false.
+                  :enable_auto_breadcrumbs,
                   # Install a process-wide `at_exit` hook that captures the
                   # exception terminating the process (global uncaught
                   # handler). Opt out by setting this false.
                   :install_at_exit_handler,
                   # Event pre-processing hook. A callable (proc/lambda) invoked
-                  # once just before transport with the event Hash; returns a
-                  # (possibly modified) event Hash, or nil to DROP the event.
-                  # Runs for exception + message capture. Fail-open: if it
-                  # raises, the original event is sent.
+                  # once just before transport with a sanitized event Hash;
+                  # returns a (possibly modified) event Hash, or nil to DROP the
+                  # event. Runs for exception + message capture. The transport
+                  # sanitizes again after the hook; fail-open sends the
+                  # sanitized pre-callback event if the hook raises.
                   :before_send,
                   # Deterministic head-sampling for error/message events in
                   # [0.0, 1.0]. 1.0 keeps everything (default); 0.0 drops all.
@@ -124,7 +134,7 @@ module AllStak
                   :offline_queue_max_entries,
                   :offline_queue_max_bytes,
                   :offline_queue_max_age_s,
-                  # Sentry-parity PII control. When FALSE (default), value-pattern
+                  # PII control. When FALSE (default), value-pattern
                   # scrubbing strips email + IP addresses from free-text values
                   # before they hit the wire, and any auto-collected client IP
                   # the SDK attaches is dropped. When TRUE, the caller has opted
@@ -197,7 +207,7 @@ module AllStak
       @offline_queue_max_entries = nil
       @offline_queue_max_bytes   = nil
       @offline_queue_max_age_s   = nil
-      # Sentry parity: default FALSE. Opt in via ALLSTAK_SEND_DEFAULT_PII.
+      # Default FALSE. Opt in via ALLSTAK_SEND_DEFAULT_PII.
       @send_default_pii = %w[1 true yes on].include?(ENV["ALLSTAK_SEND_DEFAULT_PII"].to_s.strip.downcase)
       @extra_denylist   = parse_extra_denylist(ENV["ALLSTAK_EXTRA_DENYLIST"])
       @service_name    = ENV["ALLSTAK_SERVICE"] || "ruby-service"
@@ -211,6 +221,9 @@ module AllStak
       @capture_http_requests        = true
       @capture_user_context         = true
       @capture_sql                  = true
+      # Auto breadcrumbs: default ON for server runtimes. Honors
+      # ALLSTAK_AUTO_BREADCRUMBS=0/false.
+      @enable_auto_breadcrumbs      = !%w[0 false no off].include?(ENV["ALLSTAK_AUTO_BREADCRUMBS"].to_s.strip.downcase)
       @install_at_exit_handler      = true
       @before_send                  = nil
       @sample_rate                  = 1.0

data/lib/allstak/integrations/active_record.rb

@@ -60,6 +60,24 @@ module AllStak
                 trace_id: client.tracing.current_trace_id,
                 span_id: client.tracing.current_span_id
               )
+
+              # Query breadcrumb so the recent SQL trail lands on the next
+              # captured exception in this thread. The SQL is truncated for the
+              # breadcrumb message; value-pattern PII scrubbing still runs on the
+              # wire path. Auto-gated via config.enable_auto_breadcrumbs.
+              client.errors.add_breadcrumb(
+                type: "query",
+                message: sql.length > 300 ? "#{sql[0, 300]}…" : sql,
+                level: status == "error" ? "error" : "info",
+                data: {
+                  "name"       => name.empty? ? nil : name,
+                  "durationMs" => event.duration.to_i,
+                  "status"     => status,
+                  "db"         => db_name,
+                  "dbType"     => db_type
+                }.reject { |_, v| v.nil? },
+                auto: true
+              )
             rescue => e
               # never raise into host
               AllStak.logger.debug("[AllStak] AR subscriber error: #{e.message}") rescue nil

data/lib/allstak/integrations/logger.rb

@@ -0,0 +1,201 @@
+require "logger"
+
+module AllStak
+  module Integrations
+    # Optional structured-log adapter.
+    #
+    # A drop-in {::Logger}-compatible sink that forwards every log record to
+    # AllStak's `/ingest/v1/logs` endpoint (via {AllStak.log}). It is intended
+    # to be *broadcast alongside* your existing logger so app logs keep going to
+    # STDOUT/file unchanged while also flowing into AllStak — no per-call code.
+    #
+    # ERROR PROMOTION: records at or above {#error_promotion_level} (default
+    # ERROR) are additionally captured as AllStak "message" error-group entries
+    # (via {AllStak.capture_message}) so error-level logs surface in the Errors
+    # list, not just the log stream. Set `error_promotion: false` to disable.
+    #
+    # OPT-IN by design — adding this adapter is the only manual step; after that
+    # `Rails.logger.error(...)` / `logger.warn(...)` ship automatically.
+    #
+    #   # Rails 7.1+ (BroadcastLogger) — keep existing logging, add AllStak:
+    #   AllStak::Integrations::Logger.attach_to_rails!
+    #
+    #   # Or compose manually with any Ruby Logger:
+    #   sink = AllStak::Integrations::Logger.new
+    #   Rails.logger.broadcast_to(sink)            # Rails 7.1+
+    #   # ...or wrap a single logger so both get every line:
+    #   Rails.logger = AllStak::Integrations::Logger.broadcast(Rails.logger)
+    #
+    # Fully fail-open: a transport/SDK error never propagates into the host's
+    # logging path, and the adapter is a graceful no-op when the SDK is not
+    # configured.
+    class Logger < ::Logger
+      # Map Ruby Logger severities to AllStak log levels.
+      SEVERITY_TO_LEVEL = {
+        ::Logger::DEBUG => "debug",
+        ::Logger::INFO  => "info",
+        ::Logger::WARN  => "warn",
+        ::Logger::ERROR => "error",
+        ::Logger::FATAL => "fatal",
+        ::Logger::UNKNOWN => "error"
+      }.freeze
+
+      attr_reader :error_promotion_level
+
+      # @param level [Integer] minimum severity to forward (default DEBUG).
+      # @param error_promotion [Boolean] capture >= error_promotion_level
+      #   records as AllStak message events too (default true).
+      # @param error_promotion_level [Integer] severity threshold for promotion
+      #   (default ::Logger::ERROR).
+      def initialize(level: ::Logger::DEBUG, error_promotion: true,
+                     error_promotion_level: ::Logger::ERROR)
+        # logdev=nil: this sink does not write to any device of its own; it only
+        # forwards into AllStak. Composition (broadcast) keeps the real device.
+        super(nil)
+        self.level = level
+        @error_promotion = error_promotion != false
+        @error_promotion_level = error_promotion_level
+      end
+
+      # Core Logger entry point. Every severity helper (#debug/#info/#warn/
+      # #error/#fatal/#unknown) and `<<` funnel through #add, so overriding it
+      # captures the whole surface. Returns true (Logger#add contract) and never
+      # raises into the host.
+      def add(severity, message = nil, progname = nil, &block)
+        severity ||= ::Logger::UNKNOWN
+        return true if severity < level
+
+        text = resolve_message(message, progname, &block)
+        forward(severity, text, progname)
+        true
+      rescue StandardError
+        true
+      end
+
+      # `logger << "raw"` writes an UNKNOWN-severity record in Ruby Logger.
+      def <<(msg)
+        add(::Logger::UNKNOWN, msg.to_s)
+        msg
+      end
+
+      class << self
+        # Compose `existing` with an AllStak sink so both receive every record.
+        # Prefers Rails' BroadcastLogger when available; otherwise returns a
+        # {BroadcastLogger} shim. Returns `existing` unchanged on any failure.
+        def broadcast(existing, **opts)
+          sink = new(**opts)
+          if defined?(::ActiveSupport::BroadcastLogger)
+            ::ActiveSupport::BroadcastLogger.new(existing, sink)
+          else
+            BroadcastLogger.new([existing, sink])
+          end
+        rescue StandardError
+          existing
+        end
+
+        # Attach an AllStak sink to the current Rails.logger without replacing
+        # the existing logging destinations. Idempotent and fail-open. Returns
+        # true when (now) attached, false otherwise (no Rails / no logger).
+        def attach_to_rails!(**opts)
+          return false unless defined?(::Rails) && ::Rails.respond_to?(:logger)
+          current = ::Rails.logger
+          return false if current.nil?
+          return true if @attached_to_rails
+
+          sink = new(**opts)
+          if current.respond_to?(:broadcast_to)
+            # Rails 7.1+ BroadcastLogger — add without disturbing existing sinks.
+            current.broadcast_to(sink)
+          else
+            ::Rails.logger = broadcast(current, **opts)
+          end
+          @attached_to_rails = true
+          true
+        rescue StandardError
+          false
+        end
+
+        # Test seam.
+        def reset_attached!
+          @attached_to_rails = false
+        end
+      end
+
+      private
+
+      # Ruby Logger's message-resolution rules: an explicit message wins; else a
+      # block's value; else the progname is treated as the message.
+      def resolve_message(message, progname, &block)
+        if message.nil?
+          block ? block.call : progname
+        else
+          message
+        end
+      end
+
+      def forward(severity, text, progname)
+        return if text.nil?
+        return unless AllStak.respond_to?(:initialized?) && AllStak.initialized?
+
+        level = SEVERITY_TO_LEVEL.fetch(severity, "info")
+        msg = text.to_s
+        return if msg.empty?
+
+        metadata = {}
+        metadata["logger"] = progname.to_s unless progname.nil? || progname.to_s.empty?
+
+        sink = AllStak.log
+        sink&.log(level, msg, metadata: metadata.empty? ? nil : metadata)
+
+        # ERROR PROMOTION: surface error/fatal logs as message error-group
+        # entries too, so they appear in the Errors list. Best-effort.
+        if @error_promotion && severity >= @error_promotion_level
+          AllStak.capture_message(msg, level: level, metadata: metadata.empty? ? nil : metadata)
+        end
+      rescue StandardError
+        nil
+      end
+
+      # Minimal broadcast shim for runtimes without ActiveSupport::BroadcastLogger
+      # (plain Ruby, older Rails). Fans every public Logger call out to each
+      # delegate; reads (e.g. #level) come from the first. Fail-open per call.
+      class BroadcastLogger
+        def initialize(loggers)
+          @loggers = Array(loggers)
+        end
+
+        %i[debug info warn error fatal unknown add log <<].each do |m|
+          define_method(m) do |*args, &block|
+            @loggers.each do |l|
+              begin
+                l.public_send(m, *args, &block) if l.respond_to?(m)
+              rescue StandardError
+                nil
+              end
+            end
+            true
+          end
+        end
+
+        # Read-ish delegations resolve against the first logger.
+        def level
+          @loggers.first&.level
+        end
+
+        def level=(value)
+          @loggers.each { |l| l.level = value if l.respond_to?(:level=) }
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          @loggers.any? { |l| l.respond_to?(name, include_private) } || super
+        end
+
+        def method_missing(name, *args, &block)
+          target = @loggers.find { |l| l.respond_to?(name) }
+          return super unless target
+          target.public_send(name, *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/allstak/integrations/net_http.rb

@@ -70,6 +70,24 @@ module AllStak
                 span_id: span_id,
                 error_fingerprint: error_fp
               )
+
+              # Outbound-call breadcrumb so it lands on the trail of any
+              # exception captured later in the same thread. Auto-gated.
+              client.errors.add_breadcrumb(
+                type: "http",
+                message: "#{method} #{host}#{path} #{status}",
+                level: (error_fp || status >= 500) ? "error" : "info",
+                data: {
+                  "direction"  => "outbound",
+                  "method"     => method,
+                  "host"       => host,
+                  "path"       => path,
+                  "status"     => status,
+                  "durationMs" => duration,
+                  "error"      => error_fp
+                }.reject { |_, v| v.nil? },
+                auto: true
+              )
             rescue
               # never raise into host
             end

data/lib/allstak/integrations/rack.rb

@@ -80,6 +80,23 @@ module AllStak
                 )
                 span.set_tag("http.status_code", status.to_i.to_s)
                 span.finish(status.to_i >= 500 || captured ? "error" : "ok")
+
+                # Inbound-request breadcrumb so it lands on the trail of any
+                # exception captured later in the same thread. Auto-gated.
+                client.errors.add_breadcrumb(
+                  type: "http",
+                  message: "#{env["REQUEST_METHOD"] || "GET"} #{path} #{status.to_i}",
+                  level: (status.to_i >= 500 || captured) ? "error" : "info",
+                  data: {
+                    "direction" => "inbound",
+                    "method"    => env["REQUEST_METHOD"] || "GET",
+                    "host"      => env["HTTP_HOST"] || "localhost",
+                    "path"      => path,
+                    "status"    => status.to_i,
+                    "durationMs" => duration
+                  },
+                  auto: true
+                )
               rescue => err
                 # never raise into host
                 config.debug && warn("[AllStak] rack request capture failed: #{err.message}")
@@ -167,7 +184,7 @@ module AllStak
           email = env["allstak.user_email"]
           return nil if id.nil? && email.nil?
           # The client IP here is AUTO-collected by the middleware (not set
-          # explicitly by the app via setUser). Sentry parity: drop it unless
+          # explicitly by the app via setUser). Privacy default: drop it unless
           # the caller opted into PII via send_default_pii. Guarded so a nil/old
           # config defaults to the privacy-preserving behavior.
           send_pii = config.respond_to?(:send_default_pii?) ? config.send_default_pii? : false

data/lib/allstak/integrations/sidekiq.rb

@@ -117,7 +117,8 @@ module AllStak
           client.errors.add_breadcrumb(
             type: "sidekiq",
             message: "process #{worker_class}",
-            data: { "queue" => job_queue, "jid" => jid }.reject { |_, v| v.nil? }
+            data: { "queue" => job_queue, "jid" => jid }.reject { |_, v| v.nil? },
+            auto: true
           )
 
           span = client.tracing.start_span(

data/lib/allstak/modules/errors.rb

@@ -1,5 +1,6 @@
 require "json"
 require_relative "../sampling"
+require_relative "../sanitizer"
 
 module AllStak
   module Modules
@@ -8,13 +9,17 @@ module AllStak
       PATH = "/ingest/v1/errors".freeze
       MAX_BREADCRUMBS = 50
 
+      # 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
@@ -28,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,
@@ -76,7 +87,9 @@ module AllStak
           payload.delete(:user)           if payload[:user]&.empty?
           payload.delete(:requestContext) if payload[:requestContext]&.empty?
 
-          # Sampling first, then before_send, then transport (which scrubs).
+          # 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?
@@ -119,7 +132,8 @@ module AllStak
           payload.delete(:user)           if payload[:user]&.empty?
           payload.delete(:requestContext) if payload[:requestContext]&.empty?
 
-          # Sampling first, then before_send, then transport (which scrubs).
+          # 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?
@@ -140,6 +154,28 @@ 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
@@ -151,19 +187,44 @@ module AllStak
       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.
+      # 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
-        return payload unless hook.respond_to?(:call)
+        sanitized = sanitize_before_send(payload)
+        return sanitized unless hook.respond_to?(:call)
         begin
-          hook.call(payload)
+          hook.call(sanitized)
         rescue => e
-          @logger.warn("[AllStak] before_send raised; sending original event: #{e.class}: #{e.message}")
-          payload
+          @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)

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,
@@ -37,6 +41,8 @@ module AllStak
           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"

data/lib/allstak/sanitizer.rb

@@ -11,13 +11,13 @@
 #      Hash keys against the canonical denylist. Conforms to the canonical
 #      AllStak SDK denylist defined in docs/standards/sdk-platform-standards.md.
 #
-#   2. VALUE-PATTERN redaction (Sentry data-scrubbing parity): scans free-text
+#   2. VALUE-PATTERN redaction (data scrubbing): scans free-text
 #      *string values* for PII that leaks regardless of key name. Two tiers:
 #        A) ALWAYS scrubbed — credit-card numbers that pass the Luhn checksum,
 #           and US SSNs written with hyphens. High-risk financial/identity data
 #           never legitimately wanted in telemetry.
 #        B) Scrubbed UNLESS send_default_pii — email addresses and IPv4
-#           addresses. Default send_default_pii=false matches Sentry.
+#           addresses. Default send_default_pii=false (privacy-safe).
 #
 # Semantics:
 # - Key match: case-insensitive substring match on Hash keys.
@@ -133,7 +133,7 @@ module AllStak
 
     # Top-level subtrees that are never value-scrubbed. `user` holds data the
     # caller explicitly set via setUser (intentional identification — ships as
-    # before, matching Sentry). `frames`/`stackTrace` hold structured stack
+    # before). `frames`/`stackTrace` hold structured stack
     # frames whose filenames/functions must not be corrupted.
     VALUE_SCRUB_SKIP_SUBTREES = %w[
       user
@@ -172,7 +172,7 @@ module AllStak
     #   may extend but not narrow the canonical list.
     # @param send_default_pii [Boolean] when true, the tier-B value scrubbers
     #   (email, IPv4/IPv6) are disabled — the caller has opted into PII. Tier-A
-    #   (credit card, SSN) is ALWAYS applied. Default false (Sentry parity).
+    #   (credit card, SSN) is ALWAYS applied. Default false (privacy-safe).
     # @param values [Boolean] when false, only key-name redaction runs (no
     #   value-pattern scrubbing). Useful for an intermediate pre-scrub (e.g.
     #   Sidekiq job args) where the wire-path scrub will value-scrub later with

data/lib/allstak/session_tracker.rb

@@ -23,7 +23,7 @@ module AllStak
     PATH_END   = "/ingest/v1/sessions/end".freeze
 
     # Lifecycle status. Vocabulary matches the backend `/sessions/end` contract
-    # and Sentry's release-health conventions:
+    # and standard release-health conventions:
     #   ok       — ended normally, at most non-fatal logs.
     #   errored  — at least one HANDLED error captured; process kept running.
     #   crashed  — an UNHANDLED/fatal exception ended the process.

data/lib/allstak/transport/event_spool.rb

@@ -15,9 +15,8 @@ module AllStak
     #   { "v" => 1, "path" => "/ingest/v1/errors", "payload" => {...},
     #     "ts" => 1700000000.123 }
     #
-    # Sentry parity: this is the Ruby analogue of Sentry's offline/transport
-    # cache dir — events that cannot be delivered are persisted (PII-scrubbed)
-    # and replayed on the next init.
+    # Offline durability: an on-disk transport cache — events that cannot be
+    # delivered are persisted (PII-scrubbed) and replayed on the next init.
     #
     # HARD invariants:
     #   * Fail-open everywhere. A read-only FS, a sandboxed/serverless runtime,

data/lib/allstak/transport/http_transport.rb

@@ -196,7 +196,7 @@ module AllStak
 
       # Sanitizer options derived from config. Guarded with respond_to? so a
       # bare/stub config (some transport unit tests) still scrubs with safe
-      # defaults: PII off (Sentry parity), no extra denylist.
+      # defaults: PII off (privacy-safe), no extra denylist.
       def scrub_options
         {
           send_default_pii: @config.respond_to?(:send_default_pii?) ? @config.send_default_pii? : false,

data/lib/allstak/version.rb

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

data/lib/allstak.rb

@@ -21,6 +21,10 @@ require_relative "allstak/integrations/rack"
 require_relative "allstak/integrations/active_record"
 require_relative "allstak/integrations/net_http"
 require_relative "allstak/integrations/sidekiq"
+# Optional structured-log adapter. Defined on require but NOT auto-attached —
+# it only ships logs once the app opts in via Logger.attach_to_rails! /
+# Logger.broadcast, so existing logging behavior is preserved by default.
+require_relative "allstak/integrations/logger"
 # The Rails Railtie self-installs on require when Rails is present, and is a
 # guarded no-op otherwise. Loading it here means Rails apps that `require
 # "allstak"` get the Rack middleware auto-wired without manual setup.
@@ -163,6 +167,15 @@ module AllStak
       AllStak::GlobalHandler.capture_unhandled(exc)
     end
 
+    # Manually record a breadcrumb on the current thread's ring buffer. It is
+    # attached to the next captured exception on this thread. Cross-SDK parity
+    # with JS addBreadcrumb / Python add_breadcrumb. Safe no-op when the SDK is
+    # not configured. Manual breadcrumbs are always recorded (independent of
+    # the enable_auto_breadcrumbs toggle, which only gates auto-instrumentation).
+    def add_breadcrumb(type:, message:, level: "info", data: nil)
+      @client&.errors&.add_breadcrumb(type: type, message: message, level: level, data: data)
+    end
+
     def set_user(**kw)
       @client&.set_user(**kw)
     end

metadata

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