Honeybadger for Crystal

HTTP::Handler and exception notifier for the :zap: 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"]? || "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

Add the shard to shard.yml

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" => "[email protected]"
})

# 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 = "API Key"
  config.environment = "production"
end

The following configuration options are available:

| Name | Type | Default | Example | Environment Var | | ----- | ---- | ------- | ------- | --------------- | | api_key | String | "" | "badgers" | HONEYBADGER_API_KEY | | endpoint | Path|String | "https://api.honeybadger.io" | "https://honeybadger.example.com/" | HONEYBADGER_ENDPOINT | | hostname | String | The hostname of the current server. | "badger" | HONEYBADGER_HOSTNAME | | project_root | String | The current working directory | "/path/to/project" | HONEYBADGER_PROJECT_ROOT | | report_data | bool | true | false | HONEYBADGER_REPORT_DATA | | development_environments | Array(String) | ["development","test"] | | HONEYBADGER_DEVELOPMENT_ENVIRONMENTS | | environment | String? | nil | "production" | HONEYBADGER_ENVIRONMENT | | merge_log_context | bool | true | false | n/a |

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

CrystalDoc.info

honeybadger