errorgap 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a6d206f60530a163bfebf7cbc25d4ef0f889a81d1b15c78f440c2141e4efc3a
-  data.tar.gz: d9346233cd3aec6e191a13efcec513fdfec9fadececb304549afc1527f4da3a7
+  metadata.gz: a962a442c79c4d80123b06eb6cd8afb1e41cdce3b944101e8d9b6112343f2279
+  data.tar.gz: 61cd50f45d49df099b0ecd54cf18442c19cc31d837b275a0f7903322fbc57c1f
 SHA512:
-  metadata.gz: c35e78949f9cbd4e30e24acacfbd5857f3d3003aa763f6d41c26a1713dde9c3e55a62bfe0bc24caa6941029910423ba1c5b0609ee4f48fed890ff1dbc4364e5a
-  data.tar.gz: 73a7f26536826709ceb3feb1624f48caa336dc2f6981c558a7d692a2ddbbef93206ff6397f4fa4192cc6f2306a486d8125f80df5750d4ecce168845ed6466e61
+  metadata.gz: e93b57a2558bde0c050d4c806ecb62c57d87ef41af342a8a3ede7071d12c3f71033d008c84dcfa250e5b5314f60ae93d4bf6b02ea546954a291b65f6f7516906
+  data.tar.gz: a456b31419bec30d07d25d3b0fd597d638008e6994c51e2e66f92a67df9bf78ad1e9ab27655ef4ee8abd2e83176b3be681796cf399d77b24bebcf24704093365

data/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-07-20
+
+### Added
+
+- **Nested exception causes.** The `cause` chain of a raised exception is now
+  walked and reported: each cause appears under `context.causes`, and every
+  link's frames are merged into a single, re-indexed backtrace so the dashboard
+  renders the whole chain in one view.
+- **Breadcrumbs.** `Errorgap.add_breadcrumb(message, category:, metadata:)`
+  records a diagnostic trail (a fixed-size ring, `config.max_breadcrumbs`,
+  default 25) that is attached to subsequent notices as `context.breadcrumbs`.
+  `Errorgap.clear_breadcrumbs` empties it.
+- **Structured logs.** `Errorgap.log(message, level:, source:)` delivers log
+  lines to the ingestion API. Levels (`trace`/`debug`/`info`/`warn`/`error`/
+  `fatal`, plus common aliases) are normalized and ranked; anything below
+  `config.minimum_log_level` (default `info`) is dropped locally.
+  `config.logs_enabled` toggles delivery.
+- **Manual APM API.** `Errorgap.track_transaction` and `Errorgap.track_job`
+  time a block and deliver a transaction, yielding a span recorder for manual
+  DB/HTTP spans (`spans.database`, `spans.external`) — automatic
+  `sql.active_record` spans recorded during the block are merged in.
+  `Errorgap.notify_transaction` delivers a prebuilt transaction. This lets
+  non-Rails apps and background jobs report APM data.
+- **Source excerpts for dependency frames.** Backtrace source is now attached to
+  any readable frame (bounded by the existing 25-frame cap), not only in-app
+  frames, so dependency frames show source in the dashboard.
+- `Errorgap.flush` joins in-flight async delivery threads before process exit.
+
 ## [0.4.0] - 2026-07-16
 
 ### Fixed

data/README.md

@@ -45,6 +45,51 @@ rescue => error
 end
 ```
 
+`Errorgap.notify` walks the exception's `cause` chain: each cause is reported
+under `context.causes` and its frames are merged into one backtrace. Source
+excerpts are attached to readable app **and** dependency frames.
+
+## Breadcrumbs
+
+```ruby
+Errorgap.add_breadcrumb("received request", category: "http")
+Errorgap.add_breadcrumb("loaded order", category: "db", metadata: { id: 7 })
+# ...later notices include the trail above
+```
+
+The buffer keeps the most recent `config.max_breadcrumbs` entries (default 25);
+`Errorgap.clear_breadcrumbs` empties it.
+
+## Structured logs
+
+```ruby
+Errorgap.log("payment captured", level: "info", source: "payments")
+```
+
+Levels are `trace < debug < info < warn < error < fatal` (with aliases like
+`warning`/`critical`); anything below `config.minimum_log_level` (default
+`info`) is dropped locally. Set `config.logs_enabled = false` to disable.
+
+## APM
+
+The Rack middleware records a web transaction per request automatically (with
+`sql.active_record` and view spans). To time work manually — or in a plain Ruby
+app or background job — use the block API:
+
+```ruby
+Errorgap.track_transaction(method: "GET", path: "/orders/{id}", path_raw: "/orders/7", status_code: 200) do |spans|
+  spans.database("SELECT * FROM orders WHERE id = 7", 4.2, fn_name: "Repo.load")
+  spans.external(30.0, fn_name: "Gateway.fetch")
+end
+
+Errorgap.track_job("ReceiptJob", queue: "mailers") do |spans|
+  spans.database("SELECT total FROM receipts WHERE id = 1", 3.1)
+end
+```
+
+Enable with `config.apm_enabled = true` (and optionally `config.apm_sample_rate`).
+Call `Errorgap.flush` before process exit to drain async deliveries.
+
 ## Rack
 
 ```ruby

data/lib/errorgap/breadcrumbs.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Errorgap
+  # Fixed-size ring of recent application events (requests, queries, jobs)
+  # attached to every notice as context.breadcrumbs. Thread-safe so it can be
+  # written from request threads and read at notify time.
+  class Breadcrumbs
+    def initialize(capacity)
+      @capacity = capacity.to_i
+      @crumbs = []
+      @mutex = Mutex.new
+    end
+
+    def add(message, category: nil, metadata: nil)
+      return if @capacity <= 0
+
+      crumb = { message: message.to_s, timestamp: Time.now.utc.iso8601(3) }
+      crumb[:category] = category.to_s if category
+      crumb[:metadata] = metadata if metadata
+
+      @mutex.synchronize do
+        @crumbs << crumb
+        @crumbs.shift(@crumbs.length - @capacity) if @crumbs.length > @capacity
+      end
+    end
+
+    def clear
+      @mutex.synchronize { @crumbs = [] }
+    end
+
+    def to_a
+      @mutex.synchronize { @crumbs.dup }
+    end
+  end
+end

data/lib/errorgap/configuration.rb

@@ -13,7 +13,10 @@ module Errorgap
                   :filter_keys,
                   :ignore_environments,
                   :apm_enabled,
-                  :apm_sample_rate
+                  :apm_sample_rate,
+                  :logs_enabled,
+                  :minimum_log_level,
+                  :max_breadcrumbs
 
     def initialize
       @endpoint = ENV.fetch("ERRORGAP_ENDPOINT", "http://127.0.0.1:3030")
@@ -27,6 +30,9 @@ module Errorgap
       @ignore_environments = ENV.fetch("ERRORGAP_IGNORE_ENVIRONMENTS", "").split(",").map(&:strip).reject(&:empty?)
       @apm_enabled = false
       @apm_sample_rate = 1.0
+      @logs_enabled = true
+      @minimum_log_level = "info"
+      @max_breadcrumbs = 25
     end
 
     def validate!

data/lib/errorgap/log_delivery.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "time"
+
+module Errorgap
+  # Delivers structured log lines to the ingestion API. Levels are ranked so a
+  # configurable minimum threshold can drop low-severity logs before any
+  # request is made.
+  class LogDelivery
+    LEVELS = %w[trace debug info warn error fatal].freeze
+    LEVEL_ALIASES = { "warning" => "warn", "err" => "error", "critical" => "fatal", "panic" => "fatal" }.freeze
+
+    def initialize(configuration)
+      configure(configuration)
+    end
+
+    def configure(configuration)
+      @configuration = configuration
+    end
+
+    def log(message, level: "info", source: nil, environment: nil, occurred_at: nil, sync: false)
+      return unless @configuration.logs_enabled
+      return if @configuration.ignored_environment?
+
+      normalized = self.class.normalize_level(level)
+      return if self.class.rank(normalized) < self.class.rank(self.class.normalize_level(@configuration.minimum_log_level))
+
+      payload = {
+        message: message.to_s,
+        level: normalized,
+        environment: environment || @configuration.environment,
+        occurred_at: (occurred_at || Time.now).utc.iso8601(3)
+      }
+      payload[:source] = source.to_s if source
+
+      if sync || !@configuration.async
+        deliver(payload)
+      else
+        Errorgap.register_thread(Thread.new { deliver(payload) })
+        nil
+      end
+    end
+
+    def deliver(payload)
+      uri = URI.join(
+        @configuration.endpoint.end_with?("/") ? @configuration.endpoint : "#{@configuration.endpoint}/",
+        "api/projects/#{@configuration.project_slug}/logs"
+      )
+      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(payload)
+
+      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] log delivery error: #{exception.class}: #{exception.message}")
+    end
+
+    def self.normalize_level(level)
+      value = level.to_s.strip.downcase
+      value = LEVEL_ALIASES.fetch(value, value)
+      LEVELS.include?(value) ? value : "info"
+    end
+
+    def self.rank(level)
+      LEVELS.index(level) || LEVELS.index("info")
+    end
+
+    private
+
+    def present?(value)
+      !value.nil? && !value.to_s.empty?
+    end
+  end
+end

data/lib/errorgap/notice.rb

@@ -10,25 +10,28 @@ module Errorgap
     SOURCE_RADIUS = 6
     MAX_SOURCE_FRAMES = 25
     MAX_SOURCE_LINE_LENGTH = 400
+    MAX_CAUSE_DEPTH = 10
 
-    def self.from_exception(error, configuration:, context: {}, environment: {}, session: {}, params: {})
+    def self.from_exception(error, configuration:, context: {}, environment: {}, session: {}, params: {}, breadcrumbs: [])
       new(
         error: error,
         configuration: configuration,
         context: context,
         environment: environment,
         session: session,
-        params: params
+        params: params,
+        breadcrumbs: breadcrumbs
       )
     end
 
-    def initialize(error:, configuration:, context:, environment:, session:, params:)
+    def initialize(error:, configuration:, context:, environment:, session:, params:, breadcrumbs: [])
       @error = error
       @configuration = configuration
       @context = context || {}
       @environment = environment || {}
       @session = session || {}
       @params = params || {}
+      @breadcrumbs = Array(breadcrumbs)
     end
 
     def to_h
@@ -52,32 +55,64 @@ module Errorgap
     private
 
     def default_context
-      {
+      context = {
         notifier: "errorgap-ruby",
         notifier_version: Errorgap::VERSION,
         environment: @configuration.environment,
         root_directory: @configuration.root_directory
       }
+      causes = collect_causes
+      context[:causes] = causes unless causes.empty?
+      context[:breadcrumbs] = @breadcrumbs unless @breadcrumbs.empty?
+      context
     end
 
+    # Walks the exception's `cause` chain (Ruby's nested exceptions) and merges
+    # every link's frames into one backtrace, re-indexed, so the dashboard
+    # renders the full chain in a single view.
     def backtrace_frames
       source_frames = 0
-      Array(@error.backtrace).map.with_index do |line, index|
-        file, line_number, function = parse_backtrace_line(line)
-        frame = {
-          file: relative_file(file),
-          line: line_number,
-          function: function,
-          in_app: in_app?(file),
-          index: index
-        }
-        if in_app?(file) && source_frames < MAX_SOURCE_FRAMES &&
-           (source = source_excerpt(file, line_number))
-          frame[:source] = source
-          source_frames += 1
+      index = 0
+      frames = []
+      error_chain.each do |link|
+        Array(link.backtrace).each do |line|
+          file, line_number, function = parse_backtrace_line(line)
+          absolute = absolute_frame_path(file)
+          frame = {
+            file: display_path(absolute),
+            line: line_number,
+            function: function,
+            in_app: within_root?(absolute),
+            index: index
+          }
+          if source_frames < MAX_SOURCE_FRAMES && (source = source_excerpt(absolute, line_number))
+            frame[:source] = source
+            source_frames += 1
+          end
+          frames << frame.compact
+          index += 1
         end
-        frame.compact
       end
+      frames
+    end
+
+    # The causes beyond the root error, as {type, message} pairs.
+    def collect_causes
+      error_chain.drop(1).map do |link|
+        { type: link.class.name, message: link.message.to_s }
+      end
+    end
+
+    def error_chain
+      chain = []
+      seen = {}
+      current = @error
+      while current.is_a?(Exception) && !seen[current.object_id] && chain.length < MAX_CAUSE_DEPTH
+        seen[current.object_id] = true
+        chain << current
+        current = current.cause
+      end
+      chain
     end
 
     # Reads the lines around the failing line so the server can show source
@@ -111,16 +146,30 @@ module Errorgap
       [match[1], match[2].to_i, match[3]]
     end
 
-    def relative_file(file)
+    # Ruby reports the entry script by the (possibly relative) path it was
+    # invoked with, while `require`d files use absolute paths. Resolve relative
+    # frames against the configured root so the entry point — and framework
+    # frames reported relative to the app root — classify as in-app too.
+    def absolute_frame_path(file)
+      path = file.to_s
+      return path if path.start_with?("/") || path.match?(%r{\A[A-Za-z]:[\\/]})
+
+      root = @configuration.root_directory.to_s
+      root.empty? ? path : File.expand_path(path, root)
+    end
+
+    def within_root?(absolute_path)
       root = @configuration.root_directory.to_s
-      return file if root.empty?
+      return false if root.empty?
 
-      file.to_s.sub(%r{\A#{Regexp.escape(root)}/?}, "")
+      absolute_path == root || absolute_path.start_with?("#{root}/")
     end
 
-    def in_app?(file)
+    def display_path(absolute_path)
       root = @configuration.root_directory.to_s
-      !root.empty? && file.to_s.start_with?(root)
+      return absolute_path if root.empty?
+
+      absolute_path.sub(%r{\A#{Regexp.escape(root)}/?}, "")
     end
 
     def filter_hash(hash)

data/lib/errorgap/notifier.rb

@@ -20,7 +20,7 @@ module Errorgap
       @configuration = configuration
     end
 
-    def notify(error, context: {}, environment: {}, session: {}, params: {}, sync: false)
+    def notify(error, context: {}, environment: {}, session: {}, params: {}, breadcrumbs: [], sync: false)
       @configuration.validate!
       return Response.new(status: 202, body: "ignored environment") if @configuration.ignored_environment?
 
@@ -30,13 +30,14 @@ module Errorgap
         context: context,
         environment: environment,
         session: session,
-        params: params
+        params: params,
+        breadcrumbs: breadcrumbs
       )
 
       if sync || !@configuration.async
         deliver(notice)
       else
-        Thread.new { deliver(notice) }
+        Errorgap.register_thread(Thread.new { deliver(notice) })
         Response.new(status: 202, body: "queued")
       end
     rescue StandardError => exception

data/lib/errorgap/span_recorder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Errorgap
+  # Yielded to `Errorgap.track_transaction` / `track_job` blocks so callers can
+  # record spans manually (outside Rails' automatic `sql.active_record`
+  # instrumentation) — e.g. outbound HTTP calls or queries in a plain Ruby
+  # service. Spans are appended to the same thread-local store the automatic
+  # collector uses, so manual and automatic spans merge into one transaction.
+  class SpanRecorder
+    def database(sql, duration_ms, file: nil, line: nil, fn_name: nil)
+      SpanCollector.store << Span.new(
+        kind: "db",
+        sql: SpanCollector.normalize_sql(sql.to_s),
+        file: file, line: line, fn_name: fn_name,
+        duration_ms: duration_ms.to_f.round(3)
+      )
+    end
+
+    def external(duration_ms, file: nil, line: nil, fn_name: nil)
+      SpanCollector.store << Span.new(
+        kind: "http",
+        file: file, line: line, fn_name: fn_name,
+        duration_ms: duration_ms.to_f.round(3)
+      )
+    end
+
+    def add(span)
+      SpanCollector.store << span
+    end
+  end
+end

data/lib/errorgap/transacter.rb

@@ -18,7 +18,7 @@ module Errorgap
       return if @configuration.ignored_environment?
       return unless should_sample?
 
-      Thread.new { deliver(transaction) }
+      Errorgap.register_thread(Thread.new { deliver(transaction) })
     end
 
     def deliver(transaction)

data/lib/errorgap/version.rb

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

data/lib/errorgap.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 require_relative "errorgap/configuration"
+require_relative "errorgap/breadcrumbs"
 require_relative "errorgap/notifier"
 require_relative "errorgap/notice"
+require_relative "errorgap/log_delivery"
 require_relative "errorgap/transaction"
 require_relative "errorgap/span_collector"
+require_relative "errorgap/span_recorder"
 require_relative "errorgap/transacter"
 require_relative "errorgap/rack_middleware"
 require_relative "errorgap/version"
@@ -15,6 +18,8 @@ module Errorgap
       yield(configuration)
       notifier.configure(configuration)
       transacter.configure(configuration)
+      log_delivery.configure(configuration)
+      @breadcrumbs = Breadcrumbs.new(configuration.max_breadcrumbs)
     end
 
     def configuration
@@ -29,6 +34,14 @@ module Errorgap
       @transacter ||= Transacter.new(configuration)
     end
 
+    def log_delivery
+      @log_delivery ||= LogDelivery.new(configuration)
+    end
+
+    def breadcrumbs
+      @breadcrumbs ||= Breadcrumbs.new(configuration.max_breadcrumbs)
+    end
+
     def notify(error, context: {}, environment: {}, session: {}, params: {}, sync: false)
       notifier.notify(
         error,
@@ -36,9 +49,119 @@ module Errorgap
         environment: environment,
         session: session,
         params: params,
+        breadcrumbs: breadcrumbs.to_a,
+        sync: sync
+      )
+    end
+
+    # Record a diagnostic breadcrumb attached to subsequent notices.
+    def add_breadcrumb(message, category: nil, metadata: nil)
+      breadcrumbs.add(message, category: category, metadata: metadata)
+    end
+
+    def clear_breadcrumbs
+      breadcrumbs.clear
+    end
+
+    # Deliver a structured log line at the given level.
+    def log(message, level: "info", source: nil, environment: nil, occurred_at: nil, sync: false)
+      log_delivery.log(
+        message,
+        level: level,
+        source: source,
+        environment: environment,
+        occurred_at: occurred_at,
         sync: sync
       )
     end
+
+    # Deliver a prebuilt APM transaction, honoring apm_enabled and sampling.
+    def notify_transaction(transaction, sync: false)
+      return unless configuration.apm_enabled
+      return if configuration.ignored_environment?
+      return unless sample_apm?
+
+      if sync || !configuration.async
+        transacter.deliver(transaction)
+      else
+        register_thread(Thread.new { transacter.deliver(transaction) })
+      end
+    end
+
+    # Time an HTTP interaction and deliver it as a transaction. The block
+    # receives a SpanRecorder for manual DB/HTTP spans; any automatic
+    # `sql.active_record` spans recorded during the block are merged in.
+    def track_transaction(method: nil, path: nil, path_raw: nil, status_code: nil, kind: "web", environment: nil, sync: false)
+      SpanCollector.start
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      occurred = Time.now
+      begin
+        yield(SpanRecorder.new) if block_given?
+      ensure
+        elapsed_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+        transaction = Transaction.new(
+          kind: kind, method: method, path: path, path_raw: path_raw,
+          status_code: status_code, duration_ms: elapsed_ms.round(2),
+          environment: environment || configuration.environment,
+          occurred_at: occurred, spans: SpanCollector.flush
+        )
+        notify_transaction(transaction, sync: sync)
+      end
+    end
+
+    # Time a background job and deliver it as a `job` transaction.
+    def track_job(job_class, queue: "default", environment: nil, sync: false)
+      SpanCollector.start
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      occurred = Time.now
+      begin
+        yield(SpanRecorder.new) if block_given?
+      ensure
+        elapsed_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+        transaction = Transaction.new(
+          kind: "job", job_class: job_class, queue: queue,
+          duration_ms: elapsed_ms.round(2),
+          environment: environment || configuration.environment,
+          occurred_at: occurred, spans: SpanCollector.flush
+        )
+        notify_transaction(transaction, sync: sync)
+      end
+    end
+
+    # Join any in-flight async delivery threads. Call before process exit to
+    # avoid dropping queued notices/transactions/logs.
+    def flush
+      threads = thread_mutex.synchronize do
+        pending = delivery_threads.dup
+        delivery_threads.clear
+        pending
+      end
+      threads.each { |thread| thread.join(5) }
+      nil
+    end
+
+    def register_thread(thread)
+      thread_mutex.synchronize { delivery_threads << thread }
+      thread
+    end
+
+    private
+
+    def sample_apm?
+      rate = configuration.apm_sample_rate.to_f
+      return true if rate >= 1.0
+      return false if rate <= 0.0
+
+      rand < rate
+    end
+
+    def delivery_threads
+      @delivery_threads ||= []
+    end
+
+    def thread_mutex
+      @thread_mutex ||= Mutex.new
+    end
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: errorgap
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Errorgap
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-17 00:00:00.000000000 Z
+date: 2026-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -65,12 +65,15 @@ files:
 - README.md
 - exe/errorgap
 - lib/errorgap.rb
+- lib/errorgap/breadcrumbs.rb
 - lib/errorgap/configuration.rb
+- lib/errorgap/log_delivery.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/span_recorder.rb
 - lib/errorgap/transacter.rb
 - lib/errorgap/transaction.rb
 - lib/errorgap/version.rb