Hawk Ruby

Ruby error reporting for Hawk, with optional Rails and background job integrations.

• Runs on CRuby 3.3 or later, with optional Rails and background job adapters.
• Built for Hawk: sends events directly to its native collector without a forwarding service.
• The default client bounds delivery to one background thread and a queue of 100 events.
• Excludes request bodies, headers, cookies, and job arguments by default.

Run this command from your application's directory, which must contain a Gemfile:

bundle add hawk-ruby --version "~> 0.1.1" --require hawk

Copy the integration token from your Hawk project into HAWK_TOKEN. Save this example as report.rb:

require "hawk"

Hawk.init do |config|
  config.token = ENV.fetch("HAWK_TOKEN")
end

Hawk.capture_message("Hello from Ruby") # => String capture ID when accepted
Hawk.flush(timeout: 5.0) # => true when pending delivery attempts finish

Run it with bundle exec ruby report.rb. A capture ID confirms local acceptance; it does not confirm receipt by Hawk.

After Hawk initialization, add this example to your application's checkout.rb:

Hawk.set_context(component: "checkout")
Hawk.set_user(id: "customer-42")
Hawk.add_breadcrumb(message: "Payment started", category: "checkout")
Hawk.capture { raise "Checkout failed" } # raises RuntimeError after reporting

Hawk.capture reports an escaping exception and raises the same exception again. You can also call Hawk.capture_exception(error) from a rescue handler.

A missing or empty token disables reporting. A malformed nonempty token raises Hawk::ConfigurationError during initialization.

Use require: "hawk/rails" in your Gemfile for Rails. Initialize Hawk in config/initializers/hawk.rb before workers start.

Rails enables request capture, Rails.error, Action Cable, Active Job, and safe notification breadcrumbs. Solid Queue works through Active Job.

Add the relevant adapter requires to your application's startup file:

require "hawk/rack"
require "hawk/rake"
require "hawk/sidekiq"
require "hawk/resque"
require "hawk/delayed_job"

Rails also detects loaded job backends during initialization. The adapters preserve native retries, arguments, and failure storage.

See integrations for placement, supported versions, propagation limits, and exclusions.

See configuration for settings and API documentation to build the YARD reference.

The default client uses one background thread and a queue of 100 events. Capture never waits for queue space. Each delivery makes one bounded HTTP attempt.

The queue is held in memory. An accepted capture ID confirms local acceptance. flush confirms that pending attempts finished, including failed attempts.

Request bodies, headers, cookies, and job arguments are excluded by default. Sensitive keys are filtered before hooks run. Review configuration before enabling additional data.

Source snippets are enabled within configured source roots. Set send_source = false to exclude them.

bundle exec rake check:fast
bundle exec rake check:docs
bundle exec rake check:coverage
bundle exec rake check:crap
bundle exec rake check:audit
bundle exec rake test:package

Coverage runs the 13 compatibility lanes for the current Ruby. Install their bundles first with bundle install --gemfile gemfiles/NAME.gemfile.

The CI workflow defines 39 runtime combinations across Ruby 3.3, 3.4, and 4.0. It enforces complete types, 100% line and branch coverage, and measured CRAP scores at most 10.

Use bundle exec rake check:complexity for local complexity feedback without coverage. See verification for observed results and remaining acceptance gaps.

MIT. See LICENSE.

Leonid Svyatov maintains Hawk Ruby. Use GitHub issues for questions and defect reports.

Read the changelog for releases and the contributing guide to propose a change.