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"]? || "{{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

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

Sending Events to Honeybadger Insights

You can send custom events to Honeybadger Insights to track important business metrics and user actions in your application:

# Send a simple event
Honeybadger.event(name: "user.signup")

# Send an event with properties
Honeybadger.event(
  name: "order.completed",
  total: 99.99,
  items: ["book", "shirt"],
  user_id: 123
)

Events are buffered and sent in batches to optimize performance. The buffer is flushed when either:

60 seconds have elapsed
The buffer size exceeds 5MB

Events are sent asynchronously by default, so they won't block your application's execution.

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:

| 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