allstak 0.1.1 → 0.3.0

data/lib/allstak/client.rb

@@ -1,15 +1,27 @@
 module AllStak
   # The AllStak SDK client. Create once via {AllStak.configure}.
   class Client
-    attr_reader :config, :logger, :errors, :logs, :http, :tracing, :database, :cron, :tags, :contexts
+    attr_reader :config, :logger, :errors, :logs, :http, :tracing, :database, :cron, :tags, :contexts, :session_tracker
 
     def initialize(config, logger)
       @config = config
       @logger = logger
       @transport = Transport::HttpTransport.new(config, logger)
 
-      @errors   = Modules::Errors.new(@transport, config, logger)
-      @logs     = Modules::Logs.new(@transport, config, logger)
+      # Release-health session tracker: one session per process. Started by
+      # AllStak.configure after the release is resolved; ended in #shutdown.
+      @session_tracker = SessionTracker.new(config, @transport, logger)
+
+      @errors   = Modules::Errors.new(@transport, config, logger,
+                                      session_id_provider: -> { @session_tracker&.current_session_id })
+      # 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)
@@ -20,6 +32,37 @@ module AllStak
       at_exit { shutdown rescue nil }
     end
 
+    # The active release-health session id (nil before start / after shutdown).
+    def current_session_id
+      @session_tracker&.current_session_id
+    end
+
+    # Begin the release-health session. Idempotent + fail-open. Called by
+    # AllStak.configure once the release has been finalized.
+    def start_session
+      @session_tracker&.start
+    end
+
+    # Replay any telemetry persisted by a previous process/outage. Runs on a
+    # daemon thread so init never blocks on the network; fully fail-open. Called
+    # by AllStak.configure after the client is built. No-op when the offline
+    # queue is disabled/unavailable.
+    def drain_offline_queue
+      transport = @transport
+      return unless transport.respond_to?(:drain_spool)
+      thread = Thread.new do
+        begin
+          transport.drain_spool
+        rescue StandardError => e
+          @logger&.debug("[AllStak] offline drain failed: #{e.class}: #{e.message}")
+        end
+      end
+      thread.abort_on_exception = false
+      self
+    rescue StandardError
+      self
+    end
+
     def set_user(id: nil, email: nil, ip: nil)
       @errors.set_user(id: id, email: email, ip: ip)
     end
@@ -30,11 +73,13 @@ module AllStak
 
     def capture_exception(exc, **kw)
       kw = merge_default_metadata(kw)
+      mark_session_for(kw)
       @errors.capture_exception(exc, **kw)
     end
 
     def capture_error(exception_class, message, **kw)
       kw = merge_default_metadata(kw)
+      mark_session_for(kw)
       @errors.capture_error(exception_class, message, **kw)
     end
 
@@ -80,10 +125,28 @@ module AllStak
       @http.shutdown
       @tracing.shutdown
       @database.shutdown
+      # Graceful shutdown: end the release-health session last so its
+      # /sessions/end carries the final accumulated status. Best-effort.
+      @session_tracker&.end rescue nil
     end
 
     private
 
+    # Mark the active session errored/crashed based on the captured event's
+    # mechanism. An at_exit/unhandled event (handled=false) is a crash;
+    # everything else is a handled error. Fail-open — never raises.
+    def mark_session_for(kw)
+      tracker = @session_tracker
+      return unless tracker
+      meta = kw[:metadata]
+      handled_false =
+        meta.is_a?(Hash) &&
+        (meta["handled"] == false || meta[:handled] == false)
+      handled_false ? tracker.record_crash : tracker.record_error
+    rescue StandardError
+      nil
+    end
+
     # Fold the persistent tags + contexts into any explicit metadata caller
     # passed. Caller-supplied keys win on conflict.
     def merge_default_metadata(kw)

data/lib/allstak/config.rb

@@ -1,17 +1,215 @@
+require_relative "version"
+
 module AllStak
+  # Runtime release detection from the local git checkout.
+  #
+  # The parsing logic is split from the actual shelling-out so it stays
+  # seamable: tests inject a fake "git runner" callable instead of relying on a
+  # real repository on disk.
+  #
+  # PRODUCTION HONESTY: a deployed artifact (packaged gem / container image)
+  # usually has no `.git` directory, so {.detect_release} returns nil there and
+  # the SDK version constant becomes the effective release. Runtime git
+  # detection mainly helps source/dev deployments running inside a checkout.
+  module GitRelease
+    module_function
+
+    # Default runner: shells out to the real `git` binary from the process
+    # working directory with a short timeout. Raises on any failure (git
+    # missing, no repo, timeout) so callers can treat every failure uniformly.
+    DEFAULT_RUNNER = lambda do |args|
+      require "open3"
+      require "timeout"
+      out = nil
+      Timeout.timeout(2) do
+        stdout, _stderr, status = Open3.capture3("git", *args)
+        raise "git exited #{status.exitstatus}" unless status.success?
+        out = stdout
+      end
+      out.to_s
+    end
+
+    # Best-effort release string from local git. Order:
+    #   1. `git describe --tags --always --dirty` (preferred).
+    #   2. else `git rev-parse --short HEAD`, with `-dirty` appended when
+    #      `git status --porcelain` is non-empty.
+    # Fully guarded: returns nil if the runner raises or yields nothing for both
+    # strategies. Never raises.
+    def detect_release(runner = DEFAULT_RUNNER)
+      begin
+        described = runner.call(["describe", "--tags", "--always", "--dirty"]).to_s.strip
+        return described unless described.empty?
+      rescue StandardError
+        # fall through to rev-parse
+      end
+
+      begin
+        sha = runner.call(["rev-parse", "--short", "HEAD"]).to_s.strip
+        return nil if sha.empty?
+
+        status = begin
+          runner.call(["status", "--porcelain"]).to_s
+        rescue StandardError
+          ""
+        end
+        return "#{sha}-dirty" unless status.strip.empty?
+
+        sha
+      rescue StandardError
+        nil
+      end
+    end
+  end
+
   # SDK configuration. Populated via {AllStak.configure}.
   class Config
+    SDK_NAME    = "allstak-ruby"
+    # Single source of truth: keep the wire `sdk.version` in lockstep with
+    # the gem version declared in version.rb.
+    SDK_VERSION = AllStak::VERSION
+
     attr_accessor :api_key, :host, :environment, :release, :service_name,
                   :flush_interval_ms, :buffer_size, :debug,
                   :connect_timeout, :read_timeout, :max_retries,
                   :capture_unhandled_exceptions, :capture_http_requests,
-                  :capture_user_context, :capture_sql
+                  :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 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.
+                  :sample_rate,
+                  # Span sampling rate in [0.0, 1.0]. nil disables span
+                  # sampling entirely (every span kept, traceparent sampled
+                  # flag stays "01" — the historical behavior). When set, span
+                  # creation is sampled and the propagated traceparent sampled
+                  # flag reflects the decision.
+                  :traces_sample_rate,
+                  # When true (default), and no explicit release or release env
+                  # var is found, the SDK tries local git (git describe) once at
+                  # init and finally falls back to the SDK version constant so
+                  # release is never empty. Set false to disable the git +
+                  # version-constant fallbacks (explicit + env still apply).
+                  :auto_detect_release,
+                  # When true (default), register the resolved release with
+                  # AllStak at runtime startup without requiring CI/CD.
+                  :auto_register_release,
+                  # When true (default), the SDK tracks one release-health
+                  # session per process: it POSTs /sessions/start on configure
+                  # and /sessions/end on graceful shutdown (at_exit), and marks
+                  # the session errored/crashed as events are captured. Set
+                  # false to opt out entirely. Automatically disabled under a
+                  # unit-test runtime.
+                  :enable_auto_session_tracking,
+                  # Offline/persistent event queue. When true (default), an
+                  # un-deliverable PII-scrubbed envelope (network outage, retries
+                  # exhausted, shutdown with events still buffered) is written to
+                  # a filesystem spool and re-sent on the next SDK init. Best-
+                  # effort + bounded; degrades silently to in-memory behavior
+                  # when the spool dir is not writable (read-only FS, sandboxed,
+                  # serverless). Set false to disable persistence entirely.
+                  :enable_offline_queue,
+                  # Spool directory. nil → <tmpdir>/allstak-spool. Configure to
+                  # point at a durable, writable path (e.g. a mounted volume).
+                  :offline_queue_dir,
+                  # Spool bounds. Oldest entries are evicted first when over a
+                  # limit. Sane server defaults live in EventSpool.
+                  :offline_queue_max_entries,
+                  :offline_queue_max_bytes,
+                  :offline_queue_max_age_s,
+                  # 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
+                  # into PII: those tier-B value scrubbers are disabled and the
+                  # auto-collected client IP is allowed through. High-risk
+                  # financial/identity data (credit-card numbers passing Luhn,
+                  # hyphenated US SSNs) is ALWAYS scrubbed regardless of this
+                  # flag, and explicitly-set user data (setUser id/email/ip) is
+                  # NEVER stripped. Honors ALLSTAK_SEND_DEFAULT_PII=1/true.
+                  :send_default_pii,
+                  # Extra key-name denylist terms (case-insensitive substring)
+                  # merged into the canonical denylist on the wire path. Extends,
+                  # never narrows. Honors ALLSTAK_EXTRA_DENYLIST (comma-separated).
+                  :extra_denylist,
+                  # Release-tracking metadata. All optional; we auto-detect
+                  # the common ones from CI env vars below.
+                  :dist, :commit_sha, :branch, :platform, :sdk_name, :sdk_version
+
+    # Process-wide cache so we shell out to git at most once. `false` means
+    # "resolved to nil" (distinct from "not yet resolved").
+    @git_release_cache = nil
+    @git_release_resolved = false
+
+    class << self
+      # Resolve the git-derived release once per process and cache it.
+      def cached_git_release
+        return @git_release_cache if @git_release_resolved
+
+        @git_release_resolved = true
+        @git_release_cache =
+          begin
+            GitRelease.detect_release
+          rescue StandardError
+            nil
+          end
+      end
+
+      # Test seam: reset the cache between examples.
+      def reset_git_release_cache!
+        @git_release_resolved = false
+        @git_release_cache = nil
+      end
+
+      # Test seam: pre-seed the resolved git release so #finalize_release! can be
+      # exercised without shelling out to a real repo.
+      def seed_git_release_cache!(value)
+        @git_release_resolved = true
+        @git_release_cache = value
+      end
+    end
 
     def initialize
       @api_key         = ENV["ALLSTAK_API_KEY"].to_s
       @host            = ENV["ALLSTAK_HOST"] || "https://api.allstak.sa"
-      @environment     = ENV["ALLSTAK_ENVIRONMENT"]
-      @release         = ENV["ALLSTAK_RELEASE"]
+      @environment     = ENV["ALLSTAK_ENVIRONMENT"] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "production"
+      # 1. explicit release is set via AllStak.configure after initialize.
+      # 2. env-var detection (unchanged).
+      @release         = ENV["ALLSTAK_RELEASE"] ||
+                         ENV["VERCEL_GIT_COMMIT_SHA"]&.slice(0, 12) ||
+                         ENV["RAILWAY_GIT_COMMIT_SHA"]&.slice(0, 12) ||
+                         ENV["RENDER_GIT_COMMIT"]&.slice(0, 12)
+      @auto_detect_release = true
+      @auto_register_release = true
+      @enable_auto_session_tracking = true
+      # Offline/persistent event queue: default ON for server runtimes; nil dir
+      # → <tmpdir>/allstak-spool. nil bound knobs fall back to EventSpool
+      # defaults. Honors ALLSTAK_OFFLINE_QUEUE=0/false and ALLSTAK_OFFLINE_QUEUE_DIR.
+      @enable_offline_queue = !%w[0 false no off].include?(ENV["ALLSTAK_OFFLINE_QUEUE"].to_s.strip.downcase)
+      @offline_queue_dir         = ENV["ALLSTAK_OFFLINE_QUEUE_DIR"]
+      @offline_queue_max_entries = nil
+      @offline_queue_max_bytes   = nil
+      @offline_queue_max_age_s   = nil
+      # 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"
       @flush_interval_ms = 2_000
       @buffer_size     = 500
@@ -23,14 +221,72 @@ 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
+      @traces_sample_rate           = nil
+      # Release metadata
+      @platform    = "ruby"
+      @sdk_name    = SDK_NAME
+      @sdk_version = SDK_VERSION
+      @commit_sha  = ENV["ALLSTAK_COMMIT_SHA"] || ENV["GIT_COMMIT"] || ENV["VERCEL_GIT_COMMIT_SHA"] ||
+                     ENV["RAILWAY_GIT_COMMIT_SHA"] || ENV["RENDER_GIT_COMMIT"]
+      @branch      = ENV["ALLSTAK_BRANCH"] || ENV["GIT_BRANCH"] || ENV["VERCEL_GIT_COMMIT_REF"] ||
+                     ENV["RAILWAY_GIT_BRANCH"]
+    end
+
+    # Resolve the release after explicit user config has been applied (called
+    # from {AllStak.configure} once the user's block has run). Resolution order:
+    #   1. explicit @release (set by the user) — kept as-is.
+    #   2. release env var — already applied in #initialize.
+    #   3. local git (cached, guarded) when auto_detect_release.
+    #   4. SDK version constant when auto_detect_release.
+    # Never raises and never overwrites a non-empty release.
+    def finalize_release!
+      return self unless @release.nil? || @release.to_s.empty?
+      return self unless @auto_detect_release
+
+      @release = AllStak::Config.cached_git_release
+      @release = SDK_VERSION if @release.nil? || @release.to_s.empty?
+      self
+    end
+
+    # Release-tracking tags merged into every event payload's metadata.
+    def release_tags
+      tags = {}
+      tags["sdk.name"]     = @sdk_name     if @sdk_name
+      tags["sdk.version"]  = @sdk_version  if @sdk_version
+      tags["platform"]     = @platform     if @platform
+      tags["dist"]         = @dist         if @dist
+      tags["commit.sha"]   = @commit_sha   if @commit_sha
+      tags["commit.branch"] = @branch      if @branch
+      tags
     end
 
     def valid?
       !@api_key.to_s.empty?
     end
 
+    # Idiomatic predicate for the PII toggle (coerces truthy config values).
+    def send_default_pii?
+      @send_default_pii ? true : false
+    end
+
     def host=(value)
       @host = value.to_s.sub(%r{/+\z}, "")
     end
+
+    private
+
+    # Parse a comma/space-separated env list into a clean array of terms.
+    # Returns nil when empty so the default canonical denylist is unaffected.
+    def parse_extra_denylist(raw)
+      return nil if raw.nil?
+      terms = raw.to_s.split(/[,\s]+/).map(&:strip).reject(&:empty?)
+      terms.empty? ? nil : terms
+    end
   end
 end

data/lib/allstak/global_handler.rb

@@ -0,0 +1,100 @@
+module AllStak
+  # Global uncaught-exception capture.
+  #
+  # Ruby has no first-class "uncaught exception" callback, but it runs
+  # `at_exit` blocks during interpreter teardown — and while they run, `$!`
+  # still holds the exception that is killing the process (if any). Inspecting
+  # `$!` from inside an `at_exit` block is the idiomatic way to catch a
+  # top-level unhandled exception. We capture it, mark it unhandled
+  # (mechanism handled=false), and do a best-effort synchronous flush before
+  # the process dies.
+  #
+  # We are deliberately conservative about WHAT counts as an unhandled
+  # termination so a clean exit (or a normal `exit`/`exit!`) is never reported
+  # as an error:
+  #   - `$!` must be present and be an Exception.
+  #   - SystemExit is treated as unhandled only when its status is non-zero
+  #     (i.e. `exit(1)` / `abort`), never `exit(0)` / `exit` (clean exit).
+  #   - SignalException (e.g. Ctrl-C / SIGINT) is ignored.
+  module GlobalHandler
+    MECHANISM = "at_exit".freeze
+
+    module_function
+
+    # Install the process-wide at_exit hook. Idempotent: the actual at_exit
+    # block is registered exactly once per process, regardless of how many
+    # times this is called (reconfigure, multiple configure calls, etc.).
+    # The block reads the live client at exit time, so reconfiguration is
+    # honored without re-registering.
+    def install!(logger = nil)
+      return if @installed
+      @installed = true
+      logger&.debug("[AllStak] installing at_exit unhandled-exception handler")
+      at_exit { run_at_exit($!) }
+    end
+
+    def installed?
+      @installed == true
+    end
+
+    # Test seam: forget that we installed (does NOT unregister the real
+    # at_exit block — Ruby has no API for that — but lets a test drive
+    # install!/idempotency logic deterministically).
+    def reset!
+      @installed = false
+    end
+
+    # The body of the at_exit hook, factored out so it is directly unit
+    # testable without actually terminating the process. `exc` is whatever
+    # `$!` held at exit time.
+    def run_at_exit(exc)
+      return unless AllStak.initialized?
+      return unless unhandled_termination?(exc)
+      capture_unhandled(exc)
+    end
+
+    # Decide whether `exc` represents a genuine unhandled termination that we
+    # should report, vs. a clean/expected exit we must ignore.
+    def unhandled_termination?(exc)
+      return false unless exc.is_a?(Exception)
+      # Ignore Ctrl-C / signal-driven teardown.
+      return false if exc.is_a?(SignalException)
+      # `exit`/`exit(0)` raise SystemExit with success? == true: clean exit.
+      if exc.is_a?(SystemExit)
+        return exc.respond_to?(:success?) ? !exc.success? : exc.status.to_i != 0
+      end
+      true
+    end
+
+    # Capture an exception as a global, unhandled event and flush
+    # synchronously. Safe to call directly as a documented integration point:
+    #
+    #   begin
+    #     run_worker
+    #   rescue => e
+    #     AllStak::GlobalHandler.capture_unhandled(e)
+    #     raise
+    #   end
+    #
+    # Also surfaced as {AllStak.capture_unhandled}.
+    def capture_unhandled(exc)
+      return nil unless AllStak.initialized?
+      client = AllStak.client
+      begin
+        client.capture_exception(
+          exc,
+          metadata: {
+            "mechanism" => MECHANISM,
+            "handled"   => false
+          }
+        )
+      rescue => e
+        AllStak.logger&.debug("[AllStak] at_exit capture failed: #{e.class}: #{e.message}")
+      ensure
+        # Best-effort synchronous flush so buffered telemetry leaves the
+        # process before it dies. Never raise out of an at_exit hook.
+        client.flush rescue nil
+      end
+    end
+  end
+end

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