errorgap 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a962a442c79c4d80123b06eb6cd8afb1e41cdce3b944101e8d9b6112343f2279
-  data.tar.gz: 61cd50f45d49df099b0ecd54cf18442c19cc31d837b275a0f7903322fbc57c1f
+  metadata.gz: '0841cbcd204e3167a443244774a3f05a4b692dc6b706b76db7cd3af7943296b1'
+  data.tar.gz: ec4b272a9c9102c7fc9643c6d66042ded9ee1e7ed9457f5bd59ea05f835293f2
 SHA512:
-  metadata.gz: e93b57a2558bde0c050d4c806ecb62c57d87ef41af342a8a3ede7071d12c3f71033d008c84dcfa250e5b5314f60ae93d4bf6b02ea546954a291b65f6f7516906
-  data.tar.gz: a456b31419bec30d07d25d3b0fd597d638008e6994c51e2e66f92a67df9bf78ad1e9ab27655ef4ee8abd2e83176b3be681796cf399d77b24bebcf24704093365
+  metadata.gz: '07229bfc0552894549309bb7b0c54363d59d70d09714cf66ccfc0f71d534c78030e55afceb32129e93d55eee0f1fb17a6b81eb2914986db367708fdfcf66c54d'
+  data.tar.gz: 96adaebf03ed7d0ef8f5f127ea1ccefafb6e70690235f6029e52b8fb3c7b4bf96d9e2ff263d41941b168a3b95cc9a8c87805ddffe43a2dfd4178328d05b15bd3

data/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.7.0] - 2026-10-03
+
+### Added
+
+- **Releases.** `config.release` (default `ENV["ERRORGAP_RELEASE"]`) is sent
+  as `context.release` on every notice, tying errors to the deploy that
+  shipped them.
+- **Browser trace links.** The Rack middleware reads the `x-errorgap-trace`
+  header sent by `@errorgap/browser` 0.3+ and records it as the transaction's
+  `trace_id`, so errorgap links a browser API call to the server request that
+  answered it. Only well-formed UUIDs are accepted.
+
+## [0.6.0] - 2026-10-03
+
+### Added
+
+- **Errors link to their request.** Every APM transaction (Rack middleware,
+  `track_transaction`, `track_job`) now has an id, sent as the transaction's
+  `id`, and errors reported while it runs carry it as
+  `context.transaction_id`. Errorgap shows the error a request actually raised
+  on its trace instead of matching by route and time, and links each
+  occurrence to its trace. The id is fiber-local, so concurrent requests never
+  share one, and is sent even when APM sampling drops the transaction.
+  `Errorgap.current_transaction_id` and `Errorgap.with_transaction_id` expose
+  it for custom instrumentation.
+
 ## [0.5.0] - 2026-07-20
 
 ### Added

data/README.md

@@ -31,9 +31,18 @@ Errorgap.configure do |config|
   # Skip reporting entirely (errors and APM) in these environments.
   # Also configurable via ERRORGAP_IGNORE_ENVIRONMENTS="test,development".
   config.ignore_environments = %w[test development]
+
+  # The deployed version or commit (defaults to ERRORGAP_RELEASE). Errors carry
+  # it, so errorgap ties each one to the deploy that shipped it.
+  config.release = ENV["GIT_SHA"]
 end
 ```
 
+When the errorgap browser SDK is on the page, its API calls send an
+`x-errorgap-trace` header; the Rack middleware records it on the request's
+transaction, so the browser's Performance view links each call to the server
+request that answered it.
+
 ## Manual Notification
 
 ```ruby
@@ -90,6 +99,13 @@ end
 Enable with `config.apm_enabled = true` (and optionally `config.apm_sample_rate`).
 Call `Errorgap.flush` before process exit to drain async deliveries.
 
+Every transaction gets an id, and errors reported while it runs — from the
+middleware, `Errorgap.notify`, or inside `track_transaction`/`track_job` —
+carry it as `context.transaction_id`. Errorgap then shows the error a request
+actually raised on its trace, and links each occurrence to its request.
+`Errorgap.current_transaction_id` returns the id in effect (fiber-local), and
+`Errorgap.with_transaction_id { |id| ... }` scopes one around custom work.
+
 ## Rack
 
 ```ruby

data/lib/errorgap/configuration.rb

@@ -16,7 +16,8 @@ module Errorgap
                   :apm_sample_rate,
                   :logs_enabled,
                   :minimum_log_level,
-                  :max_breadcrumbs
+                  :max_breadcrumbs,
+                  :release
 
     def initialize
       @endpoint = ENV.fetch("ERRORGAP_ENDPOINT", "http://127.0.0.1:3030")
@@ -33,6 +34,9 @@ module Errorgap
       @logs_enabled = true
       @minimum_log_level = "info"
       @max_breadcrumbs = 25
+      # The deployed version or commit: errors are attributed to the deploy
+      # that shipped them.
+      @release = ENV["ERRORGAP_RELEASE"].to_s.strip.empty? ? nil : ENV["ERRORGAP_RELEASE"].strip
     end
 
     def validate!

data/lib/errorgap/notice.rb

@@ -61,6 +61,7 @@ module Errorgap
         environment: @configuration.environment,
         root_directory: @configuration.root_directory
       }
+      context[:release] = @configuration.release if @configuration.release
       causes = collect_causes
       context[:causes] = causes unless causes.empty?
       context[:breadcrumbs] = @breadcrumbs unless @breadcrumbs.empty?

data/lib/errorgap/rack_middleware.rb

@@ -7,30 +7,52 @@ module Errorgap
     end
 
     def call(env)
-      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      SpanCollector.start if apm_enabled?
+      return call_without_transaction(env) unless apm_enabled?
 
-      status, headers, body = @app.call(env)
-      [status, headers, body]
+      # Errors raised while this request runs carry its transaction id.
+      Errorgap.with_transaction_id do |transaction_id|
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        SpanCollector.start
+        begin
+          status, headers, body = @app.call(env)
+          [status, headers, body]
+        rescue Exception => exception # rubocop:disable Lint/RescueException
+          notify_once(env, exception)
+          raise
+        ensure
+          elapsed_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000.0
+          record_transaction(env, status || 500, elapsed_ms, transaction_id)
+        end
+      end
+    end
+
+    private
+
+    def call_without_transaction(env)
+      @app.call(env)
     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
+    UUID = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+
+    # The x-errorgap-trace header a browser SDK sent with this call, linking
+    # the browser's view of it to this transaction. Only a well-formed UUID.
+    def browser_trace_id(env)
+      value = env["HTTP_X_ERRORGAP_TRACE"].to_s.strip
+      value.match?(UUID) ? value.downcase : nil
+    end
 
     def apm_enabled?
       Errorgap.configuration.apm_enabled
     end
 
-    def record_transaction(env, status_code, elapsed_ms)
+    def record_transaction(env, status_code, elapsed_ms, transaction_id)
       spans = SpanCollector.flush
       txn = Transaction.new(
+        id: transaction_id,
+        trace_id: browser_trace_id(env),
         kind: "web",
         method: env["REQUEST_METHOD"],
         path: route_pattern(env),

data/lib/errorgap/transaction.rb

@@ -17,13 +17,15 @@ module Errorgap
   end
 
   Transaction = Struct.new(
-    :kind, :method, :path, :path_raw, :status_code,
+    :id, :trace_id, :kind, :method, :path, :path_raw, :status_code,
     :duration_ms, :environment, :occurred_at, :spans,
     :job_class, :queue,
     keyword_init: true
   ) do
     def to_h
       {
+        id: id,
+        trace_id: trace_id,
         kind: kind,
         method: method,
         path: path,

data/lib/errorgap/version.rb

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

data/lib/errorgap.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 require_relative "errorgap/configuration"
 require_relative "errorgap/breadcrumbs"
 require_relative "errorgap/notifier"
@@ -43,6 +45,10 @@ module Errorgap
     end
 
     def notify(error, context: {}, environment: {}, session: {}, params: {}, sync: false)
+      # The request or job this error was raised in, so errorgap links the two.
+      if (transaction_id = current_transaction_id) && !context.key?(:transaction_id) && !context.key?("transaction_id")
+        context = context.merge(transaction_id: transaction_id)
+      end
       notifier.notify(
         error,
         context: context,
@@ -75,6 +81,26 @@ module Errorgap
       )
     end
 
+    TRANSACTION_ID_KEY = :errorgap_transaction_id
+
+    # The id of the APM transaction running on this fiber, if any. Notices
+    # reported while it is set carry it as `context.transaction_id`.
+    def current_transaction_id
+      Thread.current[TRANSACTION_ID_KEY]
+    end
+
+    # Run the block as one transaction: a new id is current for its duration
+    # (fiber-local, so concurrent requests never share one) and the previous
+    # one is restored after. Yields the id.
+    def with_transaction_id
+      previous = Thread.current[TRANSACTION_ID_KEY]
+      id = SecureRandom.uuid
+      Thread.current[TRANSACTION_ID_KEY] = id
+      yield id
+    ensure
+      Thread.current[TRANSACTION_ID_KEY] = previous
+    end
+
     # Deliver a prebuilt APM transaction, honoring apm_enabled and sampling.
     def notify_transaction(transaction, sync: false)
       return unless configuration.apm_enabled
@@ -92,39 +118,45 @@ module Errorgap
     # 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)
+      with_transaction_id do |transaction_id|
+        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(
+            id: transaction_id,
+            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
     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)
+      with_transaction_id do |transaction_id|
+        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(
+            id: transaction_id,
+            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
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: errorgap
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Errorgap
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake