allstak 0.1.1 → 0.3.0

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

@@ -1,4 +1,6 @@
 require "net/http"
+require "securerandom"
+require "allstak/propagation"
 
 module AllStak
   module Integrations
@@ -38,6 +40,10 @@ module AllStak
           client = AllStak.client
           # Short-circuit: do NOT instrument our own ingest calls
           return super if host.include?("ingest") || host_matches_allstak?(host)
+          trace_id = client.tracing.current_trace_id
+          span_id = client.tracing.current_span_id
+          request_id = SecureRandom.hex(16)
+          AllStak::Propagation.apply_request_headers(req, trace_id: trace_id, request_id: request_id, span_id: span_id, sampled: client.tracing.current_trace_sampled?)
 
           begin
             response = super
@@ -59,9 +65,29 @@ module AllStak
                 duration_ms: duration,
                 request_size: req_size,
                 response_size: resp_size,
-                trace_id: client.tracing.current_trace_id,
+                trace_id: trace_id,
+                request_id: request_id,
+                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

@@ -1,3 +1,6 @@
+require "securerandom"
+require "allstak/propagation"
+
 module AllStak
   module Integrations
     module Rack
@@ -20,14 +23,23 @@ module AllStak
           start = now_ms
           started_at = Time.now.utc.iso8601(3)
 
-          # Trace id — adopt incoming or mint fresh per request
-          incoming = env["HTTP_X_ALLSTAK_TRACE_ID"] || env["HTTP_TRACEPARENT"]
-          if incoming && !incoming.empty?
-            client.tracing.set_trace_id(incoming)
+          trace_id = trace_id_from_env(env)
+          parent_span_id = parent_span_id_from_env(env)
+          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
           trace_id = client.tracing.current_trace_id
+          span = client.tracing.start_span(
+            "http.server",
+            description: "#{env["REQUEST_METHOD"] || "GET"} #{env["PATH_INFO"] || "/"}",
+            tags: {
+              "http.method" => env["REQUEST_METHOD"] || "GET",
+              "http.route" => env["PATH_INFO"] || "/"
+            }
+          )
 
           status = 0
           headers = {}
@@ -61,18 +73,41 @@ module AllStak
                   request_size: req_size,
                   response_size: resp_size || 0,
                   trace_id: trace_id,
+                  request_id: request_id,
+                  span_id: span.span_id,
+                  parent_span_id: parent_span_id,
                   user_id: user_id
                 )
+                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}")
               end
             end
+            span.finish(status.to_i >= 500 || captured ? "error" : "ok") unless span.finished?
 
             # Exception capture
             if captured && config.capture_unhandled_exceptions
               begin
-                user_ctx = config.capture_user_context ? build_user_context(env) : nil
+                user_ctx = config.capture_user_context ? build_user_context(env, config) : nil
                 req_ctx = AllStak::Models::RequestContext.new(
                   method: env["REQUEST_METHOD"],
                   path: env["PATH_INFO"],
@@ -85,7 +120,8 @@ module AllStak
                   "http.path"   => env["PATH_INFO"],
                   "http.host"   => env["HTTP_HOST"],
                   "http.status" => status.to_i == 0 ? 500 : status.to_i,
-                  "traceId"     => trace_id
+                  "traceId"     => trace_id,
+                  "requestId"   => request_id
                 }
                 client.errors.capture_exception(
                   captured,
@@ -99,8 +135,14 @@ module AllStak
               end
             end
 
-            # Best-effort response header for downstream trace linkage
-            headers["X-AllStak-Trace-Id"] = trace_id if headers && !captured
+            # Best-effort response headers for downstream trace linkage.
+            AllStak::Propagation.apply_headers(
+              headers,
+              trace_id: trace_id,
+              request_id: request_id,
+              span_id: span.span_id,
+              sampled: client.tracing.current_trace_sampled?
+            ) if headers && !captured
           end
 
           [status, headers, body]
@@ -112,6 +154,20 @@ 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"]
+        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"]
+        end
+
         def extract_user_id(env)
           # Rack-standard: env["warden"]? env["rack.session"]?
           # Apps can set env["allstak.user_id"] directly.
@@ -123,11 +179,16 @@ module AllStak
           nil
         end
 
-        def build_user_context(env)
+        def build_user_context(env, config = nil)
           id = extract_user_id(env)
           email = env["allstak.user_email"]
           return nil if id.nil? && email.nil?
-          ip = env["REMOTE_ADDR"] || env["HTTP_X_FORWARDED_FOR"]
+          # The client IP here is AUTO-collected by the middleware (not set
+          # 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
+          ip = send_pii ? (env["REMOTE_ADDR"] || env["HTTP_X_FORWARDED_FOR"]) : nil
           AllStak::Models::UserContext.new(id: id, email: email, ip: ip)
         end
       end

data/lib/allstak/integrations/rails.rb

@@ -0,0 +1,59 @@
+require_relative "rack"
+
+module AllStak
+  module Integrations
+    module Rails
+      # Auto-install the AllStak Rack middleware into a Rails application's
+      # middleware stack so Rails apps get inbound request telemetry, trace
+      # propagation, and unhandled-exception capture WITHOUT any manual
+      # `config.middleware.use` wiring.
+      #
+      # `Railtie` is only defined (and the initializer only registered) when
+      # `Rails::Railtie` is available, so requiring this file is a no-op in
+      # non-Rails processes. The middleware-insertion itself is idempotent:
+      # the Rack stack rejects a middleware that's already present, and we
+      # guard explicitly as well.
+      def self.install!
+        return false unless defined?(::Rails::Railtie)
+        return true if defined?(AllStak::Integrations::Rails::Railtie)
+
+        railtie_class = Class.new(::Rails::Railtie) do
+          railtie_name "allstak" if respond_to?(:railtie_name)
+
+          initializer "allstak.insert_middleware" do |app|
+            AllStak::Integrations::Rails.insert_middleware(app)
+          end
+        end
+
+        const_set(:Railtie, railtie_class)
+        true
+      end
+
+      # Insert the Rack middleware into the given Rails app's middleware stack,
+      # unless it's already present. Returns true when (now) present.
+      def self.insert_middleware(app)
+        stack = app.config.middleware
+        mw = AllStak::Integrations::Rack::Middleware
+        return true if middleware_present?(stack, mw)
+        stack.use(mw)
+        true
+      rescue => e
+        # Never let observability wiring break Rails boot.
+        warn("[AllStak] failed to insert Rack middleware: #{e.message}") if AllStak.respond_to?(:logger) && AllStak.logger&.debug?
+        false
+      end
+
+      # Best-effort idempotency check across Rails middleware-stack versions.
+      def self.middleware_present?(stack, mw)
+        return stack.include?(mw) if stack.respond_to?(:include?)
+        false
+      rescue
+        false
+      end
+    end
+  end
+end
+
+# Eagerly attempt installation when Rails is already loaded at require time.
+# Safe no-op otherwise.
+AllStak::Integrations::Rails.install! if defined?(::Rails::Railtie)

data/lib/allstak/integrations/sidekiq.rb

@@ -0,0 +1,184 @@
+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? },
+            auto: true
+          )
+
+          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