allstak 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 943cc01f8f95ed1cabef20b1c88b50e462b7be871c0a962a46c225e85902e355
-  data.tar.gz: f61664c5d936089b368e22c3c71d32f58f05081a35b478814a5b4f041b799133
+  metadata.gz: ea16fc5869d09516a29301382b4d59d9e3f33018226516beb208aa1c826a77f3
+  data.tar.gz: 6b73ffb1e1319585c2be4c7398181cf9beae32a4ea17914501df6ae1a5df2a66
 SHA512:
-  metadata.gz: 7262178e8689bed7b675cc0fd60c494978ce73f826eac9566fc063054d33043c8475350e0780acadfd81c23a626c30f3ab24e1b5ca2e3191b83898b81e473f82
-  data.tar.gz: e41f14091f0e5abde8930f421394a36bdaf12e617d5376c4126f86cb700c16de740f6fdb632bd60ddc0f3dd15ba655e6c75d532b43b3bfe297b8f04ff03bfc43
+  metadata.gz: 1a21a2da36cf561691221369b9cf25fdfc4063300fc3f32452652d6f0987044b9121d719a597db9d6b18d617583e0253e8ee59f08539c8f2ed3c1efe5ffd543a
+  data.tar.gz: 43e2c1d26dd502e77fe498e4850352235a63be28fa33ac5c2d61a4ee7171cafda55bc11285d781de96664cdb962becf4df387c83573ccdfa495de3e80fe05695

data/CHANGELOG.md

@@ -3,6 +3,173 @@
 All notable changes to the AllStak Ruby SDK.
 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 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)
+  with `durationMs` + final status. Status model `ok | errored | crashed |
+  abnormal`: handled errors transition `ok -> errored`, an unhandled/fatal
+  exception sets `crashed` (terminal). Status transitions are in-memory only —
+  only `start`/`end` perform network I/O, so per-error latency is unaffected,
+  enabling crash-free session/user rates on the backend.
+- Idempotent and re-entrancy safe (double `start`/`end` are no-ops). Sessions
+  are never sampled. Fully fail-open: a network error or read-only runtime must
+  never crash app boot or shutdown.
+- Opt-out via `config.enable_auto_session_tracking = false`. Auto-disables under
+  a unit-test runtime so the suite never emits session traffic. The active
+  `sessionId` is attached to error/event payloads (and is allowlisted in the
+  sanitizer so it survives PII scrubbing).
+
+### Added — Offline / persistent transport queue
+- `AllStak::Transport::EventSpool` — a filesystem spool for un-sent telemetry
+  envelopes so events survive a process restart, network outage, or shutdown.
+  One JSON file per envelope (atomic temp-write + rename) so a partially written
+  file is discarded without losing the rest of the queue. Persisted bytes are
+  **already PII-scrubbed** by the caller before they hit disk.
+- Bounded by COUNT (default 100), BYTES (default 4 MiB), and AGE (default 48h),
+  evicting OLDEST-first via an embedded millis+seq ordering. Stale entries past
+  max-age are dropped on drain. On the next SDK init the queue is replayed and
+  delivered entries are removed; unreadable/oversized entries are dropped.
+- Default ON for server runtimes (`config.enable_offline_queue`), spool dir
+  `<tmpdir>/allstak-spool` (override via `config.offline_queue_dir`), with
+  configurable `offline_queue_max_entries` / `_max_bytes` / `_max_age_s`. Env
+  overrides: `ALLSTAK_OFFLINE_QUEUE`, `ALLSTAK_OFFLINE_QUEUE_DIR`. Fully
+  fail-open: a read-only / sandboxed / serverless FS degrades silently to
+  in-memory behavior and never blocks capture or init.
+
+### 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 (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`, ; 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
+  `stackTrace`/`frames` subtrees are key-name-redacted but never value-scrubbed,
+  and structured scalar keys (release, sdk/version, url/path/host, span/trace
+  ids, `sessionId`, timestamp) are skipped. Strings over 16 KiB are passed
+  through. Value scrubbing is fail-open: any error falls back to the
+  key-redacted (non-value-scrubbed) structure.
+
+### Added — Global capture, sampling, and release auto-detection
+- `AllStak::GlobalHandler` — global `at_exit` hook captures uncaught exceptions
+  (mechanism `at_exit`), feeding session crash status, before re-raising.
+- `before_send` callback + client-side event/trace sampling hooks.
+- Runtime release auto-detection from local git (`AllStak.register_runtime_release`
+  / `config.detect_release`) so events are attributed to a release without
+  manual configuration; auto-disabled under a test runtime.
+- Transport hardening: every wire payload is sanitized at the single
+  `HttpTransport#post` chokepoint, the `sdk.version` wire value is corrected,
+  and `Retry-After` is honored on 429/503.
+
+### Added — Sidekiq integration
+- `AllStak::Integrations::Sidekiq::Middleware` — Sidekiq **server** middleware
+  that starts a fresh trace per job, wraps execution in a `queue.process`
+  span + breadcrumb, and auto-captures job failures with worker class, jid,
+  queue, and (PII-sanitized via `Sanitizer`) args, re-raising so Sidekiq's
+  retry machinery still runs.
+- `death_handler` registration captures jobs that exhaust their retries
+  (`mechanism=sidekiq.death`).
+- Auto-registered by `AllStak.configure` via `Sidekiq.configure_server` when
+  Sidekiq is present; a graceful, idempotent no-op otherwise.
+
+### Added — Rails Railtie
+- `AllStak::Integrations::Rails::Railtie` — a real `Rails::Railtie` that
+  auto-inserts the Rack middleware into the app's middleware stack via an
+  initializer. Rails apps are now instrumented **without manual wiring**,
+  matching the prior README claim. Guarded (only loads when `Rails::Railtie`
+  is defined) and idempotent.
+
+### Docs
+- README + gemspec description corrected to reflect real auto-install behavior
+  (Railtie + Sidekiq server middleware) instead of the previously overstated
+  "Rails middleware" claim. Fixed stale `AllStak::Rack::Middleware` and
+  `AllStak.start_span` references.
+
+### Tests / tooling
+- New minitest coverage for the Sidekiq middleware (capture + context + span +
+  no-op without Sidekiq), the Railtie (middleware insertion + guarded without
+  Rails), and backfill for `Client`, `HttpTransport`, and `Modules::Errors`.
+- Removed unused `rspec` / `webmock` dev-dependencies (the suite is minitest
+  only; transport tests stub `Net::HTTP` directly). CI workflow simplified
+  accordingly.
+- Added minitest coverage for the new waves: `test_session_tracker`,
+  `test_session_error_wiring`, `test_event_spool`, `test_offline_queue`,
+  `test_send_default_pii`, plus value-pattern cases in `test_sanitizer` and
+  `test_global_handler` / `test_release_autodetect` / `test_retry_after`.
+  Full suite: 177 runs, 448 assertions, 0 failures.
+
+### Repo hygiene
+- Untracked stray build/vendor artifacts that the `.gitignore` already covers
+  but were committed before the ignore rules existed: the root `*.gem` packs
+  (`allstak-0.1.0.gem`, `allstak-0.1.1.gem`) and the committed
+  `vendor/bundle/` dependency cache. These are not part of the published gem
+  (`spec.files` ships only `lib/**/*.rb`, README, CHANGELOG, LICENSE, gemspec).
+
+## 0.1.2 — 2026-05-18
+
+### Added — Recursive payload sanitizer
+- New `AllStak::Sanitizer` module with `scrub(payload, extra_denylist: nil)`.
+  25-term canonical denylist, recursive over `Hash` / `Array`, `[REDACTED]`
+  substitution, `object_id` Set cycle protection, pure (no caller mutation).
+- Wired into `AllStak::Transport::HttpTransport#post` — every wire payload
+  is scrubbed before serialization. One chokepoint protects errors, logs,
+  http, db, traces.
+- Fail-open: if the sanitizer raises on a pathological payload, the SDK
+  logs at Warning level and sends raw — telemetry is never blocked.
+
+### Live canary E2E
+- 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`.
+  All scrubbed.
+
+### Tests
+- `test/test_sanitizer.rb` — 12 runs, 51 assertions, 0 failures.
+
 ## 0.1.0 — 2026-04-11
 
 First public release. Driven end-to-end through a real Sinatra + ActiveRecord

data/README.md

@@ -1,291 +1,168 @@
-# AllStak Ruby SDK
+# allstak
 
-Official Ruby SDK for [AllStak](https://allstak.dev) — error tracking,
-structured logs, HTTP + ActiveRecord monitoring, distributed tracing, and cron
-monitoring for Rack-based Ruby applications (Rails, Sinatra, Roda, Hanami).
+AllStak SDK for Ruby, Rails, Rack, and Sidekiq. Captures exceptions, logs, inbound and outbound HTTP requests, ActiveRecord queries, Sidekiq job failures, spans, and cron heartbeats. Rails apps are auto-instrumented via a Railtie; Sidekiq via a server middleware.
 
-```ruby
-gem "allstak"
-```
+## Install
 
 ```bash
-bundle install
-# or
 gem install allstak
 ```
 
-## 60-second setup
+Or add it to your Gemfile:
 
 ```ruby
-require "allstak"
-
-AllStak.configure do |c|
-  c.api_key      = ENV["ALLSTAK_API_KEY"]
-  c.environment  = "production"
-  c.release      = "myapp@1.2.3"
-  c.service_name = "myapp-api"
-end
-
-# Rack / Sinatra / Rails:
-use AllStak::Integrations::Rack::Middleware
-
-# Manual capture:
-begin
-  risky!
-rescue => e
-  AllStak.capture_exception(e)
-end
+gem "allstak"
 ```
 
-That is the whole setup. Every request, every unhandled exception, every
-ActiveRecord query, every outbound Net::HTTP call, and every trace are
-captured automatically.
-
-## Public API (cross-SDK consistent)
-
-Every method below is a module-level method on `AllStak`, matching the
-names used by the JS, Python, Java, Go, PHP, and .NET SDKs so docs carry
-across languages.
+## Setup
 
 ```ruby
-AllStak.configure { |c| ... }                          # once at bootstrap
-
-AllStak.set_user(id: "42", email: "alice@example.com") # user context
-AllStak.clear_user
-
-AllStak.set_tag("service", "checkout")                 # sticky tag
-AllStak.set_tags(region: "us-east-1", tier: "web")     # bulk
-AllStak.set_context("deployment", "canary")            # sticky context
-
-AllStak.capture_exception(exc)                         # preferred for errors
-AllStak.capture_error("DomainError", "bad input")      # without a throwable
-AllStak.capture_message("hello", level: "info")        # plain string event
+require "allstak"
 
-AllStak.log.info("request started", metadata: {...})   # structured logs
-AllStak.tracing                                        # Tracing module
-AllStak.http                                           # HTTP monitor
-AllStak.database                                       # DB query monitor
-AllStak.cron.job("daily-report") { run_job }           # cron heartbeats
+AllStak.configure do |config|
+  config.api_key = ENV["ALLSTAK_API_KEY"]
+  config.environment = ENV.fetch("APP_ENV", "production")
+  config.release = ENV["ALLSTAK_RELEASE"]
+  config.service_name = "checkout-api"
+end
 
-AllStak.flush                                          # drain buffers
-AllStak.shutdown                                       # drain + close
+AllStak.capture_exception(StandardError.new("checkout failed"))
+AllStak.log.info("payment retry", metadata: { order_id: "ord_123" })
 ```
 
-`AllStak.capture_message`, `AllStak.set_tag`, and `AllStak.set_context`
-landed in 0.1.1 as cross-SDK parity additions. Older 0.1.0 code that only
-used `capture_exception` / `capture_error` keeps working — no breaking
-changes.
-
 ## Rails
 
+For Rails apps there is **no manual wiring**. Requiring the gem loads a
+`Railtie` that auto-inserts the AllStak Rack middleware into your application's
+middleware stack during boot. Just configure the SDK during app initialization
+(e.g. in `config/initializers/allstak.rb`):
+
 ```ruby
-# config/initializers/allstak.rb
 require "allstak"
 
-AllStak.configure do |c|
-  c.api_key      = ENV["ALLSTAK_API_KEY"]
-  c.environment  = Rails.env
-  c.release      = "myapp@#{ENV['GIT_SHA'] || 'dev'}"
-  c.service_name = "myapp-api"
+AllStak.configure do |config|
+  config.api_key = ENV["ALLSTAK_API_KEY"]
+  config.environment = Rails.env
+  config.service_name = "checkout-api"
 end
-
-Rails.application.config.middleware.use AllStak::Integrations::Rack::Middleware
 ```
 
-## Sinatra
+You then get inbound request telemetry, trace propagation, unhandled-exception
+capture, ActiveRecord query instrumentation, and outbound `Net::HTTP` capture
+automatically. The middleware insertion is idempotent.
 
-```ruby
-require "sinatra/base"
-require "allstak"
+## Rack (non-Rails)
 
-AllStak.configure { |c| c.api_key = ENV["ALLSTAK_API_KEY"] }
+For plain Rack apps (Sinatra, Roda, etc.), add the middleware yourself:
 
-class MyApp < Sinatra::Base
-  use AllStak::Integrations::Rack::Middleware
-  # ...
-end
+```ruby
+use AllStak::Integrations::Rack::Middleware
 ```
 
-## What gets captured automatically
-
-| What                                  | How                                        |
-| ------------------------------------- | ------------------------------------------ |
-| Unhandled exceptions                  | Rack middleware                            |
-| Inbound HTTP requests                 | Rack middleware                            |
-| Per-request trace ID                  | Rack middleware                            |
-| User context (from env/session)       | Rack middleware                            |
-| ActiveRecord SQL queries              | `sql.active_record` subscriber             |
-| Outbound HTTP via `Net::HTTP`         | `Net::HTTP#request` patched                |
+## Sidekiq
 
-The ActiveRecord subscriber and Net::HTTP patch are installed automatically
-by `AllStak.configure` — no extra setup needed.
+When Sidekiq is present, `AllStak.configure` registers a Sidekiq **server
+middleware** automatically — no manual setup. It wraps each job in a span and
+breadcrumb, and captures job failures with worker class, jid, queue, and
+(PII-sanitized) args as context, then re-raises so Sidekiq's retry machinery
+still runs. Jobs that exhaust their retries are also captured via a death
+handler. When Sidekiq is not installed, this is a graceful no-op.
 
-## ActiveRecord
-
-`AllStak.configure` installs an `ActiveSupport::Notifications` subscriber on
-`sql.active_record`, which gives you normalized SQL, duration, row counts,
-status, and error messages for every query — whether it's from an Active Record
-relation, a `find_by_sql`, or a raw `connection.execute`. No duplication,
-because every AR query fires exactly one `sql.active_record` event.
+## Spans
 
 ```ruby
-# Nothing to do — this just works:
-User.where(email: "alice@example.com").first
-# → captured as: SELECT "users".* FROM "users" WHERE "users"."email" = ? LIMIT ?
+AllStak.tracing.in_span("checkout.authorize") do
+  authorize_payment
+end
 ```
 
-## Outbound HTTP (Net::HTTP)
+## Breadcrumbs
 
-```ruby
-# Also nothing to do:
-Net::HTTP.get(URI("https://api.example.com/v1/data"))
-# → captured as outbound HTTP telemetry with method, host, path, status, duration
-```
+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:
 
-The SDK patches `Net::HTTP#request` at `configure` time. Since every
-convenience method (`get`, `post`, `post_form`, etc.) funnels through
-`#request`, there is no duplication. Calls to your AllStak ingest host are
-skipped to avoid recursive instrumentation.
+- 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.
 
-## Manual capture cheat sheet
+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
-# Errors
-AllStak.capture_exception(exc, metadata: { order_id: "ORD-123" })
-AllStak.capture_error("StripeTimeout", "Stripe /v1/charges timed out after 30s", level: "error")
-
-# Logs (buffered, flushed in background)
-AllStak.log.info("Order placed", metadata: { id: "ORD-1" })
-AllStak.log.warn("Slow query", metadata: { ms: 4500 })
-AllStak.log.error("Payment failed", metadata: { gateway: "stripe" })
-# valid levels: debug | info | warn | error | fatal
-
-# Distributed tracing (block-form)
-AllStak.tracing.in_span("db.query", description: "SELECT users") do |span|
-  span.set_tag("db.type", "postgresql")
-  rows = User.all.to_a
-end
+AllStak.add_breadcrumb(type: "auth", message: "password reset requested",
+                       data: { "userId" => current_user.id })
+```
 
-# Cron monitoring — slug auto-created on first ping
-AllStak.cron.job("daily-report") do
-  generate_report
-end
+Disable automatic collection (manual `add_breadcrumb` still works) with
+`enable_auto_breadcrumbs = false` or `ALLSTAK_AUTO_BREADCRUMBS=0`.
 
-# User context (for events that should show who was affected)
-AllStak.set_user(id: "u-1", email: "alice@example.com")
-AllStak.clear_user
+## Structured logs (optional)
 
-# Graceful flush
-AllStak.flush
-```
+Ship your application logs to AllStak by composing the optional log adapter
+with your existing logger — existing log destinations are preserved:
 
-## Dashboard mapping
+```ruby
+# Rails 7.1+ (broadcast alongside the current logger):
+AllStak::Integrations::Logger.attach_to_rails!
+
+# Any Ruby logger:
+logger = AllStak::Integrations::Logger.broadcast(logger)
+```
 
-| Your code                                 | Dashboard page        |
-| ----------------------------------------- | --------------------- |
-| `AllStak.capture_exception` / middleware  | **Errors**, **Incidents** |
-| `AllStak.log.*`                           | **Logs**              |
-| Rack middleware (inbound)                 | **Requests**          |
-| `Net::HTTP` (outbound, auto)              | **Requests** (outbound) |
-| ActiveRecord queries (auto)               | **Database**          |
-| `AllStak.tracing.in_span`                 | **Traces**            |
-| `AllStak.cron.job` / `cron.ping`          | **Cron Jobs**         |
+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                    | Default                   | Notes |
-| ------------------------- | ------------------------- | ----- |
-| `api_key`                 | `ENV["ALLSTAK_API_KEY"]`  | Your `ask_live_...` key. |
-| `host`                    | `https://api.allstak.sa`   | Override with your AllStak ingest host. |
-| `environment`             | `nil`                     | e.g. `"production"` |
-| `release`                 | `nil`                     | e.g. `"myapp@1.2.3"` |
-| `service_name`            | `"ruby-service"`          | Shown on spans and logs. |
-| `flush_interval_ms`       | `2000`                    | Background flush interval. |
-| `buffer_size`             | `500`                     | Max buffered items per feature. |
-| `debug`                   | `false`                   | Verbose SDK logging. |
-| `connect_timeout`         | `3`                       | Transport connect timeout (seconds). |
-| `read_timeout`            | `3`                       | Transport read timeout (seconds). |
-| `max_retries`             | `5`                       | Retry 5xx with exponential backoff. |
-| `capture_unhandled_exceptions` | `true`               | Auto-capture from middleware. |
-| `capture_http_requests`        | `true`               | Auto-capture inbound HTTP. |
-| `capture_user_context`         | `true`               | Attach user claims to errors. |
-| `capture_sql`                  | `true`               | Auto-capture AR queries. |
-
-Environment variables: `ALLSTAK_API_KEY`, `ALLSTAK_HOST`, `ALLSTAK_ENVIRONMENT`,
-`ALLSTAK_RELEASE`, `ALLSTAK_SERVICE`, `ALLSTAK_DEBUG`.
-
-## Production notes
-
-- **Never crashes your app.** Every integration catches its own exceptions
-  and logs at debug level. The middleware re-raises so your framework's
-  exception handler still runs.
-- **Retries.** 5xx and network errors retry with exponential backoff
-  (1s → 2s → 4s → 8s, +jitter, max 5 attempts). 4xx are not retried.
-- **401 disables the SDK.** An invalid API key disables the SDK for the
-  rest of the process — no further events are sent, a warning is logged
-  once, and your app keeps running.
-- **Flush on shutdown.** `at_exit` triggers a best-effort flush.
-- **Thread-safe.** All public APIs are safe to call from any thread.
-  Trace context uses Ruby's thread-local storage.
-- **Non-blocking.** Telemetry is buffered and flushed on background threads.
-  Your request pipeline is never blocked by SDK work.
+| Option | Description |
+| --- | --- |
+| `api_key` | Project API key. |
+| `environment` | Deployment environment. |
+| `release` | App version or commit SHA. |
+| `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). |
+| `traces_sample_rate` | Float in `[0.0, 1.0]` span sampling rate. `nil` (default) keeps every span and the `traceparent` sampled flag; when set, span creation is sampled and the propagated `traceparent` flag reflects the decision. |
+
+For top-level uncaught exceptions outside Rack (workers, threads, rake tasks), the `at_exit` handler catches genuine unhandled terminations automatically. You can also report manually at a boundary:
 
-## Troubleshooting
+```ruby
+begin
+  run_worker
+rescue => e
+  AllStak.capture_unhandled(e) # mechanism=at_exit, handled=false
+  raise
+end
+```
 
-| Symptom                              | Fix                                              |
-| ------------------------------------ | ------------------------------------------------ |
-| No events in dashboard               | Check `host` and `api_key`. Set `debug = true`.  |
-| 401 warning                          | Invalid API key. Create a new one in Settings.   |
-| Inbound requests missing             | Make sure `use AllStak::Integrations::Rack::Middleware`. |
-| DB queries missing                   | Make sure `AllStak.configure` runs BEFORE your first AR query. |
-| Outbound HTTP missing                | Same — `configure` must run before the first `Net::HTTP` call. |
-| Cron monitor not appearing           | Auto-created on first ping; check the slug matches. |
+## Privacy
 
-## Full Sinatra + ActiveRecord example
+The SDK redacts common sensitive headers and fields. Avoid putting secrets in custom metadata.
 
-```ruby
-require "sinatra/base"
-require "active_record"
-require "allstak"
+## Troubleshooting
 
-AllStak.configure do |c|
-  c.api_key      = ENV["ALLSTAK_API_KEY"]
-  c.environment  = "production"
-  c.release      = "taskflow@1.4.2"
-  c.service_name = "taskflow-api"
-end
+- No events: confirm `ALLSTAK_API_KEY` is available before configuration.
+- Missing request telemetry (Rails): confirm `require "allstak"` runs at boot so the Railtie can auto-insert the middleware.
+- Missing request telemetry (plain Rack): confirm `use AllStak::Integrations::Rack::Middleware` is in your Rack stack.
+- Short-lived job: call `AllStak.flush` before exit when possible.
 
-ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: "app.db")
-
-class Task < ActiveRecord::Base; end
-
-class TaskFlow < Sinatra::Base
-  use AllStak::Integrations::Rack::Middleware
-
-  get "/tasks" do
-    Task.all.to_json
-  end
-
-  post "/tasks/:id/notify" do
-    task = Task.find(params[:id])
-    AllStak.tracing.in_span("http.notify", description: "POST httpbin.org/post") do |span|
-      span.set_tag("task.id", task.id.to_s)
-      uri = URI("https://httpbin.org/post")
-      Net::HTTP.post(uri, { task_id: task.id }.to_json, "Content-Type" => "application/json")
-    end
-    { ok: true }.to_json
-  end
-
-  error do
-    # Framework-level rescue. Sinatra handles the exception before Rack middleware
-    # sees it, so forward manually:
-    e = env["sinatra.error"]
-    AllStak.capture_exception(e) if e
-    status 500
-    { error: e.class.name, message: e.message }.to_json
-  end
-end
-```
+## Contributing and Support
+
+- Report bugs with the GitHub bug report template: https://github.com/AllStak/allstak-ruby/issues/new/choose
+- Open pull requests using the checklist in [CONTRIBUTING.md](CONTRIBUTING.md).
+- Report security vulnerabilities privately through [SECURITY.md](SECURITY.md).
 
 ## License
 

data/allstak.gemspec

@@ -4,19 +4,19 @@ Gem::Specification.new do |spec|
   spec.name          = "allstak"
   spec.version       = AllStak::VERSION
   spec.authors       = ["AllStak"]
-  spec.email         = ["sdk@allstak.dev"]
+  spec.email         = ["sdk@allstak.sa"]
 
   spec.summary       = "Official AllStak Ruby SDK — error tracking, logs, HTTP + ActiveRecord monitoring, tracing, and cron monitoring"
-  spec.description   = "Production-ready Ruby SDK for AllStak observability: Rack/Rails middleware, ActiveRecord instrumentation, outbound HTTP capture, distributed tracing, cron monitoring, and structured logs."
-  spec.homepage      = "https://allstak.dev"
+  spec.description   = "Production-ready Ruby SDK for AllStak observability: auto-installing Rails Railtie and Rack middleware, a Sidekiq server middleware, ActiveRecord instrumentation, outbound HTTP capture, distributed tracing, cron monitoring, and structured logs."
+  spec.homepage      = "https://allstak.sa"
   spec.license       = "MIT"
   spec.required_ruby_version = ">= 3.0.0"
 
   spec.metadata["homepage_uri"]      = spec.homepage
-  spec.metadata["source_code_uri"]   = "https://github.com/allstak-io/allstak-ruby"
-  spec.metadata["changelog_uri"]     = "https://github.com/allstak-io/allstak-ruby/blob/main/CHANGELOG.md"
-  spec.metadata["bug_tracker_uri"]   = "https://github.com/allstak-io/allstak-ruby/issues"
-  spec.metadata["documentation_uri"] = "https://allstak.dev/docs/sdks/ruby"
+  spec.metadata["source_code_uri"]   = "https://github.com/AllStak/allstak-ruby"
+  spec.metadata["changelog_uri"]     = "https://github.com/AllStak/allstak-ruby/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"]   = "https://github.com/AllStak/allstak-ruby/issues"
+  spec.metadata["documentation_uri"] = "https://allstak.sa/docs/sdks/ruby"
   spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = Dir[
@@ -33,8 +33,9 @@ Gem::Specification.new do |spec|
   # Framework integrations (Rack, Rails, ActiveRecord, Net::HTTP) are loaded
   # lazily and only activate when the host app has them available.
 
-  spec.add_development_dependency "rspec",        "~> 3.12"
-  spec.add_development_dependency "webmock",      "~> 3.19"
+  # Tests use minitest only (Ruby's bundled stdlib test framework); the
+  # transport tests stub Net::HTTP directly, so no rspec/webmock is needed.
+  spec.add_development_dependency "rake",         "~> 13.0"
   spec.add_development_dependency "rack",         "~> 3.0"
   spec.add_development_dependency "activerecord", "~> 8.0"
 end