Honeybadger for Crystal

HTTP::Handler and exception notifier for the ⚡️ Honeybadger error notifier.

Resources

The change log for this shard is included in this repository: https://github.com/honeybadger-io/honeybadger-crystal/blob/main/CHANGELOG.md

Getting Started

Installation

Update your shard.yml to include honeybadger:

dependencies:
+  honeybadger:
+    github: honeybadger-io/honeybadger-crystal

Configure your API key (available under Project Settings in Honeybadger):

Honeybadger.configure do |config|
  config.api_key = ENV["HONEYBADGER_API_KEY"]? || "{{PROJECT_API_KEY}}"
  config.environment = ENV["HONEYBADGER_ENVIRONMENT"]? || "production"
end

Reporting Errors

Reporting Errors in Web Frameworks

If you're using a web framework, add the Honeybadger::Handler to the HTTP::Server stack:

HTTP::Server.new([Honeybadger::Handler.new]) do |context|
  # ...
end

Details for adding the handler to:

Reporting errors in Lucky Framework

1. Add the shard to shard.yml

2. Add Honeybadger::AuthenticHandler to your middleware stack:

   require "honeybadger"
   require "honeybadger/framework_handlers/authentic_handler.cr"
   
   def middleware : Array(HTTP::Handler)
     [
       # ...
       Lucky::ErrorHandler.new(action: Errors::Show),
       Honeybadger::AuthenticHandler.new,
       # ...
     ] of HTTP::Handler
   end
   

Read more about HTTP Handlers in Lucky here.

Reporting errors in Amber Framework

Read more about Pipelines in Amber here.

Reporting Errors Manually

For non-web contexts, or to manually report exceptions to Honeybadger, use Honeybadger.notify:

begin
  # run application code
  raise "OH NO!"
rescue exception
  Honeybadger.notify(exception)
end

Identifying Users

Honeybadger can track what users have encountered each error. To identify the current user in error reports, add a user identifier and/or email address to Honeybadger's context hash:

# Explicit Context
Honeybadger.notify(exception, context: {
  "user_id" => user.id,
  "user_email" => "user@example.com"
})

# Managed Context
Honeybadger.context(user_id: user.id)

For an example of identifying users in HTTP handlers, see demo/http_context.cr

Learn more about context data in Honeybadger

Configuration

To set configuration options, use the Honeybadger.configure method:

Honeybadger.configure do |config|
  config.api_key = "{{PROJECT_API_KEY}}"
  config.environment = "production"
end

The following configuration options are available:

Documentation for context variables can be found in the Configuration class

Environment based config

Honeybadger can also be configured from environment variables. Each variable has a correlated environment variable and is prefixed with HONEYBADGER_. For example:

env HONEYBADGER_API_KEY=2468 ./server

All environment variables are documented in the configuration table above.

Version Requirements

Crystal > 0.36.1

Development

The packaged demo app creates a minimal http server which responds to /raise by generating an exception.

To run the demo app, raise an exception, and send it to the honeybadger API:

• HONEYBADGER_API_KEY=nnnnnnnn script/demo