errorgap 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9fc092f673d279e6295144e0bcd302fabf729ff193b00b14ed651706f9cbb388
+  data.tar.gz: e89ffdc6f5eaab044376725d9baa3b8584a428d7f4799a89f5c22c13b9a96b30
+SHA512:
+  metadata.gz: b93c2e7bbd4c4b29364a98db702c7463ac21906d73a5ace7fd779fecc209187284bc666badd6a5fe70854ae4a8f3367bbf73b8b49d0ac9e9673248e5c86ec83a
+  data.tar.gz: c5563c43afef3637222dc69b82388bd5cb42fb44daa5494c83a79d5c053da778c1fa15dc85915a6eea0ef6e7b079a002c8b1e3a6b7a5be447c2e37be5f2e7f58

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Errorgap
+
+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,65 @@
+# Errorgap Ruby
+
+Ruby notifier for Errorgap. It captures exceptions, normalizes backtraces, and sends notices to a Errorgap server.
+
+## Installation
+
+Add the gem to your application:
+
+```ruby
+gem "errorgap"
+```
+
+Then install:
+
+```sh
+bundle install
+```
+
+## Configuration
+
+```ruby
+require "errorgap"
+
+Errorgap.configure do |config|
+  config.endpoint = ENV.fetch("ERRORGAP_ENDPOINT", "http://127.0.0.1:3030")
+  config.project_slug = ENV["ERRORGAP_PROJECT_SLUG"]
+  config.project_id = ENV["ERRORGAP_PROJECT_ID"]
+  config.api_key = ENV["ERRORGAP_API_KEY"]
+  config.environment = ENV.fetch("RAILS_ENV", ENV.fetch("RACK_ENV", "development"))
+end
+```
+
+## Manual Notification
+
+```ruby
+begin
+  risky_operation
+rescue => error
+  Errorgap.notify(error, context: { component: "billing" })
+  raise
+end
+```
+
+## Rack
+
+```ruby
+use Errorgap::RackMiddleware
+```
+
+## Rails
+
+In Rails, requiring the gem installs the Rack middleware automatically through the Railtie.
+
+Generate an initializer:
+
+```sh
+rails generate errorgap:install
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+```

data/exe/errorgap

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "errorgap"
+
+command = ARGV.shift
+
+case command
+when "test"
+  Errorgap.notify(RuntimeError.new("Errorgap test exception"), sync: true)
+  puts "Sent test exception to Errorgap."
+else
+  warn "Usage: errorgap test"
+  exit 1
+end

data/lib/errorgap/configuration.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Errorgap
+  class Configuration
+    attr_accessor :endpoint,
+                  :project_id,
+                  :project_slug,
+                  :api_key,
+                  :environment,
+                  :root_directory,
+                  :async,
+                  :logger,
+                  :filter_keys,
+                  :apm_enabled,
+                  :apm_sample_rate
+
+    def initialize
+      @endpoint = ENV.fetch("ERRORGAP_ENDPOINT", "http://127.0.0.1:3030")
+      @project_id = ENV["ERRORGAP_PROJECT_ID"]
+      @project_slug = ENV["ERRORGAP_PROJECT_SLUG"]
+      @api_key = ENV["ERRORGAP_API_KEY"]
+      @environment = ENV.fetch("RAILS_ENV", ENV.fetch("RACK_ENV", "development"))
+      @root_directory = Dir.pwd
+      @async = true
+      @filter_keys = %w[password password_confirmation token secret api_key authorization cookie]
+      @apm_enabled = false
+      @apm_sample_rate = 1.0
+    end
+
+    def validate!
+      raise ArgumentError, "Errorgap project_slug is required" if blank?(project_slug)
+
+      true
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/errorgap/notice.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Errorgap
+  class Notice
+    def self.from_exception(error, configuration:, context: {}, environment: {}, session: {}, params: {})
+      new(
+        error: error,
+        configuration: configuration,
+        context: context,
+        environment: environment,
+        session: session,
+        params: params
+      )
+    end
+
+    def initialize(error:, configuration:, context:, environment:, session:, params:)
+      @error = error
+      @configuration = configuration
+      @context = context || {}
+      @environment = environment || {}
+      @session = session || {}
+      @params = params || {}
+    end
+
+    def to_h
+      {
+        project_id: @configuration.project_id,
+        received_at: Time.now.utc.iso8601,
+        errors: [
+          {
+            type: @error.class.name,
+            message: @error.message.to_s,
+            backtrace: backtrace_frames
+          }
+        ],
+        context: default_context.merge(stringify_hash(@context)),
+        environment: stringify_hash(@environment),
+        session: stringify_hash(@session),
+        params: filter_hash(@params)
+      }
+    end
+
+    private
+
+    def default_context
+      {
+        notifier: "errorgap-ruby",
+        notifier_version: Errorgap::VERSION,
+        environment: @configuration.environment,
+        root_directory: @configuration.root_directory
+      }
+    end
+
+    def backtrace_frames
+      Array(@error.backtrace).map.with_index do |line, index|
+        file, line_number, function = parse_backtrace_line(line)
+        {
+          file: relative_file(file),
+          line: line_number,
+          function: function,
+          in_app: in_app?(file),
+          index: index
+        }.compact
+      end
+    end
+
+    def parse_backtrace_line(line)
+      match = line.match(/\A(.+?):(\d+)(?::in `(.*)')?\z/)
+      return [line, nil, nil] unless match
+
+      [match[1], match[2].to_i, match[3]]
+    end
+
+    def relative_file(file)
+      root = @configuration.root_directory.to_s
+      return file if root.empty?
+
+      file.to_s.sub(%r{\A#{Regexp.escape(root)}/?}, "")
+    end
+
+    def in_app?(file)
+      root = @configuration.root_directory.to_s
+      !root.empty? && file.to_s.start_with?(root)
+    end
+
+    def filter_hash(hash)
+      stringify_hash(hash).each_with_object({}) do |(key, value), filtered|
+        filtered[key] = sensitive?(key) ? "[FILTERED]" : value
+      end
+    end
+
+    def sensitive?(key)
+      @configuration.filter_keys.any? { |filter| key.to_s.downcase.include?(filter.downcase) }
+    end
+
+    def stringify_hash(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        result[key.to_s] = value.is_a?(Hash) ? stringify_hash(value) : value
+      end
+    end
+  end
+end

data/lib/errorgap/notifier.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Errorgap
+  class Notifier
+    Response = Struct.new(:status, :body, :error, keyword_init: true) do
+      def success?
+        error.nil? && status.to_i.between?(200, 299)
+      end
+    end
+
+    def initialize(configuration)
+      configure(configuration)
+    end
+
+    def configure(configuration)
+      @configuration = configuration
+    end
+
+    def notify(error, context: {}, environment: {}, session: {}, params: {}, sync: false)
+      @configuration.validate!
+      notice = Notice.from_exception(
+        error,
+        configuration: @configuration,
+        context: context,
+        environment: environment,
+        session: session,
+        params: params
+      )
+
+      if sync || !@configuration.async
+        deliver(notice)
+      else
+        Thread.new { deliver(notice) }
+        Response.new(status: 202, body: "queued")
+      end
+    rescue StandardError => exception
+      log(exception)
+      Response.new(error: exception)
+    end
+
+    def deliver(notice)
+      uri = URI.join(@configuration.endpoint.end_with?("/") ? @configuration.endpoint : "#{@configuration.endpoint}/", "api/projects/#{@configuration.project_slug}/notices")
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request["User-Agent"] = "errorgap-ruby/#{Errorgap::VERSION}"
+      request["X-Errorgap-Project-Key"] = @configuration.api_key if present?(@configuration.api_key)
+      request.body = JSON.generate(notice.to_h)
+
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
+        http.request(request)
+      end
+      Response.new(status: response.code.to_i, body: response.body)
+    rescue StandardError => exception
+      log(exception)
+      Response.new(error: exception)
+    end
+
+    private
+
+    def log(exception)
+      @configuration.logger&.warn("[errorgap] #{exception.class}: #{exception.message}")
+    end
+
+    def present?(value)
+      !value.nil? && !value.to_s.empty?
+    end
+  end
+end

data/lib/errorgap/rack_middleware.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Errorgap
+  class RackMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      SpanCollector.start if apm_enabled?
+
+      status, headers, body = @app.call(env)
+      [status, headers, body]
+    rescue Exception => exception # rubocop:disable Lint/RescueException
+      notify_once(env, exception)
+      raise
+    ensure
+      if apm_enabled?
+        elapsed_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000.0
+        record_transaction(env, status || 500, elapsed_ms)
+      end
+    end
+
+    private
+
+    def apm_enabled?
+      Errorgap.configuration.apm_enabled
+    end
+
+    def record_transaction(env, status_code, elapsed_ms)
+      spans = SpanCollector.flush
+      txn = Transaction.new(
+        kind: "web",
+        method: env["REQUEST_METHOD"],
+        path: route_pattern(env),
+        path_raw: env["PATH_INFO"],
+        status_code: status_code,
+        duration_ms: elapsed_ms.round(2),
+        environment: Errorgap.configuration.environment,
+        occurred_at: Time.now,
+        spans: spans
+      )
+      Errorgap.transacter.deliver_async(txn)
+    rescue StandardError => exception
+      Errorgap.configuration.logger&.warn("[errorgap] APM record error: #{exception.message}")
+    end
+
+    def route_pattern(env)
+      # Rails: use controller#action as the normalised route pattern
+      if (params = env["action_dispatch.request.path_parameters"])
+        controller = params[:controller]
+        action = params[:action]
+        return "#{controller}##{action}" if controller && action
+      end
+
+      # Sinatra: env['sinatra.route'] is "GET /path/:id"
+      if (sinatra_route = env["sinatra.route"])
+        return sinatra_route.split(" ", 2).last
+      end
+
+      # Plain Rack fallback
+      env["PATH_INFO"]
+    end
+
+    def notify_once(env, exception)
+      notified = env["errorgap.notified_exception_ids"] ||= {}
+      return if notified[exception.object_id]
+
+      notified[exception.object_id] = true
+      Errorgap.notify(
+        exception,
+        context: rack_context(env),
+        environment: rack_environment(env),
+        session: rack_session(env),
+        params: rack_params(env),
+        sync: true
+      )
+    end
+
+    def rack_context(env)
+      {
+        url: "#{env['rack.url_scheme']}://#{env['HTTP_HOST']}#{env['PATH_INFO']}",
+        component: env["SCRIPT_NAME"],
+        action: env["REQUEST_METHOD"]
+      }
+    end
+
+    def rack_environment(env)
+      {
+        method: env["REQUEST_METHOD"],
+        path: env["PATH_INFO"],
+        query_string: env["QUERY_STRING"],
+        user_agent: env["HTTP_USER_AGENT"],
+        remote_addr: env["REMOTE_ADDR"]
+      }
+    end
+
+    def rack_session(env)
+      session = env["rack.session"]
+      session.respond_to?(:to_hash) ? session.to_hash : {}
+    end
+
+    def rack_params(env)
+      request = defined?(Rack::Request) ? Rack::Request.new(env) : nil
+      request ? request.params : {}
+    rescue StandardError
+      {}
+    end
+  end
+end

data/lib/errorgap/rails/railtie.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Errorgap
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer "errorgap.configure_rails" do |app|
+        Errorgap.configure do |config|
+          config.root_directory = app.root.to_s
+          config.environment = ::Rails.env.to_s
+          config.logger = ::Rails.logger
+        end
+      end
+
+      initializer "errorgap.insert_middleware" do |app|
+        app.config.middleware.use Errorgap::RackMiddleware
+      end
+
+      initializer "errorgap.install_span_collector" do
+        SpanCollector.install if Errorgap.configuration.apm_enabled
+      end
+
+      generators do
+        require "generators/errorgap/install_generator"
+      end
+    end
+  end
+end

data/lib/errorgap/span_collector.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Errorgap
+  class SpanCollector
+    THREAD_KEY = :errorgap_spans
+
+    # Quoted strings and standalone numeric literals → ?
+    NORMALIZE_PATTERN = /
+      '(?:[^'\\]|\\.)*'   # single-quoted string literals
+      |
+      \b\d+(?:\.\d+)?\b   # integer and float literals
+    /x
+
+    SKIP_NAMES = %w[SCHEMA EXPLAIN CACHE].freeze
+
+    class << self
+      # Call once at boot (from Railtie) when APM is enabled.
+      def install
+        return unless defined?(ActiveSupport::Notifications)
+
+        ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
+          next unless Thread.current[THREAD_KEY]
+          next if SKIP_NAMES.any? { |n| payload[:name]&.start_with?(n) }
+          next if payload[:cached]
+
+          duration_ms = payload[:duration] || 0.0
+          sql = normalize_sql(payload[:sql].to_s)
+
+          store << Span.new(kind: "db", sql: sql, duration_ms: duration_ms.round(3))
+        end
+      end
+
+      def start
+        Thread.current[THREAD_KEY] = []
+      end
+
+      def flush
+        spans = Thread.current[THREAD_KEY] || []
+        Thread.current[THREAD_KEY] = nil
+        spans
+      end
+
+      def store
+        Thread.current[THREAD_KEY] ||= []
+      end
+
+      def normalize_sql(sql)
+        sql.gsub(NORMALIZE_PATTERN, "?").gsub(/\s+/, " ").strip
+      end
+    end
+  end
+end

data/lib/errorgap/transacter.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Errorgap
+  class Transacter
+    def initialize(configuration)
+      configure(configuration)
+    end
+
+    def configure(configuration)
+      @configuration = configuration
+    end
+
+    def deliver_async(transaction)
+      return unless should_sample?
+
+      Thread.new { deliver(transaction) }
+    end
+
+    def deliver(transaction)
+      uri = URI.join(
+        @configuration.endpoint.end_with?("/") ? @configuration.endpoint : "#{@configuration.endpoint}/",
+        "api/projects/#{@configuration.project_slug}/transactions"
+      )
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request["User-Agent"] = "errorgap-ruby/#{Errorgap::VERSION}"
+      request["X-Errorgap-Project-Key"] = @configuration.api_key if present?(@configuration.api_key)
+      request.body = JSON.generate(transaction.to_h)
+
+      Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
+        http.request(request)
+      end
+    rescue StandardError => exception
+      @configuration.logger&.warn("[errorgap] APM delivery error: #{exception.class}: #{exception.message}")
+    end
+
+    private
+
+    def should_sample?
+      rate = @configuration.apm_sample_rate.to_f
+      return true if rate >= 1.0
+      return false if rate <= 0.0
+
+      rand < rate
+    end
+
+    def present?(value)
+      !value.nil? && !value.to_s.empty?
+    end
+  end
+end

data/lib/errorgap/transaction.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Errorgap
+  Span = Struct.new(:kind, :sql, :file, :line, :fn_name, :duration_ms, keyword_init: true) do
+    def to_h
+      {
+        kind: kind,
+        sql: sql,
+        file: file,
+        line: line,
+        fn_name: fn_name,
+        duration_ms: duration_ms
+      }.compact
+    end
+  end
+
+  Transaction = Struct.new(
+    :kind, :method, :path, :path_raw, :status_code,
+    :duration_ms, :environment, :occurred_at, :spans,
+    :job_class, :queue,
+    keyword_init: true
+  ) do
+    def to_h
+      {
+        kind: kind,
+        method: method,
+        path: path,
+        path_raw: path_raw,
+        status_code: status_code,
+        duration_ms: duration_ms,
+        environment: environment,
+        occurred_at: occurred_at&.utc&.iso8601(3),
+        spans: Array(spans).map(&:to_h),
+        job_class: job_class,
+        queue: queue
+      }.compact
+    end
+  end
+end

data/lib/errorgap/version.rb

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

data/lib/errorgap.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "errorgap/configuration"
+require_relative "errorgap/notifier"
+require_relative "errorgap/notice"
+require_relative "errorgap/transaction"
+require_relative "errorgap/span_collector"
+require_relative "errorgap/transacter"
+require_relative "errorgap/rack_middleware"
+require_relative "errorgap/version"
+
+module Errorgap
+  class << self
+    def configure
+      yield(configuration)
+      notifier.configure(configuration)
+      transacter.configure(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def notifier
+      @notifier ||= Notifier.new(configuration)
+    end
+
+    def transacter
+      @transacter ||= Transacter.new(configuration)
+    end
+
+    def notify(error, context: {}, environment: {}, session: {}, params: {}, sync: false)
+      notifier.notify(
+        error,
+        context: context,
+        environment: environment,
+        session: session,
+        params: params,
+        sync: sync
+      )
+    end
+  end
+end
+
+require_relative "errorgap/rails/railtie" if defined?(Rails::Railtie)

data/lib/generators/errorgap/install_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Errorgap
+  class InstallGenerator < ::Rails::Generators::Base
+    def create_initializer
+      create_file "config/initializers/errorgap.rb", <<~RUBY
+        # frozen_string_literal: true
+
+        Errorgap.configure do |config|
+          config.endpoint = ENV.fetch("ERRORGAP_ENDPOINT", "http://127.0.0.1:3030")
+          config.project_slug = ENV["ERRORGAP_PROJECT_SLUG"]
+          config.project_id = ENV["ERRORGAP_PROJECT_ID"]
+          config.api_key = ENV["ERRORGAP_API_KEY"]
+          config.environment = Rails.env
+          config.root_directory = Rails.root.to_s
+          config.logger = Rails.logger
+
+          # Enable APM performance monitoring (opt-in).
+          # Records HTTP request timing and DB query spans via ActiveSupport::Notifications.
+          # config.apm_enabled = true
+          # config.apm_sample_rate = 1.0   # 0.0–1.0; sample a fraction of requests
+        end
+      RUBY
+    end
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: errorgap
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Errorgap
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-07-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Captures Ruby exceptions and sends them to a Errorgap server.
+email:
+- support@errorgap.com
+executables:
+- errorgap
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/errorgap
+- lib/errorgap.rb
+- lib/errorgap/configuration.rb
+- lib/errorgap/notice.rb
+- lib/errorgap/notifier.rb
+- lib/errorgap/rack_middleware.rb
+- lib/errorgap/rails/railtie.rb
+- lib/errorgap/span_collector.rb
+- lib/errorgap/transacter.rb
+- lib/errorgap/transaction.rb
+- lib/errorgap/version.rb
+- lib/generators/errorgap/install_generator.rb
+homepage: https://github.com/errorgaphq/errorgap-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/errorgaphq/errorgap-ruby
+  source_code_uri: https://github.com/errorgaphq/errorgap-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby notifier for Errorgap error tracking.
+test_files: []