errorgap 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75cf1e4a725d5e1c7f484a577814d71403fbdc4e6c6cd4bcec3d0eca30f00478
-  data.tar.gz: 98d336466f4eceedc7ad6fc03fff038704d10872e30c6b7f5376528e424dd73b
+  metadata.gz: 0b1e9118a26db2870eb0aa90b9a4ef3784138e078d03b2959ce1b064949b53de
+  data.tar.gz: e3da3e394f5aa7961c5956f8fdfa5346696086324b48eedac330e0d95dd42f59
 SHA512:
-  metadata.gz: 44e3afd205bce67d34e40e6b71a5c67b43615dc04acc299f7188f0e01d514844e7b836523a0dcae0e95388b7b38875c76f2ffc012d3a83b316450182b5a2fb36
-  data.tar.gz: b8b2d440abe90925b5750cf6526b34449d00d913d5bd47a8d74339ce8ba9c5622abe55949b66465ad1f1f0b0972ee26446c258086a98280c94dcdff36b66a229
+  metadata.gz: b8d0f1bae2b1df08c0893e414a8916a4cc7487afa5443eb3c1de0860133baca93d71c29935552c158ec93392b878b44933848e53ed5761aca84fd141014d2702
+  data.tar.gz: a9ba148ab19bba740b6d877403ee628c43f303a27abfdd20347a5728d7860ea1ec792739b3b23c5b1992066cdd309ac457fd28de60fd9bb7cca4af19bddc49b6

data/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.8.0] - 2026-10-06
+
+### Added
+
+- **Sign-ins.** `config.auth_events = true` reports sign-ins to errorgap's
+  Security › Logins (`POST /logins/web`). Devise and other Warden apps are
+  covered automatically: successful sign-ins and failed sign-in attempts
+  (`locked` for locked accounts), without remember-me cookies, signed-out
+  page visits or expired sessions. `Errorgap.sign_in(outcome, user:,
+  request:)` reports anything else (`password_reset`, `mfa_failure`, …).
+  `config.app_name` and `config.auth_user` control how the app and user are
+  named. Passwords and tokens are never sent.
+
+## [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

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
@@ -70,6 +79,41 @@ 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.
 
+## Sign-ins
+
+Report sign-ins to your app; errorgap shows them beside SSH logins in
+Security › Logins, flags a new IP, country or hour for a user, and alerts on
+a sign-in after many failures. Off until you opt in, since events carry user
+names and IPs:
+
+```ruby
+Errorgap.configure do |config|
+  config.auth_events = true
+  config.app_name = "oxcoffee-web"   # default: the project slug
+  config.auth_user = :email          # or :id, or ->(user) { ... }
+end
+```
+
+**Devise / Warden** apps need nothing else: the Railtie installs Warden hooks
+that report each successful sign-in and each failed attempt (a POST that
+Warden rejects; a locked account reports `locked`). Visiting a protected
+page while signed out, expired sessions and remember-me cookies are not
+reported. Outside Rails, call `Errorgap::WardenHooks.install` after
+configuring.
+
+Anything else, or other outcomes:
+
+```ruby
+Errorgap.sign_in("success", user: user.email, request: request)
+Errorgap.sign_in("mfa_failure", user: user.email, request: request)
+Errorgap.sign_in("password_reset", user: user.email, request: request)
+```
+
+Outcomes: `success`, `failure`, `password_reset`, `mfa_failure`, `locked`.
+The request supplies the IP (`remote_ip`), user agent and path. Passwords
+and tokens are never sent; errorgap can also store user names hashed
+(Security › Logins › Web apps › Privacy).
+
 ## APM
 
 The Rack middleware records a web transaction per request automatically (with

data/lib/errorgap/configuration.rb

@@ -16,7 +16,11 @@ module Errorgap
                   :apm_sample_rate,
                   :logs_enabled,
                   :minimum_log_level,
-                  :max_breadcrumbs
+                  :max_breadcrumbs,
+                  :release,
+                  :auth_events,
+                  :auth_user,
+                  :app_name
 
     def initialize
       @endpoint = ENV.fetch("ERRORGAP_ENDPOINT", "http://127.0.0.1:3030")
@@ -33,6 +37,17 @@ 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
+      # Sign-ins to this app (Security › Logins). Off until you opt in: they
+      # carry user names and IPs.
+      @auth_events = false
+      # How a signed-in user is named: a method (:email) or a proc. Default:
+      # email, username, login, then id.
+      @auth_user = nil
+      # The app's name in Security › Logins; defaults to the project slug.
+      @app_name = nil
     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

@@ -35,6 +35,15 @@ module Errorgap
       raise
     end
 
+    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
@@ -43,6 +52,7 @@ module Errorgap
       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/rails/railtie.rb

@@ -25,6 +25,11 @@ module Errorgap
         SpanCollector.install
       end
 
+      # After config/initializers, so `auth_events` is readable here.
+      config.after_initialize do
+        Errorgap::WardenHooks.install if Errorgap.configuration.auth_events
+      end
+
       generators do
         require "generators/errorgap/install_generator"
       end

data/lib/errorgap/sign_ins.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "time"
+
+module Errorgap
+  # Sign-ins to this app, shown beside SSH logins in Security › Logins.
+  # Opt in with `config.auth_events = true`. Only who, from where and the
+  # result are sent: never passwords, tokens or session ids.
+  class SignIns
+    OUTCOMES = %w[success failure password_reset mfa_failure locked].freeze
+
+    def initialize(configuration)
+      configure(configuration)
+    end
+
+    def configure(configuration)
+      @configuration = configuration
+    end
+
+    # `request` (Rack or ActionDispatch) fills in the IP, user agent and path.
+    def record(outcome, user: nil, request: nil, ip: nil, user_agent: nil, path: nil, method: nil,
+               occurred_at: nil, sync: false)
+      return unless @configuration.auth_events
+      return if @configuration.ignored_environment?
+
+      outcome = outcome.to_s
+      unless OUTCOMES.include?(outcome)
+        @configuration.logger&.warn("[errorgap] unknown sign-in outcome #{outcome.inspect}")
+        return
+      end
+
+      if request
+        ip ||= request.respond_to?(:remote_ip) ? request.remote_ip : request.ip
+        user_agent ||= request.user_agent
+        path ||= "#{request.request_method} #{request.path}"
+      end
+      event = { occurred_at: (occurred_at || Time.now).utc.iso8601(3), outcome: outcome }
+      event[:user] = user.to_s if present?(user)
+      event[:ip] = ip.to_s if present?(ip)
+      event[:user_agent] = user_agent.to_s[0, 512] if present?(user_agent)
+      event[:path] = path.to_s[0, 200] if present?(path)
+      event[:method] = method.to_s if present?(method)
+      payload = {
+        app: @configuration.app_name || @configuration.project_slug,
+        environment: @configuration.environment,
+        sdk: "errorgap-ruby #{Errorgap::VERSION}",
+        events: [event]
+      }
+
+      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}/logins/web"
+      )
+      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] sign-in delivery error: #{exception.class}: #{exception.message}")
+    end
+
+    private
+
+    def present?(value)
+      !value.nil? && !value.to_s.strip.empty?
+    end
+  end
+end

data/lib/errorgap/transaction.rb

@@ -17,7 +17,7 @@ module Errorgap
   end
 
   Transaction = Struct.new(
-    :id, :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
@@ -25,6 +25,7 @@ module Errorgap
     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.6.0"
+  VERSION = "0.8.0"
 end

data/lib/errorgap/warden_hooks.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Errorgap
+  # Devise and other Warden apps: report sign-ins without touching the
+  # controllers. The Rails railtie installs these when `auth_events` is on;
+  # elsewhere call `Errorgap::WardenHooks.install` after configuring.
+  module WardenHooks
+    # Failures that are not a sign-in attempt: visiting a protected page
+    # signed out, an expired session, an account that is not confirmed.
+    NOT_ATTEMPTS = %i[unauthenticated timeout inactive unconfirmed].freeze
+    # Form fields that hold the name being signed in with.
+    USER_PARAMS = %w[email login username].freeze
+
+    class << self
+      def install
+        return false unless defined?(::Warden::Manager)
+        return true if @installed
+
+        ::Warden::Manager.after_authentication do |user, auth, opts|
+          Errorgap::WardenHooks.on_success(user, auth, opts)
+        end
+        ::Warden::Manager.before_failure do |env, opts|
+          Errorgap::WardenHooks.on_failure(env, opts)
+        end
+        @installed = true
+      end
+
+      def on_success(user, auth, _opts = {})
+        # A remember-me cookie signing the user back in is not a new sign-in.
+        return if auth.respond_to?(:winning_strategy) && auth.winning_strategy.respond_to?(:key) &&
+                  auth.winning_strategy.key == :rememberable
+
+        Errorgap.sign_in("success", user: identify(user), request: request_for(auth.env))
+      rescue StandardError => exception
+        Errorgap.configuration.logger&.warn("[errorgap] sign-in hook error: #{exception.class}: #{exception.message}")
+      end
+
+      def on_failure(env, opts = {})
+        message = opts[:message]&.to_sym
+        return if NOT_ATTEMPTS.include?(message)
+
+        request = request_for(env)
+        return unless request&.post?
+
+        outcome = message == :locked ? "locked" : "failure"
+        # Warden points PATH_INFO at the failure app before this runs; the
+        # form's path is in `attempted_path` (query string dropped).
+        path = opts[:attempted_path] ? "#{request.request_method} #{opts[:attempted_path].to_s.split('?').first}" : nil
+        Errorgap.sign_in(outcome, user: attempted_user(request, opts[:scope]), request: request, path: path)
+      rescue StandardError => exception
+        Errorgap.configuration.logger&.warn("[errorgap] sign-in hook error: #{exception.class}: #{exception.message}")
+      end
+
+      # How a signed-in user is named: `config.auth_user` (a method name or a
+      # proc), else email, username, login, then id.
+      def identify(user)
+        pick = Errorgap.configuration.auth_user
+        return pick.call(user) if pick.respond_to?(:call)
+        return user.public_send(pick) if pick && user.respond_to?(pick)
+
+        %i[email username login id].each do |name|
+          return user.public_send(name) if user.respond_to?(name)
+        end
+        nil
+      end
+
+      private
+
+      def attempted_user(request, scope)
+        params = request.params
+        fields = scope && params[scope.to_s].is_a?(Hash) ? params[scope.to_s] : params
+        USER_PARAMS.each do |name|
+          value = fields[name]
+          return value if value.is_a?(String) && !value.strip.empty?
+        end
+        nil
+      end
+
+      def request_for(env)
+        if defined?(::ActionDispatch::Request)
+          ::ActionDispatch::Request.new(env)
+        elsif defined?(::Rack::Request)
+          ::Rack::Request.new(env)
+        end
+      end
+    end
+  end
+end

data/lib/errorgap.rb

@@ -7,6 +7,8 @@ require_relative "errorgap/breadcrumbs"
 require_relative "errorgap/notifier"
 require_relative "errorgap/notice"
 require_relative "errorgap/log_delivery"
+require_relative "errorgap/sign_ins"
+require_relative "errorgap/warden_hooks"
 require_relative "errorgap/transaction"
 require_relative "errorgap/span_collector"
 require_relative "errorgap/span_recorder"
@@ -21,6 +23,7 @@ module Errorgap
       notifier.configure(configuration)
       transacter.configure(configuration)
       log_delivery.configure(configuration)
+      sign_ins.configure(configuration)
       @breadcrumbs = Breadcrumbs.new(configuration.max_breadcrumbs)
     end
 
@@ -40,6 +43,19 @@ module Errorgap
       @log_delivery ||= LogDelivery.new(configuration)
     end
 
+    def sign_ins
+      @sign_ins ||= SignIns.new(configuration)
+    end
+
+    # Report a sign-in to this app: "success", "failure", "password_reset",
+    # "mfa_failure" or "locked". Pass the request for its IP, user agent and
+    # path. Needs `config.auth_events = true`; Devise apps get this
+    # automatically from the Warden hooks.
+    def sign_in(outcome, user: nil, request: nil, ip: nil, user_agent: nil, path: nil, method: nil, sync: false)
+      sign_ins.record(outcome, user: user, request: request, ip: ip, user_agent: user_agent,
+                               path: path, method: method, sync: sync)
+    end
+
     def breadcrumbs
       @breadcrumbs ||= Breadcrumbs.new(configuration.max_breadcrumbs)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: errorgap
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Errorgap
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-03 00:00:00.000000000 Z
+date: 2026-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -72,11 +72,13 @@ files:
 - lib/errorgap/notifier.rb
 - lib/errorgap/rack_middleware.rb
 - lib/errorgap/rails/railtie.rb
+- lib/errorgap/sign_ins.rb
 - lib/errorgap/span_collector.rb
 - lib/errorgap/span_recorder.rb
 - lib/errorgap/transacter.rb
 - lib/errorgap/transaction.rb
 - lib/errorgap/version.rb
+- lib/errorgap/warden_hooks.rb
 - lib/generators/errorgap/install_generator.rb
 homepage: https://github.com/errorgaphq/errorgap-ruby
 licenses: