crystal reference: Documentation for the Honeybadger Crystal client library (SDK) and platform. # Honeybadger for Crystal > Honeybadger monitors your Crystal applications for errors and exceptions so that you can fix them wicked fast. **Typical installation time:** \~2 minutes Hi there! You’ve found Honeybadger’s guide to **Crystal exception and error tracking**. Once installed, Honeybadger will automatically report errors in your Crystal application. ## Getting started [Section titled “Getting started”](#getting-started) [Source Code](https://github.com/honeybadger-io/honeybadger-crystal) ### Installation [Section titled “Installation”](#installation) Update your `shard.yml` to include honeybadger: ```diff dependencies: honeybadger: github: honeybadger-io/honeybadger-crystal ``` Configure your API key (available under Project Settings in Honeybadger): ```crystal Honeybadger.configure do |config| config.api_key = ENV["HONEYBADGER_API_KEY"]? || "PROJECT_API_KEY" config.environment = ENV["HONEYBADGER_ENVIRONMENT"]? || "production" end ``` ### Reporting errors [Section titled “Reporting errors”](#reporting-errors) #### Reporting errors in web frameworks [Section titled “Reporting errors in web frameworks”](#reporting-errors-in-web-frameworks) If you’re using a web framework, add the `Honeybadger::Handler` to the `HTTP::Server` stack: ```crystal HTTP::Server.new([Honeybadger::Handler.new]) do |context| # ... end ``` Details for adding the handler to: ##### Reporting errors in [Lucky Framework](https://luckyframework.org) [Section titled “Reporting errors in Lucky Framework”](#reporting-errors-in-lucky-framework) 1. Add the shard to `shard.yml` 2. Add `Honeybadger::AuthenticHandler` to your middleware stack: ```crystal 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](https://luckyframework.org/guides/http-and-routing/http-handlers). ##### Reporting errors in [Amber Framework](https://amberframework.org) [Section titled “Reporting errors in Amber Framework”](#reporting-errors-in-amber-framework) Read more about Pipelines in Amber [here](https://docs.amberframework.org/amber/guides/routing/pipelines#sharing-pipelines). #### Reporting errors manually [Section titled “Reporting errors manually”](#reporting-errors-manually) For non-web contexts, or to manually report exceptions to Honeybadger, use `Honeybadger.notify`: ```crystal begin # run application code raise "OH NO!" rescue exception Honeybadger.notify(exception) end ``` ### Identifying users [Section titled “Identifying users”](#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: ```crystal # 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](https://github.com/honeybadger-io/honeybadger-crystal/blob/main/demo/http_context.cr) [Learn more about context data in Honeybadger](https://docs.honeybadger.io/guides/errors/#context-data) ### Sending events to Honeybadger Insights [Section titled “Sending events to Honeybadger Insights”](#sending-events-to-honeybadger-insights) You can send custom events to [Honeybadger Insights](https://docs.honeybadger.io/guides/insights/) to track important business metrics and user actions in your application: ```crystal # 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 [Section titled “Configuration”](#configuration) To set configuration options, use the `Honeybadger.configure` method: ```crystal 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](https://github.com/honeybadger-io/honeybadger-crystal/blob/main/src/honeybadger/configuration.cr) ### Environment based config [Section titled “Environment based config”](#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: ```plaintext env HONEYBADGER_API_KEY=2468 ./server ``` All environment variables are documented in the configuration table above. ## Version requirements [Section titled “Version requirements”](#version-requirements) Crystal > 0.36.1