allstak 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 943cc01f8f95ed1cabef20b1c88b50e462b7be871c0a962a46c225e85902e355
+  data.tar.gz: f61664c5d936089b368e22c3c71d32f58f05081a35b478814a5b4f041b799133
+SHA512:
+  metadata.gz: 7262178e8689bed7b675cc0fd60c494978ce73f826eac9566fc063054d33043c8475350e0780acadfd81c23a626c30f3ab24e1b5ca2e3191b83898b81e473f82
+  data.tar.gz: e41f14091f0e5abde8930f421394a36bdaf12e617d5376c4126f86cb700c16de740f6fdb632bd60ddc0f3dd15ba655e6c75d532b43b3bfe297b8f04ff03bfc43

data/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to the AllStak Ruby SDK.
+This project follows [Semantic Versioning](https://semver.org/).
+
+## 0.1.0 — 2026-04-11
+
+First public release. Driven end-to-end through a real Sinatra + ActiveRecord
++ SQLite + JWT application (TaskFlow API) with full auth, CRUD, validation,
+outbound HTTP, cron, and real exceptions — verified in the AllStak dashboard
+against every feature page via Chrome DevTools MCP.
+
+### Highlights
+
+- **Rack middleware** that auto-captures inbound HTTP telemetry, unhandled
+  exceptions, request context, user context (env-standard + session), and
+  per-request trace lifecycle in one line: `use AllStak::Integrations::Rack::Middleware`.
+- **ActiveRecord instrumentation** via `ActiveSupport::Notifications`
+  (`sql.active_record` subscriber) — zero-config, one event per query,
+  no duplication.
+- **Net::HTTP instrumentation** via `Module#prepend` on `Net::HTTP#request` —
+  all convenience methods (`get`, `post`, etc.) funnel through `#request`, so
+  there is no duplication, and calls to the AllStak ingest host are filtered
+  out to avoid recursive instrumentation.
+- **Distributed tracing** with `AllStak.tracing.in_span(...)` block form that
+  uses `ensure` to finish the span even on non-local flow (`throw :halt`,
+  early returns, etc.) — so Sinatra's `halt` does not orphan spans.
+
+### Added
+
+- `AllStak::Config` — all config via ENV or block form, with sensible defaults.
+- `AllStak::Transport::HttpTransport` — retry/backoff (1s → 2s → 4s → 8s
+  + jitter, max 5), 401 disable, 4xx no-retry, thread-safe.
+- `AllStak::Transport::FlushBuffer` — bounded ring buffer with background
+  timer thread, 80% early-flush, overflow warning, single-flight drain.
+- `AllStak::Modules::Errors` — `capture_exception`, `capture_error`,
+  breadcrumbs, user context, full `RequestContext` + trace ID serialization.
+- `AllStak::Modules::Logs` — buffered structured logs with
+  `debug | info | warn | error | fatal` levels (normalizes `"warning"` → `"warn"`).
+- `AllStak::Modules::HttpMonitor` — inbound + outbound HTTP telemetry,
+  batched up to 100 per POST, query-string stripping.
+- `AllStak::Modules::Tracing` — span hierarchy with thread-local parent
+  tracking, `finish`-on-`ensure` block helper.
+- `AllStak::Modules::Database` — normalized SQL, MD5 query hash, query-type
+  detection, status + error + row count, batched up to 100.
+- `AllStak::Modules::Cron` — `job(slug) { ... }` block helper with success
+  and failure heartbeat, plus direct `ping`.
+- `AllStak::Integrations::Rack::Middleware` — Rack 3-compatible middleware
+  with trace adoption (`X-AllStak-Trace-Id` / `traceparent`).
+- `AllStak::Integrations::ActiveRecordIntegration::Subscriber` —
+  `sql.active_record` subscriber, auto-installed by `AllStak.configure`.
+- `AllStak::Integrations::NetHTTP` — `Net::HTTP#request` patch,
+  auto-installed by `AllStak.configure`.
+- `AllStak::Models::UserContext` / `RequestContext` — serialized objects
+  attached to error events.
+
+### Verified production surface
+
+- Real register/login/logout/JWT flow ✔
+- Real CRUD with ownership / forbidden / 404 / state-transition guards ✔
+- Real ActiveRecord validation failures ✔
+- Real unhandled exceptions with full stack, user, request context, trace ✔
+- 89 logs across `taskflow-ruby-api` service ✔
+- 97 inbound + 3 outbound HTTP requests (success + failure) ✔
+- 349 ActiveRecord queries (SELECT / INSERT / UPDATE / DELETE) grouped ✔
+- Distributed tracing with span linking on error detail ✔
+- 2 cron monitors (healthy + failed) auto-created ✔
+
+### Breaking changes
+
+None — initial public release.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) AllStak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,292 @@
+# AllStak Ruby SDK
+
+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).
+
+```ruby
+gem "allstak"
+```
+
+```bash
+bundle install
+# or
+gem install allstak
+```
+
+## 60-second setup
+
+```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
+```
+
+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.
+
+```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
+
+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.flush                                          # drain buffers
+AllStak.shutdown                                       # drain + close
+```
+
+`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
+
+```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"
+end
+
+Rails.application.config.middleware.use AllStak::Integrations::Rack::Middleware
+```
+
+## Sinatra
+
+```ruby
+require "sinatra/base"
+require "allstak"
+
+AllStak.configure { |c| c.api_key = ENV["ALLSTAK_API_KEY"] }
+
+class MyApp < Sinatra::Base
+  use AllStak::Integrations::Rack::Middleware
+  # ...
+end
+```
+
+## 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                |
+
+The ActiveRecord subscriber and Net::HTTP patch are installed automatically
+by `AllStak.configure` — no extra setup needed.
+
+## 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.
+
+```ruby
+# Nothing to do — this just works:
+User.where(email: "alice@example.com").first
+# → captured as: SELECT "users".* FROM "users" WHERE "users"."email" = ? LIMIT ?
+```
+
+## Outbound HTTP (Net::HTTP)
+
+```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
+```
+
+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.
+
+## Manual capture cheat sheet
+
+```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
+
+# Cron monitoring — slug auto-created on first ping
+AllStak.cron.job("daily-report") do
+  generate_report
+end
+
+# User context (for events that should show who was affected)
+AllStak.set_user(id: "u-1", email: "alice@example.com")
+AllStak.clear_user
+
+# Graceful flush
+AllStak.flush
+```
+
+## Dashboard mapping
+
+| 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**         |
+
+## 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.
+
+## Troubleshooting
+
+| 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. |
+
+## Full Sinatra + ActiveRecord example
+
+```ruby
+require "sinatra/base"
+require "active_record"
+require "allstak"
+
+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
+
+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
+```
+
+## License
+
+MIT

data/allstak.gemspec

@@ -0,0 +1,40 @@
+require_relative "lib/allstak/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "allstak"
+  spec.version       = AllStak::VERSION
+  spec.authors       = ["AllStak"]
+  spec.email         = ["sdk@allstak.dev"]
+
+  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.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["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "allstak.gemspec"
+  ]
+
+  spec.require_paths = ["lib"]
+
+  # No runtime dependencies — the SDK uses only the Ruby standard library.
+  # 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"
+  spec.add_development_dependency "rack",         "~> 3.0"
+  spec.add_development_dependency "activerecord", "~> 8.0"
+end

data/lib/allstak/client.rb

@@ -0,0 +1,98 @@
+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
+
+    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)
+      @http     = Modules::HttpMonitor.new(@transport, config, logger)
+      @tracing  = Modules::Tracing.new(@transport, config, logger)
+      @database = Modules::Database.new(@transport, config, logger)
+      @cron     = Modules::Cron.new(@transport, logger, config)
+      @tags     = {}
+      @contexts = {}
+
+      at_exit { shutdown rescue nil }
+    end
+
+    def set_user(id: nil, email: nil, ip: nil)
+      @errors.set_user(id: id, email: email, ip: ip)
+    end
+
+    def clear_user
+      @errors.clear_user
+    end
+
+    def capture_exception(exc, **kw)
+      kw = merge_default_metadata(kw)
+      @errors.capture_exception(exc, **kw)
+    end
+
+    def capture_error(exception_class, message, **kw)
+      kw = merge_default_metadata(kw)
+      @errors.capture_error(exception_class, message, **kw)
+    end
+
+    # Capture a standalone string as an "error group" at the given level.
+    # Cross-SDK parity with JS/Python/PHP/Java `captureMessage`.
+    # Implemented on top of capture_error so the dashboard surfaces it as
+    # an "info"/"warning"/"error" level entry in the Errors list.
+    def capture_message(message, level: "info", **kw)
+      kw = merge_default_metadata(kw)
+      @errors.capture_error("Message", message.to_s, level: level.to_s, **kw)
+    end
+
+    # Attach a key/value tag to every subsequent event sent by the SDK.
+    # Cross-SDK parity with JS `setTag` and Python `set_tag`.
+    def set_tag(key, value)
+      @tags[key.to_s] = value.to_s
+      self
+    end
+
+    # Bulk-set tags.
+    def set_tags(pairs)
+      pairs.each { |k, v| set_tag(k, v) }
+      self
+    end
+
+    # Attach a key/value context entry (goes into metadata on every event).
+    # Cross-SDK parity with JS/Python `setContext`.
+    def set_context(key, value)
+      @contexts[key.to_s] = value
+      self
+    end
+
+    def flush
+      @logs.flush
+      @http.flush
+      @tracing.flush
+      @database.flush
+    end
+
+    def shutdown
+      flush
+      @logs.shutdown
+      @http.shutdown
+      @tracing.shutdown
+      @database.shutdown
+    end
+
+    private
+
+    # Fold the persistent tags + contexts into any explicit metadata caller
+    # passed. Caller-supplied keys win on conflict.
+    def merge_default_metadata(kw)
+      return kw if @tags.empty? && @contexts.empty?
+      base = {}
+      base.merge!(@tags) unless @tags.empty?
+      base.merge!(@contexts) unless @contexts.empty?
+      existing = kw[:metadata] || {}
+      kw.merge(metadata: base.merge(existing))
+    end
+  end
+end

data/lib/allstak/config.rb

@@ -0,0 +1,36 @@
+module AllStak
+  # SDK configuration. Populated via {AllStak.configure}.
+  class Config
+    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
+
+    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"]
+      @service_name    = ENV["ALLSTAK_SERVICE"] || "ruby-service"
+      @flush_interval_ms = 2_000
+      @buffer_size     = 500
+      @debug           = !ENV["ALLSTAK_DEBUG"].to_s.empty?
+      @connect_timeout = 3
+      @read_timeout    = 3
+      @max_retries     = 5
+      @capture_unhandled_exceptions = true
+      @capture_http_requests        = true
+      @capture_user_context         = true
+      @capture_sql                  = true
+    end
+
+    def valid?
+      !@api_key.to_s.empty?
+    end
+
+    def host=(value)
+      @host = value.to_s.sub(%r{/+\z}, "")
+    end
+  end
+end

data/lib/allstak/integrations/active_record.rb

@@ -0,0 +1,78 @@
+module AllStak
+  module Integrations
+    module ActiveRecordIntegration
+      # Subscribes to `sql.active_record` via ActiveSupport::Notifications and records
+      # every ORM-level query with timing, status, and connection metadata.
+      #
+      # Skips:
+      #   * schema / EXPLAIN / SAVEPOINT / TRANSACTION / nil SQL
+      #   * our own AllStak internal transport (there is none on AR side, but guarded)
+      #
+      # Duplicates are avoided because ActiveRecord fires a single `sql.active_record`
+      # event per executed command — whether it's from an ORM query, a `find_by_sql`,
+      # or `connection.execute`. Raw-SQL executions done through the AR connection
+      # are therefore captured via the same subscriber without double-counting.
+      class Subscriber
+        IGNORED_NAMES = [
+          "SCHEMA", "EXPLAIN", "TRANSACTION", "SAVEPOINT", "RELEASE SAVEPOINT"
+        ].freeze
+
+        def self.install!
+          return if @installed
+          return unless defined?(::ActiveSupport::Notifications)
+
+          ::ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+            begin
+              event = ::ActiveSupport::Notifications::Event.new(*args)
+              name = event.payload[:name].to_s
+              sql  = event.payload[:sql].to_s
+              next if sql.empty?
+              next if IGNORED_NAMES.include?(name)
+              next unless AllStak.initialized?
+
+              client = AllStak.client
+              config = client.config
+              next unless config.capture_sql
+
+              status = event.payload[:exception] ? "error" : "success"
+              error_message = event.payload[:exception].is_a?(Array) ? event.payload[:exception].last.to_s : nil
+              rows = event.payload[:row_count].to_i rescue -1
+
+              db_name = nil
+              db_type = nil
+              if defined?(::ActiveRecord::Base) && ::ActiveRecord::Base.respond_to?(:connection_db_config)
+                begin
+                  cfg = ::ActiveRecord::Base.connection_db_config
+                  db_name = cfg.database rescue nil
+                  db_type = cfg.adapter  rescue nil
+                rescue
+                end
+              end
+
+              client.database.record(
+                sql: sql,
+                duration_ms: event.duration.to_i,
+                status: status,
+                error_message: error_message,
+                database_name: db_name,
+                database_type: db_type,
+                rows_affected: rows >= 0 ? rows : -1,
+                trace_id: client.tracing.current_trace_id,
+                span_id: client.tracing.current_span_id
+              )
+            rescue => e
+              # never raise into host
+              AllStak.logger.debug("[AllStak] AR subscriber error: #{e.message}") rescue nil
+            end
+          end
+
+          @installed = true
+        end
+
+        def self.installed?
+          @installed == true
+        end
+      end
+    end
+  end
+end