allstak 0.1.1

data/lib/allstak/modules/tracing.rb

@@ -0,0 +1,170 @@
+require "securerandom"
+
+module AllStak
+  module Modules
+    # Distributed tracing — spans with parent-child hierarchy via Thread-local state.
+    class Tracing
+      PATH = "/ingest/v1/spans".freeze
+      VALID_STATUSES = %w[ok error timeout].freeze
+
+      def initialize(transport, config, logger)
+        @transport = transport
+        @config = config
+        @logger = logger
+        @buffer = Transport::FlushBuffer.new(
+          name: "tracing",
+          max_size: config.buffer_size,
+          interval_ms: config.flush_interval_ms,
+          flush_proc: method(:flush_batch),
+          logger: logger
+        )
+      end
+
+      def current_trace_id
+        Thread.current[:allstak_trace_id] ||= SecureRandom.hex(16)
+      end
+
+      def set_trace_id(trace_id)
+        Thread.current[:allstak_trace_id] = trace_id
+      end
+
+      def current_span_id
+        stack = Thread.current[:allstak_span_stack]
+        stack&.last
+      end
+
+      def reset_trace
+        Thread.current[:allstak_trace_id] = nil
+        Thread.current[:allstak_span_stack] = nil
+      end
+
+      def start_span(operation, description: "", tags: nil)
+        trace_id = current_trace_id
+        span_id = SecureRandom.hex(8)
+        parent = current_span_id || ""
+        Thread.current[:allstak_span_stack] ||= []
+        Thread.current[:allstak_span_stack] << span_id
+
+        Span.new(
+          trace_id: trace_id,
+          span_id: span_id,
+          parent_span_id: parent,
+          operation: operation,
+          description: description,
+          service: @config.service_name,
+          environment: @config.environment || "",
+          release: (@config.respond_to?(:release) ? @config.release : nil) || "",
+          tags: tags || {},
+          start_time_millis: (Time.now.to_f * 1000).to_i,
+          on_finish: method(:on_span_finish)
+        )
+      end
+
+      # Block-form helper: automatically finishes the span on return,
+      # on raise, or on non-local flow (e.g. Sinatra's `throw :halt`).
+      def in_span(operation, description: "", tags: nil)
+        span = start_span(operation, description: description, tags: tags)
+        status = "ok"
+        begin
+          return yield(span)
+        rescue => e
+          status = "error"
+          raise
+        ensure
+          span.finish(status) unless span.finished?
+        end
+      end
+
+      def flush
+        @buffer.flush
+      end
+
+      def shutdown
+        @buffer.shutdown
+      end
+
+      private
+
+      def on_span_finish(span)
+        stack = Thread.current[:allstak_span_stack]
+        stack&.delete(span.span_id)
+        @buffer.push(span.to_h)
+      end
+
+      def flush_batch(items)
+        begin
+          @transport.post(PATH, { spans: items })
+        rescue Transport::AllStakAuthError
+          return
+        rescue Transport::AllStakTransportError => e
+          @logger.debug("[AllStak] span transport error: #{e.message}")
+        rescue => e
+          @logger.debug("[AllStak] span unexpected error: #{e.message}")
+        end
+      end
+    end
+
+    class Span
+      attr_reader :trace_id, :span_id
+
+      def initialize(trace_id:, span_id:, parent_span_id:, operation:, description:,
+                     service:, environment:, tags:, start_time_millis:, on_finish:, release: "")
+        @trace_id = trace_id
+        @span_id = span_id
+        @parent_span_id = parent_span_id
+        @operation = operation
+        @description = description
+        @service = service
+        @environment = environment
+        @release = release
+        @tags = tags.dup
+        @start_time_millis = start_time_millis
+        @end_time_millis = nil
+        @status = "ok"
+        @finished = false
+        @on_finish = on_finish
+      end
+
+      def set_tag(key, value)
+        @tags[key.to_s] = value.to_s
+        self
+      end
+
+      def set_description(description)
+        @description = description
+        self
+      end
+
+      def finished?
+        @finished
+      end
+
+      def finish(status = "ok")
+        return if @finished
+        @finished = true
+        @status = Tracing::VALID_STATUSES.include?(status) ? status : "ok"
+        @end_time_millis = (Time.now.to_f * 1000).to_i
+        @on_finish.call(self)
+      end
+
+      def to_h
+        end_ms = @end_time_millis || (Time.now.to_f * 1000).to_i
+        {
+          traceId: @trace_id,
+          spanId: @span_id,
+          parentSpanId: @parent_span_id,
+          operation: @operation,
+          description: @description,
+          status: @status,
+          durationMs: end_ms - @start_time_millis,
+          startTimeMillis: @start_time_millis,
+          endTimeMillis: end_ms,
+          service: @service,
+          environment: @environment,
+          release: @release,
+          tags: @tags
+        }
+      end
+    end
+  end
+end

data/lib/allstak/transport/flush_buffer.rb

@@ -0,0 +1,91 @@
+require "monitor"
+
+module AllStak
+  module Transport
+    # Bounded ring buffer with a background flush thread.
+    #
+    # * Max size: `maxsize` (default 500)
+    # * Eviction: oldest item dropped when full
+    # * Flush triggers: interval timer, >= 80% capacity, explicit flush, shutdown
+    # * Single-flight: only one flush runs at a time
+    class FlushBuffer
+      include MonitorMixin
+
+      def initialize(name:, max_size:, interval_ms:, flush_proc:, logger:)
+        super()
+        @name = name
+        @max_size = max_size
+        @interval = interval_ms / 1000.0
+        @flush_proc = flush_proc
+        @logger = logger
+        @queue = []
+        @stopped = false
+        @overflow_warned = false
+        @flushing_mutex = Mutex.new
+        start_timer
+      end
+
+      def push(item)
+        synchronize do
+          if @queue.length >= @max_size
+            @queue.shift
+            unless @overflow_warned
+              @overflow_warned = true
+              @logger.warn("[AllStak] Buffer #{@name} full (#{@max_size}); oldest events dropped")
+            end
+          else
+            @overflow_warned = false
+          end
+          @queue << item
+        end
+        flush if count >= (@max_size * 0.8)
+      end
+
+      def count
+        synchronize { @queue.length }
+      end
+
+      def flush
+        @flushing_mutex.synchronize do
+          drained = synchronize do
+            next [] if @queue.empty?
+            current = @queue
+            @queue = []
+            current
+          end
+          return if drained.empty?
+          begin
+            @flush_proc.call(drained)
+          rescue => e
+            @logger.debug("[AllStak] flush error in #{@name}: #{e.class}: #{e.message}")
+          end
+        end
+      end
+
+      def shutdown
+        @stopped = true
+        @timer_thread&.wakeup rescue nil
+        @timer_thread&.join(2)
+        flush
+      end
+
+      private
+
+      def start_timer
+        @timer_thread = Thread.new do
+          Thread.current.name = "allstak-flush-#{@name}" if Thread.current.respond_to?(:name=)
+          until @stopped
+            sleep @interval
+            break if @stopped
+            begin
+              flush
+            rescue => e
+              @logger.debug("[AllStak] timer flush error: #{e.message}")
+            end
+          end
+        end
+        @timer_thread.abort_on_exception = false
+      end
+    end
+  end
+end

data/lib/allstak/transport/http_transport.rb

@@ -0,0 +1,97 @@
+require "net/http"
+require "uri"
+require "json"
+
+module AllStak
+  module Transport
+    class AllStakAuthError < StandardError; end
+    class AllStakTransportError < StandardError; end
+
+    # HTTP transport with retry/backoff and 401-disable.
+    #
+    # Contract:
+    #   connect timeout = 3s   · read timeout = 3s
+    #   backoff         = 1s → 2s → 4s → 8s (+ jitter 0-500ms)
+    #   max attempts    = 5
+    #   401             → disable SDK
+    #   4xx (400/403/404/422) → no retry
+    #   5xx / network   → retry
+    class HttpTransport
+      NON_RETRYABLE_STATUSES = [400, 401, 403, 404, 422].freeze
+      BACKOFF_DELAYS = [1.0, 2.0, 4.0, 8.0].freeze
+
+      attr_reader :disabled
+
+      def initialize(config, logger)
+        @config = config
+        @logger = logger
+        @base_url = config.host
+        @api_key = config.api_key
+        @disabled = false
+      end
+
+      def disabled?
+        @disabled
+      end
+
+      def post(path, payload)
+        raise AllStakAuthError, "SDK disabled" if @disabled
+
+        uri = URI.parse("#{@base_url}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = @config.connect_timeout
+        http.read_timeout = @config.read_timeout
+
+        last_exc = nil
+        last_status = 0
+        max_attempts = [[@config.max_retries.to_i, 1].max, 5].min
+
+        (1..max_attempts).each do |attempt|
+          begin
+            req = Net::HTTP::Post.new(uri.request_uri, {
+              "Content-Type"   => "application/json",
+              "X-AllStak-Key"  => @api_key,
+              "User-Agent"     => "allstak-ruby/#{AllStak::VERSION}"
+            })
+            req.body = payload.is_a?(String) ? payload : JSON.generate(payload)
+            @logger.debug("[AllStak] POST #{path} attempt=#{attempt}") if @config.debug
+
+            resp = http.request(req)
+            last_status = resp.code.to_i
+            body = resp.body.to_s
+
+            if last_status == 401
+              @disabled = true
+              @logger.warn("[AllStak] SDK disabled: invalid API key (401). No further events will be sent.")
+              raise AllStakAuthError, "Invalid API key"
+            end
+
+            return [last_status, body] if NON_RETRYABLE_STATUSES.include?(last_status)
+            return [last_status, body] if last_status < 400
+
+            # 5xx → retry
+          rescue AllStakAuthError
+            raise
+          rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, Errno::ECONNRESET,
+                 SocketError, EOFError, IOError => e
+            last_exc = e
+            @logger.debug("[AllStak] transport error attempt=#{attempt}: #{e.class}: #{e.message}") if @config.debug
+          rescue => e
+            last_exc = e
+            @logger.debug("[AllStak] unexpected transport error attempt=#{attempt}: #{e.class}: #{e.message}") if @config.debug
+          end
+
+          if attempt < max_attempts
+            delay = BACKOFF_DELAYS[[attempt - 1, BACKOFF_DELAYS.length - 1].min]
+            delay += rand * 0.5
+            sleep(delay)
+          end
+        end
+
+        raise AllStakTransportError,
+              "All #{max_attempts} attempts failed for POST #{path}. last_status=#{last_status} last_error=#{last_exc&.message}"
+      end
+    end
+  end
+end

data/lib/allstak/version.rb

@@ -0,0 +1,3 @@
+module AllStak
+  VERSION = "0.1.1"
+end

data/lib/allstak.rb

@@ -0,0 +1,151 @@
+require "logger"
+require "time"
+
+require_relative "allstak/version"
+require_relative "allstak/config"
+require_relative "allstak/transport/http_transport"
+require_relative "allstak/transport/flush_buffer"
+require_relative "allstak/models/user_context"
+require_relative "allstak/modules/errors"
+require_relative "allstak/modules/logs"
+require_relative "allstak/modules/http_monitor"
+require_relative "allstak/modules/tracing"
+require_relative "allstak/modules/database"
+require_relative "allstak/modules/cron"
+require_relative "allstak/client"
+require_relative "allstak/integrations/rack"
+require_relative "allstak/integrations/active_record"
+require_relative "allstak/integrations/net_http"
+
+# Official AllStak Ruby SDK.
+#
+# Quick start:
+#
+#   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 / Rails: add the middleware
+#   use AllStak::Integrations::Rack::Middleware
+#
+#   # Manual:
+#   AllStak.capture_exception(exc)
+#   AllStak.log.info("hello", metadata: { foo: "bar" })
+#   AllStak.cron.job("daily-report") { generate_report }
+module AllStak
+  @mutex = Mutex.new
+
+  class << self
+    attr_reader :logger
+
+    def configure
+      @mutex.synchronize do
+        @config ||= Config.new
+        yield @config if block_given?
+        @logger = Logger.new($stderr).tap do |l|
+          l.level = @config.debug ? Logger::DEBUG : Logger::WARN
+          l.progname = "allstak"
+        end
+        if @config.valid?
+          @client = Client.new(@config, @logger)
+          # Auto-wire integrations that are safe to install
+          AllStak::Integrations::ActiveRecordIntegration::Subscriber.install!
+          AllStak::Integrations::NetHTTP.install!
+        else
+          @logger.warn("[AllStak] api_key not set — SDK not started")
+          @client = nil
+        end
+        @client
+      end
+    end
+
+    def initialized?
+      !@client.nil?
+    end
+
+    def client
+      @client or raise "AllStak not configured. Call AllStak.configure { |c| ... } first."
+    end
+
+    def capture_exception(exc, **kw)
+      @client&.capture_exception(exc, **kw)
+    end
+
+    def capture_error(exception_class, message, **kw)
+      @client&.capture_error(exception_class, message, **kw)
+    end
+
+    # Cross-SDK parity with JS captureMessage / Python capture_message /
+    # Java captureMessage. Emits a string as an error-group entry at the
+    # given level. Safe no-op if the SDK is not configured.
+    def capture_message(message, level: "info", **kw)
+      @client&.capture_message(message, level: level, **kw)
+    end
+
+    def set_user(**kw)
+      @client&.set_user(**kw)
+    end
+
+    def clear_user
+      @client&.clear_user
+    end
+
+    # Attach a tag that sticks to every future event.
+    # Cross-SDK parity with JS setTag / Python set_tag.
+    def set_tag(key, value)
+      @client&.set_tag(key, value)
+    end
+
+    def set_tags(pairs)
+      @client&.set_tags(pairs)
+    end
+
+    # Attach a custom context entry to every future event.
+    # Cross-SDK parity with JS/Python setContext.
+    def set_context(key, value)
+      @client&.set_context(key, value)
+    end
+
+    def log
+      @client&.logs
+    end
+
+    def tracing
+      @client&.tracing
+    end
+
+    def http
+      @client&.http
+    end
+
+    def database
+      @client&.database
+    end
+
+    def cron
+      @client&.cron
+    end
+
+    def flush
+      @client&.flush
+    end
+
+    def shutdown
+      @client&.shutdown
+    end
+
+    # Test helper.
+    def reset!
+      @mutex.synchronize do
+        @client&.shutdown rescue nil
+        @client = nil
+        @config = nil
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: allstak
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- AllStak
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: 'Production-ready Ruby SDK for AllStak observability: Rack/Rails middleware,
+  ActiveRecord instrumentation, outbound HTTP capture, distributed tracing, cron monitoring,
+  and structured logs.'
+email:
+- sdk@allstak.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- allstak.gemspec
+- lib/allstak.rb
+- lib/allstak/client.rb
+- lib/allstak/config.rb
+- lib/allstak/integrations/active_record.rb
+- lib/allstak/integrations/net_http.rb
+- lib/allstak/integrations/rack.rb
+- lib/allstak/models/user_context.rb
+- lib/allstak/modules/cron.rb
+- lib/allstak/modules/database.rb
+- lib/allstak/modules/errors.rb
+- lib/allstak/modules/http_monitor.rb
+- lib/allstak/modules/logs.rb
+- lib/allstak/modules/tracing.rb
+- lib/allstak/transport/flush_buffer.rb
+- lib/allstak/transport/http_transport.rb
+- lib/allstak/version.rb
+homepage: https://allstak.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://allstak.dev
+  source_code_uri: https://github.com/allstak-io/allstak-ruby
+  changelog_uri: https://github.com/allstak-io/allstak-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/allstak-io/allstak-ruby/issues
+  documentation_uri: https://allstak.dev/docs/sdks/ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official AllStak Ruby SDK — error tracking, logs, HTTP + ActiveRecord monitoring,
+  tracing, and cron monitoring
+test_files: []