Project

errorgap

0.0
The project is in a healthy, maintained state
Captures Ruby exceptions and sends them to a Errorgap server.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Development

~> 5.0
~> 13.0
 Project Readme

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:

gem "errorgap"

Then install:

bundle install

Configuration

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"))

  # 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.
  # Unset, it is detected: the platform's commit variable, a Capistrano
  # REVISION file, then the git checkout.
  config.release = ENV["GIT_SHA"]

  # Change a notice before it is sent, or return false to drop it.
  config.before_notify do |notice|
    false if notice[:errors].first[:type] == "ActionController::RoutingError"
  end
end

filter_keys (substrings or regexps, case-insensitive) are masked at any depth in params, the session and the query string. config.timeout (5 s) and config.queue_size (100) bound delivery: notices are queued and sent by one background thread, retried after a network failure or 5xx, and paused when the server answers 429.

Background jobs

In Rails, ActiveJob (any adapter) and Sidekiq jobs need no setup: each job is timed as a job transaction when APM is on, and an error it raises is reported with the job class, queue, id and arguments, then re-raised. Outside Rails:

Errorgap::Integrations::ActiveJob.install
Errorgap::Integrations::Sidekiq.install

Resque, Delayed Job and Rake tasks are covered the same way (in Rails with no setup; elsewhere Errorgap::Integrations::Resque.install, Errorgap::Integrations::DelayedJob.install, Errorgap::Integrations::Rake.install).

Remote settings

Errors, performance data and logs can each be switched off for a project in errorgap (Project settings › What SDKs send). Running apps follow within ten minutes, with no deploy. If errorgap cannot be reached, everything stays on. config.remote_settings = false ignores the project's switches.

Users

Errors raised in a request carry the signed-in Warden / Devise user's id and email (config.capture_user = false to turn off). Anywhere else:

Errorgap.set_user(id: account.id, email: account.email)

Deploys

bundle exec errorgap deploy --sha "$GIT_SHA" --branch main

or Errorgap.track_release(sha:, branch:) from a deploy script, or config.track_release = true to record the release when a process reports its first error.

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

begin
  risky_operation
rescue => error
  Errorgap.notify(error, context: { component: "billing" })
  raise
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

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

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.

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:

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:

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 sql.active_record and view spans). To time work manually — or in a plain Ruby app or background job — use the block API:

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")   # Net::HTTP calls are recorded for you
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.

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

use Errorgap::RackMiddleware

Rails

In Rails, requiring the gem installs the Rack middleware automatically through the Railtie.

Generate an initializer:

rails generate errorgap:install

Development

bundle install
bundle exec rake