miniapm 1.0.0

data/lib/miniapm/testing.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module MiniAPM
+  # Testing utilities for capturing and inspecting spans/errors in tests
+  #
+  # Usage:
+  #   require 'miniapm/testing'
+  #
+  #   RSpec.describe "MyFeature" do
+  #     before { MiniAPM::Testing.enable! }
+  #     after { MiniAPM::Testing.disable! }
+  #
+  #     it "tracks spans" do
+  #       perform_action
+  #       expect(MiniAPM::Testing.spans).to include(
+  #         having_attributes(name: /process_action/)
+  #       )
+  #     end
+  #   end
+  #
+  module Testing
+    class << self
+      # Enable test mode - captures spans/errors instead of sending them
+      def enable!
+        @enabled = true
+        @spans = []
+        @errors = []
+        @mutex = Mutex.new
+
+        # Stub the record methods to capture instead of send
+        install_test_hooks!
+      end
+
+      # Disable test mode and restore normal behavior
+      def disable!
+        @enabled = false
+        clear!
+        uninstall_test_hooks!
+      end
+
+      # Check if test mode is enabled
+      def enabled?
+        @enabled || false
+      end
+
+      # Get all captured spans
+      def spans
+        @mutex.synchronize { @spans.dup }
+      end
+
+      # Get all captured errors
+      def errors
+        @mutex.synchronize { @errors.dup }
+      end
+
+      # Alias for spans
+      def recorded_spans
+        spans
+      end
+
+      # Alias for errors
+      def recorded_errors
+        errors
+      end
+
+      # Clear all captured data
+      def clear!
+        @mutex&.synchronize do
+          @spans = []
+          @errors = []
+        end
+      end
+
+      # Find spans matching criteria
+      def find_spans(name: nil, category: nil, &block)
+        result = spans
+        result = result.select { |s| s.name.match?(name) } if name
+        result = result.select { |s| s.category == category } if category
+        result = result.select(&block) if block_given?
+        result
+      end
+
+      # Find errors matching criteria
+      def find_errors(exception_class: nil, message: nil, &block)
+        result = errors
+        result = result.select { |e| e.exception_class == exception_class } if exception_class
+        result = result.select { |e| e.message.match?(message) } if message
+        result = result.select(&block) if block_given?
+        result
+      end
+
+      # Check if any span matches
+      def span_recorded?(name: nil, category: nil)
+        find_spans(name: name, category: category).any?
+      end
+
+      # Check if any error matches
+      def error_recorded?(exception_class: nil, message: nil)
+        find_errors(exception_class: exception_class, message: message).any?
+      end
+
+      # Record a span (called by test hooks)
+      def record_span(span)
+        return unless enabled?
+
+        @mutex.synchronize { @spans << span }
+      end
+
+      # Record an error (called by test hooks)
+      def record_error(error)
+        return unless enabled?
+
+        @mutex.synchronize { @errors << error }
+      end
+
+      private
+
+      def install_test_hooks!
+        # Guard against double installation
+        return if @hooks_installed
+
+        # Store original methods
+        @original_record_span = MiniAPM.method(:record_span)
+        @original_record_error = MiniAPM.method(:record_error)
+
+        # Replace with test versions (suppress warnings)
+        testing = self
+        original_verbose = $VERBOSE
+        begin
+          $VERBOSE = nil
+          MiniAPM.define_singleton_method(:record_span) do |span|
+            testing.record_span(span)
+          end
+
+          MiniAPM.define_singleton_method(:record_error) do |exception, context: {}|
+            error_event = ErrorEvent.from_exception(exception, context)
+            testing.record_error(error_event)
+          end
+        ensure
+          $VERBOSE = original_verbose
+        end
+
+        @hooks_installed = true
+      end
+
+      def uninstall_test_hooks!
+        return unless @hooks_installed
+
+        original_verbose = $VERBOSE
+        begin
+          $VERBOSE = nil
+          MiniAPM.define_singleton_method(:record_span, @original_record_span)
+          MiniAPM.define_singleton_method(:record_error, @original_record_error)
+        ensure
+          $VERBOSE = original_verbose
+        end
+
+        @original_record_span = nil
+        @original_record_error = nil
+        @hooks_installed = false
+      end
+    end
+  end
+end
+
+# RSpec integration
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.before(:each, :miniapm) do
+      MiniAPM::Testing.enable!
+    end
+
+    config.after(:each, :miniapm) do
+      MiniAPM::Testing.disable!
+    end
+  end
+end
+
+# Minitest integration
+if defined?(Minitest)
+  module MiniAPM
+    module Testing
+      module MinitestHooks
+        def before_setup
+          super
+          MiniAPM::Testing.enable! if self.class.miniapm_enabled?
+        end
+
+        def after_teardown
+          MiniAPM::Testing.disable! if self.class.miniapm_enabled?
+          super
+        end
+      end
+
+      module MinitestClassMethods
+        def miniapm_enabled?
+          @miniapm_enabled || false
+        end
+
+        def enable_miniapm!
+          @miniapm_enabled = true
+        end
+      end
+    end
+  end
+
+  Minitest::Test.prepend(MiniAPM::Testing::MinitestHooks)
+  Minitest::Test.extend(MiniAPM::Testing::MinitestClassMethods)
+end

data/lib/miniapm/trace.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module MiniAPM
+  class Trace
+    attr_reader :trace_id
+    attr_accessor :sampled
+
+    def initialize(trace_id: nil, sampled: nil)
+      @trace_id = trace_id || SecureRandom.hex(16)
+      @sampled = sampled.nil? ? should_sample? : sampled
+      @mutex = Mutex.new
+    end
+
+    def sampled?
+      @sampled
+    end
+
+    private
+
+    def should_sample?
+      rand < MiniAPM.configuration.sample_rate
+    end
+  end
+end

data/lib/miniapm/transport/batch_sender.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module MiniAPM
+  module Transport
+    class BatchSender
+      SHUTDOWN_TIMEOUT = 5 # seconds to wait for flush on shutdown
+      MAX_RETRY_ATTEMPTS = 3
+      BASE_RETRY_DELAY = 1.0 # seconds
+      MAX_CONCURRENT_SENDS = 4
+
+      # Circuit breaker settings
+      CIRCUIT_FAILURE_THRESHOLD = 5  # failures before opening circuit
+      CIRCUIT_RESET_TIMEOUT = 60     # seconds before trying again
+
+      class << self
+        def start!
+          @start_mutex ||= Mutex.new
+
+          @start_mutex.synchronize do
+            return if @started
+
+            @started = true
+            @shutdown = false
+
+            @queues = {
+              span: Queue.new,
+              error: Queue.new
+            }
+
+            @mutex = Mutex.new
+            @batches = { span: [], error: [] }
+            @last_flush = Time.now
+
+            # Stats for monitoring
+            reset_stats!
+
+            # Bounded thread pool for sending
+            @send_queue = Queue.new
+            @send_threads = MAX_CONCURRENT_SENDS.times.map do |i|
+              Thread.new { send_worker_loop(i) }
+            end
+
+            start_worker_thread!
+            setup_shutdown_hook!
+
+            MiniAPM.logger.debug { "MiniAPM BatchSender started" }
+          end
+        end
+
+        def stop!
+          @start_mutex ||= Mutex.new
+
+          @start_mutex.synchronize do
+            return unless @started
+
+            @shutdown = true
+
+            # Drain queues and flush remaining data
+            drain_queues_to_batches!
+            flush_all!
+
+            # Wait for worker thread
+            @worker_thread&.join(SHUTDOWN_TIMEOUT)
+
+            # Signal send threads to stop and wait
+            MAX_CONCURRENT_SENDS.times { @send_queue << :shutdown }
+            @send_threads&.each { |t| t.join(SHUTDOWN_TIMEOUT) }
+
+            @started = false
+
+            MiniAPM.logger.debug { "MiniAPM BatchSender stopped" }
+          end
+        end
+
+        def enqueue(type, item)
+          return unless @started
+
+          queue = @queues[type]
+          return unless queue
+
+          config = MiniAPM.configuration
+
+          # Drop if queue is full (backpressure)
+          if queue.size >= config.max_queue_size
+            increment_stat(:dropped, type)
+            MiniAPM.logger.warn { "MiniAPM: Queue full, dropping #{type}" }
+            return
+          end
+
+          queue << item
+          increment_stat(:enqueued, type)
+        end
+
+        def started?
+          @started || false
+        end
+
+        # Force flush all pending data (useful for testing)
+        def flush!
+          return unless @started
+
+          # First, drain queues into batches
+          drain_queues_to_batches!
+
+          # Then flush all batches
+          flush_all!
+
+          # Wait for send queue to drain
+          deadline = Time.now + 5 # 5 second timeout
+          while @send_queue&.size&.positive? && Time.now < deadline
+            sleep 0.1
+          end
+        end
+
+        # Get current stats
+        def stats
+          @mutex.synchronize { @stats.dup }
+        end
+
+        # Reset stats
+        def reset_stats!
+          @mutex.synchronize do
+            @stats = {
+              enqueued: { span: 0, error: 0 },
+              sent: { span: 0, error: 0 },
+              dropped: { span: 0, error: 0 },
+              failed: { span: 0, error: 0 },
+              retries: 0,
+              circuit_opened: 0
+            }
+            # Circuit breaker state
+            @circuit_failures = 0
+            @circuit_opened_at = nil
+          end
+        end
+
+        # Check if circuit breaker allows requests
+        def circuit_open?
+          @mutex.synchronize do
+            return false if @circuit_failures < CIRCUIT_FAILURE_THRESHOLD
+
+            # Check if we should try again (half-open state)
+            if @circuit_opened_at && (Time.now - @circuit_opened_at) >= CIRCUIT_RESET_TIMEOUT
+              MiniAPM.logger.info { "MiniAPM: Circuit breaker half-open, attempting request" }
+              return false
+            end
+
+            true
+          end
+        end
+
+        def record_circuit_success!
+          @mutex.synchronize do
+            @circuit_failures = 0
+            @circuit_opened_at = nil
+          end
+        end
+
+        def record_circuit_failure!
+          @mutex.synchronize do
+            @circuit_failures += 1
+            if @circuit_failures >= CIRCUIT_FAILURE_THRESHOLD && @circuit_opened_at.nil?
+              @circuit_opened_at = Time.now
+              @stats[:circuit_opened] += 1
+              MiniAPM.logger.warn { "MiniAPM: Circuit breaker opened after #{@circuit_failures} failures" }
+            end
+          end
+        end
+
+        private
+
+        def drain_queues_to_batches!
+          @queues.each do |type, queue|
+            @mutex.synchronize do
+              while !queue.empty?
+                begin
+                  item = queue.pop(true) # non-blocking
+                  @batches[type] << item
+                rescue ThreadError
+                  break
+                end
+              end
+            end
+          end
+        end
+
+        def increment_stat(stat, type = nil)
+          @mutex.synchronize do
+            if type
+              @stats[stat][type] += 1
+            else
+              @stats[stat] += 1
+            end
+          end
+        end
+
+        def start_worker_thread!
+          @worker_thread = Thread.new do
+            Thread.current.name = "miniapm-batcher"
+            Thread.current.report_on_exception = false
+
+            until @shutdown
+              begin
+                process_queues
+              rescue StandardError => e
+                MiniAPM.logger.error { "MiniAPM worker error: #{e.class}: #{e.message}" }
+              end
+
+              sleep 0.1 # Small sleep to prevent busy-waiting
+            end
+          end
+        end
+
+        def send_worker_loop(worker_id)
+          Thread.current.name = "miniapm-sender-#{worker_id}"
+          Thread.current.report_on_exception = false
+
+          loop do
+            work = @send_queue.pop
+            break if work == :shutdown
+
+            type, items = work
+            send_with_retry(type, items)
+          end
+        end
+
+        def process_queues
+          config = MiniAPM.configuration
+
+          @queues.each do |type, queue|
+            # Drain queue into batch
+            @mutex.synchronize do
+              while !queue.empty? && @batches[type].size < config.batch_size
+                begin
+                  item = queue.pop(true) # non-blocking
+                  @batches[type] << item
+                rescue ThreadError
+                  break
+                end
+              end
+            end
+
+            # Flush if batch is full or timer expired
+            flush_type!(type) if should_flush?(type)
+          end
+        end
+
+        def should_flush?(type)
+          @mutex.synchronize do
+            batch = @batches[type]
+            return false if batch.empty?
+
+            config = MiniAPM.configuration
+            batch.size >= config.batch_size ||
+              (Time.now - @last_flush) >= config.flush_interval
+          end
+        end
+
+        def flush_type!(type)
+          items = nil
+
+          @mutex.synchronize do
+            batch = @batches[type]
+            return if batch.empty?
+
+            items = batch.dup
+            batch.clear
+            @last_flush = Time.now
+          end
+
+          return unless items && !items.empty?
+
+          # Queue for sending (bounded by thread pool)
+          @send_queue << [type, items]
+        end
+
+        def flush_all!
+          @queues.each_key { |type| flush_type!(type) }
+        end
+
+        def send_with_retry(type, items)
+          # Check circuit breaker first
+          if circuit_open?
+            MiniAPM.logger.debug { "MiniAPM: Circuit open, dropping #{items.size} #{type}(s)" }
+            increment_stat(:dropped, type)
+            return false
+          end
+
+          attempts = 0
+
+          loop do
+            attempts += 1
+            result = send_batch(type, items)
+
+            if result[:success]
+              @mutex.synchronize { @stats[:sent][type] += items.size }
+              record_circuit_success!
+              return true
+            end
+
+            # Don't retry on client errors (4xx)
+            if result[:status] && result[:status] >= 400 && result[:status] < 500
+              MiniAPM.logger.warn { "MiniAPM: Client error #{result[:status]}, not retrying" }
+              increment_stat(:failed, type)
+              return false
+            end
+
+            # Check if we should retry
+            if attempts >= MAX_RETRY_ATTEMPTS
+              MiniAPM.logger.error { "MiniAPM: Failed to send #{type} after #{attempts} attempts" }
+              increment_stat(:failed, type)
+              record_circuit_failure!
+              return false
+            end
+
+            # Exponential backoff
+            delay = BASE_RETRY_DELAY * (2 ** (attempts - 1))
+            delay += rand * delay * 0.1 # Add jitter
+            increment_stat(:retries)
+            MiniAPM.logger.debug { "MiniAPM: Retrying #{type} in #{delay.round(2)}s (attempt #{attempts})" }
+            sleep delay
+          end
+        end
+
+        def send_batch(type, items)
+          case type
+          when :span
+            Exporters::OTLP.export(items)
+          when :error
+            Exporters::Errors.export_batch(items)
+          end
+        rescue StandardError => e
+          MiniAPM.logger.error { "MiniAPM send error: #{e.class}: #{e.message}" }
+          { success: false, error: e }
+        end
+
+        def setup_shutdown_hook!
+          at_exit { stop! }
+        end
+      end
+    end
+  end
+end

data/lib/miniapm/transport/http.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module MiniAPM
+  module Transport
+    class HTTP
+      DEFAULT_TIMEOUT = 10
+      DEFAULT_OPEN_TIMEOUT = 5
+
+      class << self
+        def post(url, payload, headers: {})
+          uri = URI.parse(url)
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = DEFAULT_OPEN_TIMEOUT
+          http.read_timeout = DEFAULT_TIMEOUT
+          http.write_timeout = DEFAULT_TIMEOUT if http.respond_to?(:write_timeout=)
+
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request["Content-Type"] = "application/json"
+          request["User-Agent"] = "miniapm-ruby/#{MiniAPM::VERSION}"
+
+          headers.each { |key, value| request[key] = value }
+
+          request.body = payload.is_a?(String) ? payload : JSON.generate(payload)
+
+          response = http.request(request)
+
+          {
+            status: response.code.to_i,
+            body: response.body,
+            success: response.is_a?(Net::HTTPSuccess)
+          }
+        rescue StandardError => e
+          MiniAPM.logger.warn { "MiniAPM HTTP error: #{e.class}: #{e.message}" }
+          { status: 0, body: e.message, success: false, error: e }
+        end
+      end
+    end
+  end
+end

data/lib/miniapm/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MiniAPM
+  VERSION = "1.0.0"
+end