hawk-ruby 0.1.0

data/lib/hawk/breadcrumbs/net_http.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Hawk
+  module Breadcrumbs
+    # Guard Net::HTTP's internal recursion while retaining the response block API.
+    module NetHTTP
+      def self.install
+        ::Net::HTTP.prepend(Methods) unless ::Net::HTTP.ancestors.include?(Methods)
+      end
+
+      def self.record(client, request, host, status, started)
+        path = request.path.split("?", 2).first.to_s
+        path = URI.parse(path).path if path.start_with?("http://", "https://")
+        data = { "method" => request.method, "host" => host, "path" => path, "status" => status,
+                 "duration_ms" => (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000 }
+        client.add_breadcrumb(category: "http", message: "HTTP request", data: data)
+      rescue StandardError
+        nil
+      end
+
+      def self.connection_failed(client, host, started)
+        data = { "method" => "CONNECT", "host" => host,
+                 "duration_ms" => (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000 }
+        client.add_breadcrumb(category: "http", message: "HTTP connection failed", data: data)
+      rescue StandardError
+        nil
+      end
+
+      # The ensure path records failed operations without replacing their errors.
+      module Methods
+        def start(&block)
+          # @type var client: Hawk::Client?
+          client = Hawk::Breadcrumbs.client(:http)
+          # @type var started: Float
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          yielded = false
+          return super unless block && client
+
+          super do |http|
+            yielded = true
+            block.call(http)
+          end
+        rescue StandardError
+          NetHTTP.connection_failed(client, address, started) if client && !yielded
+          raise
+        end
+
+        def request(request, body = nil, &)
+          # @type var client: Hawk::Client?
+          client = Hawk::Breadcrumbs.client(:http)
+          return super unless client
+
+          # @type var started: Float?
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          # @type var response: ::Net::HTTPResponse?
+          response = Hawk::Breadcrumbs.guard(:http) { super }
+        ensure
+          NetHTTP.record(client, request, address, response&.code, started) if client && started
+        end
+      end
+    end
+  end
+end

data/lib/hawk/breadcrumbs/rails.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hawk
+  module Breadcrumbs
+    # Notification payloads are intentionally excluded from automatic breadcrumbs.
+    module Rails
+      EVENTS = /\A(?:
+        sql\.active_record|process_action\.action_controller|deliver\.action_mailer|
+        (?:enqueue|enqueue_at|enqueue_retry|perform|perform_start|retry_stopped|discard)\.active_job
+      )\z/x
+
+      def self.install
+        return if @installed
+
+        ActiveSupport::Notifications.monotonic_subscribe(EVENTS) do |name, started, finished, _id, _payload|
+          client = Hawk::Breadcrumbs.client(:rails)
+          client&.add_breadcrumb(category: "rails", message: name,
+                                 data: { "duration_ms" => (finished - started) * 1000 })
+        end
+        @installed = true
+      end
+    end
+  end
+end

data/lib/hawk/breadcrumbs.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Breadcrumb buffers belong to scopes; instrumentation guards belong to fibers.
+  module Breadcrumbs
+    def self.install(configuration)
+      if configuration.breadcrumbs_logger || configuration.logger_error_level
+        require_relative "breadcrumbs/logger"
+        Logger.install
+      end
+      return unless configuration.breadcrumbs_http
+
+      require_relative "breadcrumbs/net_http"
+      NetHTTP.install
+    end
+
+    def self.guard(category)
+      key = "hawk.instrumentation.#{category}"
+      # @type var previous: top
+      previous = Thread.current[key]
+      Thread.current[key] = true
+      yield
+    ensure
+      Thread.current[key] = previous
+    end
+
+    def self.suppressed?(category)
+      # @type var value: top
+      value = Thread.current["hawk.instrumentation.#{category}"]
+      case value
+      when true then true
+      else false
+      end
+    end
+
+    def self.client(category)
+      client = Hawk.client
+      return unless client&.enabled?
+      return if suppressed?(:sdk) || suppressed?(category)
+
+      client if enabled?(client.configuration, category)
+    end
+
+    def self.enabled?(config, category)
+      case category
+      when :logger then config.breadcrumbs_logger || !config.logger_error_level.nil?
+      when :http then config.breadcrumbs_http
+      when :rails then config.breadcrumbs_rails && config.integration_enabled?(:rails)
+      else false
+      end
+    end
+
+    def self.add(client, raw)
+      return unless client.enabled?
+
+      entry = filtered(client.configuration, raw)
+      return unless entry
+
+      buffer = client.current_scope.breadcrumbs
+      buffer << entry
+      buffer.shift while buffer.size > 50
+      nil
+    rescue StandardError
+      client.diagnostics.increment(:filtered)
+      nil
+    end
+
+    def self.filtered(configuration, raw)
+      entry = JSONValue.object(raw).merge("timestamp" => (Time.now.to_f * 1000).to_i)
+      entry = JSONValue.object(Filter.new(configuration).call(entry))
+      entry = framework_filtered(configuration, entry)
+      return unless entry
+
+      hook = configuration.before_breadcrumb
+      return entry unless hook
+
+      case result = Hook.call { hook.call(entry) }
+      when Hash then JSONValue.object(result)
+      end
+    end
+
+    def self.framework_filtered(configuration, entry)
+      filter = configuration.framework_filter
+      return entry unless filter
+
+      case result = Hook.call { filter.call(entry) }
+      when Hash then JSONValue.object(result)
+      end
+    end
+    private_class_method :filtered, :enabled?, :framework_filtered
+  end
+end

data/lib/hawk/client.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Owns policy and scope state; delivery receives detached JSON strings.
+  class Client
+    attr_reader :configuration, :diagnostics
+
+    def self.build(configuration)
+      diagnostics = Diagnostics.new(configuration.diagnostic_callback, logger: configuration.diagnostic_logger)
+      delivery = Delivery.new(configuration, transport: Transport.new(configuration), diagnostics: diagnostics)
+      new(configuration, delivery: delivery, diagnostics: diagnostics)
+    end
+
+    def initialize(configuration, delivery:, diagnostics: nil)
+      configuration.validate!
+      configuration.release = Release.detect(configuration)
+      @configuration = configuration
+      @delivery = delivery
+      @diagnostics = diagnostics || Diagnostics.new(configuration.diagnostic_callback,
+                                                    logger: configuration.diagnostic_logger)
+      @store = ScopeStore.new(configuration, SecureRandom.uuid)
+      @closed = false
+    end
+
+    def current_scope
+      @store.current
+    end
+
+    def enabled?
+      !@closed && @configuration.enabled?
+    end
+
+    def set_context(context)
+      current_scope.set_context(context)
+    end
+
+    def set_user(user)
+      current_scope.set_user(user)
+    end
+
+    def with_scope
+      previous = current_scope
+      @store.replace(previous.copy)
+      begin
+        yield current_scope
+      ensure
+        @store.replace(previous)
+      end
+    end
+
+    def using_scope(scope)
+      previous = current_scope
+      @store.replace(scope.copy)
+      begin
+        yield
+      ensure
+        @store.replace(previous)
+      end
+    end
+
+    def with_boundary(kind:, metadata:, inherit: false)
+      previous = current_scope
+      @store.clear_escape unless previous.boundary
+      scope = boundary_scope(previous, kind, metadata, inherit)
+      @store.replace(scope)
+      begin
+        yield
+      ensure
+        @store.replace(previous)
+      end
+    end
+
+    def capture_exception(exception, context: {}, user: nil, level: :error)
+      identifier = dispatch(exception: exception, context: context, user: user, level: level)
+      current_scope.ledger.accept(exception, evict: !current_scope.boundary) if identifier
+      identifier
+    end
+
+    def capture_message(message, context: {}, user: nil, level: :info)
+      dispatch(message: message, context: context, user: user, level: level)
+    end
+
+    def add_breadcrumb(entry)
+      Breadcrumbs.add(self, entry)
+    end
+
+    def capture(&)
+      Boundary.run(self, kind: :capture, metadata: {}, inherit: true, &)
+    end
+
+    def report(exception, mechanism:, context: {}, level: :error, handled: false)
+      return if normal_termination?(exception)
+      return if mechanism == "request" && expected_request_error?(exception)
+
+      case current_scope.ledger.accept(exception, evict: !current_scope.boundary)
+      when :duplicate then return nil
+      when :overflow
+        @diagnostics.increment(:duplicate_overflow)
+        return nil
+      end
+      dispatch(exception: exception, context: context, level: level,
+               addons: { "mechanism" => mechanism, "handled" => handled })
+    end
+
+    def remember_escape(exception)
+      @store.remember_escape(exception)
+    end
+
+    def consume_escape(exception)
+      @store.consume_escape(exception)
+    end
+
+    def flush(timeout: @configuration.flush_timeout)
+      @delivery.flush(timeout: timeout)
+    rescue StandardError
+      false
+    end
+
+    def close(timeout: @configuration.flush_timeout)
+      @closed = true
+      @store.clear
+      @delivery.close(timeout: timeout)
+    rescue StandardError
+      false
+    end
+
+    private
+
+    def boundary_scope(previous, kind, metadata, inherit)
+      scope = inherit ? previous.copy : Scope.new(context: @configuration.context, user: @configuration.user)
+      scope.ledger = previous.boundary ? previous.ledger : Scope::Ledger.new
+      scope.boundary = true
+      scope.addons = (inherit ? previous.addons : scope.addons).merge(metadata).merge("boundary" => kind.to_s)
+      scope
+    end
+
+    def dispatch(exception: nil, message: nil, context: {}, user: nil, level: :error, addons: {})
+      return unless eligible?(exception)
+
+      identifier = SecureRandom.uuid
+      encoded = Event.new(configuration: @configuration, id: identifier, exception: exception, message: message,
+                          level: level, **current_scope.event_data(context, user, @configuration.user, addons)).encode
+      unless encoded
+        @diagnostics.increment(:filtered)
+        return nil
+      end
+      identifier if @delivery.enqueue(identifier, encoded.freeze)
+    rescue StandardError
+      @diagnostics.increment(:failed)
+      nil
+    end
+
+    def eligible?(exception)
+      return false unless enabled?
+      return false unless rand < @configuration.sample_rate
+      return true unless exception
+
+      names = exception.class.ancestors.filter_map(&:name)
+      @configuration.ignored_exceptions.none? { |name| names.include?(name) }
+    end
+
+    def normal_termination?(exception)
+      case exception
+      when SystemExit, SignalException then true
+      else false
+      end
+    end
+
+    def expected_request_error?(exception)
+      expected = %w[ActionController::RoutingError AbstractController::ActionNotFound
+                    ActionController::UnknownAction ActiveRecord::RecordNotFound]
+      exception.class.ancestors.any? { |ancestor| expected.include?(ancestor.name) }
+    end
+  end
+end

data/lib/hawk/configuration.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Settings are validated before clients install handlers or start delivery.
+  class Configuration
+    attr_accessor :token, :endpoint, :environment, :enabled_environments, :release, :detect_release,
+                  :sample_rate, :delivery_mode, :queue_capacity, :source_roots, :send_source,
+                  :connect_timeout, :read_timeout, :write_timeout, :flush_timeout, :limit_cooldown,
+                  :context, :user, :ignored_exceptions, :filter_parameters, :integrations, :global_errors,
+                  :before_send, :before_breadcrumb, :framework_filter, :diagnostic_callback, :diagnostic_logger,
+                  :propagate_job_context,
+                  :include_request_body, :include_job_arguments, :include_headers, :include_cookies,
+                  :breadcrumbs_logger, :breadcrumbs_http, :breadcrumbs_rails, :logger_error_level
+
+    def initialize
+      initialize_identity
+      initialize_delivery
+      initialize_privacy
+      initialize_hooks
+    end
+
+    def validate!
+      value = @token
+      Token.decode(value) if value && !value.empty?
+      collector_uri if enabled?
+      validate_delivery
+      validate_callbacks
+      unless valid_number?(@sample_rate) && @sample_rate <= 1
+        raise ConfigurationError, "sample_rate must be finite and between 0 and 1"
+      end
+
+      nil
+    end
+
+    def enabled?
+      value = @token
+      environments = @enabled_environments
+      !!(value && !value.empty? && (environments.nil? || environments.include?(@environment)))
+    end
+
+    def collector_uri
+      override = @endpoint
+      return Token.decode(@token || "").endpoint unless override
+
+      uri = URI.parse(override)
+      raise ConfigurationError, "Collector endpoint must use HTTPS or loopback HTTP" unless allowed_uri?(uri)
+
+      uri
+    rescue URI::InvalidURIError
+      raise ConfigurationError, "Invalid collector endpoint"
+    end
+
+    def integration_enabled?(name)
+      @integrations.fetch(name, true)
+    end
+
+    private
+
+    def allowed_uri?(uri)
+      return false unless uri.host && uri.userinfo.nil? && uri.fragment.nil?
+      return true if uri.is_a?(URI::HTTPS)
+
+      uri.is_a?(URI::HTTP) && ["127.0.0.1", "::1"].include?(uri.hostname)
+    end
+
+    def initialize_identity
+      @token = ENV.fetch("HAWK_TOKEN", nil)
+      @endpoint = nil
+      @environment = ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+      @enabled_environments = nil
+      @release = ENV["HAWK_RELEASE"] || ENV.fetch("REVISION", nil)
+      @detect_release = false
+      @source_roots = [Dir.pwd]
+      @send_source = true
+    end
+
+    def initialize_delivery
+      @sample_rate = 1.0
+      @delivery_mode = :async
+      @queue_capacity = 100
+      @connect_timeout = 1.0
+      @read_timeout = 2.0
+      @write_timeout = 2.0
+      @flush_timeout = 5.0
+      @limit_cooldown = 60.0
+    end
+
+    def initialize_privacy
+      @context = {}
+      @user = nil
+      @ignored_exceptions = []
+      @filter_parameters = []
+      @include_request_body = false
+      @include_job_arguments = false
+      @include_headers = false
+      @include_cookies = false
+    end
+
+    def initialize_hooks
+      @before_send = nil
+      @before_breadcrumb = nil
+      @framework_filter = nil
+      @diagnostic_callback = nil
+      @diagnostic_logger = nil
+      @propagate_job_context = true
+      @integrations = {}
+      @global_errors = true
+      @breadcrumbs_logger = false
+      @breadcrumbs_http = false
+      @breadcrumbs_rails = true
+      @logger_error_level = nil
+    end
+
+    def validate_delivery
+      unless @queue_capacity.is_a?(Integer) && @queue_capacity.positive?
+        raise ConfigurationError, "queue_capacity must be a positive integer"
+      end
+      raise ConfigurationError, "delivery_mode must be async or sync" unless %i[async sync].include?(@delivery_mode)
+
+      [@connect_timeout, @read_timeout, @write_timeout, @flush_timeout, @limit_cooldown].each do |value|
+        raise ConfigurationError, "Timeouts must be finite and nonnegative" unless valid_number?(value)
+      end
+    end
+
+    def valid_number?(value)
+      case value
+      when Float, Integer then value.finite? && value >= 0
+      else false
+      end
+    end
+
+    def validate_callbacks
+      [@before_send, @before_breadcrumb, @framework_filter, @diagnostic_callback].each do |callback|
+        raise ConfigurationError, "Hooks must be callable" unless callback.nil? || callback.respond_to?(:call)
+      end
+    end
+  end
+end

data/lib/hawk/delayed_job.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../hawk"
+require "delayed_job"
+require "delayed/plugin"
+
+module Hawk
+  # Native lifecycle callbacks retain retries, payloads, and failure storage.
+  module DelayedJob
+    def self.install
+      return unless supported_version?
+      return if ::Delayed::Worker.plugins.include?(Plugin)
+
+      # Initialize existing callbacks before attaching the new plugin once.
+      ::Delayed::Worker.lifecycle
+      ::Delayed::Worker.plugins << Plugin
+      Plugin.new
+    end
+
+    def self.supported_version?
+      specification = Gem.loaded_specs.fetch("delayed_job")
+      specification.version.to_s.start_with?("4.")
+    end
+
+    def self.client
+      client = Hawk.client
+      client if client&.enabled? && client.configuration.integration_enabled?(:delayed_job)
+    end
+
+    def self.run(job, &)
+      client = self.client
+      return yield unless client
+
+      metadata = { "job" => { "backend" => "delayed_job", "id" => job.id,
+                              "queue" => job.queue, "attempts" => job.attempts } }
+      Boundary.run(client, kind: :delayed_job, metadata: metadata, &)
+    end
+
+    def self.report(job)
+      client = self.client
+      error = job.error
+      client.report(error, mechanism: "delayed_job.backend") if client && error
+      nil
+    end
+
+    AROUND = lambda do |_worker, job, &block|
+      DelayedJob.run(job, &block) if block
+    end
+
+    # Worker rebuilds this callback set when a new worker is constructed.
+    class Plugin < ::Delayed::Plugin
+      callbacks do |lifecycle|
+        lifecycle.around(:perform, &AROUND)
+        lifecycle.after(:error) { |_worker, job| DelayedJob.report(job) }
+        lifecycle.after(:failure) { |_worker, job| DelayedJob.report(job) }
+      end
+    end
+  end
+end
+
+Hawk::DelayedJob.install

data/lib/hawk/delivery.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Queue capacity never blocks capture; flush and close have explicit deadlines.
+  class Delivery
+    def initialize(configuration, transport:, diagnostics:)
+      @configuration = configuration
+      @transport = transport
+      @diagnostics = diagnostics
+      @closed = false
+      reset
+    end
+
+    def enqueue(_identifier, encoded)
+      reset if @pid != Process.pid
+      return false unless @transport.available?
+
+      snapshot = encoded.dup.freeze
+      accepted = @mutex.synchronize { accept(snapshot) }
+      unless accepted
+        @diagnostics.increment(:overflow) unless @closed
+        return false
+      end
+      deliver(snapshot) if @configuration.delivery_mode == :sync
+      true
+    end
+
+    def flush(timeout:)
+      reset if @pid != Process.pid
+      return false unless timeout.finite? && timeout >= 0
+      return false if Thread.current.equal?(@worker)
+
+      deadline = monotonic + timeout
+      @mutex.synchronize do
+        while @pending.positive?
+          remaining = deadline - monotonic
+          return false unless remaining.positive?
+
+          @condition.wait(@mutex, remaining)
+        end
+      end
+      true
+    end
+
+    def close(timeout:)
+      reset if @pid != Process.pid
+      deadline = monotonic + timeout
+      @mutex.synchronize do
+        @closed = true
+        @condition.broadcast
+      end
+      return false unless flush(timeout: timeout)
+
+      worker = @worker
+      worker.nil? || !worker.join([deadline - monotonic, 0.0].max).nil?
+    end
+
+    private
+
+    def reset
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @queue = []
+      @pending = 0
+      @worker = nil
+      @pid = Process.pid
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def accept(encoded)
+      return false if @closed
+      return false if @queue.size >= @configuration.queue_capacity
+
+      @pending += 1
+      if @configuration.delivery_mode == :async
+        @queue << encoded
+        worker = @worker || Thread.new { work }
+        worker.report_on_exception = false
+        @worker = worker
+        @condition.signal
+      end
+      true
+    end
+
+    def next_event
+      @mutex.synchronize do
+        @condition.wait(@mutex) while @queue.empty? && !@closed
+        @queue.shift
+      end
+    end
+
+    def work
+      while (encoded = next_event)
+        deliver(encoded)
+      end
+    end
+
+    def deliver(encoded)
+      result = @transport.send(encoded)
+      @diagnostics.increment(result == :accepted ? :sent : :failed)
+    rescue StandardError
+      @diagnostics.increment(:failed)
+    ensure
+      @mutex.synchronize do
+        @pending -= 1
+        @condition.broadcast
+      end
+    end
+  end
+end