This is the full developer documentation for Honeybadger.io
# Honeybadger Docs
> Official Honeybadger documentation.
Honeybadger provides error tracking, uptime monitoring, logging, and application performance insights in one simple platform that helps developers understand and fix issues faster.
## Product guides
[Section titled “Product guides”](#product-guides)
[Error monitoring ](/guides/errors/)Get notified when errors occur in your applications
[Insights & Logging ](/guides/insights/)Analyze logs, error trends, patterns, and more
[Dashboards & APM ](/guides/dashboards/)Customize your monitoring dashboards to spot trends
[Uptime monitoring ](/guides/uptime/)Get notified when your API and website are unresponsive
[Check-ins ](/guides/check-ins/)Tracking pings from scheduled tasks and cron jobs
[Deployments ](/guides/deployments/)Viewing and tracking deployments
[Status pages ](/guides/status-pages/)Give users insight into your system status
[Reports ](/guides/reports/)Viewing and understanding reports
[Accounts ](/guides/accounts/)Manage billing and users
[Projects ](/guides/projects/)Projects contain your errors, check-ins & uptime
[Integrations ](/guides/integrations/)Connect Honeybadger to your favorite tools
[User Management ](/guides/user-management/)User membership for project, teams, and accounts
[User Settings ](/guides/user-settings/)Your personal preferences
[Heroku ](/guides/heroku/)Honeybadger + Heroku <3
## Client libraries (SDKs)
[Section titled “Client libraries (SDKs)”](#client-libraries-sdks)
[ Ruby ](/lib/ruby/)
[ JavaScript ](/lib/javascript/)
[ PHP ](/lib/php/)
[ Python ](/lib/python/)
[ Elixir ](/lib/elixir/)
[ Java ](/lib/java/)
[ Go ](/lib/go/)
[ Cocoa ](/lib/cocoa/)
[ .NET/C# ](/lib/dotnet/)
[ Crystal ](/lib/crystal/)
[ Clojure ](/lib/clojure/)
[ Other platforms ](/lib/other/)
# API documentation
> Complete API documentation for Honeybadger's REST and reporting APIs.
Honeybadger’s APIs allow you to report exceptions from your applications, monitor your scheduled tasks, and retrieve and update the data we generate from your app’s errors.
## Reporting
[Section titled “Reporting”](#reporting)
These endpoints are the core of Honeybadger and how you get your data into our system.
[Exceptions ](/api/reporting-exceptions/)`api.honeybadger.io/v1/notices`
[Check-Ins ](/api/reporting-check-ins/)`api.honeybadger.io/v1/check_in/:id`
[Deployments ](/api/reporting-deployments/)`api.honeybadger.io/v1/deploys`
[Source Maps ](/api/reporting-source-maps/)`api.honeybadger.io/v1/source_maps`
[Events ](/api/reporting-events/)`api.honeybadger.io/v1/events`
## Data API
[Section titled “Data API”](#data-api)
The Data API can be used to access data stored in your Honeybadger account and to make changes to your account data.
[Faults ](/api/faults/)
[Uptime ](/api/uptime/)
[Check-Ins ](/api/check-ins/)
[Comments ](/api/comments/)
[Deployments ](/api/deployments/)
[Projects ](/api/projects/)
[Teams ](/api/teams/)
[Environments ](/api/environments/)
[Accounts ](/api/accounts/)
[Status Pages ](/api/status-pages/)
# Accounts API reference
> API reference for managing account information and users.
In Honeybadger, all resources are tied to an account. A user may belong to one or more accounts (for instance, you can have a work account and a personal account). The Accounts API allows you to programmatically fetch details about your accounts.
## Get all accounts
[Section titled “Get all accounts”](#get-all-accounts)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/
```
Returns a list of all accounts the authenticated user belongs to.
```json
{
"results": [
{
"id": "Me3upk",
"email": "homerjsimpson@gmail.com",
"name": "homer",
"active": true,
"parked": false
},
{
"id": "9bYfrm",
"email": "homer.j@simpsons.io",
"name": "Work",
"active": true,
"parked": false
}
],
"links": {
"self": "http://localhost:3000/v2/accounts"
}
}
```
## Get info for one account
[Section titled “Get info for one account”](#get-info-for-one-account)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ID
```
Returns info about an account, including the quota consumption for the current month. Each of the three sets of quota info is returned as an array of arrays, with one date & count pair for each day of the month, starting at midnight UTC on the first of the month. The different types of stats are as follows:
* Stored: The number of error notifications saved and available for display in the UI
* Limited: The number of notifications that were discarded due to throttling (429 responses)
* Ignored: Notifications discarded as a result of errors being flagged as ignored in the UI
The quota\_consumed value is a percentage, so `0.75` would mean 75% of the month’s quota has been consumed. The quota resets at the first of the month.
```json
{
"id": "Me3upk",
"email": "homerjsimpson@gmail.com",
"name": "homer",
"active": true,
"parked": false,
"quota_consumed": 0.75,
"api_stats": {
"stored": [
[ 1648767600, 116 ],
[ 1648771200, 65 ],
...
],
"limited": [],
"ignored": []
}
}
```
## Get a list of account users or user details
[Section titled “Get a list of account users or user details”](#get-a-list-of-account-users-or-user-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ID/users
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ID/users/ID
```
Returns all the users or a single user for the given account:
```json
{
"results": [
{
"id": 1,
"role": "Owner",
"name": "",
"email": "westley@honeybadger.io"
}
]
}
```
## Update a user
[Section titled “Update a user”](#update-a-user)
```bash
curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"user":{"role":"Admin"}}' https://app.honeybadger.io/v2/accounts/ID/users/ID
```
The list of valid fields is as follows:
| Field name | Type | Description |
| ---------- | ------ | ----------------------------------------------- |
| `role` | string | One of “Member”, “Billing”, “Admin”, or “Owner” |
## Remove a user from the account
[Section titled “Remove a user from the account”](#remove-a-user-from-the-account)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/accounts/ID/users/ID
```
## Create an invitation for a user to join an account
[Section titled “Create an invitation for a user to join an account”](#create-an-invitation-for-a-user-to-join-an-account)
```bash
curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' \
-d '{"invitation":{"email":"inigo@honeybadger.io"}}' \
https://app.honeybadger.io/v2/accounts/ID/invitations
```
You can specify these fields:
| Field name | Type | Description |
| ---------- | ------ | --------------------------------------------------------- |
| `email` | string | The invited user’s email address. |
| `role` | string | One of “Member”, “Billing”, “Admin”, or “Owner” |
| `team_ids` | array | Array of team ids to which the invited user will be added |
Returns the created user invitation:
```json
{
"id": 9,
"token": "e62394d2",
"email": "inigo@honeybadger.io",
"created_by": {
"email": "westley@honeybadger.io",
"name": "Westley"
},
"accepted_by": null,
"role": "Member",
"accepted_at": null,
"created_at": "2013-01-08T15:42:16Z",
"team_ids": []
}
```
## Update an account invitation
[Section titled “Update an account invitation”](#update-an-account-invitation)
```bash
curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' \
-d '{"invitation":{"role": "Admin"}}' \
https://app.honeybadger.io/v2/accounts/ID/invitations/ID
```
You can specify either of these fields:
| Field name | Type | Description |
| ---------- | ------ | --------------------------------------------------------- |
| `role` | string | One of “Member”, “Billing”, “Admin”, or “Owner” |
| `team_ids` | array | Array of team ids to which the invited user will be added |
## Get an account invitation list or account invitation details
[Section titled “Get an account invitation list or account invitation details”](#get-an-account-invitation-list-or-account-invitation-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ID/invitations
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ID/invitations/ID
```
Returns a list of account invitations or a single account invitation for the given account:
```json
{
"results": [
{
"id": 9,
"token": "e62394d2",
"email": "",
"created_by": {
"email": "westley@honeybadger.io",
"name": "Westley"
},
"accepted_by": {
"email": "inigo@honeybadger.io",
"name": "Inigo Montoya"
},
"role": "Member",
"accepted_at": "2013-01-08T15:42:41Z",
"created_at": "2013-01-08T15:42:16Z",
"team_ids": []
}
]
}
```
## Delete an account invitation
[Section titled “Delete an account invitation”](#delete-an-account-invitation)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/accounts/ID/invitations/ID
```
# Check-ins API reference
> API reference for managing check-ins with endpoints to create, read, update, and delete scheduled task and cron monitors.
## Get a check-in list or check-in details
[Section titled “Get a check-in list or check-in details”](#get-a-check-in-list-or-check-in-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/check_ins
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/check_ins/ID
```
Returns a list of check-ins or a single check-in for a project. There are two different types of check-ins, simple or cron, and the response varies a bit between the two types.
### Simple check-in
[Section titled “Simple check-in”](#simple-check-in)
```json
{
"state": "pending",
"schedule_type": "simple",
"reported_at": null,
"expected_at": null,
"missed_count": 0,
"grace_period": "5 minutes",
"id": "XXXXXX",
"name": "Hourly clean up",
"slug": "hourly-clean-up",
"url": "https://api.honeybadger.io/v1/check_in/XXXXXX",
"report_period": "1 hour"
}
```
### Cron check-in
[Section titled “Cron check-in”](#cron-check-in)
```json
{
"state": "reporting",
"schedule_type": "cron",
"reported_at": "2018-01-16T12:36:11Z",
"expected_at": "2018-01-17T12:36:11Z",
"missed_count": 0,
"grace_period": "",
"id": "YYYYYY",
"name": "Hourly check",
"slug": "hourly-check",
"url": "https://api.honeybadger.io/v1/check_in/YYYYYY",
"cron_schedule": "30 * * * *",
"cron_timezone": "UTC"
}
```
## Create a check-in
[Section titled “Create a check-in”](#create-a-check-in)
```bash
curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"check_in":{"name":"Daily reports", "report_period":"1 day", "schedule_type":"simple"}}' https://app.honeybadger.io/v2/projects/ID/check_ins
```
This endpoint returns either the simple or cron check-in response described above, depending on the type of check-in you create.
These fields can be provided:
| Field name | Type | Description |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | |
| slug | string | Optional identifier for more human-friendly check-in URL. |
| schedule\_type | string | Valid values are “simple” or “cron”. If you specify “cron”, then the “cron\_schedule” field is required. |
| report\_period | string | For simple check-ins, the amount of time that can elapse before the check-in is reported as missing. E.g., “1 day” would require a hit to the API daily to maintain the “reporting” status. Valid time periods are “minute”, “hour”, “day”, “week”, and “month”: “5 minutes”, “7 days”, etc. |
| grace\_period | string | The amount of time to allow a job to not report before it’s reported as missing. Valid values are the same as the report\_period field. |
| cron\_schedule | string | For a `schedule_type` of “cron”, the [cron-compatible string](https://en.wikipedia.org/wiki/Cron#Overview) that defines when the job should be expected to hit the API. |
| cron\_timezone | string | The timezone setting for your server that is running the cron job to be monitored. The default value is “UTC”. Valid timezone values are listed [here](./timezones). |
## Update a check-in
[Section titled “Update a check-in”](#update-a-check-in)
```bash
curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"check_in":{"name":"Updated check-in name"}}' https://app.honeybadger.io/v2/projects/ID/check_ins/ID
```
The fields listed in the previous section other than `schedule_type` can be updated. In other words, the schedule type can’t be changed. The `report_period` field is only valid for simple check-ins, and the `cron_schedule` and `cron_timezone` fields are only valid for cron check-ins.
## Update all check-ins
[Section titled “Update all check-ins”](#update-all-check-ins)
Caution
Use this endpoint with caution, as it will delete all existing check-ins if you send an empty payload.
```bash
curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"check_ins":[{"name":"Updated check-in name", "slug":"my-slug"}]}' https://app.honeybadger.io/v2/projects/ID/check_ins
```
Similar to updating a single check-in, this endpoint can be used to update multiple check-ins at once. All check-ins need to be unique by slug and by name (if provided). Any check-ins that do not have a matching slug or name will be created, and any check-ins that are not present in the request will be deleted.
The results will be an array of the updated check-ins and any check-ins that were created or deleted. The response will look like this:
```json
{
"results": [
{
"operation": "update",
"slug": "my-changed-slug",
"success": true
},
{
"operation": "create",
"slug": "my-changed-slug",
"success": false,
"errors": ["Slug is not unique"]
},
{
"operation": "delete",
"slug": "my-deleted-slug",
"success": true
}
]
}
```
## Delete a check-in
[Section titled “Delete a check-in”](#delete-a-check-in)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/check_ins/ID
```
# Check-in timezone values
> Complete list of supported timezones for Honeybadger check-in scheduling and cron monitoring configuration.
Use the friendly name (like Pacific Time (US & Canada) instead of America/Los\_Angeles) when working with the API. The other labels are provided here for search-ability. 🙂
| Value for `cron_timezone` (use this) | AKA (don’t use this) |
| ------------------------------------ | ------------------------------- |
| UTC | Etc/UTC |
| Abu Dhabi | Asia/Muscat |
| Adelaide | Australia/Adelaide |
| Alaska | America/Juneau |
| Almaty | Asia/Almaty |
| American Samoa | Pacific/Pago\_Pago |
| Amsterdam | Europe/Amsterdam |
| Arizona | America/Phoenix |
| Astana | Asia/Dhaka |
| Athens | Europe/Athens |
| Atlantic Time (Canada) | America/Halifax |
| Auckland | Pacific/Auckland |
| Azores | Atlantic/Azores |
| Baghdad | Asia/Baghdad |
| Baku | Asia/Baku |
| Bangkok | Asia/Bangkok |
| Beijing | Asia/Shanghai |
| Belgrade | Europe/Belgrade |
| Berlin | Europe/Berlin |
| Bern | Europe/Zurich |
| Bogota | America/Bogota |
| Brasilia | America/Sao\_Paulo |
| Bratislava | Europe/Bratislava |
| Brisbane | Australia/Brisbane |
| Brussels | Europe/Brussels |
| Bucharest | Europe/Bucharest |
| Budapest | Europe/Budapest |
| Buenos Aires | America/Argentina/Buenos\_Aires |
| Cairo | Africa/Cairo |
| Canberra | Australia/Melbourne |
| Cape Verde Is. | Atlantic/Cape\_Verde |
| Caracas | America/Caracas |
| Casablanca | Africa/Casablanca |
| Central America | America/Guatemala |
| Central Time (US & Canada) | America/Chicago |
| Chatham Is. | Pacific/Chatham |
| Chennai | Asia/Kolkata |
| Chihuahua | America/Chihuahua |
| Chongqing | Asia/Chongqing |
| Copenhagen | Europe/Copenhagen |
| Darwin | Australia/Darwin |
| Dhaka | Asia/Dhaka |
| Dublin | Europe/Dublin |
| Eastern Time (US & Canada) | America/New\_York |
| Edinburgh | Europe/London |
| Ekaterinburg | Asia/Yekaterinburg |
| Fiji | Pacific/Fiji |
| Georgetown | America/Guyana |
| Greenland | America/Godthab |
| Guadalajara | America/Mexico\_City |
| Guam | Pacific/Guam |
| Hanoi | Asia/Bangkok |
| Harare | Africa/Harare |
| Hawaii | Pacific/Honolulu |
| Helsinki | Europe/Helsinki |
| Hobart | Australia/Hobart |
| Hong Kong | Asia/Hong\_Kong |
| Indiana (East) | America/Indiana/Indianapolis |
| International Date Line West | Etc/GMT+12 |
| Irkutsk | Asia/Irkutsk |
| Islamabad | Asia/Karachi |
| Istanbul | Europe/Istanbul |
| Jakarta | Asia/Jakarta |
| Jerusalem | Asia/Jerusalem |
| Kabul | Asia/Kabul |
| Kaliningrad | Europe/Kaliningrad |
| Kamchatka | Asia/Kamchatka |
| Karachi | Asia/Karachi |
| Kathmandu | Asia/Kathmandu |
| Kolkata | Asia/Kolkata |
| Krasnoyarsk | Asia/Krasnoyarsk |
| Kuala Lumpur | Asia/Kuala\_Lumpur |
| Kuwait | Asia/Kuwait |
| Kyiv | Europe/Kiev |
| La Paz | America/La\_Paz |
| Lima | America/Lima |
| Lisbon | Europe/Lisbon |
| Ljubljana | Europe/Ljubljana |
| London | Europe/London |
| Madrid | Europe/Madrid |
| Magadan | Asia/Magadan |
| Marshall Is. | Pacific/Majuro |
| Mazatlan | America/Mazatlan |
| Melbourne | Australia/Melbourne |
| Mexico City | America/Mexico\_City |
| Mid-Atlantic | Atlantic/South\_Georgia |
| Midway Island | Pacific/Midway |
| Minsk | Europe/Minsk |
| Monrovia | Africa/Monrovia |
| Monterrey | America/Monterrey |
| Montevideo | America/Montevideo |
| Moscow | Europe/Moscow |
| Mountain Time (US & Canada) | America/Denver |
| Mumbai | Asia/Kolkata |
| Muscat | Asia/Muscat |
| Nairobi | Africa/Nairobi |
| New Caledonia | Pacific/Noumea |
| New Delhi | Asia/Kolkata |
| Newfoundland | America/St\_Johns |
| Novosibirsk | Asia/Novosibirsk |
| Nuku’alofa | Pacific/Tongatapu |
| Osaka | Asia/Tokyo |
| Pacific Time (US & Canada) | America/Los\_Angeles |
| Paris | Europe/Paris |
| Perth | Australia/Perth |
| Port Moresby | Pacific/Port\_Moresby |
| Prague | Europe/Prague |
| Pretoria | Africa/Johannesburg |
| Puerto Rico | America/Puerto\_Rico |
| Quito | America/Lima |
| Rangoon | Asia/Rangoon |
| Riga | Europe/Riga |
| Riyadh | Asia/Riyadh |
| Rome | Europe/Rome |
| Samara | Europe/Samara |
| Samoa | Pacific/Apia |
| Santiago | America/Santiago |
| Sapporo | Asia/Tokyo |
| Sarajevo | Europe/Sarajevo |
| Saskatchewan | America/Regina |
| Seoul | Asia/Seoul |
| Singapore | Asia/Singapore |
| Skopje | Europe/Skopje |
| Sofia | Europe/Sofia |
| Solomon Is. | Pacific/Guadalcanal |
| Srednekolymsk | Asia/Srednekolymsk |
| Sri Jayawardenepura | Asia/Colombo |
| St. Petersburg | Europe/Moscow |
| Stockholm | Europe/Stockholm |
| Sydney | Australia/Sydney |
| Taipei | Asia/Taipei |
| Tallinn | Europe/Tallinn |
| Tashkent | Asia/Tashkent |
| Tbilisi | Asia/Tbilisi |
| Tehran | Asia/Tehran |
| Tijuana | America/Tijuana |
| Tokelau Is. | Pacific/Fakaofo |
| Tokyo | Asia/Tokyo |
| Ulaanbaatar | Asia/Ulaanbaatar |
| Urumqi | Asia/Urumqi |
| Vienna | Europe/Vienna |
| Vilnius | Europe/Vilnius |
| Vladivostok | Asia/Vladivostok |
| Volgograd | Europe/Volgograd |
| Warsaw | Europe/Warsaw |
| Wellington | Pacific/Auckland |
| West Central Africa | Africa/Algiers |
| Yakutsk | Asia/Yakutsk |
| Yerevan | Asia/Yerevan |
| Zagreb | Europe/Zagreb |
| Zurich | Europe/Zurich |
# Comments API reference
> API reference for managing error comments with endpoints to create, read, update, and delete resources.
## Get a comment list or comment details
[Section titled “Get a comment list or comment details”](#get-a-comment-list-or-comment-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/comments
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/comments/ID
```
Returns a list of comments or a single comment for the given fault with the following format:
```json
{
"id": 14,
"fault_id": 2,
"event": null,
"source": "unknown",
"notices_count": 0,
"created_at": "2012-08-22T15:47:26Z",
"author": "Inigo",
"body": "You killed my father; prepare to die"
}
```
## Create a comment
[Section titled “Create a comment”](#create-a-comment)
```bash
curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"comment":{"body":"My comment"}}' https://app.honeybadger.io/v2/projects/ID/faults/ID/comments
```
The `body` field is the only field that can be included in the payload.
## Update a comment
[Section titled “Update a comment”](#update-a-comment)
```bash
curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"comment":{"body":"Updated comment"}}' https://app.honeybadger.io/v2/projects/ID/faults/ID/comments/ID
```
## Delete a comment
[Section titled “Delete a comment”](#delete-a-comment)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/faults/ID/comments/ID
```
# Deployments API reference
> API reference for managing deployments with endpoints to read and delete resources.
## Get a deploy list or deploy details
[Section titled “Get a deploy list or deploy details”](#get-a-deploy-list-or-deploy-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/deploys
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/deploys/ID
```
Returns a list of deploys or a single deploy for the given project with the following format:
```json
{
"created_at": "2013-04-30T13:12:51Z",
"environment": "production",
"local_username": "deploy",
"project_id": 1,
"repository": "some/repo",
"revision": "2013-04-29-take-2-16-g6cf7eae"
}
```
The deploy list can be filtered with a number of URL parameters:
| Parameter | Description |
| ---------------- | --------------------------------------------------------- |
| `environment` | A string with the desired environment, e.g., ‘production’ |
| `local_username` | Username of the person doing the deployment |
| `created_after` | A Unix timestamp (number of seconds since the epoch) |
| `created_before` | A Unix timestamp (number of seconds since the epoch) |
| `limit` | Number of results to return (max and default are 25) |
The deploy list is always ordered by creation time descending.
## Delete a deploy
[Section titled “Delete a deploy”](#delete-a-deploy)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/deploys/ID
```
# Environments API reference
> API reference for managing environments with endpoints to retrieve and configure environment-specific settings.
In Honeybadger, errors are grouped by the environment they occurred in. When an error is reported with a new environment, the environment is automatically stored, so you can search and filter by it in the future. You can also add, remove and manage your projects’ environments via the API.
## Get all environments
[Section titled “Get all environments”](#get-all-environments)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/PROJECT_ID/environments
```
Returns a list of all recorded environments in this project.
```json
{
"results": [
{
"id": 1,
"project_id": 1,
"name": "production",
"notifications": true,
"created_at": "2021-08-10T13:56:29.513358Z",
"updated_at": "2021-08-10T13:56:29.513358Z"
}
],
"links": {
"self": "http://localhost:3000/v2/projects/1/environments"
}
}
```
## Get a single environment’s details
[Section titled “Get a single environment’s details”](#get-a-single-environments-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/PROJECT_ID/environments/ID
```
```json
{
"id": 1,
"project_id": 1,
"name": "production",
"notifications": true,
"created_at": "2021-08-10T13:56:29.513358Z",
"updated_at": "2021-08-10T13:56:29.513358Z"
}
```
## Create an environment
[Section titled “Create an environment”](#create-an-environment)
```bash
curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' \
-d '{
"environment": {
"name": "Test",
"notifications": true
}
}' https://app.honeybadger.io/v2/projects/PROJECT_ID/environments
```
You can specify these fields within the `environment` object:
| Field name | Type | Description |
| --------------- | ------- | ---------------------------------------------------------------------- |
| `name` | string | The name of the environment |
| `notifications` | boolean | (Optional) Enable notifications for this environment. Default: `true`. |
Returns a 201 Created response containing the created environment’s details.
## Update an environment
[Section titled “Update an environment”](#update-an-environment)
```bash
curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' \
-d '{
"environment": {
"name": "Staging",
"notifications": false
}
}' https://app.honeybadger.io/v2/projects/PROJECT_ID/environments/ID
```
You can specify any of these fields within the `environment` object:
| Field name | Type | Description |
| --------------- | ------- | ----------------------------------------- |
| `name` | string | The name of the environment |
| `notifications` | boolean | Enable notifications for this environment |
Returns an empty response (204 No Content) if successful.
## Delete an environment
[Section titled “Delete an environment”](#delete-an-environment)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/PROJECT_ID/environments/ID
```
Returns an empty response (204 No Content) if successful.
# Errors API reference
> API reference for managing errors (faults) with endpoints to create, read, update, and delete error data.
Note
A **fault** is synonymous with an **error**, in that it contains a collection of **notices** (individual error events)
## Get a fault list or fault details
[Section titled “Get a fault list or fault details”](#get-a-fault-list-or-fault-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID
```
Returns a list of faults or a single fault for the given project with the following format:
```json
{
"action": "runtime_error",
"assignee": {
"email": "westley@honeybadger.io",
"id": 1,
"name": "Westley"
},
"comments_count": 0,
"component": "pages",
"created_at": "2013-01-22T16:33:22.704628Z",
"environment": "development",
"id": 2,
"ignored": false,
"klass": "RuntimeError",
"last_notice_at": "2013-02-11T19:18:31.991903Z",
"message": "This is a runtime error",
"notices_count": 7,
"project_id": 1,
"resolved": false,
"tags": ["internal"],
"url": "https://app.honeybadger.io/projects/1/faults/2"
}
```
The fault list can be filtered with a number of URL parameters:
| Parameter | Description |
| ----------------- | ---------------------------------------------------- |
| `q` | A [search string](/guides/errors/search/) |
| `created_after` | A Unix timestamp (number of seconds since the epoch) |
| `occurred_after` | A Unix timestamp (number of seconds since the epoch) |
| `occurred_before` | A Unix timestamp (number of seconds since the epoch) |
| `limit` | Number of results to return (max and default are 25) |
The fault list can be ordered with the order parameter in the URL, with the following possible values:
| Value | Description |
| ---------- | --------------------------------------------------------------- |
| `recent` | List the errors that have most recently occurred first |
| `frequent` | List the errors that have received the most notifications first |
The default order is by creation time.
If the search query affects the amount of matched notices, the `notices_count` field may not be accurate. For those cases, we add a `notices_count_in_range` field to the payload which reflects the notice counts with the query applied.
## Get a count of faults
[Section titled “Get a count of faults”](#get-a-count-of-faults)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/summary
```
Returns a total count of all the errors for a project and counts of errors grouped by environment, resolution status, and ignored status. The counts can be filtered by these parameters:
| Parameter | Description |
| ----------------- | ---------------------------------------------------- |
| `q` | A [search string](/guides/errors/search/) |
| `created_after` | A Unix timestamp (number of seconds since the epoch) |
| `occurred_after` | A Unix timestamp (number of seconds since the epoch) |
| `occurred_before` | A Unix timestamp (number of seconds since the epoch) |
For example, to get a count of open faults in production, you would use the `q` parameter to filter the results:
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/summary?q=environment%3Aproduction%20-is%3Aresolved%20-is%3Aignored
```
## Update a fault
[Section titled “Update a fault”](#update-a-fault)
```bash
curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"fault":{"resolved":true}}' https://app.honeybadger.io/v2/projects/ID/faults/ID
```
The following fields can be updated:
| Field name | Type | Description |
| ------------- | ------- | ----------- |
| `resolved` | boolean | |
| `ignored` | boolean | |
| `assignee_id` | integer | |
## Delete a fault
[Section titled “Delete a fault”](#delete-a-fault)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/faults/ID
```
## Get a count of occurrences for a fault
[Section titled “Get a count of occurrences for a fault”](#get-a-count-of-occurrences-for-a-fault)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/occurrences
```
Provides the number of times errors have been encountered for a particular fault.
```json
[
[ 1510963200, 1 ],
[ 1511049600, 0 ],
[ 1511136000, 0 ],
[ 1511222400, 1 ],
...
]
```
The data can be filtered with these URL parameters:
| Parameter | Description |
| --------- | ------------------------------------------------------------ |
| `period` | One of “hour”, “day”, “week”, or “month”. Defaults to “hour” |
## Pausing and unpausing faults
[Section titled “Pausing and unpausing faults”](#pausing-and-unpausing-faults)
You can pause notifications for a period of time or for the number of occurrences of a fault. This doesn’t affect the resolved/unresolved status.
```bash
curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"time":"day"}' https://app.honeybadger.io/v2/projects/ID/faults/ID/pause
curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"count":100}' https://app.honeybadger.io/v2/projects/ID/faults/ID/pause
```
Valid values for `time` are “hour”, “day”, and “week”, and valid values for `count` are 10, 100, and 1000.
You can clear the pause for a fault, or for all of a project’s faults:
```bash
curl -u AUTH_TOKEN: -X POST https://app.honeybadger.io/v2/projects/ID/faults/ID/unpause
curl -u AUTH_TOKEN: -X POST https://app.honeybadger.io/v2/projects/ID/faults/unpause
```
You don’t need to provide a request body for the unpause endpoints. The response body will be empty, and the status code will be 200.
## Bulk-resolving faults
[Section titled “Bulk-resolving faults”](#bulk-resolving-faults)
You can mark all faults for a project as resolved using this endpoint:
```bash
curl -u AUTH_TOKEN: -X POST https://app.honeybadger.io/v2/projects/ID/faults/resolve
```
The faults to be resolved can be filtered with the URL parameter `q`, which is a [search string](/guides/errors/search/).
This endpoint returns a successful response (200) with an empty body when the request is successful.
## Linking faults to existing 3rd-party issues
[Section titled “Linking faults to existing 3rd-party issues”](#linking-faults-to-existing-3rd-party-issues)
```bash
curl -u AUTH_TOKEN: -H 'Content-type: application/json' -d '{"channel_id":123, "data":{"number":42}}' -X POST https://app.honeybadger.io/v2/projects/ID/faults/ID/link
```
This associates an existing GitHub issue, Pivotal Tracker story, etc. with a fault. Once associated, the error detail page in the UI will include a link to the associated issue. The `channel_id` portion of the payload can be obtained from the [integrations](/api/projects#get-a-list-of-integrations-for-a-project) API endpoint. The `data` portion of the payload varies depending on which type of integration is being referenced:
### GitHub
[Section titled “GitHub”](#github)
| Field name | type | Description |
| ---------- | ------- | -------------------------------------------------------------------------------------------- |
| `number` | integer | The issue number at the end of the issue URL: \*\* |
### Jira
[Section titled “Jira”](#jira)
| Field name | type | Description |
| ---------- | ------- | -------------------------------------------------------------------------------------------------- |
| `id` | integer | The issue id at the end of the issue URL: \*\* |
| `key` | string | The issue label: HB-123 |
| `self` | url | The issue URL: |
### Pivotal Tracker
[Section titled “Pivotal Tracker”](#pivotal-tracker)
| Field name | type | Description |
| ------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `story_id` | integer | The story number at the end of the story URL: \*\* |
| `project_id` | integer | The Pivotal Tracker project ID |
| `pivotal_url` | url | The story URL: |
### Trello
[Section titled “Trello”](#trello)
| Field name | type | Description |
| ---------- | ------ | ------------------------------------------------------------------ |
| `id` | string | The card ID, e.g. 60ca3275a482444bcaae2a8a |
| `shortUrl` | url | Shortened version of the card URL: |
This endpoint is also used to update an existing link (e.g., to change the issue number for a linked GitHub issue).
## Unlinking faults
[Section titled “Unlinking faults”](#unlinking-faults)
```bash
curl -u AUTH_TOKEN: -H 'Content-type: application/json' -d '{"channel_id":123}' -X POST https://app.honeybadger.io/v2/projects/ID/faults/ID/unlink
```
This removes the link to an associated GitHub issue, Pivotal Tracker story, etc. The `channel_id` portion of the payload can be obtained from the [integrations](/api/projects/#get-a-list-of-integrations-for-a-project) API endpoint.
## Get a list of notices
[Section titled “Get a list of notices”](#get-a-list-of-notices)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/notices
```
Returns a list of notices for the given fault with the following format:
```json
{
"created_at": "2013-02-11T19:18:31.123931Z",
"environment": {
"environment_name": "development",
"hostname": "apollo.local",
"project_root": {
"path": "/Users/bob/code/crywolf"
}
},
"cookies" { ... },
"fault_id": 2,
"id": "f78391e4-7789-49f0-888e-5f6c07a222f2",
"url": "https://app.honeybadger.io/projects/1/faults/2/d23e5f62-747f-11e2-a65e-4f2716edc8b7"
"message": "RuntimeError: This is a runtime error",
"web_environment": {
"CONTENT_LENGTH": "82",
"CONTENT_TYPE": "application/x-www-form-urlencoded",
"HTTP_USER_AGENT": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_4) AppleWebKit/537.4 (KHTML, like Gecko) Chrome/22.0.1229.79 Safari/537.4",
...
},
"request": {
"action": "runtime_error",
"component": "pages",
"context": {
"cart_id": "8EF99AFC-B4DB-4FC5-A92A-9A6F86ABD364"
},
"params": {
"_method": "post",
"a": "1",
"action": "runtime_error",
"authenticity_token": "...",
"b": "2",
"controller": "pages"
},
"session": {
"_csrf_token": "...",
"session_id": "..."
},
"url": "http://example.com/pages/runtime_error?a=1&b=2",
"user": {
"email": "foo@bar.com",
"id": 1
}
},
"backtrace": [
{
"number": "4",
"file": "/Users/westley/code/crywolf/app/controllers/pages_controller.rb",
"method": "runtime_error"
},
...
],
"application_trace": []
}
```
The notice list can be filtered with these URL parameters:
| Parameter | Description |
| ---------------- | ---------------------------------------------------- |
| `created_after` | A Unix timestamp (number of seconds since the epoch) |
| `created_before` | A Unix timestamp (number of seconds since the epoch) |
| `limit` | Number of results to return (max and default are 25) |
The notice list is always ordered by creation time descending.
## Get a list of affected users
[Section titled “Get a list of affected users”](#get-a-list-of-affected-users)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/faults/ID/affected_users
```
Returns a list of the users who were affected by an error:
```json
[
{
"user": "bob@example.com",
"count": 4
},
{
"user": "ann@example.com",
"count": 1
}
]
```
The data can be filtered with the URL parameter `q`, which is a [search string](/guides/errors/search/).
# Data API
> Get started with Honeybadger's REST API including authentication, rate limits, and basic usage examples.
Our REST Data API can be used to access the data stored in your Honeybadger account and to make changes to your account data. To learn about reporting exception data, deployments, and other events, check out the [API](/api/) documentation.
## Glossary
[Section titled “Glossary”](#glossary)
The resource names used by the API may be different from those used in our web UI. Here is a glossary of the most important resource names:
* **Project:** A container that holds all your data for a single app or service.
* **Fault:** Called an “error” in the web UI. It has many Notices.
* **Notice:** Called an “error occurrence” in the web UI.
* **Site:** Called an “uptime check” in the web UI.
* **CheckIn:** Manages dead-man-switch checks.
* **Team:** Connects Honeybadger users to projects.
* **TeamInvitation:** Invites a user to join a team.
## Authentication
[Section titled “Authentication”](#authentication)
Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). Each request should be sent with your personal authentication token (available from [your profile page](https://app.honeybadger.io/users/edit)) as the basic auth username value. You do not need to provide a password.
For example, you can request your projects list with `curl` like so (the trailing colon after the token prevents curl from asking for a password):
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects
```
## Rate limiting
[Section titled “Rate limiting”](#rate-limiting)
You can make up to 360 requests per hour to our API. After you reach the limit for the hour, additional requests will receive a response with the 403 (Forbidden) status code. The following headers, returned with every API response, can provide you the information about your rate limit:
| Header | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `X-RateLimit-Limit` | The number of requests that you can make per hour |
| `X-RateLimit-Remaining` | The number of requests you can make before getting an error |
| `X-RateLimit-Reset` | A Unix timestamp (number of seconds since the epoch) when remaining requests counter will be reset to the maximum |
## Format
[Section titled “Format”](#format)
The API returns JSON by default, but you should include `Accept: application/json` in your request headers. Lists of items are always paginated, even if there is only one page of results. The general response format for a list is as follows:
```json
{
"links": {
"self": "https://app.honeybadger.io/v2/...",
"next": "https://app.honeybadger.io/v2/..."
}
"results": [
{ ... },
{ ... }
]
}
```
You can get the page after the current page by loading the value found in the `next` element of the `links` hash and the page before the current page by loading the value found in the `prev` element of the links hash. Either or both of those elements may be missing from the links hash if we can determine there is no next page or previous page of results. On the other hand, there may be a next link that, when loaded, results in no records being found — in which case, the `results` top-level element will be an empty array.
## Requests and responses
[Section titled “Requests and responses”](#requests-and-responses)
When you create or update resources, send the request (via POST for creations or PUT for updates) with the `Content-type` header as application/json, the `Accept` header as application/json and the request body as a valid json object. No request body is required for deleting a resource via the DELETE method.
A successful POST request will return a 201 status code and the JSON representation of the just-created resource as the response body.
A PUT request that successfully updates an object will return a 204 status code with no response body.
Responses for successful DELETE requests return a status code of 204 and an empty response body.
Requests that result in errors will return a JSON response body like so:
```json
{ "errors": "Reason for error" }
```
The status code will be 403 if there is a permissions problem, 422 if the request was invalid, or in the 500 range if something unexpected happened.
# Projects API reference
> API reference for managing projects with endpoints to create, retrieve, update, and delete resources, and fetch reports.
## Get a project list or project details
[Section titled “Get a project list or project details”](#get-a-project-list-or-project-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects?account_id=ACCOUNT_ID
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID
```
Returns a list or a single project with the following format:
```json
{
"active": true,
"created_at": "2012-06-09T20:33:27.798800Z",
"earliest_notice_at": "2015-12-18T19:30:32.470689Z",
"environments": ["development", "production"],
"fault_count": 14,
"id": 1,
"last_notice_at": "2016-06-14T18:31:54.000000Z",
"name": "Rails exception tracking gem",
"owner": {
"email": "westley@honeybadger.io",
"id": 1,
"name": "Westley"
},
"sites": [
{
"active": true,
"id": "9eed6a7e-af77-4cc6-8c55-7a5afa59a90b",
"last_checked_at": "2016-06-15T12:57:29.646956Z",
"name": "Main site",
"state": "up",
"url": "http://www.example.com"
}
],
"teams": [
{
"id": 1,
"name": "Team Marie"
}
],
"token": "098sflj2",
"unresolved_fault_count": 1,
"users": [
{
"email": "inigo@honeybadger.io",
"id": 2,
"name": "Inigo Montoya"
},
{
"email": "westley@honeybadger.io",
"id": 1,
"name": "Westley"
}
]
}
```
If the `account_id` parameter is not supplied when requesting the list of projects, all projects will be returned across all accounts to which the provided AUTH\_TOKEN has access.
## Create a project
[Section titled “Create a project”](#create-a-project)
```bash
curl -u AUTH_TOKEN: \
-X POST \
-H 'Content-type: application/json' \
-d '{"project":{"name":"My project"}}' \
https://app.honeybadger.io/v2/projects?account_id=ACCOUNT_ID
```
Here is a list of the fields that can be provided:
| Field name | Type | Description |
| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | |
| `resolve_errors_on_deploy` | boolean | Whether all unresolved faults should be marked as resolved when a deploy is recorded |
| `disable_public_links` | boolean | Whether to allow fault details to be publicly shareable via a button on the fault detail page |
| `language` | string | One of “js”, “elixir”, “golang”, “java”, “node”, “php”, “python”, “ruby”, or “other” |
| `user_url` | string | A URL format like `"http://example.com/admin/users/[user_id]"` that will be displayed on the fault detail page and have \[user\_id] replaced with the user\_id from the fault’s context hash. |
| `source_url` | string | A URL format like `"https://gitlab.com/username/reponame/blob/[sha]/[file]#L[line]"` that is used to link lines in the backtrace to your git browser. This can be left blank if you provide the repository info in your deploy payloads or if you use the GitHub integration for your project. |
| `purge_days` | integer | The number of days to retain data (up the to max number of days available to your subscription plan). |
| `user_search_field` | string | A field such as “context.user\_email” that you provide in your error context. This field will be used to create the aggregated list of affected users. |
If the `account_id` query parameter is not provided, the project will be associated with the first account accessible by the user associated with the AUTH\_TOKEN.
## Update a project
[Section titled “Update a project”](#update-a-project)
```bash
curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"project":{"name":"Updated project name"}}' https://app.honeybadger.io/v2/projects/ID
```
The fields listed in the prior section are also available when updating a project.
## Delete a project
[Section titled “Delete a project”](#delete-a-project)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID
```
## Get a count of occurrences for all projects or a single project
[Section titled “Get a count of occurrences for all projects or a single project”](#get-a-count-of-occurrences-for-all-projects-or-a-single-project)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/occurrences
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/occurrences
```
Provides the number of times errors have been encountered in your project or across all your projects.
```json
[
[ 1510963200, 1440 ],
[ 1511049600, 1441 ],
[ 1511136000, 1441 ],
[ 1511222400, 1441 ],
...
]
```
The data is returned as an array of epoch seconds/count pairs, and it can be filtered with these URL parameters:
| Parameter | Description |
| ------------- | ------------------------------------------------------------ |
| `period` | One of “hour”, “day”, “week”, or “month”. Defaults to “hour” |
| `environment` | Limit results to this environment |
When the period is “hour” (the default), the data returned is the most recent 60 one-minute buckets. When it is “day”, the data comes from the most recent 24 one-hour buckets, and when it is “week” or “month”, the data is grouped into one-day buckets. All times and bucket boundaries are UTC.
## Get a list of integrations for a project
[Section titled “Get a list of integrations for a project”](#get-a-list-of-integrations-for-a-project)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/integrations
```
Returns a list of integrations (a.k.a. channels) for a project:
```json
[
{
"id": 9693,
"active": false,
"events": ["occurred", "assigned"],
"site_ids": ["605e7c8e-e6c8-4102-a8f8-37a9431ee78be"],
"options": {
"url": "http://requestb.in/7d87eae"
},
"excluded_environments": [],
"filters": [],
"type": "WebHook"
}
]
```
The `options` element varies depending on the type of integration.
## Get report data
[Section titled “Get report data”](#get-report-data)
The following endpoints provide the data that is displayed on the Reports tab for a project.
These URL parameters can be used to filter the data returned by each of the report endpoints:
| Parameter | Description |
| ------------- | ---------------------------------------------------------------------- |
| `start` | Date/time in ISO 8601 format for the beginning of the reporting period |
| `stop` | Date/time in ISO 8601 format for the end of the reporting period |
| `environment` | Limit results to this environment |
### Notices by class
[Section titled “Notices by class”](#notices-by-class)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/reports/notices_by_class
```
Returns a count of error notifications processed, grouped by class.
```json
[
["RuntimeError", 8347],
["SocketError", 4651]
]
```
### Notices by location
[Section titled “Notices by location”](#notices-by-location)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/reports/notices_by_location
```
Returns a count of error notifications processed, grouped by location. The location is framework-dependent; e.g., for Rails applications it’s a combination of the controller and the action.
```json
[
["inquiries#create", 2904],
["members#details", 862]
]
```
### Notices by user
[Section titled “Notices by user”](#notices-by-user)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/reports/notices_by_user
```
Returns a count of error notifications processed, grouped by user (assuming you are providing user\_id and/or user\_email in the context).
```json
[
["julia@example.com", 579],
["marie@example.com", 289]
]
```
### Notices by day
[Section titled “Notices by day”](#notices-by-day)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/reports/notices_per_day
```
Returns a count of error notifications processed, grouped by day (with days starting at midnight UTC).
```json
[
["2023-01-24T00:00:00.000000+00:00", 3161],
["2023-01-25T00:00:00.000000+00:00", 2620],
["2023-01-26T00:00:00.000000+00:00", 2852],
["2023-01-27T00:00:00.000000+00:00", 2502],
["2023-01-28T00:00:00.000000+00:00", 1759],
["2023-01-29T00:00:00.000000+00:00", 1420],
["2023-01-30T00:00:00.000000+00:00", 3027],
["2023-01-31T00:00:00.000000+00:00", 1624]
]
```
# Reporting check-ins
> API reference for reporting check-ins to Honeybadger to monitor scheduled tasks and cron jobs.
To report a check-in, simply send a GET request to the endpoint URL you received when creating the check-in:
```bash
curl https://api.honeybadger.io/v1/check_in/XyZZy
```
You can also send an email (no subject or body required) to `XyZZy@report.hbchk.in`, where `XyZZy` is the same (case-sensitive) ID from the endpoint URL.
If you specify a [slug](/guides/check-ins/#slugs) for a check-in, you can use that slug and the project’s API key in the URL rather than the ID:
```bash
curl https://api.honeybadger.io/v1/check_in/PROJECT_API_KEY/my_identifier
```
You can find more information on using check-ins [here](/guides/check-ins/).
# Reporting deployments
> API reference for reporting deployments to Honeybadger to correlate errors with releases and track code changes.
Reporting deployments to our API allows you to see a history of deployments on each project’s [Deployments page](/guides/deployments). This can be useful for tracking when changes were made to your application, and for [correlating changes with errors](/guides/deployments#searching-with-deployments).
Honeybadger has specific features for tracking deployments for some of our supported languages:
* [Ruby](/lib/ruby/getting-started/tracking-deployments/)
* [Javascript](/lib/javascript/guides/tracking-deploys/)
* [PHP/Forge](/lib/php/guides/tracking-deploys/)
We also support reporting deployments via the following methods:
* [GitHub Actions](https://github.com/marketplace/actions/honeybadger-deploy-action)
* [Heroku webhooks](/guides/heroku/#heroku-deployment-tracking)
## Sending deployment notifications manually
[Section titled “Sending deployment notifications manually”](#sending-deployment-notifications-manually)
If you need to manually notify Honeybadger of a deploy, you can use our API directly.
To do this, make a POST request to `https://api.honeybadger.io/v1/deploys` with the following parameters:
| Parameter | Required | Description |
| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| api\_key | Required | Your project’s API key |
| deploy\[environment] | Optional | The environment name. Example: `production` |
| deploy\[revision] | Optional | The VCS revision being deployed. Could be a git hash, or a tag name. Example: `7cd4bac1bd7e2ddf858d10ee86e362c8d8e2f912` |
| deploy\[repository] | Optional | The base URL of the VCS repository. It should be HTTPS-style. Example: `https://github.com/honeybadger-io/honeybadger-ruby` |
| deploy\[local\_username] | Optional | The name of the user who is deploying. Example: `Jane` |
Here’s an example `curl` command to do a deploy notification:
```sh
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
&& curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"
```
You can also send a JSON payload when specifying the content type as `application/json`:
```bash
curl https://api.honeybadger.io/v1/deploys \
-H 'X-API-Key: Your project API key' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"deploy": {
"environment": "production",
"local_username": "sam",
"revision": "7cd4bac1bd7e2ddf858d10ee86e362c8d8e2f912",
"repository": "https://github.com/someuser/somerepo"
}
}'
```
If everything goes well, you’ll get a response saying `{"status":"OK"}`
# Reporting events
> API reference for sending events to Honeybadger Insights for monitoring and analysis.
Events you send to this API will appear in [Honeybadger Insights](/guides/insights), where you can query and visualize the events.
Your [newline-delimited JSON](https://en.wikipedia.org/wiki/JSON_streaming#Newline-Delimited_JSON) payload should be submitted as the body of a POST request to with the following headers:
* X-API-Key: The API key from your project settings page
* Accept: application/json
* User-Agent: ”{{ Client name }} {{ client version }}; {{ language version }}; {{ platform }}”
Regarding the format of the User-Agent header, you can see an example of how that’s generated in our Ruby implementation [here](https://github.com/honeybadger-io/honeybadger-ruby/blob/991d7cb85ea3f224d6cf0943a87f690de9f9b051/lib/honeybadger/util/http.rb#L21), which generates a string like this: `HB-Ruby 2.1.1; 2.2.7; x86_64-linux-gnu`. If you don’t have all this information available to send, that’s OK, but the more the merrier. :)
If all went well with your POST, you’ll get a response with the status code 201 and information about the just-logged error as a JSON hash.
If all *didn’t* go well, you could get a response with one of these status codes:
| Status Code | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `403` | Either the API key is incorrect or the account has been deactivated |
| `413` | The payload size was too large. The maximum acceptable size is 102,400 bytes |
| `422` | The payload couldn’t be processed. |
| `429` | The API key was valid, but the payload was not accepted because you hit a rate limit (i.e., we have received too much traffic for this API key). |
| `500` | Our bad! :) |
## Sample payloads
[Section titled “Sample payloads”](#sample-payloads)
Each line of the payload must be a single JSON object. The structure of the events you send to this endpoint is up to you, based on your use case. For example, if you wanted to send lines from an unstructured log, you could send a payload like this:
```json
{"ts": "2023-08-31T09:19:30Z", "message": "This is a log line"}
{"ts": "2023-08-31T09:19:30Z", "message": "This is another log line"}
```
We strongly recommend you send structured logs to make querying a better experience:
```json
{
"ts": "2023-08-31T16:17:57Z",
"level": "info",
"action": "health",
"controller": "PagesController",
"method": "GET",
"path": "/health",
"status": 200,
"duration": 322
}
```
Sending events in this way would make it easy to do analytical queries like average request duration, counts by request path, etc.
Of course, you aren’t limited to logs — you can track any kind of event that makes sense for your application:
```json
{"ts": "2023-08-31T14:31:05Z", "event": "user.signup", "user": {"id": 42, "source": "Daring Fireball Ad"}}
{"ts": "2023-08-31T14:33:05Z", "event": "company.created", "project": {"id": 54, "name": "Spacely Space Sprockets", "shared": true}}
```
You do not need to include a `ts` element in each JSON object, but if you do, it must be an [RFC3339](https://www.rfc-editor.org/rfc/rfc3339)-formatted timestamp. If `ts` is omitted, or if it can’t be parsed as a timestamp, it will be added or replaced with the value of the current time as of the payload being processed.
## Sending events from log files and other sources
[Section titled “Sending events from log files and other sources”](#sending-events-from-log-files-and-other-sources)
Check out our instructions on how to add data from other sources, like your log files, Heroku apps, etc., in our [Insights Guide](/guides/insights#adding-data-from-other-sources).
## Limits
[Section titled “Limits”](#limits)
Nested JSON structures are supported, but limiting the nesting to 2 or 3 levels is best. Each event must be less than 100kB, and the total request size must be less than 5MB.
Information about the quotas for this endpoint can be found [here](/resources/quotas/#insights).
# Reporting errors
> API reference for reporting exceptions to Honeybadger with request formats, parameters, and response structures.
Your JSON payload should be submitted as the body of a POST request to , with the following headers:
* X-API-Key: The API key from your project settings page
* Content-Type: application/json
* Accept: application/json
* User-Agent: ”{{ Client name }} {{ client version }}; {{ language version }}; {{ platform }}”
Regarding the format of the User-Agent header, you can see an example of how that’s generated in our Ruby implementation [here](https://github.com/honeybadger-io/honeybadger-ruby/blob/991d7cb85ea3f224d6cf0943a87f690de9f9b051/lib/honeybadger/util/http.rb#L21), which generates a string like this: `HB-Ruby 2.1.1; 2.2.7; x86_64-linux-gnu`. If you don’t have all this information available to send, that’s OK, but the more the merrier. :)
If all went well with your POST, you’ll get a response with the status code 201 and information about the just-logged error as a JSON hash:
```json
{ "id": "6840eec9-6903-4f13-b511-b91ee46fda6a" }
```
You can use that ID to jump directly to the error in our UI:
E.g., `https://app.honeybadger.io/notice/6840eec9-6903-4f13-b511-b91ee46fda6a`
If all *didn’t* go well, you could get a response with one of these status codes:
| Status Code | Description |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `403` | Either the API key is incorrect or the account has been deactivated |
| `413` | The payload size was too large. The maximum acceptable size is 655,360 bytes |
| `422` | The payload couldn’t be processed. Please note that we only do *minimal* checking of the payload when it hits our API. It’s entirely possible to get a 201 response, only to have the payload end up not being able to processed later in the pipeline and thus not show up in the UI. |
| `429` | The API key was valid, but the payload was not accepted because you hit a rate limit (i.e., we have received too much traffic for this API key). |
| `500` | Our bad! :) |
## Sample payload
[Section titled “Sample payload”](#sample-payload)
Your JSON will probably vary most from the example in the `request` key of the hash, which supplies info about the request made by the user, the web server environment, and so on. The `context` key of the `request` hash should have information about the logged-in user, if any, so that we can report on the users effected by application errors.
The `backtrace` key of the `error` hash is essential, as that is used for grouping similar errors together in the Honeybadger UI. The `class` and `message` keys of the `error` hash are displayed in the Honeybadger UI and used for posting errors to other services, like Github issues.
Here’s an annotated payload for your enjoyment:
```json
{
// Please use relevant values for the name, url, and version keys of the
// `notifier` key that point back to your code/package.
"notifier": {
"name": "Honeybadger Notifier",
"url": "https://github.com/honeybadger-io/honeybadger-ruby",
"version": "1.0.0"
},
// Here's where your exception's class, message tags and backtrace go.
// The `class` and `message` attributes are what make up the error's "title" that we display in the UI.
// The `fingerprint` attribute is an optional string that is used to force errors with the same fingerprint (regardless of error class, message, or location) to be grouped together.
// The `backtrace` is a ruby-style backtrace. If the `source` attribute is included for a backtrace line, it will be displayed as a snippet in the UI,
// Last but not least, `causes` is an optional list of causes for the error.
// Honeybadger displays causes in the order they are listed here.
"error": {
"class": "RuntimeError",
"message": "RuntimeError: This is a runtime error, generated by the crywolf app",
"tags": ["wubba"],
"fingerprint": "optional string to force errors with the same fingerprint to be grouped together",
"backtrace": [
{
"number": "4",
"file": "/crywolf/app/controllers/pages_controller.rb",
"method": "runtime_error",
"source": {
"2": "",
"3": " def runtime_error",
"4": " raise RuntimeError.new(\"This is a runtime error, generated by the crywolf app\")",
"5": " end",
"6": ""
}
},
{
"number": "4",
"file": "/gems/1.9.3-p194/lib/ruby/gems/1.9.1/gems/actionpack-3.2.8/lib/action_controller/metal/implicit_render.rb",
"method": "send_action"
}
],
"causes": [
{
"class": "StandardError",
"message": "StandardError: This is the first cause",
"backtrace": [
{
"number": "8",
"file": "/crywolf/app/models/page.rb",
"method": "find"
},
{
"number": "13",
"file": "/crywolf/app/services/find.rb",
"method": "call"
}
]
}
]
},
// `breadcrumbs` are any interesting events that happened within the request leading up to the error
"breadcrumbs": {
"enabled": true,
"trail": [
{
"category": "query",
"message": "Active Record",
"metadata": {
"sql": "SELECT ?.? FROM ? ORDER BY ?.? ASC",
"connection_id": 14200,
"duration": 0.0001449
},
"timestamp": "2021-03-11T23:08:45.448Z"
},
{
"category": "request",
"message": "Action Controller Start Process",
"metadata": {
"controller": "PagesController",
"action": "home",
"format": "html",
"method": "GET",
"path": "/pages/home",
"duration": 0.0000136
},
"timestamp": "2021-03-11T23:08:45.451Z"
},
{
"category": "render",
"message": "Action View Template Render",
"metadata": {
"identifier": "/usr/lib/ruby/gems/2.7.0/gems/actionpack-6.0.3.5/lib/action_dispatch/middleware/templates/rescues/ diagnostics.html.erb",
"layout": "rescues/layout",
"duration": 0.0092867
},
"timestamp": "2021-03-11T23:08:45.554Z"
},
{
"category": "error",
"message": "RuntimeError",
"metadata": {
"exception_message": "This is a runtime error, generated by the crywolf app"
},
"timestamp": "2021-03-11T23:08:45.555Z"
},
{
"category": "notice",
"message": "Honeybadger Notice",
"metadata": {
"exception": "This is a runtime error, generated by the crywolf app"
},
"timestamp": "2021-03-11T23:08:45.555Z"
}
]
},
// `request` contains information about the HTTP request that caused this exception.
"request": {
// We display this data on the error's details page.
// `user_id` and `user_email` are special keys that are used to generate the "affected users" list in the UI.
"context": {
"user_id": 123,
"user_email": "test@example.com"
},
// In rails this is the Controller.
"component": "pages",
// In rails this is the Action.
"action": "runtime_error",
// The URL where the error occurred
"url": "http://crywolf.dev/pages/runtime_error?a=1&b=2",
// These are displayed under "params" on the error detail page
"params": {
"_method": "post",
"authenticity_token": "tuZ7y1PUEMadgKevSzgSUK6T0p267I1+NL0+rnR7xrI=",
"a": "1",
"b": "2",
"controller": "pages",
"action": "runtime_error"
},
// These are displayed under "session" on the error detail page
"session": {
"session_id": "57fb796258046e92b3201ece44531320",
"_csrf_token": "tuZ7y1PUEMadgKevSzgSUK6T0p267I1+NL0+rnR7xrI="
},
// These are displayed under "web environment" on the error detail page.
// Normally you'll just include the environment variables set by your web server.
"cgi_data": {
"REQUEST_METHOD": "POST",
"PATH_INFO": "/pages/runtime_error",
"QUERY_STRING": "a=1&b=2",
"SCRIPT_NAME": "",
"REMOTE_ADDR": "127.0.0.1",
"SERVER_ADDR": "0.0.0.0",
"SERVER_NAME": "crywolf.dev",
"SERVER_PORT": "80",
"HTTP_HOST": "crywolf.dev",
"HTTP_CONNECTION": "keep-alive",
"CONTENT_LENGTH": "82",
"HTTP_CACHE_CONTROL": "max-age=0",
"HTTP_ORIGIN": "http://crywolf.dev",
"HTTP_USER_AGENT": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_4) AppleWebKit/537.4",
"CONTENT_TYPE": "application/x-www-form-urlencoded",
"HTTP_ACCEPT": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"HTTP_REFERER": "http://crywolf.dev/",
"HTTP_ACCEPT_ENCODING": "gzip,deflate,sdch",
"HTTP_ACCEPT_LANGUAGE": "en-US,en;q=0.8",
"HTTP_ACCEPT_CHARSET": "ISO-8859-1,utf-8;q=0.7,*;q=0.3",
"HTTP_COOKIE": "_crywolf_session=BAh7B0kiD3Nlc3Npb25faWQGOgZFRkkiJTU3ZmI3OTYy",
"REMOTE_PORT": "52509",
"ORIGINAL_FULLPATH": "/pages/runtime_error?a=1&b=2"
}
},
"server": {
// The directory where your code lives. This helps us to display more concise paths.
"project_root": "/Users/josh/code/crywolf",
// Your environment name
"environment_name": "development",
// The server's hostname
"hostname": "Josh-MacBook-Air.local",
// Optional: Git sha for the deployed version of the code, for linking to GitHub, Gitlab, and BitBucket
"revision": "920201a",
// Optional: ID of the process that raised the error
"pid": 1138
}
}
```
## Payload tester
[Section titled “Payload tester”](#payload-tester)
While you’re developing an error collector in your language of choice that talks to our API, you can use our [payload tester](https://app.honeybadger.io/notice/test) to see how your payloads will be rendered in our UI.
# Uploading source maps
> API reference for uploading source maps to Honeybadger to get readable stack traces from minified JavaScript code.
Honeybadger can automatically un-minify your JavaScript code if you provide a [source map](https://web.dev/articles/source-maps) along with your minified files. Use the Source Map Upload API to upload your source maps to Honeybadger. See [Using Source Maps](/lib/javascript/guides/using-source-maps/) to learn more.
## Overview
[Section titled “Overview”](#overview)
To upload your source map files to Honeybadger, POST them to `https://api.honeybadger.io/v1/source_maps` with the following parameters:
| Param | Required | Description |
| -------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key` | Required | The API key of your Honeybadger project (see the API Key tab in project settings). |
| `minified_url` | Required | The URL of your minified JavaScript file in production. `*` can be used as a [wildcard](#wildcards). Must be an absolute URL (query strings are ignored). |
| `minified_file` | Required | The minified file itself. |
| `source_map` | Required | The source map for your minified file. |
| revision | Optional, default: `master` | The deploy revision (i.e. commit sha) that your source map applies to. This could also be a code version. For best results, set it to something unique every time your code changes. The `revision` option must also be configured in [honeybadger.js](/lib/javascript/reference/configuration/). |
| \ | Optional | One or more additional source files which may be referenced by your source map. The name should be the URL that would normally be used to access the file, and the value should be the file itself. Many source map generators include the sources in the `sourcesContent` key inside the source map, so you may not need to send these. `*` in the name can be used as a [wildcard](#wildcards). |
Here’s an example using `curl`:
```bash
curl https://api.honeybadger.io/v1/source_maps \
-F api_key=Your project API key \
-F revision=dcc69529edf375c72df39b0e9195d60d59db18ff \
-F minified_url=https://example.com/assets/application.min.js \
-F source_map=@path/to/application.js.map \
-F minified_file=@path/to/application.min.js \
-F http://example.com/assets/application.js=@path/to/application.js \
-F http://example.com/assets/utils.js=@path/to/utils.js
```
## Response codes
[Section titled “Response codes”](#response-codes)
The `/v1/source_maps` API endpoint responds with the following codes:
| Code | Status | Description |
| ----- | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `201` | Created | The files were uploaded successfully. |
| `400` | Bad Request | You’re missing a required parameter or have exceeded the maximum file size of 80MB per file (check the error message). |
| `401` | Unauthorized | Your API key is invalid. |
## Wildcards
[Section titled “Wildcards”](#wildcards)
In some cases you may want to upload the same source map for different URLs—for instance, if you serve your files from multiple subdomains, or via both HTTP and HTTPS.
An asterisk (`*`) can be used in URLs to perform a wildcard match. For example, the following example will match both the `http://` and
`https://` version of the URL:
```plaintext
http*://example.com/assets/application.min.js
```
…matches the following URLs:
```plaintext
http://example.com/assets/application.min.js
https://example.com/assets/application.min.js
```
Wildcards are *not* supported in file names:
```plaintext
// invalid (will be an exact match):
https://example.com/assets/*.min.js
```
# Status pages API reference
> API reference for managing status pages with endpoints to create, read, update, and delete resources.
Create and manage status pages within your accounts.
## Get all status pages
[Section titled “Get all status pages”](#get-all-status-pages)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ACCOUNT_ID/status_pages
```
Returns a list of all status pages in this account.
```json
{
"results": [
{
"id": "rMGSZB",
"name": "My Awesome Status Page",
"account_id": "Me3upk",
"domain": "your.custom.domain",
"url": "your.custom.domain",
"created_at": "2022-01-29T11:26:19.120153Z",
"domain_verified_at": "2022-01-29T14:02:32.570227Z",
"sites": [],
"check_ins": [
{
"check_in_id": "XXXXXX",
"display_name": "Nightly billing",
"state": "reporting",
"reported_at": "2022-01-29T00:00:02.523254Z"
}
]
},
{
"id": "vWbSWr",
"name": "Really Awesome Status Page",
"account_id": "Me3upk",
"domain": null,
"url": "vWbSWr.status.hbuptime.com",
"created_at": "2022-01-29T11:09:32.570227Z",
"domain_verified_at": null,
"sites": [
{
"site_id": "7d25f58b-d1a9-49f1-b10a-ac7ee44a6537",
"display_name": "Main site",
"state": "up",
"last_checked_at": "2022-01-29T11:09:30.982801Z"
},
{
"site_id": "7d25f58b-d1a9-49f1-b10a-ac7ee44a6557",
"display_name": "API",
"state": "up",
"last_checked_at": "2022-01-29T11:04:28.675309Z"
}
],
"check_ins": []
}
],
"links": {
"self": "http://localhost:3000/v2/accounts/4bYurk/status_pages"
}
}
```
## Get a single status page’s details
[Section titled “Get a single status page’s details”](#get-a-single-status-pages-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/accounts/ACCOUNT_ID/status_pages/ID
```
```json
{
"id": "vWbSWr",
"name": "Really Awesome Status Page",
"account_id": "Me3upk",
"domain": null,
"url": "vWbSWr.status.hbuptime.com",
"created_at": "2022-01-29T11:09:32.570227Z",
"domain_verified_at": null,
"sites": [
{
"site_id": "7d25f58b-d1a9-49f1-b10a-ac7ee44a6537",
"display_name": "Main site",
"state": "up",
"last_checked_at": "2022-01-29T11:09:30.982801Z"
},
{
"site_id": "7d25f58b-d1a9-49f1-b10a-ac7ee44a6557",
"display_name": "API",
"state": "up",
"last_checked_at": "2022-01-29T11:04:28.675309Z"
}
],
"check_ins": []
}
```
## Create a status page
[Section titled “Create a status page”](#create-a-status-page)
```bash
curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' \
-d '{
"status_page": {
"name": "Really Awesome Status Page",
"domain": "your.custom.domain",
"sites": [
{
"site_id": "7d25f58b-d1a9-49f1-b10a-ac7ee44a6537",
"display_name": "Main site"
}
]
}
}' https://app.honeybadger.io/v2/accounts/ACCOUNT_ID/status_pages
```
You can specify these fields within the `status page` object:
| Field name | Type | Description |
| --------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | The name of the status page |
| `domain` | string | (Optional) A custom domain for the status page. Setting this will trigger the domain DNS verification check. |
| `sites` | object\[] | (Optional) Details of sites to add to this status page. Each object references a site in a project in this account, and must contain the `site_id` and an optional `display_name` and `position`. The `position` field is a zero-indexed integer that controls how your sites will be ordered on the status page. |
| `check_ins` | object\[] | (Optional) Details of check-ins to add to this status page. Each object references a check-in in a project in this account, and must contain the `check_in_id` and an optional `display_name` and `position`. The `position` field is a zero-indexed integer that controls how your check-ins will be ordered on the status page. |
| `hide_branding` | boolean | Whether or not to hide the Honeybadger branding in the footer of the status page. Only available on the Team plan and above. |
| features | object | Additional customization options only available on the Team plan and above. Available options:- `home_link`: URL to hyperlink the status page title or logo to.
- `up_caption`: The caption displayed when all checks are passing.
- `down_caption`: The caption displayed when all checks are failing.
- `mixed_caption`: The caption displayed when some checks are failing.
- `custom_css`: Custom CSS that will be injected into the status page. |
Returns a 201 Created response containing the created status page’s details.
## Update a status page
[Section titled “Update a status page”](#update-a-status-page)
```bash
curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' \
-d '{
"status_page": {
"domain": "different.custom.domain",
"sites": [
{
"site_id": "7d25f58b-d1a9-49f1-b10a-ac7ee44a6537",
"display_name": "Main site"
}
]
}
}' https://app.honeybadger.io/v2/accounts/ACCOUNT_ID/status_pages/ID
```
You can specify one or more of these fields within the `status page` object:
| Field name | Type | Description |
| --------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | The name of the status page |
| `domain` | string | A custom domain for the status page. Changing this will trigger the domain DNS verification check. |
| `sites` | object\[] | Details of sites to add to this status page. Each object references a site in a project in this account, and must contain the `site_id` and an optional `display_name`. |
| `hide_branding` | boolean | Whether or not to hide the Honeybadger branding in the footer of the status page. Only available on the Team plan and above. |
| `features` | object | Additional customization options only available on the Team plan and above. Available options:- `home_link`: URL to hyperlink the status page title or logo to.
- `up_caption`: The caption displayed when all checks are passing.
- `down_caption`: The caption displayed when all checks are failing.
- `mixed_caption`: The caption displayed when some checks are failing.
- `custom_css`: Custom CSS that will be injected into the status page. |
Returns an empty response (204 No Content) if successful.
## Delete a status page
[Section titled “Delete a status page”](#delete-a-status-page)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/accounts/ACCOUNT_ID/status_pages/ID
```
Returns an empty response (204 No Content) if successful.
# Teams API reference
> API reference for managing teams with endpoints to retrieve and update team members and permissions.
## Get a team list or team details
[Section titled “Get a team list or team details”](#get-a-team-list-or-team-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/teams?account_id=ACCOUNT_ID
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/teams/ID
```
Returns a list of teams
```json
{
"id": 1,
"name": "The Avengers",
"created_at": "2013-01-11T15:40:35Z",
"owner": {
"id": 1,
"email": "thor@example.org",
"name": "Thor"
},
"members": [...],
"projects": [...],
"invitations": [...]
}
```
If the `account_id` parameter is not supplied when requesting the list of teams, all teams will be returned across all accounts to which the provided AUTH\_TOKEN has access.
## Create a team
[Section titled “Create a team”](#create-a-team)
```bash
curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"team":{"name":"My team"}}' https://app.honeybadger.io/v2/teams?account_id=ACCOUNT_ID
```
You can specify these fields:
| Field name | Type | Description |
| ---------- | ------ | ----------- |
| `name` | string | |
If the `account_id` query parameter is not provided, the team will be associated with the first account accessible by the user associated with the AUTH\_TOKEN.
## Update a team
[Section titled “Update a team”](#update-a-team)
```bash
curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"team":{"name":"Updated team name"}}' https://app.honeybadger.io/v2/teams/ID
```
## Delete a team
[Section titled “Delete a team”](#delete-a-team)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/teams/ID
```
## Get a list of team members or team member details
[Section titled “Get a list of team members or team member details”](#get-a-list-of-team-members-or-team-member-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/teams/ID/team_members
```
Returns all the members or a single team member for the given team:
```json
{
"id": 1,
"created_at": "2012-12-13T15:00:47Z",
"admin": true,
"name": "",
"email": "westley@honeybadger.io"
}
```
## Update a team member
[Section titled “Update a team member”](#update-a-team-member)
```bash
curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"team_member":{"admin":true}}' https://app.honeybadger.io/v2/teams/ID/team_members/ID
```
The list of valid fields is as follows:
| Field name | Type | Description |
| ---------- | ------- | ----------- |
| `admin` | boolean | |
## Delete a team member
[Section titled “Delete a team member”](#delete-a-team-member)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/teams/ID/team_members/ID
```
## Create a team invitation
[Section titled “Create a team invitation”](#create-a-team-invitation)
```bash
curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' \
-d '{"team_invitation":{"email":"inigo@honeybadger.io"}}' \
https://app.honeybadger.io/v2/teams/ID/team_invitations
```
You can specify these fields:
| Field name | Type | Description |
| ---------- | ------- | ------------------------------------------------------------------ |
| `email` | string | The invited user’s email address. |
| `admin` | boolean | (Optional) Set this to true to make the invited user a team admin. |
| `message` | string | (Optional) The message to be included in the invitation email. |
Returns the created team invitation:
```json
{
"id": 9,
"token": "e62394d2",
"email": "inigo@honeybadger.io",
"created_by": {
"email": "westley@honeybadger.io",
"name": "Westley"
},
"accepted_by": null,
"admin": false,
"accepted_at": null,
"created_at": "2013-01-08T15:42:16Z",
"message": null
}
```
## Update a team invitation
[Section titled “Update a team invitation”](#update-a-team-invitation)
```bash
curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' \
-d '{"team_invitation":{"admin": true}}' \
https://app.honeybadger.io/v2/teams/ID/team_invitations/ID
```
You can specify either of these fields:
| Field name | Type | Description |
| ---------- | ------- | ------------------------------------------------------- |
| `admin` | boolean | Set this to true to make the invited user a team admin. |
| `message` | string | The message to be included in the invitation email. |
## Get a team invitation list or team invitation details
[Section titled “Get a team invitation list or team invitation details”](#get-a-team-invitation-list-or-team-invitation-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/teams/ID/team_invitations
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/teams/ID/team_invitations/ID
```
Returns a list of team invitations or a single team invitation for the given team:
```json
{
"id": 9,
"token": "e62394d2",
"email": "",
"created_by": {
"email": "westley@honeybadger.io",
"name": "Westley"
},
"accepted_by": {
"email": "inigo@honeybadger.io",
"name": "Inigo Montoya"
},
"admin": true,
"accepted_at": "2013-01-08T15:42:41Z",
"created_at": "2013-01-08T15:42:16Z",
"message": null
}
```
## Delete a team invitation
[Section titled “Delete a team invitation”](#delete-a-team-invitation)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/teams/ID/team_invitations/ID
```
# Uptime API reference
> API reference for managing uptime monitors with endpoints to create, read, update, and delete resources.
## Get a site list or site details
[Section titled “Get a site list or site details”](#get-a-site-list-or-site-details)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/sites
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/sites/ID
```
Returns a list of sites or a single sites for the given project with the following format:
```json
{
"active": true,
"frequency": 5,
"id": "9eed6a7e-af77-4cc6-8c55-b7b17555330d",
"last_checked_at": "2016-06-15T12:57:29.646956Z",
"match": null,
"match_type": "success",
"name": "Main site",
"state": "down",
"url": "http://www.example.com"
}
```
## Create a site
[Section titled “Create a site”](#create-a-site)
```bash
curl -u AUTH_TOKEN: -X POST -H 'Content-type: application/json' -d '{"site":{"name":"My site","url":"https://www.example.com/"}}' https://app.honeybadger.io/v2/projects/ID/sites
```
Here is a list of the fields that can be specified:
| Field name | Type | Description |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | string | |
| `url` | string | |
| `frequency` | integer | Number of minutes between checks (valid values are 1, 5, or 15). |
| `match` | string | The status code that will be returned or string to be present/absent to indicate a passing check, depending on the value of `match_type`. Unused when the match\_type is “success”. |
| `match_type` | string | One of “success” for a status code of 200-299, “exact” for a particular status code (provided via the `match` field), “include” to require the text in `match` to be present on the page, and “exclude” to require the text in `match` to not be present on the page. |
| `request_method` | string | One of GET, POST, PUT, PATCH, or DELETE. |
| `request_body` | string | The body content to be sent with the check. |
| `request_headers` | array | Array of hashes (e.g., `[{ key: "Content-type", value: "application/json" }]`) that will be added to the request headers. |
| `locations` | array | Array of strings (e.g, `['London', 'Virginia']`) that will limit the locations that will be used for the checks. Providing an empty array (the default) will cause all locations to be used. Available locations are Virginia, Oregon, Frankfurt, Singapore, and London. |
| `validate_ssl` | boolean | Whether to have the check fail if the SSL certificate is not valid or is expired. |
| `timeout` | integer | **Business and Enterprise customers only.** How long the uptime check will wait for a response before reporting the site as down (in seconds). The default is 30 seconds and the maximum is 120 seconds. |
| outage\_threshold | integer | The number of unsuccessful checks required to trigger an alert. If this is blank, then an alert will be sent after half of the locations return with failed checks. |
| `active` | boolean | Whether to run the checks. |
## Update a site
[Section titled “Update a site”](#update-a-site)
```bash
curl -u AUTH_TOKEN: -X PUT -H 'Content-type: application/json' -d '{"site":{"name":"Updated site name"}}' https://app.honeybadger.io/v2/projects/ID/sites/ID
```
Update requests can change the same fields as create requests.
## Delete a site
[Section titled “Delete a site”](#delete-a-site)
```bash
curl -u AUTH_TOKEN: -X DELETE https://app.honeybadger.io/v2/projects/ID/sites/ID
```
## Get a list of outages for a site
[Section titled “Get a list of outages for a site”](#get-a-list-of-outages-for-a-site)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/sites/ID/outages
```
Returns a list of outages with the following format:
```json
{
"down_at": "2015-02-17T18:20:44.776959Z",
"up_at": "2015-02-17T18:22:35.614678Z",
"created_at": "2015-02-17T18:20:44.777914Z",
"status": 301,
"reason": "Expected 2xx status code. Got 301",
"headers": {
"Date": "Tue, 17 Feb 2015 18:20:44 GMT",
"Server": "DNSME HTTP Redirection",
"Location": "http://text.vote/polls",
"Connection": "close",
"Content-Length": "0"
}
}
```
The outage list can be filtered with these URL parameters:
| Parameter | Description |
| ---------------- | ---------------------------------------------------- |
| `created_after` | A Unix timestamp (number of seconds since the epoch) |
| `created_before` | A Unix timestamp (number of seconds since the epoch) |
| `limit` | Number of results to return (max and default are 25) |
The outage list is always ordered by creation time descending.
## Get a list of uptime checks for a site
[Section titled “Get a list of uptime checks for a site”](#get-a-list-of-uptime-checks-for-a-site)
```bash
curl -u AUTH_TOKEN: https://app.honeybadger.io/v2/projects/ID/sites/ID/uptime_checks
```
Returns a list of uptime checks with the following format:
```json
{
"created_at": "2016-06-16T20:19:32.852569Z",
"duration": 1201,
"location": "Singapore",
"up": true
}
```
The uptime check list can be filtered with these URL parameters:
| Parameter | Description |
| ---------------- | ---------------------------------------------------- |
| `created_after` | A Unix timestamp (number of seconds since the epoch) |
| `created_before` | A Unix timestamp (number of seconds since the epoch) |
| `limit` | Number of results to return (max and default are 25) |
The uptime check list is always ordered by creation time descending.
# Accounts
> Manage billing and users.
Accounts are the primary billing entities in Honeybadger. An account is created for you when you first sign up, unless you are signing up as a result of being invited to another user’s account. You can create additional accounts and switch between accounts using the dropdown in the navigation bar.
## Account-wide information
[Section titled “Account-wide information”](#account-wide-information)
Honeybadger can display information from several projects on an account-wide basis, including the following:
* Errors
* Uptime Checks
* Check-Ins
Links to these views are available in the left-hand sidebar. [Status Pages](/guides/status-pages) are also managed at the account level, as they can include uptime checks and check-ins from multiple projects.
## Account settings
[Section titled “Account settings”](#account-settings)
From the account settings page, you can:
* See the current billing subscription
* Edit account options
* Add & remove users
* See past invoices
* Change authentication settings
* Manage the referral program
* Park and delete accounts
To learn more about adding, removing, and editing users currently registered to an account and changing the authentication settings, please check out the [User Management](/guides/user-management) page.
## Billing
[Section titled “Billing”](#billing)
Each account is billed separately based on a chosen subscription plan and has its own payment information. The following changes can be made from the Account Settings page for each account regarding billing:
* Subscription plan
* Payment information
* Business details displayed on invoices
A list of invoices for the account is also available from the Account Settings page.
### Changing the subscription plan
[Section titled “Changing the subscription plan”](#changing-the-subscription-plan)
You can change your subscription plan at any time. When you upgrade, downgrade, or change the payment period for your subscription (switch from monthly to yearly, or vice-versa), your account will be prorated for the difference in cost between the old and new plans. The prorated amount will show up as a credit on your next invoice. When you upgrade to a plan that costs more, the next invoice will be larger than normal, as it will have the prorated charge for the newly-selected plan for the remainder of the current billing period in addition to the full charge for the next billing period.
On the payment information page we provide a link that can be used to update the account’s payment information without having to be logged in to Honeybadger. This can be useful if you are managing the account but don’t have access to a company credit card. Alternatively, you can invite additional account owners via the Users tab, and those individuals will be able to update the payment information once logged in.
Payment via purchase order/invoice is available to subscribers on any of our Business plans when billed annually. Please \[contact support]\(mailto:support\@honeybadger.io?subject=Payment by invoice) to arrange that.
## Account options
[Section titled “Account options”](#account-options)
From the account options tab, you can change the account name and the billing contact, as well as adjust whether or not overage billing is enabled. The tech contact email, if provided, will receive notifications from Honeybadger for non-billing-related information.
## Referral program
[Section titled “Referral program”](#referral-program)
Honeybadger offers a referral program that lets you earn up to 20% of referred customers’ payments as account credits. These credits can reduce your monthly bill—even down to $0.
To join the program, navigate to the Referrals tab in your account settings, accept the terms, and share your unique referral link. See the [referral program guide](/resources/referral-program) to learn more about the referral program and how to get started.
## Account parking
[Section titled “Account parking”](#account-parking)
If you’d like to suspend billing for a while, but you’d also like to preserve all the projects, users, etc. associated with your account, then you can choose to park your account. Doing so will stop all error processing, uptime checks, and check-in monitoring for the projects associated with your account. Un-parking your account will cause billing and all processing to be resumed.
## Deleting your account
[Section titled “Deleting your account”](#deleting-your-account)
When you choose to delete an account, all the data associated with the account (projects, teams, etc.) will be immediately deleted, and billing will be stopped. There is no undo for this action, so be sure you’re ready before pushing the button!
# Check-ins
> Tracking pings.
Your Honeybadger account comes with check-ins, a way for the processes running on your servers to report that they are alive. Once configured, should a check-in go missing, Honeybadger will send you an alert to let you know that your process has stopped reporting. This is especially useful for monitoring cron jobs, so you can avoid having a cron job silently fail and go unnoticed.
## Setup
[Section titled “Setup”](#setup)
When you create a check-in, you can choose either a simple or a cron-based type.
#### Simple
[Section titled “Simple”](#simple)
Honeybadger will watch the process on a specific interval (like every 5 minutes).
#### Cron
[Section titled “Cron”](#cron)
Cron scheduling allows you to use a cron expression to create an advanced check-in schedule or mirror the cron schedule on your server.
#### Grace period
[Section titled “Grace period”](#grace-period)
With either option, you can also specify a grace period, which allows some time for long-running tasks to be completed before Honeybadger sends a notification due to a lack of reporting. For example, if you have a job that reports every hour but can take up to twenty minutes to run, you can specify a grace period of twenty minutes, and Honeybadger will allow up to one hour and twenty minutes to elapse before a notification is sent.
#### URLs and emails
[Section titled “URLs and emails”](#urls-and-emails)
When you create a new check-in, you’ll get a URL that you can use to report that your process is alive. For example, if your check-in URL is `https://api.honeybadger.io/v1/check_in/XyZZy`, then you can set up a cron job like this:
```sh
@hourly /usr/bin/do_something && curl https://api.honeybadger.io/v1/check_in/XyZZy &> /dev/null
```
You will also get an email address you can use for reporting the status of your process. No subject or body text is required, but the email address *is* case-sensitive:
```sh
@hourly /usr/bin/do_something && echo mail "" | XyZZy@report.hbchk.in
```
## Slugs
[Section titled “Slugs”](#slugs)
When creating a cron job in your codebase, you can also choose to specify a slug in a separate config file. To learn how to do this, check out the [PHP/Laravel](/lib/php/guides/configuring-checkins/) and [JavaScript](/lib/javascript/guides/check-ins/) integration guides.
If you choose to specify a slug, you will have another URL you can use for reporting the check-in in addition to the URL described previously. This URL includes a project API key to scope the slug to your project. If you specify a slug of `hourly-check`, then your alternate check-in URL will look like `https://api.honeybadger.io/v1/check_in/hbp_ABC/hourly-check`.
## Notifications
[Section titled “Notifications”](#notifications)
When your check-in goes missing, we’ll notify you with information about which job failed to report on time. You can enable or disable these notifications along with the rest of the notification events in your Personal Alerts or Project Integrations settings.
## Status page integration
[Section titled “Status page integration”](#status-page-integration)
Check out our [Status Pages](/guides/status-pages/#uptime-checks) feature for information on how to present the status your check-ins to your users.
# Dashboards & APM
> Learn how to use dashboards to display widgets created from Insights queries and visualizations.
Dashboards let you collect your most important [Honeybadger Insights](/guides/insights/) charts and data in one place so you can see what’s happening with your app at a glance. Instead of running queries repeatedly or jumping between pages, dashboards give you a single view of your application’s health and performance, helping you spot trends and fix issues.
## Getting started
[Section titled “Getting started”](#getting-started)
To create a dashboard, navigate to the *Dashboards* section in your Honeybadger project, click *Create dashboard*, select the type of dashboard you want, then click *Add dashboard*.
## Automatic dashboards
[Section titled “Automatic dashboards”](#automatic-dashboards)
To help you get started quickly, Honeybadger provides pre-configured automatic dashboards with relevant widgets for common frameworks and platforms. These dashboards are automatically populated when you enable instrumentation for supported platforms.
### Getting started with automatic dashboards
[Section titled “Getting started with automatic dashboards”](#getting-started-with-automatic-dashboards)
To enable automatic dashboards for your applications, follow these steps:
1. Enable Honeybadger Insights instrumentation in your client library (e.g., [Ruby](/lib/ruby/getting-started/sending-events-to-insights/), [Elixir](/lib/elixir/insights/capturing-logs-and-events/), [PHP](/lib/php/guides/sending-events-to-insights/), etc.)
2. Deploy your application with the updated configuration
3. Navigate to the *Dashboards* section in your Honeybadger project, click *Create dashboard*, select the dashboard you want, then click *Add dashboard*.
Your dashboard will begin to populate with data as soon as your application starts sending events to Honeybadger.
## Available dashboards
[Section titled “Available dashboards”](#available-dashboards)
[ Honeybadger ](/guides/dashboards/honeybadger/)Monitor uptime, errors, notices, and deployments
[ Rails ](/guides/dashboards/rails/)Track Rails requests, controllers, queries, and cache
[ Puma ](/guides/dashboards/puma/)Monitor Puma web server performance
[ Autotuner ](/guides/dashboards/autotuner/)Track Ruby memory optimization metrics
[ Karafka ](/guides/dashboards/karafka/)Monitor Kafka message processing
[ Sidekiq ](/guides/dashboards/sidekiq/)Track background job processing
[ Phoenix ](/guides/dashboards/phoenix/)Monitor Phoenix and LiveView performance
[ Oban ](/guides/dashboards/oban/)Track Elixir background jobs
[ Laravel ](/guides/dashboards/laravel/)Monitor Laravel application metrics
[ Django ](/guides/dashboards/django/)Track Django application performance
[ Flask ](/guides/dashboards/flask/)Monitor Flask application metrics
[ Celery ](/guides/dashboards/celery/)Track Celery task performance
[ Heroku ](/guides/dashboards/heroku/)Monitor Heroku application and Postgres
## Next steps
[Section titled “Next steps”](#next-steps)
* Learn more about [Honeybadger Insights](/guides/insights/)
* Try [BadgerQL](/guides/insights/badgerql/) to explore your data and create custom dashboard widgets
* Set up [Insights Alarms](/guides/insights/alarms/) to turn your queries into actionable alerts
* Send additional data from your [infrastructure](/guides/insights/#adding-data-from-other-sources) to Honeybadger
# Autotuner dashboard
> Monitor Ruby memory optimization with heap analysis, garbage collection metrics, performance tuning suggestions, and request timing.
Drop in Dashboard for your Autotuner stats and reports.
**This dashboard includes:**
* Heap Pages over time
* Request Time over time
* Garbage Collection Count over time
* Autotuner Report suggestions
# Celery dashboard
> Monitor Celery task performance with task counts, execution times, failure rates, and status breakdowns.
Drop in Dashboard for your Celery instrumentation data.
**This dashboard includes:**
* Task counts over time by status (SUCCESS, FAILURE, etc.)
* Average task durations across all tasks
* Overall task counts & average durations per task
* Top 10 slowest task runs
* Breakdown of failures, retries & other statuses
* Total successful job count
# Django dashboard
> Monitor Django application performance with request metrics, response times, database queries, and view analysis.
Drop in Dashboard for your Django instrumentation data.
**This dashboard includes:**
* Request duration distributions (binned by 100 ms)
* Response counts over time, grouped by status codes (2XX, 3XX, 4XX, 5XX)
* Average response durations by view
* Average response durations by app
* Total request counts over time
* Slowest views (avg/max durations and Apdex)
* Top 10 slowest database queries
# Flask dashboard
> Monitor Flask application performance with request metrics, response times, database queries, and blueprint analysis.
Ready-made dashboard for monitoring Flask applications.
**This dashboard includes:**
* Average response durations by view
* Average response durations by blueprint
* Response counts over time, grouped by status codes (2XX, 3XX, 4XX, 5XX)
* Total request count over time
* Top 10 slowest views (avg/max durations and Apdex)
* Request duration distribution histogram (binned by 100 ms)
* Top 10 slowest database queries
# Heroku dashboard
> Monitor Heroku application performance with router metrics, Postgres monitoring, response time analysis, and status code tracking.
Automatic dashboard for monitoring Heroku apps. All that is required is to set up your [Heroku log drain](https://docs.honeybadger.io/guides/insights/integrations/heroku/).
**This dashboard includes:**
* Router response status code groupings
* Postgres load averages (1m, 5m, 15m interval samples)
* Query response time percentiles (50, 90, 99 percentiles)
* Top 10 avg slowest response times by path
# Honeybadger dashboard
> Monitor application health with uptime checks, error tracking, notice volume trends, deployment activity, and fault analysis.
Automatic dashboard for your Honeybadger data.
**This dashboard includes:**
* Top 5 highest uptime response times
* Top 5 faults most affecting users
* Notice volume over time
* Notice counts by time of day
* Deployments over time
# Karafka dashboard
> Monitor Kafka message processing with consumer metrics, lag monitoring, broker performance data, and topic analysis.
Automatic dashboard for your Karafka instrumentation data.
**This dashboard includes:**
* Average Consumer Duration
* Average Consumer Lag
* Number of Messages Processed by Topic
* Average Consumer Consumption and Processing Duration
* Broker Latency
* Broker Errors
# Laravel dashboard
> Track Laravel application performance with request metrics, job durations, database query analysis, and Apdex scoring.
Automatic dashboard for your Laravel instrumentation data.
**This dashboard includes:**
* Total requests over time
* Response distributions binned by 100ms
* Job durations over time
* Slowest controllers w/ Apdex score
* Overall slowest requests
* Slowest overall queries & slowest queries per request
* Slowest external requests
# Oban dashboard
> Monitor Oban background job processing with job status counts, durations, worker performance metrics, and execution analysis.
Automatic dashboard for your Oban data.
This dashboard includes:
* Overall Job counts by status
* Histogram of job counts by status
* Job durations by Worker module
* Overall Worker stats
* Slowest 10 job runs
# Phoenix dashboard
> Monitor Phoenix application performance with request stats, LiveView metrics, Ecto query analysis, and controller response monitoring.
Automatic dashboard for your Phoenix data.
This dashboard includes:
* Request Stats
* Response Counts by status code
* 10 Slowest Controller Actions
* 10 Slowest Ecto Queries
* LiveView Event Performance
* LiveView Mount Performance
* LiveView Event Counts
# Puma dashboard
> Track Puma web server performance including request throughput, thread pool metrics, backlog monitoring, and capacity analysis.
Automatic dashboard for your Puma instrumentation data.
**This dashboard includes:**
* Total requests over time
* Backlog over time
* Running threads over time
* Pool capacity over time
# Ruby on Rails dashboard
> Monitor Rails application performance with request metrics, response times, database queries, cache hit rates, and controller analysis.
Automatic dashboard for your Rails instrumentation data.
**This dashboard includes:**
* Total requests over time
* Response distributions binned by 100ms
* Controller durations & slowest controller actions
* Slowest queries & slowest queries per request
* Slowest partials
* Cache hit rates
# Sidekiq dashboard
> Monitor Sidekiq job processing with worker metrics, job durations, success/failure rates, performance analysis, and slowest job tracking.
Automatic dashboard for your Sidekiq instrumentation data.
**This dashboard includes:**
* Job counts over time by worker
* Average job duration by worker over time
* Job duration distribution (binned by 100ms, by worker)
* Job status counts (success/failure) by worker
* Aggregate worker stats: successes, failures, total and average execution time
* 10 slowest job runs (with details)
# Deployments
> Viewing and tracking deployments.
The Deployments page of a project is used to track the deployments of whatever app the project is monitoring. With deployment tracking, you can know when your code changed and what changed in it. By default, all errors are marked as resolved on deploy, meaning that when they occur again you will receive a new notification.
## How deployments work in Honeybadger
[Section titled “How deployments work in Honeybadger”](#how-deployments-work-in-honeybadger)
On the deployment page, you can see all of your most recent deployments, by default sorted by timestamp, with the most recent at the top. At the top of the page, you can choose instead to sort by what environment a deploy was pushed to, as well as adjust the time range being displayed - with presets for month to date, the last seven days, and yesterday.
For each deployment in the list, we display the timestamp, the environment affected, the user who did it, and the revision link. When GitHub or GitLab is connected, you will also see a comparison link.
If your apps are hosted on Heroku, you will also see Heroku’s own deploys in your deployment tab, with all the same information (excluding comparison links). For Heroku deploys, the user listed shows which part of Heroku had the deployment.
## Connecting with GitHub and GitLab
[Section titled “Connecting with GitHub and GitLab”](#connecting-with-github-and-gitlab)
When your project has been connected to a GitHub or GitLab account, the deploy list on the Deployments page in Honeybadger will include links to the comparison views so that you can see what exactly changed on each deploy.
## Searching with deployments
[Section titled “Searching with deployments”](#searching-with-deployments)
With the `Since Deploy` token in the error search bar, you can filter for all the errors that have occurred since your latest deployment. New code often causes errors to pop up, and when combined with the other tokens in our powerful error search system, you can easily hone in on the errors caused by new code in the environments in which the code was deployed or users that the new code affected.
To learn more about search tokens - and how to combine them - check out the [Error Search](/guides/errors/search/) documentation page.
## Reporting deployments
[Section titled “Reporting deployments”](#reporting-deployments)
Please see our [guide on reporting deployments](/api/reporting-deployments) for information on how to populate the Deployments page.
# Error monitoring
> Collect, manage, and resolve your application errors.
## Installation
[Section titled “Installation”](#installation)
Before you can start using Honeybadger to squash bugs, you will need to install our library into your app. Installation usually boils down to:
1. Installing the Honeybadger library
2. Setting the API key
3. Enabling error reporting
The details vary a little depending on language and platform. But you can always find the correct installation instructions for YOUR app on the “Project Settings” page.
In case you are wondering, we officially support:
[Ruby](/lib/ruby/), [client-side JavaScript](/lib/javascript/), [Vue](/lib/javascript/integration/vue3/), [Elixir](/lib/elixir/), [Go](/lib/go/), [NodeJS](/lib/javascript/integration/node/), [Java](/lib/java/), [Python](/lib/python/), [PHP](/lib/php/), [Clojure](/lib/clojure/), and [Cocoa](/lib/cocoa/)
Check out any of these pages to see how to install Honeybadger for your app. Once our client library is installed and configured, errors thrown by your application are automatically sent to our API.
## Error grouping
[Section titled “Error grouping”](#error-grouping)
Honeybadger groups similar exceptions together using rules which we’ve found to work the best in most cases. The default information we use to group errors is:
1. The file name, method name, and line number of the error’s location
2. The class name of the error
3. The component/controller name
We use this information to construct a “fingerprint” of the exception. Exceptions with the same fingerprint are treated as the same error in Honeybadger.
You can customize the grouping for each exception by changing the error class name, component, or stack trace—or by sending a custom fingerprint.
## Anatomy of an error
[Section titled “Anatomy of an error”](#anatomy-of-an-error)
When your app reports an error to us, we make the details available on a web page that looks like this:
Yeah, it looks a little complicated. But once you understand what all the pieces are, you will see it is quite simple.
Let’s inspect this page, piece by piece.
### Navigating occurrences
[Section titled “Navigating occurrences”](#navigating-occurrences)
Honeybadger groups identical errors together. Using our navigation bar, you can still navigate between each individual occurrence (or notice, as we also call them) of the error.
### Resolve / unresolve
[Section titled “Resolve / unresolve”](#resolve--unresolve)
When an error is marked “unresolved” we will not send you any additional notifications when it re-occurs. Errors are auto-resolved on deploy by default, but that is [configurable](/guides/projects/#general-project-settings).
## Error actions
[Section titled “Error actions”](#error-actions)
Here you can perform many of the actions available to your error. Also, as you set up [integrations](/guides/integrations/) for the project, any that can link back to the error (say, an issue tracker like GitHub) can be managed here.
### Assign an error
[Section titled “Assign an error”](#assign-an-error)
Using this button, you can assign the error currently viewed to any user in the project. This can later be used to search by assignment, or, with assignment notifications enabled, to inform a user that a new error has been assigned to them.
### Pause or ignore an error
[Section titled “Pause or ignore an error”](#pause-or-ignore-an-error)
One of the more common actions used is to ignore the occurrences of an error.
#### Pausing
[Section titled “Pausing”](#pausing)
You can choose to “Pause” for a time duration or occurrence count. We will still record the occurrences, we just will not notify you.
#### Ignoring
[Section titled “Ignoring”](#ignoring)
When you “ignore” an error we will stop recording altogether, so it will not go against your quota.
### Resolve on deploy
[Section titled “Resolve on deploy”](#resolve-on-deploy)
By default, Honeybadger resolves all the errors in your project when you [report a deployment](/api/reporting-deployments/), causing new alerts to be sent for any of the errors that re-occur. You can turn off this behavior by unchecking the “Resolve on deploy” checkbox in [Project Settings](/guides/projects/#general-project-settings). When turned off, there is a new action in the [actions area](#error-actions) of the error detail page, allowing you to resolve individual errors on the next deploy.
### Unsubscribe
[Section titled “Unsubscribe”](#unsubscribe)
Unsubscribing from an error disables it from sending notifications - but only for the user currently viewing the error. To silence it for all users, use the pause action.
### Export an error
[Section titled “Export an error”](#export-an-error)
The Export dropdown allows you to download the data for the current error as [Markdown](https://daringfireball.net/projects/markdown/), or export a JSON file of all occurrences via email.
The Markdown version includes the error summary, stack trace, environment details, and breadcrumbs for the current error formatted in standard Markdown syntax compatible with GitHub, Notion, Google Docs, and other Markdown-capable tools.
When exporting all occurrences, you’ll receive an email to download a JSON file containing the data. This file is a [newline-delimited JSON file](https://en.wikipedia.org/wiki/JSON_streaming#Newline-delimited_JSON), which means each line is a valid JSON object. Each of those JSON objects has the data (parameters, context, etc.) for a single occurrence of the error.
### Merge errors
[Section titled “Merge errors”](#merge-errors)
Using the merge action, you can combine one error with another error. This takes all the existing notices from the “donor” error and adds them to the “receiver” error’s notice history.
### Share URL
[Section titled “Share URL”](#share-url)
Sharing the URL of the error will give you a link to a webpage displaying the error. This webpage does not allow for any actions, comments, or the ability to resolve the error.
### Delete
[Section titled “Delete”](#delete)
This removes the error and all of the notice history for that error. This is especially useful if your error information happens to accidentally include sensitive information. New instances of the error will appear again on a new error page.
### Action integrations
[Section titled “Action integrations”](#action-integrations)
GitHub and other project management integrations will add another action button - in GitHub’s case the button is labeled “Create issue”. Other integrations will behave similarly.
## Anatomy of an error, continued
[Section titled “Anatomy of an error, continued”](#anatomy-of-an-error-continued)
Each error page contains a substantial amount of detail related to the error itself and a history of all the actions done to the error. You can see how many times it was resolved or merged and who performed each action.
From the top of the error page, you can see all of the categories and can click to any of them. There’s even a keyboard shortcut for each category.
### Notices
[Section titled “Notices”](#notices)
Note
**Notices** are the individual error events that are sent from your app. We also refer to them as **occurrences**.
The Notices section allows you to see the distribution of occurrences over time. You can constrain the dates and filter using the same search criteria as our [error search](/guides/errors/search/). When you view an error after doing a search, the search criteria will be applied to the notice list.
### Comments
[Section titled “Comments”](#comments)
Communicate with team members, or record notes to retain context around an error. Your comments can be formatted in GitHub-flavored markdown.
### Backtrace
[Section titled “Backtrace”](#backtrace)
Each line in the backtrace links to the GitHub or Bitbucket repo. You can even click a button to open the file in your [local editor](#local-edits).
### Request params, cookies, ENV, etc.
[Section titled “Request params, cookies, ENV, etc.”](#request-params-cookies-env-etc)
When an error occurs during a web request, we record all the relevant debug info like params, cookies, the session, etc.
### Context data
[Section titled “Context data”](#context-data)
Our clients support providing a special set of data called **context**. This data is provided by you to help with debugging. You can use our [search functionality](/guides/errors/search/#search-by-request) to find errors with specific context.
Tip
`user_id` and `user_email` are special context keys that we use to help with looking up users or sending emails (as you can see below.)
## Browsing errors
[Section titled “Browsing errors”](#browsing-errors)
Once you start collecting errors, it can be difficult to keep track of them. To make it easier, we’ve built a great interface for browsing and searching errors.
### Search
[Section titled “Search”](#search)
With advanced search, you can search by any field of params, environment, cookies or the session. Check out our dedicated [search guide](/guides/errors/search/) for more info.
### Batch actions
[Section titled “Batch actions”](#batch-actions)
You can use the *Bulk Update* dropdown to update multiple errors simultaneously. You can apply actions to all search results (this is the default), or you can use the checkboxes in the error list to apply the actions to selected errors.
1. Use the search to select which errors you’d like change.
2. Click on “Actions” and select one or more options from the drop-down.
#### Merging by batch
[Section titled “Merging by batch”](#merging-by-batch)
You can merge two or more errors to create a single error. There are two ways to merge errors:
1. Click the [Merge](#merge-errors) button in the [*Actions*](#error-actions) panel on the error detail page, as described above.
2. Select two or more errors to merge from the [error index page](#browsing-errors) using the checkboxes and use the “Merge to” action in the [*Bulk Update*](#batch-actions) dropdown.
Note: The *Bulk Update* method can merge up to ten thousand error occurrences simultaneously. You can perform multiple updates if necessary.
## Local edits
[Section titled “Local edits”](#local-edits)
One of the advanced features in Honeybadger is configuring your local editor settings so that we can display links to open files locally when showing you an error backtrace:
To configure your editor, [visit the Local Editor tab under My Settings](https://app.honeybadger.io/users/edit#editor). Select the editor you use (if you use a different editor that supports opening files via a custom protocol, [let us know about it](https://www.honeybadger.io/pages/contact)). Next, enter the absolute path to each project you wish to enable local editor links for and click “Save” at the bottom. Re-visit your error pages - they should now have the “Open in editor” links!
Most editors work without any additional setup, but Sublime and Visual Studio Code don’t ship with a custom protocol by default. In order to make them work, you’ll need to install one of these libraries:
* [Sublime 2 handler for OS X](https://github.com/asuth/subl-handler)
* [Sublime 3 handler for OS X](https://github.com/saetia/sublime-url-protocol-mac)
* [Visual Studio Code handler](https://github.com/robyoder/vscode-handler)
If you’re using Atom, make sure you’re on version 1.23 or later for this to work.
Disclaimer: We do not endorse nor support these libraries; they are 3rd party open source software.
## Content Security Policy reports
[Section titled “Content Security Policy reports”](#content-security-policy-reports)
If you use [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers to help mitigate XSS attacks, you can use Honeybadger to track policy violations. You can configure the required headers via code when using [Rails](/lib/ruby/integration-guides/rails-exception-tracking/#content-security-policy-reports) or [Sinatra](/lib/ruby/integration-guides/sinatra-exception-tracking/#content-security-policy-reports), or you can configure your web server or framework to emit the headers. Either way, configuring CSP reporting requires specifying the `report-uri` directive:
```plaintext
Content-Security-Policy: ...; report-uri https://api.honeybadger.io/v1/browser/csp?api_key=PROJECT_API_KEY&env=production
Content-Security-Policy-Report-Only: ...; report-uri https://api.honeybadger.io/v1/browser/csp?api_key=PROJECT_API_KEY&report_only=true&env=production
```
The `env` and `report_only` parameters are optional. When `report_only` is true, CSP report payloads will show up as “CSP Report” in our UI; otherwise, the label will be “CSP Error”.
Since CSP violations can be noisy, we strongly suggest you track them in a separate Honeybadger project.
# Error search
> All the ways you can find your errors.
Honeybadger provides powerful search features that let you easily find previously-occurred errors by type, location, meta-data and many other attributes. You can search for errors in a single project, or across all projects.
To search by error type and message, you can simply enter those into the search box. More advanced searches are accomplished via a special query language. We’ve provided a query builder that lets you construct useful queries quickly and easily.
## How to search
[Section titled “How to search”](#how-to-search)
Enter a free-form text value, or one or more `key:"value"` tokens into the search box. Then press enter, or click on the magnifying glass button.
Tokens are separated by spaces. Single and double quotes are allowed.
Example query: `john class:UserError -tag:wip -tag:pending component:"UsersController" action:'update'`.
Because these search queries can become quite complex, we’ve included a query builder that allows you to construct them without much typing. The query builder automatically opens when you focus the search box.
## Keyboard navigation
[Section titled “Keyboard navigation”](#keyboard-navigation)
Use the following keyboard shortcuts in the search box as you edit your query. Additional context-sensitive options will be shown to you as you type.
| Key | Response |
| ------------- | -------------------------------------------------- |
| enter | Submits form |
| tab | Tabs to next token and selects value inside quotes |
| shift-tab | Reverse-cycles selected token |
| mod backspace | Deletes selected token |
| escape | Closes hint |
## Keyboard shortcuts
[Section titled “Keyboard shortcuts”](#keyboard-shortcuts)
Quickly search errors using the following keyboard shortcuts while on the error page in the project. Note that these shortcuts immediately trigger a page load and will not preserve the state of the search builder.
| Key | Response |
| ------ | ------------------------------------ |
| / | Focus search box |
| A or a | Show resolved And Unresolved Errors |
| U or u | Show Unresolved Errors |
| R or r | Show Resolved Errors |
| M or m | Show Errors Assigned to Me |
| T or t | Show All Users’ Errors |
| J or j | Jump to another project \* |
| E or e | Show errors in all environments \*\* |
\*This shortcut can be used on any page of the project.
\*\*Use first character of environment name to filter by environment.
## How tokens are combined
[Section titled “How tokens are combined”](#how-tokens-are-combined)
When combining different tokens, we use AND. So `class:MyError assignee:myemail@domain.com` searches for `MyError` instances that are assigned to me.
When combining multiple values for the same token, we use OR. For example, `class:"Foo" class:"Bar" `will return errors with class `Foo` OR `Bar`. There’s one minor exception to this rule. Negative tokens, i.e. tokens preceded by `-` will be combined with AND.
Here are a few examples:
| Example query | Searches |
| --------------------------------------- | --------------------------------------------------- |
| `class:"Foo" is:resolved` | Resolved errors with class `Foo` |
| `-class:"Foo" is:resolved` | Resolved errors without class `Foo` |
| `-class:"Foo" -is:resolved` | Unresolved errors without class `Foo` |
| `class:"Foo" class:"Bar" is:resolved` | Resolved errors with class `Foo` OR class `Bar` |
| `-class:"Foo" -class:"Bar" is:resolved` | Resolved errors without class `Foo` AND class `Bar` |
## Examples
[Section titled “Examples”](#examples)
### Search by state
[Section titled “Search by state”](#search-by-state)
Search errors that are resolved, ignored, paused, or pending resolution, and the inverse of those states. By default, Honeybadger sorts all errors by `-is:ignored` and `-is:resolved`, showing you everything that has not been set as ignored or resolved. These tokens are automatically populated in the search box.
| Example query | Searches |
| ------------------------ | -------------------------------------------------------- |
| `is:resolved` | Resolved errors |
| `-is:resolved` | Unresolved errors |
| `is:paused` | Paused errors |
| `-is:paused` | Errors that aren’t paused |
| `is:ignored` | Ignored errors |
| `-is:ignored` | Errors that aren’t ignored |
| `is:pending_resolution` | Errors that are set to be resolved on the next deploy |
| `-is:pending_resolution` | Errors that aren’t set to be resolved on the next deploy |
### Search by assignee
[Section titled “Search by assignee”](#search-by-assignee)
Errors can be assigned to team members, and results can be refined by assignment. Tokens can be combined to search errors assigned to multiple team members.
| Example query | Searches |
| ---------------------------- | ---------------------------------------- |
| `assignee:"nobody"` | Unassigned errors |
| `assignee:"anybody"` | Errors assigned to anyone |
| `assignee:"jane@email.com"` | Errors assigned to a specific person |
| `-assignee:"jane@email.com"` | Errors not assigned to a specific person |
If other, choose a team member from the drop-down list or begin typing to trigger auto-complete.
### Search by environment
[Section titled “Search by environment”](#search-by-environment)
Search errors by your environment:
| Example query | Searches |
| ---------------------------------- | ----------------------------------- |
| `environment:"production"` | Errors occurring in production |
| `-environment:"production"` | Errors not occurring in production |
| `environment:"development"` | Errors occurring in development |
| `-environment:"development"` | Errors not occurring in development |
| `environment:"custom_environment"` | Errors occurring in any environment |
If other, choose an environment from the drop-down list or begin typing to trigger auto-complete.
### Search by date
[Section titled “Search by date”](#search-by-date)
Search errors by their occurrence. Your timezone is automatically determined but can be changed manually.
| Example query | Searches |
| ----------------------------------------- | --------------------------------------------- |
| `occurred.after:"YYYY-MM-DD 0:00 UTC-7"` | Errors last seen after an exact date |
| `occurred.before:"YYYY-MM-DD 0:00 UTC-7"` | Errors last seen before an exact date |
| `occurred.after:"24 hours ago"` | Errors last seen after a human-friendly date |
| `occurred.before:"24 hours ago"` | Errors last seen before a human-friendly date |
You can enter human-friendly dates like `today`, `this week`, or `July 1`, for example: `occurred.after:"this week"`.
If you want to see errors that **last** occurred as of a certain date — that is, they haven’t occurred again since that date — you can use `last_occurred` instead of `occurred`, like so: `last_occurred.before:"1 week ago"`.
### Search by first seen
[Section titled “Search by first seen”](#search-by-first-seen)
Search errors by when they were first seen. Your timezone is automatically determined but can be changed manually.
| Example query | Searches |
| ---------------------------------------- | ---------------------------------------------- |
| `created.after:"YYYY-MM-DD 0:00 UTC-7"` | Errors first seen after an exact date |
| `created.before:"YYYY-MM-DD 0:00 UTC-7"` | Errors first seen before an exact date |
| `created.after:"24 hours ago"` | Errors first seen after a human-friendly date |
| `created.before:"24 hours ago"` | Errors first seen before a human-friendly date |
You can enter human-friendly dates like `today`, `this week`, or `July 1`, for example: `created.after:"September 12"`.
### Search by error details
[Section titled “Search by error details”](#search-by-error-details)
Search error by class, tag, and message.
| Example query | Searches |
| -------------------------------- | ----------------------------------------------------------- |
| `class:"PermissionDeniedError"` | Errors with a certain class |
| `-class:"PermissionDeniedError"` | Errors without a certain class |
| `tag:"tag_example"` | Errors with a tag |
| `-tag:"tag_example"` | Errors Without a tag |
| `message:"404"` | Errors with a message |
| `-message:"404"` | Errors without message text |
| `has:ticket` | Errors with an associated GitHub issue, Asana task, etc. |
| `-has:ticket` | Errors without an associated GitHub issue, Asana task, etc. |
| `has:comment` | Errors that have comments from team members |
| `-has:comment` | Errors that have no comments from team members |
Class, tag, and message can be combined for specific results. For example, the query: `message:"NameError" class:"TextOrganizer" tag:"priority"` searches errors containing “NameError” from the TextOrganizer class with a “priority” tag.
### Search by location
[Section titled “Search by location”](#search-by-location)
Search errors by component, action, URL, file name, and host.
| Example query | Searches |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `component:"UsersController"` | Errors occurring in a controller/component |
| `-component:"UsersController"` | Errors not occurring in a controller/component |
| `action:"update"` | Errors occurring in an action |
| `-action:"update"` | Errors not occurring in an action |
| `request.url:"https://google.com"` | Errors occurring at a URL |
| `-request.url:"https://google.com"` | Errors not occurring at a URL |
| `request.host:"api.yoursite.com"` | Errors occurring in an application with this in the HTTP\_HOST environment variable (the Host: header provided by the browser) |
| `-request.host:"api.yoursite.com"` | Errors not occurring in an application with this in the HTTP\_HOST environment variable (the Host: header provided by the browser) |
| `file:somefile.rb` | Errors occurring in this file |
| `-file:somefile.rb` | Errors not occurring in this file |
| `hostname:"api-east1-a"` | Errors occurring on a server with this hostname |
| `-hostname:"api-east1-a"` | Errors not occurring on a server with this hostname |
| `revision:"v1.10"` | Errors occurring from a deployment tagged with this revision |
| `-revision:"v1.10"` | Errors not occurring from a deployment tagged with this revision |
Locations can be combined for more specific results. For example, the query: `component:"UsersController" action:"update" request.url:"/docs"` searches errors generated from the update action in the UsersController in the URL `camera`.
### Search by request
[Section titled “Search by request”](#search-by-request)
Search errors by context, params, user agent, or session hashes.
| Example query | Searches |
| ----------------------------------------------- | --------------------------------------------------------------------- |
| `context.user_id:*` | Errors that impacted a user (if you send user\_id in context) |
| `context.user_email:*` | Errors that impacted a user (if you send user\_email in context) |
| `context.user.email:"bob@example.io"` | Errors with a matching context value |
| `-context.user.name:"Bob"` | Errors without a matching context value |
| `params.user.first_name:"Bob"` | Errors with a matching param value |
| `params.old:"useless"` | Errors without a matching param value |
| `request.user_agent:"Googlebot` | Errors caused by a user with this user agent |
| `-request.user_agent:"Googlebot` | Errors not caused by a user with this user agent |
| `request.referer:"http://my.site.com/location` | Errors that occurred when the user came from a particular URL |
| `-request.referer:"http://my.site.com/location` | Errors that occurred when the user did not come from a particular URL |
Requests can be combined or nested for more specific results. For example, searching for context.user.email:bob\@example.com would match the following hash that was sent in the context with an error:
`{ user: { email: "bob@example.com" } }`
When searching these hashes, separate the nested levels of the hash with a period. For example `params.user.first_name:bob`.
Searches against context, params, user agent, or session hashes use \* as a wild-card, so a search for `context.user.email:*@example.com` would match any email address at example.com.
### Searching for arrays
[Section titled “Searching for arrays”](#searching-for-arrays)
When searching for data within array values, one way is to do the search on a key that contains the array value. For example, you might have a sidekiq job that shows up with params in our UI like this:
```ruby
{"job" => {"args" => [{"job_class" => "Foo", "job_id" => "123"}]}}
```
To search for “Foo”, your search should look like this: `params.job.args:*Foo*`
You could be more explicit by including the array index in the query: `params.job.args.0.job_id:123`
## Sorting results
[Section titled “Sorting results”](#sorting-results)
Error results can be sorted by date or error count.
### Sort by date
[Section titled “Sort by date”](#sort-by-date)
Sorting by “Last seen” lets you quickly jump to the newest or oldest exceptions that match your search result.
1. Go to your project’s error list page
2. Click on the table header labeled “last seen”
3. Click on it again to reverse the sort order
### Sort by count
[Section titled “Sort by count”](#sort-by-count)
Sorting by “Times” lets you see which errors have happened the most or the fewest times.
1. Go to your project’s error index
2. Click on the table header labeled “times”
3. Click on it again to reverse the sort order
## Saved searches and default search
[Section titled “Saved searches and default search”](#saved-searches-and-default-search)
You can save a search using the button with the bookmark icon to the right of the button with the search icon. This allows to easily re-use a search. You can also pin a saved search to use that search as the default search. Once you have pinned a search, those search terms will be used as the default view for the project.
## Batch actions
[Section titled “Batch actions”](#batch-actions)
You can use the *Bulk Update* dropdown to update multiple errors simultaneously. You can apply actions to all search results (this is the default), or you can use the checkboxes in the error list to apply the actions to selected errors.
1. Use the search to select which errors you’d like change.
2. Click on “Actions” and select one or more options from the drop-down.
## Free-form text search
[Section titled “Free-form text search”](#free-form-text-search)
Search through your errors by **class** or error **message** by typing your search term into the search box. Free-form text queries can also be combined with `key:value` tokens, for example: `john class:UserError component:UsersController action:update`.
# Heroku
> Honeybadger + Heroku <3.
Honeybadger has great built-in support for Heroku, including automated deployment tracking and monitoring of Heroku [platform errors](https://devcenter.heroku.com/articles/error-codes).
## Overview
[Section titled “Overview”](#overview)
There are two ways to use Honeybadger with Heroku: via our Heroku add-on, and via a regular Honeybadger account. Each has its own unique strengths.
* **Heroku Add-On:** When you purchase the Honeybadger add-on through the Heroku marketplace, you’re buying access for a single project and a single user. If this is all you need, the Heroku add-on can be super convenient. But if you have several users managing errors for multiple projects, it can be a hassle…not to mention more expensive.
* **“Regular” Honeybadger Account:** If you’ve signed up for a Honeybadger account via our website, good news! You still have access to all our Heroku-related features. We’ll cover how to set that up below. You’ll also get a plan that allows multiple projects and multiple users.
### Converting Heroku accounts
[Section titled “Converting Heroku accounts”](#converting-heroku-accounts)
If you are currently a Heroku add-on customer and would like to switch to a “regular” account, we can do that. Just email us at .
## Heroku deployment tracking
[Section titled “Heroku deployment tracking”](#heroku-deployment-tracking)
With deployment tracking, Honeybadger is notified when you deploy your app. It’s optional, but enabling it lets you do some really cool things, like:
* Send alerts to Slack whenever your project is deployed.
* Automatically resolve errors on deployment, so that any new occurrences **after** deployment will send you a new notification.
* See which errors occurred after which deployments.
It’s super easy to set up deployment tracking for your Heroku apps. Just run the following command, making sure to add your Honeybadger API key at the end:
```bash
heroku webhooks:add -i api:release -l notify -u "https://api.honeybadger.io/v1/deploys/heroku?repository=git@github.com/username/projectname&environment=production&api_key=PROJECT_API_KEY" --app app-name
```
If you’re using our Ruby gem, you can use the `honeybadger` command line tool to do the same thing:
```bash
bundle exec honeybadger heroku install_deploy_notification
```
## Heroku platform errors
[Section titled “Heroku platform errors”](#heroku-platform-errors)
> If you’re a Heroku add-on customer, platform error monitoring may already be set up. To check, run `heroku drains -a APP_NAME` and see if it mentions Honeybadger or “logplex.honeybadger.io”. If it does, you don’t need to set anything else up.
Normally, Honeybadger only sees errors that happen inside your application. On Heroku, we’re able to go one step farther and monitor [platform errors](https://devcenter.heroku.com/articles/error-codes). These include the dreaded H12 timeouts and R99 errors you may have seen in your Heroku logs.
To capture these errors we use Heroku’s log drain feature. Each line of your logs is sent to our servers in the background. We pull out the errors and throw everything else away.
To add the log drain, run the following command, replacing API\_KEY with your Honeybadger project’s secret token and APP\_NAME with the name of your Heroku app:
```bash
heroku drains:add https://logplex.honeybadger.io/heroku/v1?api_key=PROJECT_API_KEY-a APP_NAME
```
To monitor different environments in the same Honeybadger project, add the `env` parameter to the log drain endpoint, i.e.:
```bash
heroku drains:add https://logplex.honeybadger.io/heroku/v1?api_key=PROJECT_API_KEY&env=production -a APP_NAME
```
## Heroku platform logs
[Section titled “Heroku platform logs”](#heroku-platform-logs)
To send all of your Heroku logs into [Insights](/guides/insights) (in addition to errors, as described above), create an additional log drain for your Heroku app using an API key displayed on the API keys tab of the project settings page:
```bash
heroku drains:add "https://logplex.honeybadger.io/v1/events?api_key=PROJECT_API_KEY"
```
You can optionally add the `env` parameter to the log drain endpoint. If you do so, each payload recorded from Logplex will have a field named `environment` added to it. You can then add a filter for the desired environment to your queries, like `filter environment::str == 'production'`.
```bash
heroku drains:add https://logplex.honeybadger.io/v1/events?api_key=PROJECT_API_KEY&env=production
```
# Insights & Logging
> Dive into your Honeybadger and application events.
You can use [Honeybadger Insights](https://www.honeybadger.io/tour/logging-observability/) to dive into the data collected by Honeybadger and the logs and other events that you send to our [Events API](/api/reporting-events/). We provide a query language (that we lovingly call [BadgerQL](/guides/insights/badgerql/)) that enables quick discovery of what’s happening inside your applications. The Insights UI also lets you chart the results of those queries and add those charts to [dashboards](/guides/dashboards/) that you can share with your team.
## Querying and visualization
[Section titled “Querying and visualization”](#querying-and-visualization)
Our [query language](/guides/insights/badgerql/) strives to be minimalist, yet powerful. With it you can specify which fields you want to see, filter the kinds of events that should be returned, perform aggregations and calculations, and more. When you first load the Insights UI, you will see a query box that has a default query to help you get started:
```plaintext
fields @ts, @preview
| sort @ts
```
This query selects a couple of special fields — the timestamp and a preview of the fields that are available in the event — and sorts the results by time, with the most recent results first. Each row of the query is piped through the following row, which allows you to apply filters, formatting functions, and so on. Let’s do a quick walk-through to see how it works, and to see how it can be used to create visualizations of your data.
### Walk-through
[Section titled “Walk-through”](#walk-through)
Here’s an example of working with some Honeybadger data. First, filter the data to see only the results of [uptime checks](/guides/uptime/):
```plaintext
fields @ts, @preview
| filter event_type::str == "uptime_check"
| sort @ts
```
You can see that we’ve piped the initial results through `filter`, which accepts a variety of conditions, such as the string comparison shown here. You’ll also notice that we specified the data type of the `event_type` field (`str`) so the query parser can validate the functions and comparisons that you use on the field data.
Clicking on the disclosure arrow will show the all the fields that were stored for an event:
Additional disclosure controls appear inside the event detail view when the event has nested objects.
Let’s filter on some additional data that is present in these events. We can limit the results to show only the uptime checks that originated from our Virginia location, and we can change the fields that we display so we can see some info about the results of each check:
```plaintext
fields @ts, location::str, response.status_code::int, duration::int
| filter event_type::str == "uptime_check"
| filter location::str == "Virginia"
| sort @ts
```
Now let’s summarize the data to find the average response duration for all successful checks:
```plaintext
fields duration::int
| filter event_type::str == "uptime_check"
| filter location::str == "Virginia"
| filter response.status_code::int == 200
| stats avg(duration) by bin(1h) as time
| sort time
```
We use `stats` to perform all kinds of calculations, such as averages, and `by` allows us to specify the grouping for those calculations. Grouping by `bin` gives us time-series data, which makes it easy to create a chart by clicking the Line button.
From there you can experiment with different visualizations, update the query to change the chart (try changing `1h` to `15m`), and add the chart to a custom dashboard.
Of course, this functionality isn’t limited to only the data that is generated by Honeybadger. Your error data is also available for querying (`event_type::str == "notice"`), and you can send logs and events to our [API](/api/reporting-events/) to be able to query and chart your own data.
### Streams
[Section titled “Streams”](#streams)
Streams are the fundamental data sources in Honeybadger Insights. They serve as the starting point for your queries and represent the data you want to analyze.
When you create a new Honeybadger project, we automatically set up two streams for you:
**Internal stream**
The Internal Stream is a dedicated stream that stores all Honeybadger-generated events related to your project. This includes errors, deployments, notifications, uptime checks, and other internal Honeybadger data. You cannot directly send custom events to the Internal Stream, as it is managed by Honeybadger itself.
**Default stream**
The Default Stream is the primary stream for storing custom events that you send using Honeybadger client libraries or the Honeybadger API. Any event data you explicitly send to Honeybadger will be stored in the Default Stream.
#### The stream selector
[Section titled “The stream selector”](#the-stream-selector)
You can select the active streams from the stream selector at the top of the query editor. This affects the data that Insights returns for your queries.
Removing a stream you don’t need can improve your query response times, because then Insights doesn’t need to scan that data when executing your query. So for example, if you’re just querying your application logs, you can remove the *Internal* stream to get a faster response.
## Working with dashboards
[Section titled “Working with dashboards”](#working-with-dashboards)
[Dashboards](/guides/dashboards/) allow you to collect different types of charts and query results on a single page. Any query or chart that you generate can be added to a dashboard, which will then be shared with the rest of your team. Each widget on a dashboard includes a link to view the query and raw results behind the widget:
If you change the query or the visualization, you can save those changes back to your dashboard, or add them as a widget to a new dashboard.
We provide some [automatic dashboards](/guides/dashboards/#automatic-dashboards) to get you started. For example, when you [add a Heroku drain](/guides/insights/integrations/heroku/) to your app, the [automatic Heroku dashboard](/guides/dashboards/heroku/) will show data like the number of requests grouped by response code that we automatically collect from [Logplex](https://devcenter.heroku.com/articles/logplex).
To learn more about dashboards, see the [dashboards guide](/guides/dashboards/).
## Adding data from other sources
[Section titled “Adding data from other sources”](#adding-data-from-other-sources)
Insights includes all the events that Honeybadger collects, such as error notifications, uptime checks, and check-in reports, but you can send your own event data as well.
Our [API](/api/reporting-events/) accepts newline-delimited JSON, where each line is a JSON object that describes an event that you care about. You can send user audit trail events, metrics, or any other data you’d like to query and analyze. The type of data most frequently sent to Insights is application log data.
Sending structured logs in a JSON format (like [lograge](https://github.com/roidrage/lograge) produces) allows you to correlate what’s happening in your app with the error data that Honeybadger is already recording for you. See our integration guides to learn how you can easily send log events from sources such as Heroku apps and CloudWatch Logs.
[ Log files ](/guides/insights/integrations/log-files/)Use Vector to ship your log files to Honeybadger Insights
[ Ruby and Rails apps ](/guides/insights/integrations/ruby-and-rails/)Send metrics and events from Ruby and Rails apps to Honeybadger Insights
[ JavaScript apps ](/guides/insights/integrations/javascript/)Send metrics and events from JavaScript apps to Honeybadger Insights
[ PHP/Laravel apps ](/guides/insights/integrations/php-laravel/)Send metrics and events from PHP/Laravel apps to Honeybadger Insights
[ Host metrics ](/guides/insights/integrations/host-metrics/)Send host metrics to Honeybadger Insights
[ CloudWatch Logs ](/guides/insights/integrations/cloudwatch-logs/)Stream AWS CloudWatch Logs to Honeybadger Insights
[ Crunchy Bridge ](/guides/insights/integrations/crunchy-bridge/)Send Crunchy Bridge metrics to Honeybadger Insights
[ Fly.io ](/guides/insights/integrations/fly-io/)Send Fly.io app metrics to Honeybadger Insights
[ Heroku ](/guides/insights/integrations/heroku/)Send Heroku app metrics to Honeybadger Insights
[ Netlify ](/guides/insights/integrations/netlify/)Send Netlify function logs to Honeybadger Insights
[ Systemd (journald) ](/guides/insights/integrations/systemd/)Ship systemd journal logs to Honeybadger Insights
# Alarms guide
> Learn how to create Honeybadger alarms to monitor your Insights data in real time.
Insights alarms allow you to monitor your data in real time and get notified under the conditions you set. Your Honeybadger data, such as errors, deployments, and uptime checks, are already available to query. To learn how to send your own custom data to Honeybadger, see the [Getting started guide](/guides/insights/). Then, you can create alarms for anything your business needs.
## Viewing an alarm
[Section titled “Viewing an alarm”](#viewing-an-alarm)
Alarms combine a [BadgerQL](/guides/insights/badgerql/) query (“count all slow requests in the past five minutes”) with a threshold (“when count is > 2”) and trigger alerts when the query result exceeds the threshold.
In the above chart, the red line is the threshold for the alarm state. This query was in an alarm state for one period in the last hour but recently recovered.
## Creating or updating an alarm
[Section titled “Creating or updating an alarm”](#creating-or-updating-an-alarm)
### Query and timing
[Section titled “Query and timing”](#query-and-timing)
Construct a `query` using [BadgerQL](/guides/insights/badgerql/) to return data you wish to monitor. You may want to use a `filter` function to isolate the relevant data.
Use the `interval` field to specify the time window for the query. The `interval` field is a string that represents the time window for the query. The format is `1d`, `1h`, `1m`, etc. In other words, the `interval` is both the frequency and the time period over which the query is executed.
The `lag` field can be used to delay the query execution by a specified time period. The `lag` field is also a string that represents the time delay for the query. The format is `1d`, `1h`, `1m`, etc. This is useful when you want to wait for slow or late data arriving.
### Result count
[Section titled “Result count”](#result-count)
Alarms are triggered based on the number of results returned by the query. You can specify the logical comparison operator (`>`, `>=`, `<`, `<=`, `==`, `!=`) and a value count. The alarm will trigger when the number of results meets the condition.
### Description
[Section titled “Description”](#description)
It may be helpful to provide a description of the alarm to help you remember its purpose. The description is also delivered as part of the notification when you have integrations setup. Some useful information would be what the alarm is monitoring, what to do when the alarm triggers, and who to contact.
## Integrations
[Section titled “Integrations”](#integrations)
Integrations is where you can configured how to be notified when an alarm changes state. There are two states per integration that can be configured: `ok` and `alert`.
All users can update their personal notification integrations (email, etc.), while users with administrator access to the project can manage the alert settings for all of the project’s integrations.
# BadgerQL guide
> Learn how to use BadgerQL to query your log events and observability data in Honeybadger Insights.
BadgerQL is the language you use to interact with your data stored in Insights. It was designed to enable you to enrich, shape, and combine your events so you can craft any view of your data. Quick reference docs are also available in the application via the book icon in the top-right corner of the query box.
We also provide inline hints in the query editor that show info from the quick reference docs as you type:
## Functions to enrich, shape, and combine data
[Section titled “Functions to enrich, shape, and combine data”](#functions-to-enrich-shape-and-combine-data)
Functions are the core of BadgerQL. You can think of your data falling or piping through each function that you specify, getting filtered, aggregated, and so on along the way. The most common functions you will use are [`fields`](#fields) to select fields to view, [`filter`](#filter) to restrict what data appears in the results, and [`stats`](#stats) to do counts, averages, and other analyses. Keep reading to learn about all the functions we offer.
### Expand
[Section titled “Expand”](#expand)
You can use `expand` to turn an event that has a field with array data into multiple events.
```sql
expand array_field [as alias][, ...]
```
With data that has a single event like `{"id": 1, "charges": [700, 430, 200]}`, the following query will return three events, with `id` and `charge` fields:
```sql
expand charges[*]::int as charge
```
### Fields
[Section titled “Fields”](#fields)
The `fields` function enriches your results by adding extra fields. Any fields that you select or alias can be referenced in later functions, and they will be returned in the final dataset unless rewritten by later functions.
```sql
fields expr [as alias][, ...]*
```
Fields can be aliased with the `as` clause, and unsupported characters (like spaces) can be used by using backticks.
```sql
fields user_name::str as `User name`
```
Aliased fields can be used in later functions:
```sql
fields concat(first_name::str, " ", last_name::str) as full_name
| filter full_name match /^Bob.*/
```
#### Internal fields
[Section titled “Internal fields”](#internal-fields)
We set the following internal fields for you as the data is ingested:
| Name | Type | Description |
| ----------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `@id` | `String` | The event ID |
| `@ts` | `DateTime` | The reported timestamp if provided as `ts` or `timestamp`; otherwise, the time when the event was received |
| `@received_ts` | `DateTime` | The time when the event was received |
| `@stream.id` | `String` | The ID of the stream that contains the event. Each project contains at least two streams: the internal Honeybadger stream used for notices, etc., and the stream used for storing events that you send to our API. |
| `@stream.name` | `String` | The name of the stream |
| `@query.start_at` | `DateTime` | The timestamp of start of the range queried. E.g., when searching back 3 hours (the default), this will be three hours ago |
| `@query.end_at` | `DateTime` | The timestamp of end of the range queried. E.g., for the default query, this would be the time when the query was executed, since the default query searches for data up to the time the query was sent. |
| `@fill` | `Boolean` | Whether the result has filled-in values |
| `@preview` | `JSON Object` | A preview of the data stored for the event |
### Filter
[Section titled “Filter”](#filter)
Filter expects a body that results in a boolean expression, and it will exclude events where the expression returns false.
```sql
filter boolean_expr [and|or ...]*
```
Multiple piped filter functions will act as AND operations.
```sql
filter controller_name::str == "StripeController" and duration::float > 2000
| filter action_name::str == "hook"
```
### Limit
[Section titled “Limit”](#limit)
Limit the number of results returned by the query.
```sql
limit integer [by expr[, ...]*]
```
Include a `by` clause to limit the number of results per group.
```sql
limit 10 by user_id::int
```
Pipe into `limit` to restrict the final number of results returned by the query.
```sql
limit 5 by user_id::int
| limit 100
```
### Only
[Section titled “Only”](#only)
Use `only` to restrict which fields are rendered in the results and in which order they will appear.
```sql
only expr [as alias][, ...]*
```
For example, if you want to filter on a particular field, but you don’t want that field to appear in the results, you can use `only` to select the fields you want to see:
```sql
fields a, b, c
| filter c > 2
| only b, a
```
### Parse
[Section titled “Parse”](#parse)
Extract fields using regular expressions
```sql
parse expr /regex/
```
If your events have data that can be extracted using regular expressions, you can create fields from that data. The following example will extract “redis” from an event that has a field named “addon” that contains the value “redis-fitted-71581” and place it in a new field called “service”. Both the “addon” and “service” fields will appear in the results.
```sql
fields addon::str
| parse addon /(?[[:alpha:]]+)/
```
### Sort
[Section titled “Sort”](#sort)
Order events based on fields.
```sql
sort expr [desc|asc][, ...]*
```
Sort is useful to order results by time, or when calculating stats:
```sql
fields email
| filter action::str == "Logged in"
| stats count() as count by email
| sort count
```
### Stats
[Section titled “Stats”](#stats)
Aggregate event fields
```sql
stats agg_expr[, ...]* by [expr][, ...]*
```
The workhorse of Insights, `stats` allows you to perform calculations on your data. You can count events, calculate averages, and more.
```sql
stats avg(response_time::float)
```
The `by` clause allows you to group the results by one or more fields.
```sql
stats avg(response_time::float) by location::str
```
### Unique
[Section titled “Unique”](#unique)
The `unique` function filters out duplicate events based on the field(s) you specify.
```sql
unique field[, ...]
```
## Expression functions
[Section titled “Expression functions”](#expression-functions)
Expression functions can be used in a variety of places, such as filtering data, creating fields, calculating aggregates, etc. They are used to compare fields, perform arithmetic, reformat data, and more.
### Comparison
[Section titled “Comparison”](#comparison)
| Function | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `>` | |
| `<` | |
| `==` | |
| `!=` | |
| `<>` | |
| `<=` | |
| `>=` | |
| `between` | |
| `not between` | |
| `isNotNull` | |
| `isNull` | |
| `in` | Return true if field value is contained within the array of literal values. The field type must match value type in the array. |
| `not in` | Return true if field value is not contained within the array of literal values. The field type must match value type in the array. |
| `either` | Returns the first non-null value |
| `like` | Returns true when the search string matchesCan use these metacharacters: `%` - Matches an arbitrary amount of characters `_` - Matches single arbitrary characterThe string matcher is case sensitive |
| `not like` | Returns true when the search string does not matchCan use these metacharacters: `%` - Matches an arbitrary amount of characters `_` - Matches single arbitrary characterThe string matcher is case sensitive |
| `ilike` | Returns true when the search string matchesCan use these metacharacters: `%` - Matches an arbitrary amount of characters `_` - Matches single arbitrary characterThe matcher is case insensitive |
| `not ilike` | Returns true when the search string does not matchCan use these metacharacters: `%` - Matches an arbitrary amount of characters `_` - Matches single arbitrary characterThe matcher is case insensitive |
| `match` | Returns true when the regex matchesThe regex uses [re2 regex syntax](https://github.com/google/re2/wiki/Syntax) |
| `not match` | Returns true when the regex does not matchThe regex uses [re2 regex syntax](https://github.com/google/re2/wiki/Syntax) |
### Array macros
[Section titled “Array macros”](#array-macros)
| Function | Description |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `any` | Return true if any conditional logic within the arguments results in a true value.Effectively, we run the logic in the function argument through each array item, and if one matches, then we return true.A function body without an expanded array is considered invalid. |
| `all` | Return true if all conditional logic within the arguments results in a true value.Effectively, we run the logic in the function argument through each array item, and if they all match, then we return true.A function body without an expanded array is considered invalid |
### Logic
[Section titled “Logic”](#logic)
| Function | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `and` | |
| `not` | |
| `or` | |
| `if` | Single path conditional branching |
| `cond` | Multiple path conditional branchingThe `cond()` function allows for evaluating branches (ala. `if` and `else if`) through positional arguments. Each successive pair of arguments acts as an else if, with the first true boolean passing it's result as a return." |
### Arithmetic
[Section titled “Arithmetic”](#arithmetic)
| Function | Description |
| -------- | ----------- |
| `+` | |
| `-` | |
| `/` | |
| `%` | |
| `*` | |
| `abs` | |
| `pow` | |
| `log` | |
| `log2` | |
| `log10` | |
| `round` | |
| `floor` | |
| `ceil` | |
| `exp` | |
### Conversion
[Section titled “Conversion”](#conversion)
| Function | Description |
| ------------ | ----------- |
| `toInt` | |
| `toFloat` | |
| `toString` | |
| `toDate` | |
| `toDateTime` | |
| `toUnix` | |
### Dates
[Section titled “Dates”](#dates)
| Function | Description |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `now` | |
| `toTimezone` | Convert datetimes to a specific timezone.**Note:** This does not explicitly embed the timezone into the datetime, but updates the type to reflect the selected timezone (tzdatetime). |
| `toYear` | |
| `toHour` | Returns the 24-hour number (0-23) for the supplied datetime. |
| `toDay` | Returns the day of month (1-31) for the supplied datetime. |
| `toDayOfWeek` | Returns the number of the day in a week (1-7, 1 = monday) for the supplied datetime. |
| `formatDate` | Render date from format string.##### Date tokens %j day of the year (001-366) 002
%d day of the month, zero-padded (01-31) 02
%e day of the month, space-padded (1-31) 2
%V ISO 8601 week number (01-53) 01
%w weekday as a integer number with Sunday as 0 (0-6) 2
%u ISO 8601 weekday as number with Monday as 1 (1-7) 2
%a abbreviated weekday name (Mon-Sun) Mon
%W full weekday name (Monday-Sunday) Monday
%m month as an integer number (01-12) 01
%M full month name (January-December) January
%b abbreviated month name (Jan-Dec) Jan
%Q Quarter (1-4) 1
%y Year, last two digits (00-99) 18
%Y Year 2018
%C year divided by 100 and truncated to integer (00-99) 20
%g two-digit year format, aligned to ISO 8601, abbreviated from four-digit notation 18
%G four-digit year format for ISO week number, calculated from the week-based year defined by the ISO 8601 standard, normally useful only with %V 2018
%D Short MM/DD/YY date, equivalent to %m/%d/%y 01/02/18
%F short YYYY-MM-DD date, equivalent to %Y-%m-%d 2018-01-02##### Time tokens %s second (00-59) 44
%S second (00-59) 44
%f fractional second 1234560
%i minute (00-59) 33
%h hour in 12h format (01-12) 09
%I hour in 12h format (01-12) 10
%H hour in 24h format (00-23) 22
%l hour in 12h format (01-12) 09
%k hour in 24h format (00-23) 22
%r 12-hour HH:MM AM/PM time, equivalent to %H:%i %p 10:30 PM
%R 24-hour HH:MM time, equivalent to %H:%i 22:33
%p AM or PM designation PM
%T ISO 8601 time format (HH:MM:SS), equivalent to %H:%i:%S 22:33:44
%z Time offset from UTC as +HHMM or -HHMM -0500##### Other tokens %n new-line character (‘’)
%t horizontal-tab character (’)
%% a % sign % |
| `bin` | |
| `toStartOf` | |
| `toEndOf` | |
### URL
[Section titled “URL”](#url)
| Function | Description |
| -------------- | --------------------------------------------------------------------------------------------------- |
| `urlParameter` | Parse out value from valid URL query string |
| `urlPath` | Extracts the path from a URL. Example: `/hot/goss.html` The path does not include the query string. |
| `urlDomain` | Extracts the hostname from a URL. |
### JSON
[Section titled “JSON”](#json)
| Function | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `json` | Extract a value from JSON string.The result will be null if the path does not evalutate to a value, meaning arrays and objects are not valid targets.**NOTE**: While this is something we support, we encourage that you merge any JSON data into your event |
### String
[Section titled “String”](#string)
| Function | Description |
| --------------- | ---------------------------------------------------------------------------- |
| `trim` | |
| `concat` | |
| `lowercase` | |
| `uppercase` | |
| `substring` | |
| `length` | |
| `replace` | Replace all matches of a substring or regex pattern with another string. |
| `replaceFirst` | Replace the first match of a substring or regex pattern with another string. |
| `startsWith` | |
| `toHumanString` | Transform quantities into human readable friendly formats. |
### Aggregate
[Section titled “Aggregate”](#aggregate)
| Function | Description |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `count` | Return the total counts of all results.The count can be affected by supplying a boolean expression argument. If given a field, it will implicitly count non-null occurrences. |
| `percentile` | Calculate the percentile.This is an approximated result. |
| `unique` | Count all unique values |
| `min` | |
| `max` | |
| `sum` | |
| `avg` | |
| `first` | Returns the first encountered value. Results could be random if the source is not sorted. |
| `last` | Returns the last encountered value. Results could be random if the source is not sorted. |
| `apdex` | Returns the Application Performance Index (Apdex) score, which measures user satisfaction with response time. |
## Example queries and use cases
[Section titled “Example queries and use cases”](#example-queries-and-use-cases)
Find N+1 queries in your Rails app:
```plaintext
filter event_type::str == "sql.active_record"
| stats count() as queryCt, sum(duration::float) by request_id::str, query::str
| sort queryCt desc
```
What events are consuming my Insights quota?
Be sure to deselect the [Internal Stream](/guides/insights/#streams) so you only see the data you are sending:
```plaintext
stats sum(@size) as size by event_type::str
| sort size
| only toHumanString(size, "bytes"), event_type
```
# Ship your CloudWatch Logs to Honeybadger Insights
> Here's how to ship your logs from CloudWatch Logs to Honeybadger Insights.
Ingesting logs from CloudWatch Logs requires setting up a [Data Firehose](https://aws.amazon.com/firehose/) stream with a [HTTP Endpoint destination](https://docs.aws.amazon.com/firehose/latest/dev/create-destination.html#create-destination-http) that sends events to our API. Once you create [subscription filters](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SubscriptionFilters.html#FirehoseExample) for the desired log groups, log data from those groups will start flowing into Insights.
The easiest way to set this up is to use our [CloudFormation template](https://honeybadger-docs-assets.s3.amazonaws.com/insights-cloudformation-stack.yml) to create a CloudFormation stack in your AWS account. It will prompt you to enter your Honeybadger API key and the name of a log group that you want to connect to Data Firehose. You can quickly [launch this template in your AWS account](https://console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=honeybadger-insights\&templateURL=https://honeybadger-docs-assets.s3.amazonaws.com/insights-cloudformation-stack.yml) and then create additional log group subscriptions for other log groups you wish to monitor.
If you set up the Data Firehose stream manually, choose HTTP Endpoint as the destination and use the following URL as the HTTP Endpoint URL in the destination settings:
```plaintext
https://api.honeybadger.io/v1/data-firehose-events?api_key=PROJECT_API_KEY
```
# Ship your Crunchy Bridge logs to Honeybadger Insights
> Ship Postgres logs from Crunchy Bridge to Honeybadger Insights.
You can have Crunchy Bridge ship the logs from your Postgres clusters by following their [setup instructions](https://docs.crunchybridge.com/how-to/logging).
Use the following values for the logging destination:
| Field | Value |
| -------- | --------------------------------------------------------------------------------------------------------- |
| Host | in.honeybadger.io |
| Port | 6514 |
| Template | `<$PRI>1 $ISODATE $HOST $PROGRAM $PID ${MSGID:--} [honeybadger@61642 api_key=\"PROJECT_API_KEY\"] $MSG\n` |
You can choose to add additional key/value data to the structured data section of the template. E.g., if you want to add an environment field to the payload, you can specify it after the API key in the template:
```plaintext
<$PRI>1 $ISODATE $HOST $PROGRAM $PID ${MSGID:--} [honeybadger@61642 api_key=\"PROJECT_API_KEY\" environment=\"production\"] $MSG\n
```
# Ship your Fly.io logs to Honeybadger Insights
> Here's how to ship your logs from Fly.io to Honeybadger Insights.
Use [Fly.io’s log shipper app](https://github.com/superfly/fly-log-shipper) to ship logs from your apps hosted by Fly.io. First, create a new app config:
```shell
# Make a directory for your log shipper app
mkdir logshipper
cd logshipper
# Create the app but don't deploy just yet
fly launch --no-deploy --image ghcr.io/superfly/fly-log-shipper:latest
# Set some secrets. Setting HONEYBADGER_API_KEY enables the shipping of logs to your Honeybadger project.
fly secrets set ORG=personal # The org you chose when running "fly launch"
fly secrets set ACCESS_TOKEN=$(fly auth token)
fly secrets set HONEYBADGER_API_KEY=PROJECT_API_KEY
```
Edit the generated `fly.toml` file, replacing the `[http_service]` section with this:
```toml
[[services]]
http_checks = []
internal_port = 8686
```
Then deploy the app:
```shell
fly deploy
```
Once that’s done, you should see logs from your apps flowing into Insights. See the [Fly.io docs](https://fly.io/docs/going-to-production/monitoring/exporting-logs/) for more information about using the log shipper app.
# Ship your Heroku logs to Honeybadger Insights
> Here's how to ship your logs from Heroku to Honeybadger Insights.
To get your Heroku logs into Insights, create a new log drain for your Heroku app using an API key displayed on the API keys tab of the project settings page:
```bash
heroku drains:add "https://logplex.honeybadger.io/v1/events?api_key=PROJECT_API_KEY"
```
You can optionally add the `env` parameter to the log drain endpoint. If you do so, each payload recorded from Logplex will have a field named `environment` added to it. You can then add a filter for the desired environment to your queries, like `filter environment::str == 'production'`.
```bash
heroku drains:add https://logplex.honeybadger.io/v1/events?api_key=PROJECT_API_KEY&env=production
```
# Use Vector to send host metrics to Honeybadger Insights
> Here's how to use Vector to monitor host metrics and send them to Honeybadger.
You can use [Vector](https://vector.dev) to track metrics on your servers (like CPU, memory usage, disk usage, etc.) and send the metrics to Insights. Here’s a sample configuration that will encode the metrics into the newline-delimited JSON format that our API expects:
```yaml
# Put this in /etc/vector/vector.yaml
sources:
host:
type: "host_metrics"
sinks:
honeybadger_events:
type: "http"
inputs: ["host"]
uri: "https://api.honeybadger.io/v1/events"
request:
headers:
X-API-Key: "PROJECT_API_KEY"
encoding:
codec: "json"
framing:
method: "newline_delimited"
```
The metrics look like this in the Insights UI:
Here’s an example BadgerQL query you can use to get a snapshot of the disk usage:
```plaintext
fields @ts, tags.mountpoint::str, round(gauge.value::float * 100, 2) as used_percentage
| filter namespace::str == "host"
| filter name::str == "filesystem_used_ratio"
| filter gauge.value::float > 0.0
| filter tags.filesystem::str not in ["tmpfs", "devtmpfs", "squashfs"]
| sort @ts
| limit 1 by tags.mountpoint
```
Additional information about how to configure Vector to capture host metrics can be found [here](https://vector.dev/docs/reference/configuration/sources/host_metrics/).
The easiest way to run Vector is via Docker. Here’s a sample [Docker Compose](https://docs.docker.com/compose/) configuration you can use, assuming your Vector configuration is in a file named `vector.yaml`:
```yaml
version: "3.2"
services:
vector:
image: timberio/vector:latest-alpine
volumes:
- "vector.yaml:/etc/vector/vector.yaml:ro"
```
# Send logs and events from JavaScript apps to Honeybadger Insights
> Here's how to integrate your JavaScript apps with Honeybadger Insights.
#### Logs
[Section titled “Logs”](#logs)
Instrument your JavaScript application, either backend or frontend, to send your logs automatically to Honeybadger Insights. More information can be found [here](/lib/javascript/guides/sending-events-to-insights/#automatic-log-instrumentation).
#### Events
[Section titled “Events”](#events)
If you have custom events you’d like to track, use `Honeybadger.event()` to report them to Insights:
```javascript
Honeybadger.event("button_click", {
action: "buy_now",
user_id: 123,
product_id: 456,
});
```
More information about sending events to Insights from your JavaScript apps can be found [here](/lib/javascript/guides/sending-events-to-insights/#manually-sending-events).
# Use Vector to ship your log files to Honeybadger Insights
> Here's how to use Vector to watch your log files and send the events they record to Honeybadger.
You can use [Vector](https://vector.dev) to watch your existing log files and send the events they record. Here’s a sample configuration that will encode the log lines into the newline-delimited JSON format that our API expects:
```yaml
# Put this in /etc/vector/vector.yaml
sources:
app:
type: "file"
include: ["/home/app/shared/log/*.log"]
sinks:
honeybadger_events:
type: "http"
inputs: ["app"]
uri: "https://api.honeybadger.io/v1/events"
request:
headers:
X-API-Key: "PROJECT_API_KEY"
encoding:
codec: "json"
framing:
method: "newline_delimited"
```
If you are using something like [Lograge](https://github.com/roidrage/lograge) to emit JSON-formatted logs (and you should — it’s awesome), you can have Vector replace the message field with a JSON payload:
```yaml
# Put this in /etc/vector/vector.yaml
sources:
app:
type: "file"
include: ["/home/app/shared/log/*.log"]
transforms:
parse_logs:
type: "remap"
inputs: ["app"]
source: |
payload, err = parse_json(string!(.message))
if err == null {
.payload = payload
del(.message)
}
sinks:
honeybadger_events:
type: "http"
inputs: ["parse_logs"]
uri: "https://api.honeybadger.io/v1/events"
request:
headers:
X-API-Key: "PROJECT_API_KEY"
encoding:
codec: "json"
framing:
method: "newline_delimited"
```
Or if you are using logfmt-style logs, like “controller=pages action=index”, then you can add a transform that parses that into JSON:
```yaml
---
transforms:
parse_logs:
type: "remap"
inputs: ["app"]
source: |
payload, err = parse_key_value(string!(.message))
if err == null {
.payload = payload
del(.message)
}
```
Again, we **highly** recommend structured logging. 😉
By the way, Vector supports a variety of [input sources](https://vector.dev/docs/reference/configuration/sources/), such as Docker logs, Redis metrics, etc., in addition to log files. You can define whatever `sources` and `transforms` make sense for what you want to capture, then use the `sinks` section provided in the examples above to send everything to Insights.
The easiest way to run Vector is via Docker. Here’s a sample [Docker Compose](https://docs.docker.com/compose/) configuration you can use, assuming your Vector configuration is in a file named `vector.yaml`:
```yaml
version: "3.2"
services:
vector:
image: timberio/vector:latest-alpine
volumes:
- "vector.yaml:/etc/vector/vector.yaml:ro"
```
## Additional Vector configuration examples
[Section titled “Additional Vector configuration examples”](#additional-vector-configuration-examples)
### Nginx logs
[Section titled “Nginx logs”](#nginx-logs)
You can use regular expressions to extract the fields of an Nginx log to create a JSON structure in a transform:
```yaml
sources:
nginx_logs:
type: "file"
ignore_older: 86400
include:
- "/var/log/nginx/access.log"
read_from: "end"
transforms:
parse_nginx:
type: "remap"
inputs:
- "nginx_logs"
source: |
match, err = parse_regex(.message, r'(?P[^ ]*) - (?P[^ ]*) \[(?P[^\]]*)\] "(?P[^ ]*) ?(?P[^ ]*) ?(?P[^"]*)" (?P[^ ]*) (?P[^ ]*) "(?P[^"]*)" "(?P[^"]*)" (?[0-9\.]+)', true)
if err == null {
.remote_addr = match.remote_addr
.user = match.user
.timestamp = parse_timestamp(match.timestamp, "%d/%b/%Y:%H:%M:%S %z") ?? match.timestamp
.request = match.request
.method = match.method
.url = match.url
.protocol = match.protocol
.status, err = to_int(match.status)
.bytes_sent, err = to_int(match.bytes_sent)
.referer = match.referer
.user_agent = match.user_agent
.duration, err = to_float(match.duration)
del(.message)
} else {
log("Failed to parse log line: " + err, level: "error")
}
```
# Ship your Netlify logs to Honeybadger Insights
> Here's how to ship your logs from Netlify to Honeybadger Insights.
You can use Netlify’s [General HTTP endpoint](https://docs.netlify.com/monitor-sites/log-drains/?monitoring-providers=general#general-http-endpoint) to send your Netlify logs to Insights. Choose NDJSON as the Log Drain Format and enter this URL as the Full URL:
```plaintext
https://api.honeybadger.io/v1/events?api_key=PROJECT_API_KEY
```
# Send logs and events from PHP apps to Honeybadger Insights
> Here's how to integrate your PHP apps with Honeybadger Insights.
#### Logs
[Section titled “Logs”](#logs)
Instrument your PHP application, either a Lumen, a Laravel or a plain PHP app, to send your logs automatically to Honeybadger Insights. More information can be found [here](/lib/php/guides/sending-events-to-insights/).
#### Events
[Section titled “Events”](#events)
If you are using Laravel or Lumen, enable the automatic events instrumentation :
```php
'events' => [
'enabled' => true,
'automatic' => HoneybadgerLaravel::DEFAULT_EVENTS,
],
```
If you have custom events you’d like to track, use `Honeybadger.event()` to report them to Insights:
```php
Honeybadger.event('button_click', [
'action' => 'buy_now',
'user_id' => 123,
'product_id' => 456
])
```
More information about sending events to Insights from your PHP apps can be found [here](/lib/php/guides/sending-events-to-insights/).
# Send metrics and events from Ruby and Rails apps to Honeybadger Insights
> Here's how to integrate your Ruby/Ruby on Rails apps with Honeybadger Insights.
#### Logs
[Section titled “Logs”](#logs)
Sending your logs to Insights is a quick way to get some visibility into your app. There are two good options:
##### Semantic Logger
[Section titled “Semantic Logger”](#semantic-logger)
Use the [rails\_semantic\_logger gem](https://github.com/reidmorrison/rails_semantic_logger) and enable the `HoneybadgerInsights` appender by adding `config.semantic_logger.add_appender(appender: :honeybadger_insights)` to `config/application.rb`. Outside of Rails, you can use the same appender with the [semantic\_logger gem](https://github.com/reidmorrison/semantic_logger).
Please note that if you are using SolidQueue, you will need to add the following snippet to `config/initializers/solid_queue.rb` to work around a [known issue with Semantic Logger](https://github.com/reidmorrison/rails_semantic_logger/issues/237) that causes SolidQueue/ActiveJob logging to not be sent to Insights:
```yaml
# Re-open appenders after forking the worker, dispatcher, and scheduler processes
SolidQueue.on_worker_start { SemanticLogger.reopen }
SolidQueue.on_dispatcher_start { SemanticLogger.reopen }
SolidQueue.on_scheduler_start { SemanticLogger.reopen }
```
##### Lograge
[Section titled “Lograge”](#lograge)
Use [Lograge](https://github.com/roidrage/lograge) to emit JSON-formatted output to your log files and Vector to [forward them to Insights](/guides/insights/integrations/log-files/). If you go this route, be sure to disable the log tagging in your Rails environment config (`config/environments/production.rb`) by commenting out the `config.log_tags` line, as that will mess with the JSON output.
#### Metrics
[Section titled “Metrics”](#metrics)
You can get more details about what’s happening in your application by enabling our gem’s automatic instrumentation, which will report information about every SQL query, HTTP request, etc. to Insights. This will consume more Insights quota than the logging approach, but you will get much more data to use for analyzing your app’s performance, and this will populate our ready-made Rails dashboard, which includes charts for request duration, SQL query counts, and more. More information can be found [here](/lib/ruby/getting-started/collecting-and-reporting-metrics).
Alternatively, you can use [Yabeda](https://github.com/yabeda-rb/yabeda) and [our Yabeda integration](https://github.com/honeybadger-io/yabeda-honeybadger_insights) to collect and report metrics in your Ruby and Rails apps. Several default metrics, such as request counts, request duration, etc., will be reported automatically once you’ve added and configured the gems. Alternatively, you can use [Yabeda](https://github.com/yabeda-rb/yabeda) and [our Yabeda integration](https://github.com/honeybadger-io/yabeda-honeybadger_insights) to collect and report metrics in your Ruby and Rails apps. Several default metrics, such as request counts, request duration, etc., will be reported automatically once you’ve added and configured the gems.
#### Events
[Section titled “Events”](#events)
If you have custom events you’d like to track, use `Honeybadger#event` to report those events to Insights:
app/controllers/accounts\_controller.rb
```ruby
class AccountsController < ApplicationController
def create
# Account.create(...)
Honeybadger.event("Created account", account_id: account.id, account_name: account.name, plan: account.subscription.name)
end
end
```
More information about sending events to Insights from your Ruby and Rails apps can be found [here](/lib/ruby/getting-started/sending-events-to-insights).
# Use Vector to ship your systemd logs to Honeybadger Insights
> Here's how to use Vector to watch journald and send events to Honeybadger.
[Journald](https://www.freedesktop.org/software/systemd/man/latest/systemd-journald.service.html) is the logging system used by [systemd](https://systemd.io), the init system used on most modern Linux distributions. It’s a replacement for syslog and rsyslog, and it captures the logs for just about everything running on a Linux server, including services like web and database servers that are managed by systemd. Any systemd-managed process that sends output to stdout will show that output in journald.
You can use [Vector](https://vector.dev) to watch journald and relay the events it captures. Here’s a sample configuration that will encode the journald’s data into the newline-delimited JSON format that our API expects:
```yaml
# Put this in /etc/vector/vector.yaml
sources:
journald:
type: journald
include_matches:
_TRANSPORT:
- stdout
# See the Vector Remap Language reference for more info: https://vrl.dev
transforms:
parse_logs:
type: "remap"
inputs: ["journald"]
source: |
. = {"host": .host, "unit": ._SYSTEMD_USER_UNIT || ._SYSTEMD_UNIT, "message": .message, "timestamp": .timestamp}
structured = parse_json(.message) ?? {}
. = merge!(., structured)
sinks:
honeybadger:
type: "http"
inputs: ["parse_logs"]
uri: "https://api.honeybadger.io/v1/events"
request:
headers:
X-API-Key: "PROJECT_API_KEY"
encoding:
codec: "json"
framing:
method: "newline_delimited"
batch:
max_bytes: 1000000
```
Since journald captures *everything* that happens on your server, and since you probably don’t care about stuff like kernel messages, the `sources` section of the configuration limits what it will pass on to Honeybadger. This configuration will only relay events that were emitted to stdout, like web server logs, Rails application logs, and that sort of thing. If you really want to send everything that gets logged to journald, you can delete the `include_matches` portion of the configuration. See the [Vector documentation](https://vector.dev/docs/reference/configuration/sources/journald/) for more info on filtering the journald input.
The `parse_logs` transformation also reduces the amount of data sent to Insights by stripping out things like the process ID, the user running the service, etc. If you decide you want to be able to query that data in Insights, you can remove the transform and change the `honeybadger` sink `inputs` from “parse\_logs” to “journald”.
Please see our documentation on ingesting [log files](/guides/insights/integrations/log-files/) for a few more handy transformations you can use in your Vector configuration.
## Quick setup method
[Section titled “Quick setup method”](#quick-setup-method)
If you’re running a system that uses apt to manage packages, like Debian or Ubuntu, you can use the following command to fetch and run a [script](https://gist.github.com/stympy/9ccb5a809a6731f53b3335fb4e020c2c#file-install_vector-sh) that installs the Vector package, sets up the configuration file, and starts Vector as a service:
```shell
curl -sL https://gist.github.com/stympy/9ccb5a809a6731f53b3335fb4e020c2c/raw/bc5741a4e277ea3a7d6d0f5e70a67e0767aec221/install_vector.sh > install_vector.sh && \
chmod a+x install_vector.sh && \
HONEYBADGER_API_KEY="PROJECT_API_KEY" ./install_vector.sh
```
# Integrations
> Send Honeybadger data to other services.
Honeybadger has deep support for a wide variety of [third-party integrations](#supported-integrations). This page provides an overview of some cool features available for every integration. These settings are located at **Project settings > Alerts & integrations**. You can click the edit icon and customize the notifications for each integration.
## Customizing integration notifications
[Section titled “Customizing integration notifications”](#customizing-integration-notifications)
### Errors
[Section titled “Errors”](#errors)
You get to choose which error events result in a notification or ticket being created:
### Uptime checks
[Section titled “Uptime checks”](#uptime-checks)
You can edit which uptime events are sent to the integration for all or a subset of the project’s uptime checks:
### Check-Ins
[Section titled “Check-Ins”](#check-ins)
And you can also change what check-in events are reported:
### Environments
[Section titled “Environments”](#environments)
You can ignore environments. We auto-populate the list based on environments we’ve seen in your app.
## Rate escalations
[Section titled “Rate escalations”](#rate-escalations)
Escalations let you receive extra notifications when your error rate exceeds a number you’ve configured.
## Throttling
[Section titled “Throttling”](#throttling)
Avoid floods of notifications when everything goes wrong at once.
## Filters
[Section titled “Filters”](#filters)
With filters, you can be hyper-precise about which errors trigger notifications or issue creation. You could:
* Create issues in separate trackers for staging, prepared and production
* Route notifications to a certain team’s inbox whenever an error assigned to that team reoccurs.
The syntax for channel filters is essentially the same as our search syntax, with a few limitations:
* You can’t filter on params, context, session or other per-notice data
* Filters don’t support freeform text search. You must use the `key:val` syntax.
Below is a list of fields you can use when constructing your queries. Note that you can prefix any query with `-` to create its inverse.
| Example query | Matches |
| ------------------------------- | ------------------------------------------ |
| `is:resolved` | Resolved errors |
| `is:paused` | Paused errors |
| `is:ignored` | Ignored errors |
| `assignee:"nobody"` | Unassigned errors |
| `assignee:"anybody"` | Errors assigned to anyone |
| `assignee:"jane@email.com"` | Errors assigned to a specific person |
| `environment:"production"` | Errors occurring in production |
| `class:"PermissionDeniedError"` | Errors with a certain class |
| `tag:"tag_example"` | Errors with a tag |
| `message:"404"` | Errors with a message |
| `component:"UsersController"` | Errors occurring in a controller/component |
| `action:"update"` | Errors occurring in an action |
Multiple filters are evaluated using a logical OR. If any query matches the error, a notification will be sent. When using negative queries like `-class:Foo`, this OR behavior can give unexpected results. To combine multiple negative matches, use a single filter with a search term like `-class:"Foo" AND -class:"Bar"`.
## Custom formatters
[Section titled “Custom formatters”](#custom-formatters)
For some of our integrations, we allow the option to provide a custom format for specific fields (e.g., email subject line or Trello card title). Your custom format will be used for all events that are applicable for the integration (reported, assigned, marked as resolved, etc).
The following is a list of valid formatter tokens:
| Token | Description |
| --------------- | ----------------------------------------------------------------------------------- |
| `[project]` | The project name |
| `[environment]` | The operating environment — production, development, etc. |
| `[type]` | The event type — occurred, assigned, etc. |
| `[class]` | The class of the error associated with the event |
| `[message]` | The message of the error associated with the event |
| `[component]` | The component name (might be null, usually maps to the controller name) |
| `[action]` | The action name (might be null, usually maps to the controller action e.g. `index`) |
| `[fault_id]` | A unique id for the fault event |
| `[file]` | The filename with path and line number where the error occurred |
| `[backtrace]` | The backtrace of the error associated with the event (first 3 lines) |
| `[url]` | The URL of the event in the Honeybadger UI |
## Supported integrations
[Section titled “Supported integrations”](#supported-integrations)
Your Honeybadger data can be sent to a variety of third-party services, listed below. We support creating issues for errors in the SCM and project management tools, such as GitHub and Jira. For communication tools like Slack and PagerDuty, we can send notifications for errors, sites that go down (and come back up), and check-ins.
[ AlertOps ](/guides/integrations/alertops/)Send alerts to AlertOps
[ Asana ](/guides/integrations/asana/)Create Asana tasks from errors
[ Bitbucket ](/guides/integrations/bitbucket/)Create Bitbucket issues from errors
[ Campfire ](/guides/integrations/campfire/)Send notifications to Campfire
[ ClickUp ](/guides/integrations/clickup/)Create ClickUp tasks from errors
[ ClickUp Chat ](/guides/integrations/clickup-chat/)Send messages to ClickUp Chat
[ Datadog ](/guides/integrations/datadog/)Send events to Datadog
[ Discord ](/guides/integrations/discord/)Send notifications to Discord
[ Email ](/guides/integrations/email/)Receive email notifications
[ GitHub ](/guides/integrations/github/)Create GitHub issues from errors
[ GitLab ](/guides/integrations/gitlab/)Create GitLab issues from errors
[ Google Chat ](/guides/integrations/google-chat/)Send messages to Google Chat
[ ilert ](/guides/integrations/ilert/)Create ilert alerts
[ incident.io ](/guides/integrations/incident-io/)Create incidents in incident.io
[ Instatus ](/guides/integrations/instatus/)Update Instatus status page
[ Intercom ](/guides/integrations/intercom/)Send messages to Intercom
[ Jira & Jira Cloud ](/guides/integrations/jira/)Create Jira issues from errors
[ Linear ](/guides/integrations/linear/)Create Linear issues from errors
[ Mattermost ](/guides/integrations/mattermost/)Send notifications to Mattermost
[ Microsoft Teams ](/guides/integrations/microsoft-teams/)Send messages to Microsoft Teams
[ OpsGenie ](/guides/integrations/opsgenie/)Create OpsGenie alerts
[ PagerDuty ](/guides/integrations/pagerduty/)Create PagerDuty incidents
[ PagerTree ](/guides/integrations/pagertree/)Create PagerTree alerts
[ Redmine ](/guides/integrations/redmine/)Create Redmine issues from errors
[ Rootly ](/guides/integrations/rootly/)Create Rootly incidents
[ Shortcut ](/guides/integrations/shortcut/)Create Shortcut stories from errors
[ Slack ](/guides/integrations/slack/)Send notifications to Slack
[ Splunk On-Call ](/guides/integrations/splunk-on-call/)Create Splunk On-Call incidents
[ Sprintly ](/guides/integrations/sprintly/)Create Sprintly items from errors
[ Trello ](/guides/integrations/trello/)Create Trello cards from errors
[ Webhook ](/guides/integrations/webhook/)Send webhooks to custom endpoints
[ Zulip ](/guides/integrations/zulip/)Send messages to Zulip
# AlertOps
> Connect Honeybadger to AlertOps to route notifications through your incident management and alerting system.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the AlertOps integration
[Section titled “1. Select the AlertOps integration”](#1-select-the-alertops-integration)
 
### 2. Enter the AlertOps URL
[Section titled “2. Enter the AlertOps URL”](#2-enter-the-alertops-url)
After you set up the [integration URL](https://honeybadger.alertops.com/admin/MappingRulesList.aspx) at AlertOps, you can enter that URL here.
### 3. Save
[Section titled “3. Save”](#3-save)
That’s it! You’re good to go.
# Asana
> Connect Honeybadger to Asana to automatically create tasks from errors and track bug fixes in your project workflow.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Asana integration
[Section titled “1. Select the Asana integration”](#1-select-the-asana-integration)
### 2. Enter your project ID
[Section titled “2. Enter your project ID”](#2-enter-your-project-id)
You can find your Project ID from a project view. See the input hint for more details on where the ID is located.
### 3. Connect via OAuth
[Section titled “3. Connect via OAuth”](#3-connect-via-oauth)
Select the “Connect OAuth” button and give access to our app.
### 4. Save
[Section titled “4. Save”](#4-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# Bitbucket
> Connect Honeybadger to Bitbucket to automatically create issues from errors and link commits to deployments.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Bitbucket integration
[Section titled “1. Select the Bitbucket integration”](#1-select-the-bitbucket-integration)
 
### 2. Set the repository name
[Section titled “2. Set the repository name”](#2-set-the-repository-name)
The repository name includes the account name. For example, Honeybadger has a repo called “docs” the repository name we’d enter here is “honeybadger/docs”.
### 3. Authenticate
[Section titled “3. Authenticate”](#3-authenticate)
Click “Save and Authenticate With Bitbucket” to complete setup. This will send you to bitbucket.org to authenticate via OAuth.
# Campfire
> Connect Honeybadger to Campfire to receive real-time application monitoring alerts directly in your team's chat rooms.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Campfire integration
[Section titled “1. Select the Campfire integration”](#1-select-the-campfire-integration)
 
### 2. Create a chatbot integration in Basecamp
[Section titled “2. Create a chatbot integration in Basecamp”](#2-create-a-chatbot-integration-in-basecamp)
You can configure chatbots under **Basecamp** → **\[Your project]** → **Chat** → **…** (click the three dots in the upper right-hand corner of the chat window to get the context menu).
To add a chatbot, click **Configure chatbots** → **Add a new chatbot**, and type “Honeybadger” in the `Name` field.
You can optionally upload an avatar (i.e. [our logo](https://www.honeybadger.io/assets/)). Leave `Command URL` blank.
### 3. Set the chatbot URL in Honeybadger
[Section titled “3. Set the chatbot URL in Honeybadger”](#3-set-the-chatbot-url-in-honeybadger)
After you create the chatbot in Basecamp, click on “Send line from this integration to Chat…” and copy/paste the URL in the example into the
`Chatbot URL` field in Honeybadger.
### 4. Save
[Section titled “4. Save”](#4-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# ClickUp
> Connect Honeybadger to ClickUp to automatically create tasks from errors and track bug fixes in your workflow.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the ClickUp integration
[Section titled “1. Select the ClickUp integration”](#1-select-the-clickup-integration)
### 2. Connect via OAuth
[Section titled “2. Connect via OAuth”](#2-connect-via-oauth)
An OAuth dialog should appear. Log in to your account and grant access to one or more workspaces. You’ll then be redirected back to the integration page.
### 3. Select workspace and teamspace
[Section titled “3. Select workspace and teamspace”](#3-select-workspace-and-teamspace)
Select one of the available workspaces and then a teamspace.
### 4. Select a list (or folder first)
[Section titled “4. Select a list (or folder first)”](#4-select-a-list-or-folder-first)
If the task list you are looking for is in a folder, select that folder first. Task lists that are not in a folder will be immediately listed in the dropdown.
### 5. Set statuses
[Section titled “5. Set statuses”](#5-set-statuses)
After selecting a task list, set the “initial”, “resolve”, and “reopen” statuses.
### 6. Tags
[Section titled “6. Tags”](#6-tags)
Add a list of comma-separated tags you wish to be associated when a task is created.
### 7. Save
[Section titled “7. Save”](#7-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# ClickUp Chat
> Connect Honeybadger to ClickUp Chat to receive real-time application monitoring alerts in your team's chat workspace.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the ClickUp Chat integration
[Section titled “1. Select the ClickUp Chat integration”](#1-select-the-clickup-chat-integration)
### 2. Connect via OAuth
[Section titled “2. Connect via OAuth”](#2-connect-via-oauth)
An OAuth dialog should appear. Log in to your account and grant access to one or more workspaces. You’ll then be redirected back to the integration page.
### 3. Select workspace and channel
[Section titled “3. Select workspace and channel”](#3-select-workspace-and-channel)
Select one of the available workspaces and then a channel where the bot will post.
### 4. Save
[Section titled “4. Save”](#4-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# Datadog
> Connect Honeybadger to Datadog to send application events to your monitoring systems and create unified observability.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Datadog integration
[Section titled “1. Select the Datadog integration”](#1-select-the-datadog-integration)
 
### 2. Set the API key
[Section titled “2. Set the API key”](#2-set-the-api-key)
You can generate a Datadog API key on the Datadog integrations page.
### 3. Select region
[Section titled “3. Select region”](#3-select-region)
Choose from the following supported Datadog regions: US1, US3, US5, US1-FED, EU1, or AP1.
### 4. Select label (optional)
[Section titled “4. Select label (optional)”](#4-select-label-optional)
If you have multiple Datadog integrations, you can add a label to differentiate in the integration list view.
### 5. Choose whether to send metrics
[Section titled “5. Choose whether to send metrics”](#5-choose-whether-to-send-metrics)
Enabling the “Send metrics” option will result in the metric `honeybadger.occurrences_per_minute` to be reported to Datadog.
### 4. Save
[Section titled “4. Save”](#4-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# Discord
> Connect Honeybadger to Discord to receive real-time application monitoring alerts directly in your team's channels.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select Discord from the integrations list
[Section titled “1. Select Discord from the integrations list”](#1-select-discord-from-the-integrations-list)
### 2. Enter your Discord webhook URL
[Section titled “2. Enter your Discord webhook URL”](#2-enter-your-discord-webhook-url)
You can find your Discord Webhook URL under Channel Settings > Webhooks.
### 3. Save
[Section titled “3. Save”](#3-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# Email
> Configure email notifications from Honeybadger to receive real-time application monitoring alerts and incident updates directly in your inbox.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
Heads Up! This isn’t where you configure your personal email notifications. This email channel is specifically for integrating with services like Basecamp which consume inbound email.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Email integration
[Section titled “1. Select the Email integration”](#1-select-the-email-integration)
 
### 2. Enter the email address
[Section titled “2. Enter the email address”](#2-enter-the-email-address)
It’s just an email address, folks. I’m sure you can figure it out. :wink:
### 3. Save
[Section titled “3. Save”](#3-save)
That’s it! Just save and you’re ready to go.
# GitHub
> Connect Honeybadger to GitHub to automatically create issues from errors and link commits to deployments.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the GitHub integration
[Section titled “1. Select the GitHub integration”](#1-select-the-github-integration)
 
### 2. Authenticate
[Section titled “2. Authenticate”](#2-authenticate)
If you haven’t already granted our GitHub app access to your account, you will be prompted to do so. After that is done, you’ll be prompted to install our GitHub app in your GitHub repositories. Once that’s done, you’ll be able to create a new GitHub integration.
### 3. Set the repository name
[Section titled “3. Set the repository name”](#3-set-the-repository-name)
The repository name includes the account or organization name. For example, our gem is hosted at , so we’d enter “honeybadger-io/ruby” for the repo name to connect to that repository.
### 4. Enter labels (optional)
[Section titled “4. Enter labels (optional)”](#4-enter-labels-optional)
If you’d like us to label issues we create in GitHub, just enter a comma-separated list of tags here.
### 5. Title format (optional)
[Section titled “5. Title format (optional)”](#5-title-format-optional)
Customize the issue title, if you want, with our handy [custom formatters](/guides/integrations/#custom-formatters).
### 6. Save
[Section titled “6. Save”](#6-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# GitLab
> Connect Honeybadger to GitLab to automatically create issues from errors and link commits to deployments.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the GitLab integration
[Section titled “1. Select the GitLab integration”](#1-select-the-gitlab-integration)
 
### 2. Set the repository name
[Section titled “2. Set the repository name”](#2-set-the-repository-name)
The repository name includes the account or organization name. For example, if your project is hosted at , you’d enter “honeybadger-io/app” for the repo name to connect to that repository.
### 3. Enter labels (optional)
[Section titled “3. Enter labels (optional)”](#3-enter-labels-optional)
If you’d like us to label issues we create in GitLab, just enter a comma-separated list of tags here.
### 4. Enter server URL and personal access token (optional)
[Section titled “4. Enter server URL and personal access token (optional)”](#4-enter-server-url-and-personal-access-token-optional)
Our default configuration assumes you are hosting your code at gitlab.com and that we’ll use OAuth to connect to your account for creating issues. If you are using a self-hosted version of GitLab, then enter the URL of the GitLab installation and enter a personal access token. We will use that personal access token (generated in the GitLab UI at Settings -> Access Tokens) rather than OAuth.
### 5. Save
[Section titled “5. Save”](#5-save)
That’s it! You’ll be redirected to GitLab to grant OAuth access (if you left the server URL unchanged), or back to the integrations list if you used a custom server URL and a personal access token. Either way, once you’re back at the integrations list, you can Edit your new GitLab integration and use the Test button to test creating an issue in your repository.
# Google Chat
> Connect Honeybadger to Google Chat to receive real-time application monitoring alerts directly in your team's spaces.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Google Hangouts Chat integration
[Section titled “1. Select the Google Hangouts Chat integration”](#1-select-the-google-hangouts-chat-integration)
 
### 2. Set the webhook URL
[Section titled “2. Set the webhook URL”](#2-set-the-webhook-url)
You can get the Webhook URL by clicking the channel name where you want the notifications to appear in the Hangouts Chat UI:
Choosing the “Add webhooks” option presents a popup that allows you to create a new webhook. You can enter “Honeybadger” for the name, and grab a copy of HB’s [PNG bolt logo](https://honeybadger-static.s3.amazonaws.com/brand_assets/honeybadger_bolt/honeybadger_bolt.png) from our [brand assets page](https://www.honeybadger.io/assets/) for the avatar URL. Saving the webhook generates the webhook URL:
Choose the Copy link button from the actions menu to copy the URL to your clipboard, then enter that url in channel settings in the Honeybadger UI.
### 3. Save
[Section titled “3. Save”](#3-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
## Honeybadger chat bot
[Section titled “Honeybadger chat bot”](#honeybadger-chat-bot)
If you’d like to install our chat bot in Google Hangouts Chat, search for “Honeybadger” in the “Find people, rooms, bots” search box in the Chat UI. Adding our bot in Chat will prompt you to authorize the bot’s access to your Honeybadger account. Once you do that, you’ll be able to work with your Honeybadger data from within Chat.
# ilert
> Connect Honeybadger to ilert to receive real-time alerts and manage incidents from your on-call workflow.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
[ilert](https://www.ilert.com/) provides alert routing, escalations, and on-call scheduling, ensuring critical issues always reach the right person at the right time. Honeybadger can send events to ilert to trigger alerts when your applications are having problems.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the ilert integration in Honeybadger
[Section titled “1. Select the ilert integration in Honeybadger”](#1-select-the-ilert-integration-in-honeybadger)
 
### 2. Create a Honeybadger alert source in ilert
[Section titled “2. Create a Honeybadger alert source in ilert”](#2-create-a-honeybadger-alert-source-in-ilert)
Follow ilert’s instructions to [create a new alert source for Honeybadger](https://docs.ilert.com/inbound-integrations/honeybadger), and copy the “Honeybadger URL” from the integration settings page.
### 3. Copy/paste the webhook URL from ilert into Honeybadger
[Section titled “3. Copy/paste the webhook URL from ilert into Honeybadger”](#3-copypaste-the-webhook-url-from-ilert-into-honeybadger)
Copy and paste the “Honeybadger URL” from the integration settings page in ilert into the “URL” field in Honeybadger.
### 4. Save
[Section titled “4. Save”](#4-save)
That’s it! You can test the integration by clicking “Test.” Otherwise, just save it and you’re ready to go.
# incident.io
> Connect Honeybadger to incident.io to automatically create incidents from critical errors and manage your response process.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Create an API key in incident.io.
[Section titled “1. Create an API key in incident.io.”](#1-create-an-api-key-in-incidentio)
From your incident.io dashboard, go to Settings > API keys > Add new. Create an API key with the following permissions:
* Create incidents
* Edit incidents
* Create and manage on-call resources
Make sure to copy the generated token.
### 2. In Honeybadger, locate the incident.io integration.
[Section titled “2. In Honeybadger, locate the incident.io integration.”](#2-in-honeybadger-locate-the-incidentio-integration)
In the project settings, click on the **Integrations** tab where you’ll find the incident.io integration.
### 3. Fill in the required fields and save.
[Section titled “3. Fill in the required fields and save.”](#3-fill-in-the-required-fields-and-save)
Fill in API key field with the generated token from step 1 and then specify the alert source label. This will create an alert source in your incident.io account.
### 4. Test the integration.
[Section titled “4. Test the integration.”](#4-test-the-integration)
Click on the “Test this integration” button to send a test notification to your incident.io account. This is a great way to ensure that everything is set up correctly before you start receiving real notifications.
# Instatus
> Connect Honeybadger to Instatus to automatically update your status page when critical errors and application issues are detected.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Instatus integration
[Section titled “1. Select the Instatus integration”](#1-select-the-instatus-integration)
 
### 2. Set the webhook URL
[Section titled “2. Set the webhook URL”](#2-set-the-webhook-url)
Go to Instatus dashboard, under Monitors, select Custom service (webhook). Copy your component’s webhook URL, and then enter that URL into the Webhook URL field in the Honeybadger UI.
### 3. Save
[Section titled “3. Save”](#3-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# Intercom
> Connect Honeybadger to Intercom to track errors affecting specific users and provide better customer support.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Intercom integration
[Section titled “1. Select the Intercom integration”](#1-select-the-intercom-integration)
### 2. Enter your context field
[Section titled “2. Enter your context field”](#2-enter-your-context-field)
This is the field that you set in the context in your application with the user ID that is associated with your Intercom users. For example, if you are identifying users with Intercom with `current_user.id`, and you have `current_user.id` in the `user_id` field of your context, then enter `user_id` in this field.
### 3. Connect via OAuth
[Section titled “3. Connect via OAuth”](#3-connect-via-oauth)
Select the “Connect OAuth” button and give access to our app.
### 4. Save
[Section titled “4. Save”](#4-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# Jira & Jira Cloud
> Connect Honeybadger to Jira to automatically create tickets from errors and track bug fixes in your project workflow.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
We currently have two different service integrations for Jira. Both versions provide the same features, but differ in the way they authenticate requests.
## Which integration to choose?
[Section titled “Which integration to choose?”](#which-integration-to-choose)
If you are running a Jira Server, then the original [Jira](#jira) Integration is your only option. You *may also* use this integration for Jira Cloud, but we don’t recommend it as it uses Basic Authentication which requires storing credentials to make a API request.
If you are using Jira Cloud, then we highly recommend the newer [Jira Cloud](#jira-cloud) integration as this uses OAuth and only requires us to keep a token for authentication.
## Jira
[Section titled “Jira”](#jira)
### 1. Select the Jira integration
[Section titled “1. Select the Jira integration”](#1-select-the-jira-integration)
 
### 2. Configure
[Section titled “2. Configure”](#2-configure)
Here’s an overview of the options:
* The **username** and **password** will be your login for Jira.
* The **server url** is the subdomain of your Jira instance, such as “”. Don’t forget the “https\://”.
* The **project key** was setup when you created the project. It can be found (on Jira) from Project Overview > Administration > Edit Project.
* The **transition** ID’s can be set in your workflows on Jira when viewed in text mode. ID’s are unique, so make sure there are no conflicting values.
### 3. Save
[Section titled “3. Save”](#3-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
## Jira Cloud
[Section titled “Jira Cloud”](#jira-cloud)
### 1. Select the Jira Cloud integration
[Section titled “1. Select the Jira Cloud integration”](#1-select-the-jira-cloud-integration)
 
### 2. Configure
[Section titled “2. Configure”](#2-configure-1)
Here’s an overview of the options:
* The **project key** was setup when you created the project. It can be found (on Jira) from Project Overview > Administration > Edit Project.
* The **transition** ID’s can be set in your workflows on Jira when viewed in text mode. ID’s are unique, so make sure there are no conflicting values.
### 3. Save
[Section titled “3. Save”](#3-save-1)
Click “Save” to be sent to Atlassian to authorize our Honeybadger App.
That’s it! Once we have an OAuth connection to your instance you can test the integration clicking “Test”.
# Linear
> Connect Honeybadger to Linear to automatically create issues from errors and track bug fixes in your project workflow.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Linear integration
[Section titled “1. Select the Linear integration”](#1-select-the-linear-integration)
### 2. Connect via OAuth
[Section titled “2. Connect via OAuth”](#2-connect-via-oauth)
An OAuth dialog should appear. Log in to your account, and give access to our app.
### 3. Select team
[Section titled “3. Select team”](#3-select-team)
We gathered all teams associated with your account. Select the team you want to integrate with.
### 4. Project & labels (optional)
[Section titled “4. Project & labels (optional)”](#4-project--labels-optional)
We can associate a project or any labels when we create your issue.
### 5. Unresolved state
[Section titled “5. Unresolved state”](#5-unresolved-state)
This is both the initial and the state that we transition your issue back to if it is reopened.
### 6. Resolved state
[Section titled “6. Resolved state”](#6-resolved-state)
The issue state for resolved errors.
### 7. Save
[Section titled “7. Save”](#7-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# Mattermost
> Connect Honeybadger to Mattermost to receive real-time application monitoring alerts directly in your team's chat channels.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Mattermost integration
[Section titled “1. Select the Mattermost integration”](#1-select-the-mattermost-integration)
 
### 2. Set the webhook URL
[Section titled “2. Set the webhook URL”](#2-set-the-webhook-url)
Choose Integrations from the Mattermost sidebar menu, then Incoming Webhooks, and click the “Add Incoming Webhook” button. Enter the options you want, then save the new webhook. Copy the URL displayed on the next page, and then enter that URL into the Webhook URL field in the Honeybadger UI.
### 3. Save
[Section titled “3. Save”](#3-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# Microsoft Teams
> Connect Honeybadger to Microsoft Teams to receive real-time application monitoring alerts in your team collaboration workspace.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Microsoft Teams integration
[Section titled “1. Select the Microsoft Teams integration”](#1-select-the-microsoft-teams-integration)
 
### 2. Set the webhook URL
[Section titled “2. Set the webhook URL”](#2-set-the-webhook-url)
Choose Connectors from the popup channel menu, then Incoming Webhook, and click “Configure” or “Add”. Enter the options you want, then save the new webhook. Copy the provided URL, and then enter that URL into the Webhook URL field in the Honeybadger UI.
### 3. Save
[Section titled “3. Save”](#3-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# OpsGenie
> Connect Honeybadger to OpsGenie to route critical errors and application issues through your incident management and on-call alerting system.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the OpsGenie integration
[Section titled “1. Select the OpsGenie integration”](#1-select-the-opsgenie-integration)
 
### 2. Set the API key
[Section titled “2. Set the API key”](#2-set-the-api-key)
Caution
Please note that the OpsGenie integration labeled “Honeybadger” is an older version that doesn’t currently support all the events we send.
You can generate a OpsGenie API key by creating an [API Integration](https://support.atlassian.com/opsgenie/docs/create-a-default-api-integration/) by logging in to OpsGenie then going to Settings - Integrations and selecting “API”.
### 3. Select region
[Section titled “3. Select region”](#3-select-region)
We can send to both US and EU regions.
### 4. Select label (optional)
[Section titled “4. Select label (optional)”](#4-select-label-optional)
If you have multiple OpsGenie integrations, you can add a label to differentiate in the integration list view.
### 5. Save
[Section titled “5. Save”](#5-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
## Configuring OpsGenie alerts
[Section titled “Configuring OpsGenie alerts”](#configuring-opsgenie-alerts)
OpsGenie provides the option to route the alerts based on the kind of event that is reported to OpsGenie, and elements from the event payloads can be used in the alert rules. For example, when a check-in fails to report on time, Honeybadger will send the “Check-In Missing” event to OpsGenie. You can use the **Details (key-value)** condition to match that event by specifying “Event” as the **Key** and “Check-In Missing” as the **Value**:
## Event Payloads
[Section titled “Event Payloads”](#event-payloads)
The following events are supported by the OpsGenie integration:
### `Assigned`
[Section titled “Assigned”](#assigned)
Sent when an error is assigned to a user.
**Additional Details keys:** `Error Details`, `Project`, `Environment`, `Assignee Name`, `Assignee Email`
### `Cert Will Expire`
[Section titled “Cert Will Expire”](#cert-will-expire)
Sent when an SSL certificate is about to expire.
**Additional Details keys:** `Project`, `Name`, `URL`
### `Check-In Missing`
[Section titled “Check-In Missing”](#check-in-missing)
Sent when an expected check-in is missing.
**Additional Details keys:** `Check-In Details`, `Project`, `Name`
### `Check-In Reporting`
[Section titled “Check-In Reporting”](#check-in-reporting)
Sent when a check-in reports successfully.
**Additional Details keys:** `Check-In Details`, `Project`, `Name`
### `Commented`
[Section titled “Commented”](#commented)
Sent when a comment is added to an error.
**Additional Details keys:** `Error Details`, `Project`, `Environment`, `Author`
### `Deployed`
[Section titled “Deployed”](#deployed)
Sent when a deployment is recorded.
**Additional Details keys:** `Project`, `Environment`, `Revision`, `Repository`
### `Down`
[Section titled “Down”](#down)
Sent when an uptime check fails.
**Additional Details keys:** `Outage Details`, `Project`, `Name`, `URL`
### `Occurred`
[Section titled “Occurred”](#occurred)
Sent when an error occurs.
**Additional Details keys:** `Error Details`, `Project`, `Environment`
### `Rate Exceeded`
[Section titled “Rate Exceeded”](#rate-exceeded)
Sent when error rate threshold is exceeded.
**Additional Details keys:** `Error Details`, `Project`, `Environment`
### `Resolved`
[Section titled “Resolved”](#resolved)
Sent when an error is marked as resolved.
**Additional Details keys:** `Error Details`, `Project`, `Environment`
### `Unresolved`
[Section titled “Unresolved”](#unresolved)
Sent when a resolved error occurs again.
**Additional Details keys:** `Error Details`, `Project`, `Environment`
### `Up`
[Section titled “Up”](#up)
Sent when an uptime check succeeds after being down.
**Additional Details keys:** `Outage Details`, `Project`, `Name`, `URL`
# PagerDuty
> Connect Honeybadger to PagerDuty to route critical errors and application issues through your incident response workflow and on-call schedules.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the PagerDuty integration
[Section titled “1. Select the PagerDuty integration”](#1-select-the-pagerduty-integration)
 
### 2. Set the API key
[Section titled “2. Set the API key”](#2-set-the-api-key)
You can generate an integration key for Honeybadger by logging in to PagerDuty then clicking on “Add New Service” and choosing “Honeybadger” as the service type. [Here’s a walkthrough](https://www.pagerduty.com/docs/guides/honeybadger-integration-guide/).
### 3. Save
[Section titled “3. Save”](#3-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
## Event rules in PagerDuty
[Section titled “Event rules in PagerDuty”](#event-rules-in-pagerduty)
You can use PagerDuty’s [event rules](https://support.pagerduty.com/docs/event-management#section-suppression-and-event-rules) feature to suppress an event or change its severity based on data sent from Honeybadger. For instance, when an exception is sent to PagerDuty, you could set the severity to “critical” for a specific environment when `fault.environment` equals “production”.
The custom data payloads sent from Honeybadger are the same as our [webhook event payloads](/guides/integrations/webhook/#event-payloads).
## Upgrading a legacy PagerDuty integration
[Section titled “Upgrading a legacy PagerDuty integration”](#upgrading-a-legacy-pagerduty-integration)
If your integration is marked “legacy”, then you should upgrade by deleting your existing integration and then creating a new integration following the instructions above. If you use Event Rules in PagerDuty, see the next paragraph.
The custom data payload sent to PagerDuty has changed to match our [webhook event payloads](/guides/integrations/webhook/#event-payloads). If you use [event rules in PagerDuty](#event-rules-in-pagerduty) based on the old payload, you will need to update your rules.
# PagerTree
> Connect Honeybadger to PagerTree to route critical errors and application issues through your incident management and on-call system.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the PagerTree integration
[Section titled “1. Select the PagerTree integration”](#1-select-the-pagertree-integration)
 
### 2. Set the integration URL
[Section titled “2. Set the integration URL”](#2-set-the-integration-url)
Follow the steps outlined in the [PagerTree documentation](https://pagertree.com/knowledge-base/integration-honeybadger/) to get the Endpoint URL. Enter that URL into the URL field in the Honeybadger UI.
### 3. Save
[Section titled “3. Save”](#3-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# Error assigned event payload
> Sent when an error is assigned to a user.
Sent when an error is assigned to a user.
```json
{
"event": "assigned",
"message": "[Testy McTestFace/production] ActiveRecord::StatementInvalid assigned to George Jetson by Ben",
"actor": {
"id": 1,
"email": "ben@example.com",
"name": "Ben"
},
"fault": {
"project_id": 123321,
"klass": "ActiveRecord::StatementInvalid",
"component": "search",
"action": "index",
"environment": "production",
"resolved": true,
"ignored": false,
"created_at": "2023-01-31T03:10:01.126549Z",
"comments_count": 3,
"message": "PG::SyntaxError: ERROR: syntax error in tsquery: \"厄瓜多尔Google霸屏【TG飞机:@bapingseo】腾讯视频谷歌完全无广告版【TG飞机:@bapingseo】不到外贸行业运营推广计划怎么写谷歌相机的广告怎么关掉?Em0atRS3g3F4.html\"",
"notices_count": 5514,
"last_notice_at": "2023-02-06T12:20:01.772130Z",
"tags": [],
"id": 42,
"assignee": "george@example.com",
"url": "https://app.honeybadger.io/projects/123321/faults/42",
"deploy": {
"environment": "production",
"revision": "dd2ce1c1f5be3532e10fadf2224a19847f0c62e9",
"repository": "https://github.com/spacely/testy-mctestface",
"local_username": "heroku-redis@addons.heroku.com",
"created_at": "2023-02-01T05:12:31.417405Z",
"changelog": [],
"url": "https://github.com/spacely/testy-mctestface/compare/3e51742fd5f43197891a67b74a54903513e59ce5...dd2ce1c1f5be3532e10fadf2224a19847f0c62e9"
}
},
"assignee": {
"id": 99,
"email": "george@example.com",
"name": "George Jetson"
}
}
```
# Certificate expiration event payload
> Sent when an SSL certificate is about to expire.
Sent when an SSL certificate is about to expire.
```json
{
"event": "cert_will_expire",
"message": "[My Private Project] SSL certificate for gerlach-bergnaum.net will expire on 11/2/2023 11:22:41 UTC",
"project": {
"id": 4,
"name": "My Private Project"
},
"site": {
"id": "f0cacf21-8446-4545-9544-f764b9470c29",
"name": "gerlach-bergnaum.net",
"url": "http://steuber-ernser.com/martha_crona",
"frequency": 5,
"match_type": "success",
"match": null,
"state": "up",
"active": true,
"last_checked_at": "2023-07-21 17:46:24 UTC",
"retries": 0,
"proxy": 0,
"cert_will_expire_at": "2023-11-02 11:22:41 UTC",
"details_url": "http://localhost:3000/projects/4/sites/f0cacf21-8446-4545-9544-f764b9470c29"
}
}
```
# Check-in missing event payload
> Sent when an expected check-in is missing.
Sent when an expected check-in is missing.
```json
{
"event": "check_in_missing",
"message": "[Voyager Test] MISSING: Voyager hasn't checked in for 4 years",
"project": {
"id": 67747,
"name": "Voyager Test",
"created_at": "2019-12-23T21:28:16.571090Z",
"disable_public_links": false,
"pivotal_project_id": null,
"asana_workspace_id": null,
"token": "abcd1234",
"github_project": null,
"environments": [
{
"id": 94721,
"project_id": 67747,
"name": "development",
"notifications": true,
"created_at": "2020-01-08T16:00:02.343155Z",
"updated_at": "2020-01-08T16:00:02.343155Z"
},
{
"id": 94355,
"project_id": 67747,
"name": "local",
"notifications": true,
"created_at": "2019-12-23T21:28:30.733084Z",
"updated_at": "2019-12-23T21:28:30.733084Z"
}
],
"owner": {
"id": 1,
"email": "ben@example.com",
"name": "Spacely Sprockets"
},
"last_notice_at": "2020-11-10T20:07:04.000000Z",
"earliest_notice_at": "2023-05-03T19:39:33.365387Z",
"unresolved_fault_count": 3,
"fault_count": 6,
"active": true,
"users": [
{
"id": 1,
"email": "ben@example.com",
"name": "Ben"
}
],
"sites": [],
"team_id": null
},
"check_in": {
"state": "missing",
"schedule_type": "simple",
"reported_at": "2019-12-23T21:39:37.124397Z",
"expected_at": "2023-10-30T19:42:28.853152Z",
"missed_count": 33385,
"grace_period": "00:00:00",
"id": "XYZLOL",
"name": "Voyager",
"slug": null,
"url": "https://api.honeybadger.io/v1/check_in/XYZLOL",
"details_url": "https://app.honeybadger.io/projects/67747/check_ins",
"report_period": "1 hour"
}
}
```
# Check-in reporting event payload
> Sent when a check-in reports successfully.
Sent when a check-in reports successfully.
```json
{
"event": "check_in_reporting",
"message": "[Voyager Test] REPORTING: Voyager is reporting again",
"project": {
"id": 67747,
"name": "Voyager Test",
"created_at": "2019-12-23T21:28:16.571090Z",
"disable_public_links": false,
"pivotal_project_id": null,
"asana_workspace_id": null,
"token": "abcd1234",
"github_project": null,
"environments": [
{
"id": 94721,
"project_id": 67747,
"name": "development",
"notifications": true,
"created_at": "2020-01-08T16:00:02.343155Z",
"updated_at": "2020-01-08T16:00:02.343155Z"
},
{
"id": 94355,
"project_id": 67747,
"name": "local",
"notifications": true,
"created_at": "2019-12-23T21:28:30.733084Z",
"updated_at": "2019-12-23T21:28:30.733084Z"
}
],
"owner": {
"id": 1,
"email": "ben@example.com",
"name": "Spacely Sprockets"
},
"last_notice_at": "2020-11-10T20:07:04.000000Z",
"earliest_notice_at": "2023-05-03T19:39:54.491724Z",
"unresolved_fault_count": 3,
"fault_count": 6,
"active": true,
"users": [
{
"id": 1,
"email": "ben@example.com",
"name": "Ben"
}
],
"sites": [],
"team_id": null
},
"check_in": {
"state": "missing",
"schedule_type": "simple",
"reported_at": "2019-12-23T21:39:37.124397Z",
"expected_at": "2023-10-30T19:42:28.853152Z",
"missed_count": 33385,
"grace_period": "00:00:00",
"id": "XYZLOL",
"name": "Voyager",
"slug": null,
"url": "https://api.honeybadger.io/v1/check_in/XYZLOL",
"details_url": "https://app.honeybadger.io/projects/67747/check_ins",
"report_period": "1 hour"
}
}
```
# Error Comment event payload
> Sent when a comment is added to an error.
Sent when a comment is added to an error.
```json
{
"event": "commented",
"message": "[Testy McTestFace/production] Ben commented on ActiveRecord::StatementInvalid: First post!",
"actor": {
"id": 1,
"email": "ben@example.com",
"name": "Ben"
},
"fault": {
"project_id": 123321,
"klass": "ActiveRecord::StatementInvalid",
"component": "search",
"action": "index",
"environment": "production",
"resolved": true,
"ignored": false,
"created_at": "2023-01-31T03:10:01.126549Z",
"comments_count": 3,
"message": "PG::SyntaxError: ERROR: syntax error in tsquery: \"厄瓜多尔Google霸屏【TG飞机:@bapingseo】腾讯视频谷歌完全无广告版【TG飞机:@bapingseo】不到外贸行业运营推广计划怎么写谷歌相机的广告怎么关掉?Em0atRS3g3F4.html\"",
"notices_count": 5514,
"last_notice_at": "2023-02-06T12:20:01.772130Z",
"tags": [],
"id": 42,
"assignee": "george@example.com",
"url": "https://app.honeybadger.io/projects/123321/faults/42",
"deploy": {
"environment": "production",
"revision": "dd2ce1c1f5be3532e10fadf2224a19847f0c62e9",
"repository": "https://github.com/spacely/testy-mctestface",
"local_username": "heroku-redis@addons.heroku.com",
"created_at": "2023-02-01T05:12:31.417405Z",
"changelog": [],
"url": "https://github.com/spacely/testy-mctestface/compare/3e51742fd5f43197891a67b74a54903513e59ce5...dd2ce1c1f5be3532e10fadf2224a19847f0c62e9"
}
},
"comment": {
"id": 7075,
"fault_id": 2653,
"event": null,
"source": "web",
"created_at": "2012-11-29T03:44:09.381543Z",
"email": null,
"author": "Starr",
"body": "You might try shaving the yaks outside of the transaction."
}
}
```
# Deployed event payload
> Sent when a deployment is recorded.
Sent when a deployment is recorded.
```json
{
"event": "deployed",
"message": "[Testy McTestFace/production] ben@example.com deployed Testy McTestFace to production",
"project": {
"id": 123321,
"name": "Testy McTestFace",
"created_at": "2017-08-30T12:54:33.156695Z",
"disable_public_links": false,
"pivotal_project_id": null,
"asana_workspace_id": null,
"token": "zzz111",
"github_project": "spacely/testy-mctestface",
"environments": [
{
"id": 68210,
"project_id": 123321,
"name": "production",
"notifications": true,
"created_at": "2017-09-05T06:10:19.057794Z",
"updated_at": "2017-09-05T06:10:19.057794Z"
},
{
"id": 68074,
"project_id": 123321,
"name": "development",
"notifications": true,
"created_at": "2017-08-30T12:55:29.297392Z",
"updated_at": "2017-08-30T12:55:29.297392Z"
}
],
"owner": {
"id": 1,
"email": "ben@example.com",
"name": "Spacely Sprockets"
},
"last_notice_at": "2023-10-30T19:29:08.000000Z",
"earliest_notice_at": "2023-05-03T19:50:44.677809Z",
"unresolved_fault_count": 102,
"fault_count": 925,
"active": true,
"users": [
{
"id": 1,
"email": "ben@example.com",
"name": "Ben"
},
{
"id": 99,
"email": "george@example.com",
"name": "George Jetson"
}
],
"sites": [],
"team_id": 1
},
"deploy": {
"environment": "production",
"revision": "d5b13eea87cd98b45e51b92d6382198f4c102d6d",
"repository": "https://github.com/spacely/testy-mctestface",
"local_username": "ben@example.com",
"created_at": "2023-10-30T15:10:40.754174Z",
"changelog": [],
"url": "https://github.com/spacely/testy-mctestface/compare/5c9c677d9bb17cb3a211d1f65701b866e9ece5a7...d5b13eea87cd98b45e51b92d6382198f4c102d6d"
}
}
```
# Site down event payload
> Sent when an uptime check fails.
Sent when an uptime check fails.
```json
{
"event": "down",
"message": "[Testy McTestFace] Heroku is down.",
"project": {
"id": 123321,
"name": "Testy McTestFace",
"created_at": "2017-08-30T12:54:33.156695Z",
"disable_public_links": false,
"pivotal_project_id": null,
"asana_workspace_id": null,
"token": "zzz111",
"github_project": "spacely/testy-mctestface",
"environments": [
{
"id": 68210,
"project_id": 123321,
"name": "production",
"notifications": true,
"created_at": "2017-09-05T06:10:19.057794Z",
"updated_at": "2017-09-05T06:10:19.057794Z"
},
{
"id": 68074,
"project_id": 123321,
"name": "development",
"notifications": true,
"created_at": "2017-08-30T12:55:29.297392Z",
"updated_at": "2017-08-30T12:55:29.297392Z"
}
],
"owner": {
"id": 1,
"email": "ben@example.com",
"name": "Spacely Sprockets"
},
"last_notice_at": "2023-10-30T19:29:08.000000Z",
"earliest_notice_at": "2023-05-03T19:38:32.092931Z",
"unresolved_fault_count": 102,
"fault_count": 925,
"active": true,
"users": [
{
"id": 1,
"email": "ben@example.com",
"name": "Ben"
},
{
"id": 99,
"email": "george@example.com",
"name": "George Jetson"
}
],
"sites": [],
"team_id": 1
},
"site": {
"id": "c42c4c0a-6e3d-4303-9769-549ed2a5818e",
"name": "Heroku",
"url": "https://example.com",
"frequency": 5,
"match_type": "success",
"match": null,
"state": "down",
"active": true,
"last_checked_at": "2023-10-30T19:34:08.150725Z",
"retries": 0,
"proxy": 4,
"cert_will_expire_at": null,
"details_url": "https://app.honeybadger.io/projects/123321/sites/c42c4c0a-6e3d-4303-9769-549ed2a5818e"
},
"outage": {
"down_at": "2023-07-17T15:46:52.384701Z",
"up_at": "2023-07-17T15:51:56.063948Z",
"status": null,
"reason": "Connection timed out",
"headers": null,
"details_url": "https://app.honeybadger.io/projects/123321/sites/c42c4c0a-6e3d-4303-9769-549ed2a5818e"
}
}
```
# Occurred event payload
> Sent when an error occurs.
Sent when an error occurs.
```json
{
"event": "occurred",
"message": "[Testy McTestFace/production] ActiveRecord::NoDatabaseError: We could not find your database: d6ipl26lboesdi. Which can be found in the database configuration file located at config/database.yml.\n\nTo resolve this issue:\n\n- Did you create the database for th...",
"project": {
"id": 123321,
"name": "Testy McTestFace",
"created_at": "2017-08-30T12:54:33.156695Z",
"disable_public_links": false,
"pivotal_project_id": null,
"asana_workspace_id": null,
"token": "zzz111",
"github_project": "spacely/testy-mctestface",
"environments": [
{
"id": 68210,
"project_id": 123321,
"name": "production",
"notifications": true,
"created_at": "2017-09-05T06:10:19.057794Z",
"updated_at": "2017-09-05T06:10:19.057794Z"
},
{
"id": 68074,
"project_id": 123321,
"name": "development",
"notifications": true,
"created_at": "2017-08-30T12:55:29.297392Z",
"updated_at": "2017-08-30T12:55:29.297392Z"
}
],
"owner": {
"id": 1,
"email": "ben@example.com",
"name": "Spacely Sprockets"
},
"last_notice_at": "2023-10-30T19:29:08.000000Z",
"earliest_notice_at": "2023-05-03T19:35:56.783102Z",
"unresolved_fault_count": 102,
"fault_count": 925,
"active": true,
"users": [
{
"id": 1,
"email": "ben@example.com",
"name": "Ben"
},
{
"id": 99,
"email": "george@example.com",
"name": "George Jetson"
}
],
"sites": [
{
"id": "c42c4c0a-6e3d-4303-9769-549ed2a5818e",
"active": true,
"last_checked_at": "2023-10-30T19:34:08.150725Z",
"name": "Heroku",
"state": "up",
"url": "https://example.com"
}
],
"team_id": 1
},
"fault": {
"project_id": 123321,
"klass": "ActiveRecord::NoDatabaseError",
"component": "pages",
"action": "home",
"environment": "production",
"resolved": false,
"ignored": false,
"created_at": "2023-10-13T18:07:55.692256Z",
"comments_count": 0,
"message": "We could not find your database: d6ipl26lboesdi. Which can be found in the database configuration file located at config/database.yml.\n\nTo resolve this issue:\n\n- Did you create the database for this app, or delete it? You may need to create your database.\n- Has the database name changed? Check your database.yml config has the correct database name.\n\nTo create your database, run:\n\n bin/rails db:create",
"notices_count": 6,
"last_notice_at": "2023-10-13T18:08:10.000000Z",
"tags": [],
"id": 101337516,
"assignee": null,
"url": "https://app.honeybadger.io/projects/123321/faults/101337516",
"deploy": {
"environment": "production",
"revision": "0eaf61a9ec756be9f4bb511ad71b37baaa9b73ba",
"repository": "https://github.com/spacely/testy-mctestface",
"local_username": "ben@example.com",
"created_at": "2023-10-06T20:52:51.878336Z",
"changelog": [],
"url": "https://github.com/spacely/testy-mctestface/compare/d4f90c876adf4a108ebb9a6f47b5562b59578d97...0eaf61a9ec756be9f4bb511ad71b37baaa9b73ba"
}
},
"notice": {
"id": 1013375161697220500,
"environment": {},
"created_at": "2023-10-13T18:08:10.141219Z",
"message": null,
"token": "babe1d9d-67e3-4438-8c57-c544cea24ffb",
"fault_id": 101337516,
"request": {
"url": "https://example.com/",
"component": "pages",
"action": "home",
"params": {
"controller": "pages",
"action": "home"
},
"session": {},
"context": {}
},
"backtrace": [
{
"number": "81",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/postgresql_adapter.rb",
"method": "rescue in new_client",
"source": {
"79": " rescue ::PG::Error => error\n",
"80": " if conn_params && conn_params[:dbname] && error.message.include?(conn_params[:dbname])\n",
"81": " raise ActiveRecord::NoDatabaseError.db_error(conn_params[:dbname])\n",
"82": " elsif conn_params && conn_params[:user] && error.message.include?(conn_params[:user])\n",
"83": " raise ActiveRecord::DatabaseConnectionError.username_error(conn_params[:user])\n"
},
"context": "all"
},
{
"number": "77",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/postgresql_adapter.rb",
"method": "new_client",
"source": {
"75": "\n",
"76": " class << self\n",
"77": " def new_client(conn_params)\n",
"78": " PG.connect(**conn_params)\n",
"79": " rescue ::PG::Error => error\n"
},
"context": "all"
},
{
"number": "37",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/postgresql_adapter.rb",
"method": "postgresql_connection",
"source": {
"35": "\n",
"36": " ConnectionAdapters::PostgreSQLAdapter.new(\n",
"37": " ConnectionAdapters::PostgreSQLAdapter.new_client(conn_params),\n",
"38": " logger,\n",
"39": " conn_params,\n"
},
"context": "all"
},
{
"number": "656",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "public_send",
"source": {
"654": "\n",
"655": " def new_connection\n",
"656": " Base.public_send(db_config.adapter_method, db_config.configuration_hash).tap do |conn|\n",
"657": " conn.check_version\n",
"658": " end\n"
},
"context": "all"
},
{
"number": "656",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "new_connection",
"source": {
"654": "\n",
"655": " def new_connection\n",
"656": " Base.public_send(db_config.adapter_method, db_config.configuration_hash).tap do |conn|\n",
"657": " conn.check_version\n",
"658": " end\n"
},
"context": "all"
},
{
"number": "700",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "checkout_new_connection",
"source": {
"698": " def checkout_new_connection\n",
"699": " raise ConnectionNotEstablished unless @automatic_reconnect\n",
"700": " new_connection\n",
"701": " end\n",
"702": "\n"
},
"context": "all"
},
{
"number": "679",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "try_to_checkout_new_connection",
"source": {
"677": " # if successfully incremented @now_connecting establish new connection\n",
"678": " # outside of synchronized section\n",
"679": " conn = checkout_new_connection\n",
"680": " ensure\n",
"681": " synchronize do\n"
},
"context": "all"
},
{
"number": "640",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "acquire_connection",
"source": {
"638": " # and +try_to_checkout_new_connection+ we can piggyback on +synchronize+ sections\n",
"639": " # of the said methods and avoid an additional +synchronize+ overhead.\n",
"640": " if conn = @available.poll || try_to_checkout_new_connection\n",
"641": " conn\n",
"642": " else\n"
},
"context": "all"
},
{
"number": "341",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "checkout",
"source": {
"339": " # - ActiveRecord::ConnectionTimeoutError no connection can be obtained from the pool.\n",
"340": " def checkout(checkout_timeout = @checkout_timeout)\n",
"341": " checkout_and_verify(acquire_connection(checkout_timeout))\n",
"342": " end\n",
"343": "\n"
},
"context": "all"
},
{
"number": "181",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "connection",
"source": {
"179": " # held in a cache keyed by a thread.\n",
"180": " def connection\n",
"181": " @thread_cached_conns[connection_cache_key(current_thread)] ||= checkout\n",
"182": " end\n",
"183": "\n"
},
"context": "all"
},
{
"number": "211",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_handler.rb",
"method": "retrieve_connection",
"source": {
"209": " end\n",
"210": "\n",
"211": " pool.connection\n",
"212": " end\n",
"213": "\n"
},
"context": "all"
},
{
"number": "313",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_handling.rb",
"method": "retrieve_connection",
"source": {
"311": "\n",
"312": " def retrieve_connection\n",
"313": " connection_handler.retrieve_connection(connection_specification_name, role: current_role, shard: current_shard)\n",
"314": " end\n",
"315": "\n"
},
"context": "all"
},
{
"number": "280",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_handling.rb",
"method": "connection",
"source": {
"278": " # to any of the specific Active Records.\n",
"279": " def connection\n",
"280": " retrieve_connection\n",
"281": " end\n",
"282": "\n"
},
"context": "all"
},
{
"number": "433",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/core.rb",
"method": "cached_find_by_statement",
"source": {
"431": "\n",
"432": " def cached_find_by_statement(key, &block) # :nodoc:\n",
"433": " cache = @find_by_statement_cache[connection.prepared_statements]\n",
"434": " cache.compute_if_absent(key) { StatementCache.create(connection, &block) }\n",
"435": " end\n"
},
"context": "all"
},
{
"number": "317",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/core.rb",
"method": "find_by",
"source": {
"315": "\n",
"316": " keys = hash.keys\n",
"317": " statement = cached_find_by_statement(keys) { |params|\n",
"318": " wheres = keys.index_with { params.bind }\n",
"319": " where(wheres).limit(1)\n"
},
"context": "all"
},
{
"number": "69",
"file": "[PROJECT_ROOT]/app/controllers/application_controller.rb",
"method": "check_redirect",
"source": {
"67": "\n",
"68": " def check_redirect\n",
"69": " return unless (redirect = Redirect.find_by(slug: request.path.sub(%r{^/}, \"\")))\n",
"70": " redirect_to redirect.url\n",
"71": " end\n"
},
"application_file": "app/controllers/application_controller.rb",
"context": "app"
},
{
"number": "400",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "block in make_lambda",
"source": {
"398": " def make_lambda\n",
"399": " lambda do |target, value, &block|\n",
"400": " target.send(@method_name, &block)\n",
"401": " end\n",
"402": " end\n"
},
"context": "all"
},
{
"number": "180",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "block (2 levels) in halting_and_conditional",
"source": {
"178": "\n",
"179": " if !halted && user_conditions.all? { |c| c.call(target, value) }\n",
"180": " result_lambda = -> { user_callback.call target, value }\n",
"181": " env.halted = halted_lambda.call(target, result_lambda)\n",
"182": " if env.halted\n"
},
"context": "all"
},
{
"number": "34",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/abstract_controller/callbacks.rb",
"method": "block (2 levels) in ",
"source": {
"32": " included do\n",
"33": " define_callbacks :process_action,\n",
"34": " terminator: ->(controller, result_lambda) { result_lambda.call; controller.performed? },\n",
"35": " skip_after_callbacks_if_terminated: true\n",
"36": " end\n"
},
"context": "all"
},
{
"number": "181",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "block in halting_and_conditional",
"source": {
"179": " if !halted && user_conditions.all? { |c| c.call(target, value) }\n",
"180": " result_lambda = -> { user_callback.call target, value }\n",
"181": " env.halted = halted_lambda.call(target, result_lambda)\n",
"182": " if env.halted\n",
"183": " target.send :halted_callback_hook, filter, name\n"
},
"context": "all"
},
{
"number": "595",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "block in invoke_before",
"source": {
"593": "\n",
"594": " def invoke_before(arg)\n",
"595": " @before.each { |b| b.call(arg) }\n",
"596": " end\n",
"597": "\n"
},
"context": "all"
},
{
"number": "595",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "each",
"source": {
"593": "\n",
"594": " def invoke_before(arg)\n",
"595": " @before.each { |b| b.call(arg) }\n",
"596": " end\n",
"597": "\n"
},
"context": "all"
},
{
"number": "595",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "invoke_before",
"source": {
"593": "\n",
"594": " def invoke_before(arg)\n",
"595": " @before.each { |b| b.call(arg) }\n",
"596": " end\n",
"597": "\n"
},
"context": "all"
},
{
"number": "106",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "run_callbacks",
"source": {
"104": " # Common case: no 'around' callbacks defined\n",
"105": " if next_sequence.final?\n",
"106": " next_sequence.invoke_before(env)\n",
"107": " env.value = !env.halted && (!block_given? || yield)\n",
"108": " next_sequence.invoke_after(env)\n"
},
"context": "all"
},
{
"number": "233",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/abstract_controller/callbacks.rb",
"method": "process_action",
"source": {
"231": " # process_action callbacks around the normal behavior.\n",
"232": " def process_action(...)\n",
"233": " run_callbacks(:process_action) do\n",
"234": " super\n",
"235": " end\n"
},
"context": "all"
},
{
"number": "23",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_controller/metal/rescue.rb",
"method": "process_action",
"source": {
"21": " private\n",
"22": " def process_action(*)\n",
"23": " super\n",
"24": " rescue Exception => exception\n",
"25": " request.env[\"action_dispatch.show_detailed_exceptions\"] ||= show_detailed_exceptions?\n"
},
"context": "all"
},
{
"number": "67",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_controller/metal/instrumentation.rb",
"method": "block in process_action",
"source": {
"65": "\n",
"66": " ActiveSupport::Notifications.instrument(\"process_action.action_controller\", raw_payload) do |payload|\n",
"67": " result = super\n",
"68": " payload[:response] = response\n",
"69": " payload[:status] = response.status\n"
},
"context": "all"
},
{
"number": "206",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/notifications.rb",
"method": "block in instrument",
"source": {
"204": " def instrument(name, payload = {})\n",
"205": " if notifier.listening?(name)\n",
"206": " instrumenter.instrument(name, payload) { yield payload if block_given? }\n",
"207": " else\n",
"208": " yield payload if block_given?\n"
},
"context": "all"
},
{
"number": "24",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/notifications/instrumenter.rb",
"method": "instrument",
"source": {
"22": " listeners_state = start name, payload\n",
"23": " begin\n",
"24": " yield payload if block_given?\n",
"25": " rescue Exception => e\n",
"26": " payload[:exception] = [e.class.name, e.message]\n"
},
"context": "all"
},
{
"number": "206",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/notifications.rb",
"method": "instrument",
"source": {
"204": " def instrument(name, payload = {})\n",
"205": " if notifier.listening?(name)\n",
"206": " instrumenter.instrument(name, payload) { yield payload if block_given? }\n",
"207": " else\n",
"208": " yield payload if block_given?\n"
},
"context": "all"
},
{
"number": "66",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_controller/metal/instrumentation.rb",
"method": "process_action",
"source": {
"64": " ActiveSupport::Notifications.instrument(\"start_processing.action_controller\", raw_payload)\n",
"65": "\n",
"66": " ActiveSupport::Notifications.instrument(\"process_action.action_controller\", raw_payload) do |payload|\n",
"67": " result = super\n",
"68": " payload[:response] = response\n"
},
"context": "all"
},
{
"number": "259",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_controller/metal/params_wrapper.rb",
"method": "process_action",
"source": {
"257": " def process_action(*)\n",
"258": " _perform_parameter_wrapping if _wrapper_enabled?\n",
"259": " super\n",
"260": " end\n",
"261": "\n"
},
"context": "all"
},
{
"number": "27",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/railties/controller_runtime.rb",
"method": "process_action",
"source": {
"25": " # and it won't be cleaned up by the method below.\n",
"26": " ActiveRecord::LogSubscriber.reset_runtime\n",
"27": " super\n",
"28": " end\n",
"29": "\n"
},
"context": "all"
},
{
"number": "120",
"file": "[GEM_ROOT]/gems/scout_apm-5.3.5/lib/scout_apm/instruments/action_controller_rails_3_rails4.rb",
"method": "process_action",
"source": {
"118": " req.start_layer( ScoutApm::Layer.new(\"Controller\", \"#{controller_path}/#{resolved_name}\") )\n",
"119": " begin\n",
"120": " super\n",
"121": " rescue\n",
"122": " req.error!\n"
},
"context": "all"
},
{
"number": "151",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/abstract_controller/base.rb",
"method": "process",
"source": {
"149": " @_response_body = nil\n",
"150": "\n",
"151": " process_action(action_name, *args)\n",
"152": " end\n",
"153": " ruby2_keywords(:process)\n"
},
"context": "all"
},
{
"number": "39",
"file": "[GEM_ROOT]/gems/actionview-7.0.7.2/lib/action_view/rendering.rb",
"method": "process",
"source": {
"37": " def process(...) # :nodoc:\n",
"38": " old_config, I18n.config = I18n.config, I18nProxy.new(I18n.config, lookup_context)\n",
"39": " super\n",
"40": " ensure\n",
"41": " I18n.config = old_config\n"
},
"context": "all"
},
{
"number": "188",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_controller/metal.rb",
"method": "dispatch",
"source": {
"186": " set_request!(request)\n",
"187": " set_response!(response)\n",
"188": " process(name)\n",
"189": " request.commit_flash\n",
"190": " to_a\n"
},
"context": "all"
},
{
"number": "251",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_controller/metal.rb",
"method": "dispatch",
"source": {
"249": " middleware_stack.build(name) { |env| new.dispatch(name, req, res) }.call req.env\n",
"250": " else\n",
"251": " new.dispatch(name, req, res)\n",
"252": " end\n",
"253": " end\n"
},
"context": "all"
},
{
"number": "49",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/routing/route_set.rb",
"method": "dispatch",
"source": {
"47": "\n",
"48": " def dispatch(controller, action, req, res)\n",
"49": " controller.dispatch(action, req, res)\n",
"50": " end\n",
"51": " end\n"
},
"context": "all"
},
{
"number": "32",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/routing/route_set.rb",
"method": "serve",
"source": {
"30": " controller = controller req\n",
"31": " res = controller.make_response! req\n",
"32": " dispatch(controller, params[:action], req, res)\n",
"33": " rescue ActionController::RoutingError\n",
"34": " if @raise_on_name_error\n"
},
"context": "all"
},
{
"number": "50",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/journey/router.rb",
"method": "block in serve",
"source": {
"48": " req.path_parameters = tmp_params\n",
"49": "\n",
"50": " status, headers, body = route.app.serve(req)\n",
"51": "\n",
"52": " if \"pass\" == headers[\"X-Cascade\"]\n"
},
"context": "all"
},
{
"number": "32",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/journey/router.rb",
"method": "each",
"source": {
"30": "\n",
"31": " def serve(req)\n",
"32": " find_routes(req).each do |match, parameters, route|\n",
"33": " set_params = req.path_parameters\n",
"34": " path_info = req.path_info\n"
},
"context": "all"
},
{
"number": "32",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/journey/router.rb",
"method": "serve",
"source": {
"30": "\n",
"31": " def serve(req)\n",
"32": " find_routes(req).each do |match, parameters, route|\n",
"33": " set_params = req.path_parameters\n",
"34": " path_info = req.path_info\n"
},
"context": "all"
},
{
"number": "852",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/routing/route_set.rb",
"method": "call",
"source": {
"850": " req = make_request(env)\n",
"851": " req.path_info = Journey::Router::Utils.normalize_path(req.path_info)\n",
"852": " @router.serve(req)\n",
"853": " end\n",
"854": "\n"
},
"context": "all"
},
{
"number": "29",
"file": "[GEM_ROOT]/gems/scout_apm-5.3.5/lib/scout_apm/instruments/rails_router.rb",
"method": "call_with_scout_instruments",
"source": {
"27": "\n",
"28": " begin\n",
"29": " call_without_scout_instruments(*args)\n",
"30": " ensure\n",
"31": " req.stop_layer\n"
},
"context": "all"
},
{
"number": "17",
"file": "[GEM_ROOT]/gems/scout_apm-5.3.5/lib/scout_apm/middleware.rb",
"method": "call",
"source": {
"15": " def call(env)\n",
"16": " if !@enabled || @started || @attempts > MAX_ATTEMPTS\n",
"17": " @app.call(env)\n",
"18": " else\n",
"19": " attempt_to_start_agent\n"
},
"context": "all"
},
{
"number": "36",
"file": "[GEM_ROOT]/gems/warden-1.2.9/lib/warden/manager.rb",
"method": "block in call",
"source": {
"34": " result = catch(:warden) do\n",
"35": " env['warden'].on_request\n",
"36": " @app.call(env)\n",
"37": " end\n",
"38": "\n"
},
"context": "all"
},
{
"number": "34",
"file": "[GEM_ROOT]/gems/warden-1.2.9/lib/warden/manager.rb",
"method": "catch",
"source": {
"32": "\n",
"33": " env['warden'] = Proxy.new(env, self)\n",
"34": " result = catch(:warden) do\n",
"35": " env['warden'].on_request\n",
"36": " @app.call(env)\n"
},
"context": "all"
},
{
"number": "34",
"file": "[GEM_ROOT]/gems/warden-1.2.9/lib/warden/manager.rb",
"method": "call",
"source": {
"32": "\n",
"33": " env['warden'] = Proxy.new(env, self)\n",
"34": " result = catch(:warden) do\n",
"35": " env['warden'].on_request\n",
"36": " @app.call(env)\n"
},
"context": "all"
},
{
"number": "15",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/tempfile_reaper.rb",
"method": "call",
"source": {
"13": " def call(env)\n",
"14": " env[RACK_TEMPFILES] ||= []\n",
"15": " status, headers, body = @app.call(env)\n",
"16": " body_proxy = BodyProxy.new(body) do\n",
"17": " env[RACK_TEMPFILES].each(&:close!) unless env[RACK_TEMPFILES].nil?\n"
},
"context": "all"
},
{
"number": "27",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/conditional_get.rb",
"method": "call",
"source": {
"25": " case env[REQUEST_METHOD]\n",
"26": " when \"GET\", \"HEAD\"\n",
"27": " status, headers, body = @app.call(env)\n",
"28": " headers = Utils::HeaderHash[headers]\n",
"29": " if status == 200 && fresh?(env, headers)\n"
},
"context": "all"
},
{
"number": "12",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/head.rb",
"method": "call",
"source": {
"10": "\n",
"11": " def call(env)\n",
"12": " status, headers, body = @app.call(env)\n",
"13": "\n",
"14": " if env[REQUEST_METHOD] == HEAD\n"
},
"context": "all"
},
{
"number": "38",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/http/permissions_policy.rb",
"method": "call",
"source": {
"36": " def call(env)\n",
"37": " request = ActionDispatch::Request.new(env)\n",
"38": " _, headers, _ = response = @app.call(env)\n",
"39": "\n",
"40": " return response unless html_response?(headers)\n"
},
"context": "all"
},
{
"number": "36",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/http/content_security_policy.rb",
"method": "call",
"source": {
"34": " def call(env)\n",
"35": " request = ActionDispatch::Request.new env\n",
"36": " status, headers, _ = response = @app.call(env)\n",
"37": "\n",
"38": " # Returning CSP headers with a 304 Not Modified is harmful, since nonces in the new\n"
},
"context": "all"
},
{
"number": "266",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/session/abstract/id.rb",
"method": "context",
"source": {
"264": " req = make_request env\n",
"265": " prepare_session(req)\n",
"266": " status, headers, body = app.call(req.env)\n",
"267": " res = Rack::Response::Raw.new status, headers\n",
"268": " commit_session(req, res)\n"
},
"context": "all"
},
{
"number": "260",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/session/abstract/id.rb",
"method": "call",
"source": {
"258": "\n",
"259": " def call(env)\n",
"260": " context(env)\n",
"261": " end\n",
"262": "\n"
},
"context": "all"
},
{
"number": "704",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/cookies.rb",
"method": "call",
"source": {
"702": " request = ActionDispatch::Request.new env\n",
"703": "\n",
"704": " status, headers, body = @app.call(env)\n",
"705": "\n",
"706": " if request.have_cookie_jar?\n"
},
"context": "all"
},
{
"number": "27",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/callbacks.rb",
"method": "block in call",
"source": {
"25": " error = nil\n",
"26": " result = run_callbacks :call do\n",
"27": " @app.call(env)\n",
"28": " rescue => error\n",
"29": " end\n"
},
"context": "all"
},
{
"number": "99",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "run_callbacks",
"source": {
"97": "\n",
"98": " if callbacks.empty?\n",
"99": " yield if block_given?\n",
"100": " else\n",
"101": " env = Filters::Environment.new(self, false, nil)\n"
},
"context": "all"
},
{
"number": "26",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/callbacks.rb",
"method": "call",
"source": {
"24": " def call(env)\n",
"25": " error = nil\n",
"26": " result = run_callbacks :call do\n",
"27": " @app.call(env)\n",
"28": " rescue => error\n"
},
"context": "all"
},
{
"number": "28",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/debug_exceptions.rb",
"method": "call",
"source": {
"26": " def call(env)\n",
"27": " request = ActionDispatch::Request.new env\n",
"28": " _, headers, body = response = @app.call(env)\n",
"29": "\n",
"30": " if headers[\"X-Cascade\"] == \"pass\"\n"
},
"context": "all"
},
{
"number": "29",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/show_exceptions.rb",
"method": "call",
"source": {
"27": " def call(env)\n",
"28": " request = ActionDispatch::Request.new env\n",
"29": " @app.call(env)\n",
"30": " rescue Exception => exception\n",
"31": " if request.show_exceptions?\n"
},
"context": "all"
},
{
"number": "18",
"file": "[GEM_ROOT]/gems/lograge-0.12.0/lib/lograge/rails_ext/rack/logger.rb",
"method": "call_app",
"source": {
"16": " def call_app(*args)\n",
"17": " env = args.last\n",
"18": " status, headers, body = @app.call(env)\n",
"19": " # needs to have same return type as the Rails builtins being overridden, see https://github.com/roidrage/lograge/pull/333\n",
"20": " # https://github.com/rails/rails/blob/be9d34b9bcb448b265114ebc28bef1a5b5e4c272/railties/lib/rails/rack/logger.rb#L37\n"
},
"context": "all"
},
{
"number": "25",
"file": "[GEM_ROOT]/gems/railties-7.0.7.2/lib/rails/rack/logger.rb",
"method": "block in call",
"source": {
"23": "\n",
"24": " if logger.respond_to?(:tagged)\n",
"25": " logger.tagged(compute_tags(request)) { call_app(request, env) }\n",
"26": " else\n",
"27": " call_app(request, env)\n"
},
"context": "all"
},
{
"number": "99",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/tagged_logging.rb",
"method": "block in tagged",
"source": {
"97": " def tagged(*tags)\n",
"98": " if block_given?\n",
"99": " formatter.tagged(*tags) { yield self }\n",
"100": " else\n",
"101": " logger = ActiveSupport::TaggedLogging.new(self)\n"
},
"context": "all"
},
{
"number": "37",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/tagged_logging.rb",
"method": "tagged",
"source": {
"35": " def tagged(*tags)\n",
"36": " new_tags = push_tags(*tags)\n",
"37": " yield self\n",
"38": " ensure\n",
"39": " pop_tags(new_tags.size)\n"
},
"context": "all"
},
{
"number": "99",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/tagged_logging.rb",
"method": "tagged",
"source": {
"97": " def tagged(*tags)\n",
"98": " if block_given?\n",
"99": " formatter.tagged(*tags) { yield self }\n",
"100": " else\n",
"101": " logger = ActiveSupport::TaggedLogging.new(self)\n"
},
"context": "all"
},
{
"number": "25",
"file": "[GEM_ROOT]/gems/railties-7.0.7.2/lib/rails/rack/logger.rb",
"method": "call",
"source": {
"23": "\n",
"24": " if logger.respond_to?(:tagged)\n",
"25": " logger.tagged(compute_tags(request)) { call_app(request, env) }\n",
"26": " else\n",
"27": " call_app(request, env)\n"
},
"context": "all"
},
{
"number": "93",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/remote_ip.rb",
"method": "call",
"source": {
"91": " req = ActionDispatch::Request.new env\n",
"92": " req.remote_ip = GetIp.new(req, check_ip, proxies)\n",
"93": " @app.call(req.env)\n",
"94": " end\n",
"95": "\n"
},
"context": "all"
},
{
"number": "19",
"file": "[GEM_ROOT]/gems/request_store-1.5.1/lib/request_store/middleware.rb",
"method": "call",
"source": {
"17": " RequestStore.begin!\r\n",
"18": "\r\n",
"19": " status, headers, body = @app.call(env)\r\n",
"20": "\r\n",
"21": " body = Rack::BodyProxy.new(body) do\r\n"
},
"context": "all"
},
{
"number": "26",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/request_id.rb",
"method": "call",
"source": {
"24": " req = ActionDispatch::Request.new env\n",
"25": " req.request_id = make_request_id(req.headers[@header])\n",
"26": " @app.call(env).tap { |_status, headers, _body| headers[@header] = req.request_id }\n",
"27": " end\n",
"28": "\n"
},
"context": "all"
},
{
"number": "24",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/method_override.rb",
"method": "call",
"source": {
"22": " end\n",
"23": "\n",
"24": " @app.call(env)\n",
"25": " end\n",
"26": "\n"
},
"context": "all"
},
{
"number": "22",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/runtime.rb",
"method": "call",
"source": {
"20": " def call(env)\n",
"21": " start_time = Utils.clock_time\n",
"22": " status, headers, body = @app.call(env)\n",
"23": " headers = Utils::HeaderHash[headers]\n",
"24": "\n"
},
"context": "all"
},
{
"number": "148",
"file": "[GEM_ROOT]/gems/rack-timeout-0.6.3/lib/rack/timeout/core.rb",
"method": "block in call",
"source": {
"146": "\n",
"147": " response = timeout.timeout(info.timeout) do # perform request with timeout\n",
"148": " begin @app.call(env) # boom, send request down the middleware chain\n",
"149": " rescue RequestTimeoutException => e # will actually hardly ever get to this point because frameworks tend to catch this. see README for more\n",
"150": " raise RequestTimeoutError.new(env), e.message, e.backtrace # but in case it does get here, re-raise RequestTimeoutException as RequestTimeoutError\n"
},
"context": "all"
},
{
"number": "19",
"file": "[GEM_ROOT]/gems/rack-timeout-0.6.3/lib/rack/timeout/support/timeout.rb",
"method": "timeout",
"source": {
"17": " thr = Thread.current # reference to current thread to be used in timeout thread\n",
"18": " job = @scheduler.run_in(secs) { @on_timeout.call thr } # schedule this thread to be timed out; should get cancelled if block completes on time\n",
"19": " return block.call # do what you gotta do\n",
"20": " ensure #\n",
"21": " job.cancel! if job # cancel the scheduled timeout job; if the block completed on time, this\n"
},
"context": "all"
},
{
"number": "147",
"file": "[GEM_ROOT]/gems/rack-timeout-0.6.3/lib/rack/timeout/core.rb",
"method": "call",
"source": {
"145": " end\n",
"146": "\n",
"147": " response = timeout.timeout(info.timeout) do # perform request with timeout\n",
"148": " begin @app.call(env) # boom, send request down the middleware chain\n",
"149": " rescue RequestTimeoutException => e # will actually hardly ever get to this point because frameworks tend to catch this. see README for more\n"
},
"context": "all"
},
{
"number": "41",
"file": "[GEM_ROOT]/gems/judoscale-ruby-1.4.1/lib/judoscale/request_middleware.rb",
"method": "call",
"source": {
"39": " end\n",
"40": "\n",
"41": " @app.call(env)\n",
"42": " end\n",
"43": " end\n"
},
"context": "all"
},
{
"number": "29",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/cache/strategy/local_cache_middleware.rb",
"method": "call",
"source": {
"27": " def call(env)\n",
"28": " LocalCacheRegistry.set_cache_for(local_cache_key, LocalStore.new)\n",
"29": " response = @app.call(env)\n",
"30": " response[2] = ::Rack::BodyProxy.new(response[2]) do\n",
"31": " LocalCacheRegistry.set_cache_for(local_cache_key, nil)\n"
},
"context": "all"
},
{
"number": "24",
"file": "[GEM_ROOT]/gems/rack-rewrite-1.5.1/lib/rack/rewrite.rb",
"method": "call",
"source": {
"22": " return rack_response unless rack_response === true\n",
"23": " end\n",
"24": " @app.call(env)\n",
"25": " end\n",
"26": " \n"
},
"context": "all"
},
{
"number": "14",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/executor.rb",
"method": "call",
"source": {
"12": " state = @executor.run!(reset: true)\n",
"13": " begin\n",
"14": " response = @app.call(env)\n",
"15": " returned = response << ::Rack::BodyProxy.new(response.pop) { state.complete! }\n",
"16": " rescue => error\n"
},
"context": "all"
},
{
"number": "23",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/static.rb",
"method": "call",
"source": {
"21": "\n",
"22": " def call(env)\n",
"23": " @file_handler.attempt(env) || @app.call(env)\n",
"24": " end\n",
"25": " end\n"
},
"context": "all"
},
{
"number": "110",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/sendfile.rb",
"method": "call",
"source": {
"108": "\n",
"109": " def call(env)\n",
"110": " status, headers, body = @app.call(env)\n",
"111": " if body.respond_to?(:to_path)\n",
"112": " case type = variation(env)\n"
},
"context": "all"
},
{
"number": "77",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/ssl.rb",
"method": "call",
"source": {
"75": "\n",
"76": " if request.ssl?\n",
"77": " @app.call(env).tap do |status, headers, body|\n",
"78": " set_hsts_header! headers\n",
"79": " flag_cookies_as_secure! headers if @secure_cookies && !@exclude.call(request)\n"
},
"context": "all"
},
{
"number": "131",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/host_authorization.rb",
"method": "call",
"source": {
"129": "\n",
"130": " def call(env)\n",
"131": " return @app.call(env) if @permissions.empty?\n",
"132": "\n",
"133": " request = Request.new(env)\n"
},
"context": "all"
},
{
"number": "58",
"file": "[GEM_ROOT]/gems/scout_apm-5.3.5/lib/scout_apm/instruments/middleware_summary.rb",
"method": "call",
"source": {
"56": " layer = ScoutApm::Layer.new(\"Middleware\", \"Summary\")\n",
"57": " req.start_layer(layer)\n",
"58": " @app.call(env)\n",
"59": " ensure\n",
"60": " req.stop_layer\n"
},
"context": "all"
},
{
"number": "530",
"file": "[GEM_ROOT]/gems/railties-7.0.7.2/lib/rails/engine.rb",
"method": "call",
"source": {
"528": " def call(env)\n",
"529": " req = build_request env\n",
"530": " app.call req.env\n",
"531": " end\n",
"532": "\n"
},
"context": "all"
},
{
"number": "270",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/configuration.rb",
"method": "call",
"source": {
"268": " def call(env)\n",
"269": " env[Const::PUMA_CONFIG] = @config\n",
"270": " @app.call(env)\n",
"271": " end\n",
"272": " end\n"
},
"context": "all"
},
{
"number": "100",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/request.rb",
"method": "block in handle_request",
"source": {
"98": " if @supported_http_methods == :any || @supported_http_methods.key?(env[REQUEST_METHOD])\n",
"99": " status, headers, app_body = @thread_pool.with_force_shutdown do\n",
"100": " @app.call(env)\n",
"101": " end\n",
"102": " else\n"
},
"context": "all"
},
{
"number": "344",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/thread_pool.rb",
"method": "with_force_shutdown",
"source": {
"342": " t[:with_force_shutdown] = true\n",
"343": " end\n",
"344": " yield\n",
"345": " ensure\n",
"346": " t[:with_force_shutdown] = false\n"
},
"context": "all"
},
{
"number": "99",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/request.rb",
"method": "handle_request",
"source": {
"97": " begin\n",
"98": " if @supported_http_methods == :any || @supported_http_methods.key?(env[REQUEST_METHOD])\n",
"99": " status, headers, app_body = @thread_pool.with_force_shutdown do\n",
"100": " @app.call(env)\n",
"101": " end\n"
},
"context": "all"
},
{
"number": "443",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/server.rb",
"method": "process_client",
"source": {
"441": " while true\n",
"442": " @requests_count += 1\n",
"443": " case handle_request(client, requests + 1)\n",
"444": " when false\n",
"445": " break\n"
},
"context": "all"
},
{
"number": "245",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/server.rb",
"method": "block in run",
"source": {
"243": " @status = :run\n",
"244": "\n",
"245": " @thread_pool = ThreadPool.new(thread_name, @options) { |client| process_client client }\n",
"246": "\n",
"247": " if @queue_requests\n"
},
"context": "all"
},
{
"number": "151",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/thread_pool.rb",
"method": "block in spawn_thread",
"source": {
"149": "\n",
"150": " begin\n",
"151": " @out_of_band_pending = true if block.call(work)\n",
"152": " rescue Exception => e\n",
"153": " STDERR.puts \"Error reached top of thread-pool: #{e.message} (#{e.class})\"\n"
},
"context": "all"
}
],
"application_trace": [
{
"number": "69",
"file": "[PROJECT_ROOT]/app/controllers/application_controller.rb",
"method": "check_redirect",
"source": {
"67": "\n",
"68": " def check_redirect\n",
"69": " return unless (redirect = Redirect.find_by(slug: request.path.sub(%r{^/}, \"\")))\n",
"70": " redirect_to redirect.url\n",
"71": " end\n"
},
"application_file": "app/controllers/application_controller.rb",
"context": "app"
}
],
"web_environment": {
"SERVER_SOFTWARE": "puma 6.3.1 Mugi No Toki Itaru",
"GATEWAY_INTERFACE": "CGI/1.2",
"REQUEST_METHOD": "GET",
"SERVER_PROTOCOL": "HTTP/1.1",
"HTTP_HOST": "example.com",
"HTTP_CONNECTION": "close",
"HTTP_USER_AGENT": "Amazon CloudFront",
"HTTP_X_AMZ_CF_ID": "yai2eezeewaipahthieN-Yt3y0gAunRuwBHH8A==",
"HTTP_IF_NONE_MATCH": "W/\"fde6ca645252fa81edfdae38dbeef178\"",
"HTTP_ACCEPT": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7",
"HTTP_X_FORWARDED_FOR": "199.175.219.155, 64.252.73.106",
"HTTP_VIA": "2.0 yai2eezeewaipahthieN.cloudfront.net (CloudFront), 1.1 vegur",
"HTTP_ACCEPT_ENCODING": "gzip",
"HTTP_IF_MODIFIED_SINCE": "Wed, 11 Oct 2023 20:51:58 GMT",
"HTTP_SEC_CH_UA": "\"Google Chrome\";v=\"117\", \"Not;A=Brand\";v=\"8\", \"Chromium\";v=\"117\"",
"HTTP_SEC_CH_UA_MOBILE": "?0",
"HTTP_SEC_CH_UA_PLATFORM": "\"Windows\"",
"HTTP_UPGRADE_INSECURE_REQUESTS": "1",
"HTTP_SEC_PURPOSE": "prefetch;prerender",
"HTTP_PURPOSE": "prefetch",
"HTTP_SEC_FETCH_SITE": "none",
"HTTP_SEC_FETCH_MODE": "navigate",
"HTTP_SEC_FETCH_USER": "?1",
"HTTP_SEC_FETCH_DEST": "document",
"HTTP_X_REQUEST_ID": "fb536bf3-76d0-4936-a354-2a3d023b2cf4",
"HTTP_X_FORWARDED_PROTO": "https",
"HTTP_X_FORWARDED_PORT": "443",
"HTTP_CONNECT_TIME": "1",
"HTTP_X_REQUEST_START": "1697220489932",
"HTTP_TOTAL_ROUTE_TIME": "0",
"SERVER_NAME": "example.com",
"SERVER_PORT": "443",
"REMOTE_ADDR": "10.1.5.53",
"HTTP_VERSION": "HTTP/1.1"
},
"deploy": {
"environment": "production",
"revision": "0eaf61a9ec756be9f4bb511ad71b37baaa9b73ba",
"repository": "https://github.com/spacely/testy-mctestface",
"local_username": "ben@example.com",
"created_at": "2023-10-06T20:52:51.878336Z",
"changelog": [],
"url": "https://github.com/spacely/testy-mctestface/compare/d4f90c876adf4a108ebb9a6f47b5562b59578d97...0eaf61a9ec756be9f4bb511ad71b37baaa9b73ba"
},
"url": "https://app.honeybadger.io/projects/123321/faults/101337516/01HCN3JWWXRQX511BB83WM2X95"
}
}
```
# Rate exceeded event payload
> Sent when error rate threshold is exceeded.
Sent when error rate threshold is exceeded.
```json
{
"event": "rate_exceeded",
"message": "[Testy McTestFace/production] ActiveRecord::NoDatabaseError has occurred time(s) in the past ",
"project": {
"id": 123321,
"name": "Testy McTestFace",
"created_at": "2017-08-30T12:54:33.156695Z",
"disable_public_links": false,
"pivotal_project_id": null,
"asana_workspace_id": null,
"token": "zzz111",
"github_project": "spacely/testy-mctestface",
"environments": [
{
"id": 68210,
"project_id": 123321,
"name": "production",
"notifications": true,
"created_at": "2017-09-05T06:10:19.057794Z",
"updated_at": "2017-09-05T06:10:19.057794Z"
},
{
"id": 68074,
"project_id": 123321,
"name": "development",
"notifications": true,
"created_at": "2017-08-30T12:55:29.297392Z",
"updated_at": "2017-08-30T12:55:29.297392Z"
}
],
"owner": {
"id": 1,
"email": "ben@example.com",
"name": "Spacely Sprockets"
},
"last_notice_at": "2023-10-30T19:29:08.000000Z",
"earliest_notice_at": "2023-05-03T19:37:25.519130Z",
"unresolved_fault_count": 102,
"fault_count": 925,
"active": true,
"users": [
{
"id": 1,
"email": "ben@example.com",
"name": "Ben"
},
{
"id": 99,
"email": "george@example.com",
"name": "George Jetson"
}
],
"sites": [
{
"id": "c42c4c0a-6e3d-4303-9769-549ed2a5818e",
"active": true,
"last_checked_at": "2023-10-30T19:34:08.150725Z",
"name": "Heroku",
"state": "up",
"url": "https://example.com"
}
],
"team_id": 1
},
"fault": {
"project_id": 123321,
"klass": "ActiveRecord::NoDatabaseError",
"component": "pages",
"action": "home",
"environment": "production",
"resolved": false,
"ignored": false,
"created_at": "2023-10-13T18:07:55.692256Z",
"comments_count": 0,
"message": "We could not find your database: d6ipl26lboesdi. Which can be found in the database configuration file located at config/database.yml.\n\nTo resolve this issue:\n\n- Did you create the database for this app, or delete it? You may need to create your database.\n- Has the database name changed? Check your database.yml config has the correct database name.\n\nTo create your database, run:\n\n bin/rails db:create",
"notices_count": 6,
"last_notice_at": "2023-10-13T18:08:10.000000Z",
"tags": [],
"id": 101337516,
"assignee": null,
"url": "https://app.honeybadger.io/projects/123321/faults/101337516",
"deploy": {
"environment": "production",
"revision": "0eaf61a9ec756be9f4bb511ad71b37baaa9b73ba",
"repository": "https://github.com/spacely/testy-mctestface",
"local_username": "ben@example.com",
"created_at": "2023-10-06T20:52:51.878336Z",
"changelog": [],
"url": "https://github.com/spacely/testy-mctestface/compare/d4f90c876adf4a108ebb9a6f47b5562b59578d97...0eaf61a9ec756be9f4bb511ad71b37baaa9b73ba"
}
},
"notice": {
"id": 1013375161697220500,
"environment": {},
"created_at": "2023-10-13T18:08:10.141219Z",
"message": null,
"token": "babe1d9d-67e3-4438-8c57-c544cea24ffb",
"fault_id": 101337516,
"request": {
"url": "https://example.com/",
"component": "pages",
"action": "home",
"params": {
"controller": "pages",
"action": "home"
},
"session": {},
"context": {}
},
"backtrace": [
{
"number": "81",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/postgresql_adapter.rb",
"method": "rescue in new_client",
"source": {
"79": " rescue ::PG::Error => error\n",
"80": " if conn_params && conn_params[:dbname] && error.message.include?(conn_params[:dbname])\n",
"81": " raise ActiveRecord::NoDatabaseError.db_error(conn_params[:dbname])\n",
"82": " elsif conn_params && conn_params[:user] && error.message.include?(conn_params[:user])\n",
"83": " raise ActiveRecord::DatabaseConnectionError.username_error(conn_params[:user])\n"
},
"context": "all"
},
{
"number": "77",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/postgresql_adapter.rb",
"method": "new_client",
"source": {
"75": "\n",
"76": " class << self\n",
"77": " def new_client(conn_params)\n",
"78": " PG.connect(**conn_params)\n",
"79": " rescue ::PG::Error => error\n"
},
"context": "all"
},
{
"number": "37",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/postgresql_adapter.rb",
"method": "postgresql_connection",
"source": {
"35": "\n",
"36": " ConnectionAdapters::PostgreSQLAdapter.new(\n",
"37": " ConnectionAdapters::PostgreSQLAdapter.new_client(conn_params),\n",
"38": " logger,\n",
"39": " conn_params,\n"
},
"context": "all"
},
{
"number": "656",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "public_send",
"source": {
"654": "\n",
"655": " def new_connection\n",
"656": " Base.public_send(db_config.adapter_method, db_config.configuration_hash).tap do |conn|\n",
"657": " conn.check_version\n",
"658": " end\n"
},
"context": "all"
},
{
"number": "656",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "new_connection",
"source": {
"654": "\n",
"655": " def new_connection\n",
"656": " Base.public_send(db_config.adapter_method, db_config.configuration_hash).tap do |conn|\n",
"657": " conn.check_version\n",
"658": " end\n"
},
"context": "all"
},
{
"number": "700",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "checkout_new_connection",
"source": {
"698": " def checkout_new_connection\n",
"699": " raise ConnectionNotEstablished unless @automatic_reconnect\n",
"700": " new_connection\n",
"701": " end\n",
"702": "\n"
},
"context": "all"
},
{
"number": "679",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "try_to_checkout_new_connection",
"source": {
"677": " # if successfully incremented @now_connecting establish new connection\n",
"678": " # outside of synchronized section\n",
"679": " conn = checkout_new_connection\n",
"680": " ensure\n",
"681": " synchronize do\n"
},
"context": "all"
},
{
"number": "640",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "acquire_connection",
"source": {
"638": " # and +try_to_checkout_new_connection+ we can piggyback on +synchronize+ sections\n",
"639": " # of the said methods and avoid an additional +synchronize+ overhead.\n",
"640": " if conn = @available.poll || try_to_checkout_new_connection\n",
"641": " conn\n",
"642": " else\n"
},
"context": "all"
},
{
"number": "341",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "checkout",
"source": {
"339": " # - ActiveRecord::ConnectionTimeoutError no connection can be obtained from the pool.\n",
"340": " def checkout(checkout_timeout = @checkout_timeout)\n",
"341": " checkout_and_verify(acquire_connection(checkout_timeout))\n",
"342": " end\n",
"343": "\n"
},
"context": "all"
},
{
"number": "181",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_pool.rb",
"method": "connection",
"source": {
"179": " # held in a cache keyed by a thread.\n",
"180": " def connection\n",
"181": " @thread_cached_conns[connection_cache_key(current_thread)] ||= checkout\n",
"182": " end\n",
"183": "\n"
},
"context": "all"
},
{
"number": "211",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_adapters/abstract/connection_handler.rb",
"method": "retrieve_connection",
"source": {
"209": " end\n",
"210": "\n",
"211": " pool.connection\n",
"212": " end\n",
"213": "\n"
},
"context": "all"
},
{
"number": "313",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_handling.rb",
"method": "retrieve_connection",
"source": {
"311": "\n",
"312": " def retrieve_connection\n",
"313": " connection_handler.retrieve_connection(connection_specification_name, role: current_role, shard: current_shard)\n",
"314": " end\n",
"315": "\n"
},
"context": "all"
},
{
"number": "280",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/connection_handling.rb",
"method": "connection",
"source": {
"278": " # to any of the specific Active Records.\n",
"279": " def connection\n",
"280": " retrieve_connection\n",
"281": " end\n",
"282": "\n"
},
"context": "all"
},
{
"number": "433",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/core.rb",
"method": "cached_find_by_statement",
"source": {
"431": "\n",
"432": " def cached_find_by_statement(key, &block) # :nodoc:\n",
"433": " cache = @find_by_statement_cache[connection.prepared_statements]\n",
"434": " cache.compute_if_absent(key) { StatementCache.create(connection, &block) }\n",
"435": " end\n"
},
"context": "all"
},
{
"number": "317",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/core.rb",
"method": "find_by",
"source": {
"315": "\n",
"316": " keys = hash.keys\n",
"317": " statement = cached_find_by_statement(keys) { |params|\n",
"318": " wheres = keys.index_with { params.bind }\n",
"319": " where(wheres).limit(1)\n"
},
"context": "all"
},
{
"number": "69",
"file": "[PROJECT_ROOT]/app/controllers/application_controller.rb",
"method": "check_redirect",
"source": {
"67": "\n",
"68": " def check_redirect\n",
"69": " return unless (redirect = Redirect.find_by(slug: request.path.sub(%r{^/}, \"\")))\n",
"70": " redirect_to redirect.url\n",
"71": " end\n"
},
"application_file": "app/controllers/application_controller.rb",
"context": "app"
},
{
"number": "400",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "block in make_lambda",
"source": {
"398": " def make_lambda\n",
"399": " lambda do |target, value, &block|\n",
"400": " target.send(@method_name, &block)\n",
"401": " end\n",
"402": " end\n"
},
"context": "all"
},
{
"number": "180",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "block (2 levels) in halting_and_conditional",
"source": {
"178": "\n",
"179": " if !halted && user_conditions.all? { |c| c.call(target, value) }\n",
"180": " result_lambda = -> { user_callback.call target, value }\n",
"181": " env.halted = halted_lambda.call(target, result_lambda)\n",
"182": " if env.halted\n"
},
"context": "all"
},
{
"number": "34",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/abstract_controller/callbacks.rb",
"method": "block (2 levels) in ",
"source": {
"32": " included do\n",
"33": " define_callbacks :process_action,\n",
"34": " terminator: ->(controller, result_lambda) { result_lambda.call; controller.performed? },\n",
"35": " skip_after_callbacks_if_terminated: true\n",
"36": " end\n"
},
"context": "all"
},
{
"number": "181",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "block in halting_and_conditional",
"source": {
"179": " if !halted && user_conditions.all? { |c| c.call(target, value) }\n",
"180": " result_lambda = -> { user_callback.call target, value }\n",
"181": " env.halted = halted_lambda.call(target, result_lambda)\n",
"182": " if env.halted\n",
"183": " target.send :halted_callback_hook, filter, name\n"
},
"context": "all"
},
{
"number": "595",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "block in invoke_before",
"source": {
"593": "\n",
"594": " def invoke_before(arg)\n",
"595": " @before.each { |b| b.call(arg) }\n",
"596": " end\n",
"597": "\n"
},
"context": "all"
},
{
"number": "595",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "each",
"source": {
"593": "\n",
"594": " def invoke_before(arg)\n",
"595": " @before.each { |b| b.call(arg) }\n",
"596": " end\n",
"597": "\n"
},
"context": "all"
},
{
"number": "595",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "invoke_before",
"source": {
"593": "\n",
"594": " def invoke_before(arg)\n",
"595": " @before.each { |b| b.call(arg) }\n",
"596": " end\n",
"597": "\n"
},
"context": "all"
},
{
"number": "106",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "run_callbacks",
"source": {
"104": " # Common case: no 'around' callbacks defined\n",
"105": " if next_sequence.final?\n",
"106": " next_sequence.invoke_before(env)\n",
"107": " env.value = !env.halted && (!block_given? || yield)\n",
"108": " next_sequence.invoke_after(env)\n"
},
"context": "all"
},
{
"number": "233",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/abstract_controller/callbacks.rb",
"method": "process_action",
"source": {
"231": " # process_action callbacks around the normal behavior.\n",
"232": " def process_action(...)\n",
"233": " run_callbacks(:process_action) do\n",
"234": " super\n",
"235": " end\n"
},
"context": "all"
},
{
"number": "23",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_controller/metal/rescue.rb",
"method": "process_action",
"source": {
"21": " private\n",
"22": " def process_action(*)\n",
"23": " super\n",
"24": " rescue Exception => exception\n",
"25": " request.env[\"action_dispatch.show_detailed_exceptions\"] ||= show_detailed_exceptions?\n"
},
"context": "all"
},
{
"number": "67",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_controller/metal/instrumentation.rb",
"method": "block in process_action",
"source": {
"65": "\n",
"66": " ActiveSupport::Notifications.instrument(\"process_action.action_controller\", raw_payload) do |payload|\n",
"67": " result = super\n",
"68": " payload[:response] = response\n",
"69": " payload[:status] = response.status\n"
},
"context": "all"
},
{
"number": "206",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/notifications.rb",
"method": "block in instrument",
"source": {
"204": " def instrument(name, payload = {})\n",
"205": " if notifier.listening?(name)\n",
"206": " instrumenter.instrument(name, payload) { yield payload if block_given? }\n",
"207": " else\n",
"208": " yield payload if block_given?\n"
},
"context": "all"
},
{
"number": "24",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/notifications/instrumenter.rb",
"method": "instrument",
"source": {
"22": " listeners_state = start name, payload\n",
"23": " begin\n",
"24": " yield payload if block_given?\n",
"25": " rescue Exception => e\n",
"26": " payload[:exception] = [e.class.name, e.message]\n"
},
"context": "all"
},
{
"number": "206",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/notifications.rb",
"method": "instrument",
"source": {
"204": " def instrument(name, payload = {})\n",
"205": " if notifier.listening?(name)\n",
"206": " instrumenter.instrument(name, payload) { yield payload if block_given? }\n",
"207": " else\n",
"208": " yield payload if block_given?\n"
},
"context": "all"
},
{
"number": "66",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_controller/metal/instrumentation.rb",
"method": "process_action",
"source": {
"64": " ActiveSupport::Notifications.instrument(\"start_processing.action_controller\", raw_payload)\n",
"65": "\n",
"66": " ActiveSupport::Notifications.instrument(\"process_action.action_controller\", raw_payload) do |payload|\n",
"67": " result = super\n",
"68": " payload[:response] = response\n"
},
"context": "all"
},
{
"number": "259",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_controller/metal/params_wrapper.rb",
"method": "process_action",
"source": {
"257": " def process_action(*)\n",
"258": " _perform_parameter_wrapping if _wrapper_enabled?\n",
"259": " super\n",
"260": " end\n",
"261": "\n"
},
"context": "all"
},
{
"number": "27",
"file": "[GEM_ROOT]/gems/activerecord-7.0.7.2/lib/active_record/railties/controller_runtime.rb",
"method": "process_action",
"source": {
"25": " # and it won't be cleaned up by the method below.\n",
"26": " ActiveRecord::LogSubscriber.reset_runtime\n",
"27": " super\n",
"28": " end\n",
"29": "\n"
},
"context": "all"
},
{
"number": "120",
"file": "[GEM_ROOT]/gems/scout_apm-5.3.5/lib/scout_apm/instruments/action_controller_rails_3_rails4.rb",
"method": "process_action",
"source": {
"118": " req.start_layer( ScoutApm::Layer.new(\"Controller\", \"#{controller_path}/#{resolved_name}\") )\n",
"119": " begin\n",
"120": " super\n",
"121": " rescue\n",
"122": " req.error!\n"
},
"context": "all"
},
{
"number": "151",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/abstract_controller/base.rb",
"method": "process",
"source": {
"149": " @_response_body = nil\n",
"150": "\n",
"151": " process_action(action_name, *args)\n",
"152": " end\n",
"153": " ruby2_keywords(:process)\n"
},
"context": "all"
},
{
"number": "39",
"file": "[GEM_ROOT]/gems/actionview-7.0.7.2/lib/action_view/rendering.rb",
"method": "process",
"source": {
"37": " def process(...) # :nodoc:\n",
"38": " old_config, I18n.config = I18n.config, I18nProxy.new(I18n.config, lookup_context)\n",
"39": " super\n",
"40": " ensure\n",
"41": " I18n.config = old_config\n"
},
"context": "all"
},
{
"number": "188",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_controller/metal.rb",
"method": "dispatch",
"source": {
"186": " set_request!(request)\n",
"187": " set_response!(response)\n",
"188": " process(name)\n",
"189": " request.commit_flash\n",
"190": " to_a\n"
},
"context": "all"
},
{
"number": "251",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_controller/metal.rb",
"method": "dispatch",
"source": {
"249": " middleware_stack.build(name) { |env| new.dispatch(name, req, res) }.call req.env\n",
"250": " else\n",
"251": " new.dispatch(name, req, res)\n",
"252": " end\n",
"253": " end\n"
},
"context": "all"
},
{
"number": "49",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/routing/route_set.rb",
"method": "dispatch",
"source": {
"47": "\n",
"48": " def dispatch(controller, action, req, res)\n",
"49": " controller.dispatch(action, req, res)\n",
"50": " end\n",
"51": " end\n"
},
"context": "all"
},
{
"number": "32",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/routing/route_set.rb",
"method": "serve",
"source": {
"30": " controller = controller req\n",
"31": " res = controller.make_response! req\n",
"32": " dispatch(controller, params[:action], req, res)\n",
"33": " rescue ActionController::RoutingError\n",
"34": " if @raise_on_name_error\n"
},
"context": "all"
},
{
"number": "50",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/journey/router.rb",
"method": "block in serve",
"source": {
"48": " req.path_parameters = tmp_params\n",
"49": "\n",
"50": " status, headers, body = route.app.serve(req)\n",
"51": "\n",
"52": " if \"pass\" == headers[\"X-Cascade\"]\n"
},
"context": "all"
},
{
"number": "32",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/journey/router.rb",
"method": "each",
"source": {
"30": "\n",
"31": " def serve(req)\n",
"32": " find_routes(req).each do |match, parameters, route|\n",
"33": " set_params = req.path_parameters\n",
"34": " path_info = req.path_info\n"
},
"context": "all"
},
{
"number": "32",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/journey/router.rb",
"method": "serve",
"source": {
"30": "\n",
"31": " def serve(req)\n",
"32": " find_routes(req).each do |match, parameters, route|\n",
"33": " set_params = req.path_parameters\n",
"34": " path_info = req.path_info\n"
},
"context": "all"
},
{
"number": "852",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/routing/route_set.rb",
"method": "call",
"source": {
"850": " req = make_request(env)\n",
"851": " req.path_info = Journey::Router::Utils.normalize_path(req.path_info)\n",
"852": " @router.serve(req)\n",
"853": " end\n",
"854": "\n"
},
"context": "all"
},
{
"number": "29",
"file": "[GEM_ROOT]/gems/scout_apm-5.3.5/lib/scout_apm/instruments/rails_router.rb",
"method": "call_with_scout_instruments",
"source": {
"27": "\n",
"28": " begin\n",
"29": " call_without_scout_instruments(*args)\n",
"30": " ensure\n",
"31": " req.stop_layer\n"
},
"context": "all"
},
{
"number": "17",
"file": "[GEM_ROOT]/gems/scout_apm-5.3.5/lib/scout_apm/middleware.rb",
"method": "call",
"source": {
"15": " def call(env)\n",
"16": " if !@enabled || @started || @attempts > MAX_ATTEMPTS\n",
"17": " @app.call(env)\n",
"18": " else\n",
"19": " attempt_to_start_agent\n"
},
"context": "all"
},
{
"number": "36",
"file": "[GEM_ROOT]/gems/warden-1.2.9/lib/warden/manager.rb",
"method": "block in call",
"source": {
"34": " result = catch(:warden) do\n",
"35": " env['warden'].on_request\n",
"36": " @app.call(env)\n",
"37": " end\n",
"38": "\n"
},
"context": "all"
},
{
"number": "34",
"file": "[GEM_ROOT]/gems/warden-1.2.9/lib/warden/manager.rb",
"method": "catch",
"source": {
"32": "\n",
"33": " env['warden'] = Proxy.new(env, self)\n",
"34": " result = catch(:warden) do\n",
"35": " env['warden'].on_request\n",
"36": " @app.call(env)\n"
},
"context": "all"
},
{
"number": "34",
"file": "[GEM_ROOT]/gems/warden-1.2.9/lib/warden/manager.rb",
"method": "call",
"source": {
"32": "\n",
"33": " env['warden'] = Proxy.new(env, self)\n",
"34": " result = catch(:warden) do\n",
"35": " env['warden'].on_request\n",
"36": " @app.call(env)\n"
},
"context": "all"
},
{
"number": "15",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/tempfile_reaper.rb",
"method": "call",
"source": {
"13": " def call(env)\n",
"14": " env[RACK_TEMPFILES] ||= []\n",
"15": " status, headers, body = @app.call(env)\n",
"16": " body_proxy = BodyProxy.new(body) do\n",
"17": " env[RACK_TEMPFILES].each(&:close!) unless env[RACK_TEMPFILES].nil?\n"
},
"context": "all"
},
{
"number": "27",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/conditional_get.rb",
"method": "call",
"source": {
"25": " case env[REQUEST_METHOD]\n",
"26": " when \"GET\", \"HEAD\"\n",
"27": " status, headers, body = @app.call(env)\n",
"28": " headers = Utils::HeaderHash[headers]\n",
"29": " if status == 200 && fresh?(env, headers)\n"
},
"context": "all"
},
{
"number": "12",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/head.rb",
"method": "call",
"source": {
"10": "\n",
"11": " def call(env)\n",
"12": " status, headers, body = @app.call(env)\n",
"13": "\n",
"14": " if env[REQUEST_METHOD] == HEAD\n"
},
"context": "all"
},
{
"number": "38",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/http/permissions_policy.rb",
"method": "call",
"source": {
"36": " def call(env)\n",
"37": " request = ActionDispatch::Request.new(env)\n",
"38": " _, headers, _ = response = @app.call(env)\n",
"39": "\n",
"40": " return response unless html_response?(headers)\n"
},
"context": "all"
},
{
"number": "36",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/http/content_security_policy.rb",
"method": "call",
"source": {
"34": " def call(env)\n",
"35": " request = ActionDispatch::Request.new env\n",
"36": " status, headers, _ = response = @app.call(env)\n",
"37": "\n",
"38": " # Returning CSP headers with a 304 Not Modified is harmful, since nonces in the new\n"
},
"context": "all"
},
{
"number": "266",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/session/abstract/id.rb",
"method": "context",
"source": {
"264": " req = make_request env\n",
"265": " prepare_session(req)\n",
"266": " status, headers, body = app.call(req.env)\n",
"267": " res = Rack::Response::Raw.new status, headers\n",
"268": " commit_session(req, res)\n"
},
"context": "all"
},
{
"number": "260",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/session/abstract/id.rb",
"method": "call",
"source": {
"258": "\n",
"259": " def call(env)\n",
"260": " context(env)\n",
"261": " end\n",
"262": "\n"
},
"context": "all"
},
{
"number": "704",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/cookies.rb",
"method": "call",
"source": {
"702": " request = ActionDispatch::Request.new env\n",
"703": "\n",
"704": " status, headers, body = @app.call(env)\n",
"705": "\n",
"706": " if request.have_cookie_jar?\n"
},
"context": "all"
},
{
"number": "27",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/callbacks.rb",
"method": "block in call",
"source": {
"25": " error = nil\n",
"26": " result = run_callbacks :call do\n",
"27": " @app.call(env)\n",
"28": " rescue => error\n",
"29": " end\n"
},
"context": "all"
},
{
"number": "99",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/callbacks.rb",
"method": "run_callbacks",
"source": {
"97": "\n",
"98": " if callbacks.empty?\n",
"99": " yield if block_given?\n",
"100": " else\n",
"101": " env = Filters::Environment.new(self, false, nil)\n"
},
"context": "all"
},
{
"number": "26",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/callbacks.rb",
"method": "call",
"source": {
"24": " def call(env)\n",
"25": " error = nil\n",
"26": " result = run_callbacks :call do\n",
"27": " @app.call(env)\n",
"28": " rescue => error\n"
},
"context": "all"
},
{
"number": "28",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/debug_exceptions.rb",
"method": "call",
"source": {
"26": " def call(env)\n",
"27": " request = ActionDispatch::Request.new env\n",
"28": " _, headers, body = response = @app.call(env)\n",
"29": "\n",
"30": " if headers[\"X-Cascade\"] == \"pass\"\n"
},
"context": "all"
},
{
"number": "29",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/show_exceptions.rb",
"method": "call",
"source": {
"27": " def call(env)\n",
"28": " request = ActionDispatch::Request.new env\n",
"29": " @app.call(env)\n",
"30": " rescue Exception => exception\n",
"31": " if request.show_exceptions?\n"
},
"context": "all"
},
{
"number": "18",
"file": "[GEM_ROOT]/gems/lograge-0.12.0/lib/lograge/rails_ext/rack/logger.rb",
"method": "call_app",
"source": {
"16": " def call_app(*args)\n",
"17": " env = args.last\n",
"18": " status, headers, body = @app.call(env)\n",
"19": " # needs to have same return type as the Rails builtins being overridden, see https://github.com/roidrage/lograge/pull/333\n",
"20": " # https://github.com/rails/rails/blob/be9d34b9bcb448b265114ebc28bef1a5b5e4c272/railties/lib/rails/rack/logger.rb#L37\n"
},
"context": "all"
},
{
"number": "25",
"file": "[GEM_ROOT]/gems/railties-7.0.7.2/lib/rails/rack/logger.rb",
"method": "block in call",
"source": {
"23": "\n",
"24": " if logger.respond_to?(:tagged)\n",
"25": " logger.tagged(compute_tags(request)) { call_app(request, env) }\n",
"26": " else\n",
"27": " call_app(request, env)\n"
},
"context": "all"
},
{
"number": "99",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/tagged_logging.rb",
"method": "block in tagged",
"source": {
"97": " def tagged(*tags)\n",
"98": " if block_given?\n",
"99": " formatter.tagged(*tags) { yield self }\n",
"100": " else\n",
"101": " logger = ActiveSupport::TaggedLogging.new(self)\n"
},
"context": "all"
},
{
"number": "37",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/tagged_logging.rb",
"method": "tagged",
"source": {
"35": " def tagged(*tags)\n",
"36": " new_tags = push_tags(*tags)\n",
"37": " yield self\n",
"38": " ensure\n",
"39": " pop_tags(new_tags.size)\n"
},
"context": "all"
},
{
"number": "99",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/tagged_logging.rb",
"method": "tagged",
"source": {
"97": " def tagged(*tags)\n",
"98": " if block_given?\n",
"99": " formatter.tagged(*tags) { yield self }\n",
"100": " else\n",
"101": " logger = ActiveSupport::TaggedLogging.new(self)\n"
},
"context": "all"
},
{
"number": "25",
"file": "[GEM_ROOT]/gems/railties-7.0.7.2/lib/rails/rack/logger.rb",
"method": "call",
"source": {
"23": "\n",
"24": " if logger.respond_to?(:tagged)\n",
"25": " logger.tagged(compute_tags(request)) { call_app(request, env) }\n",
"26": " else\n",
"27": " call_app(request, env)\n"
},
"context": "all"
},
{
"number": "93",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/remote_ip.rb",
"method": "call",
"source": {
"91": " req = ActionDispatch::Request.new env\n",
"92": " req.remote_ip = GetIp.new(req, check_ip, proxies)\n",
"93": " @app.call(req.env)\n",
"94": " end\n",
"95": "\n"
},
"context": "all"
},
{
"number": "19",
"file": "[GEM_ROOT]/gems/request_store-1.5.1/lib/request_store/middleware.rb",
"method": "call",
"source": {
"17": " RequestStore.begin!\r\n",
"18": "\r\n",
"19": " status, headers, body = @app.call(env)\r\n",
"20": "\r\n",
"21": " body = Rack::BodyProxy.new(body) do\r\n"
},
"context": "all"
},
{
"number": "26",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/request_id.rb",
"method": "call",
"source": {
"24": " req = ActionDispatch::Request.new env\n",
"25": " req.request_id = make_request_id(req.headers[@header])\n",
"26": " @app.call(env).tap { |_status, headers, _body| headers[@header] = req.request_id }\n",
"27": " end\n",
"28": "\n"
},
"context": "all"
},
{
"number": "24",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/method_override.rb",
"method": "call",
"source": {
"22": " end\n",
"23": "\n",
"24": " @app.call(env)\n",
"25": " end\n",
"26": "\n"
},
"context": "all"
},
{
"number": "22",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/runtime.rb",
"method": "call",
"source": {
"20": " def call(env)\n",
"21": " start_time = Utils.clock_time\n",
"22": " status, headers, body = @app.call(env)\n",
"23": " headers = Utils::HeaderHash[headers]\n",
"24": "\n"
},
"context": "all"
},
{
"number": "148",
"file": "[GEM_ROOT]/gems/rack-timeout-0.6.3/lib/rack/timeout/core.rb",
"method": "block in call",
"source": {
"146": "\n",
"147": " response = timeout.timeout(info.timeout) do # perform request with timeout\n",
"148": " begin @app.call(env) # boom, send request down the middleware chain\n",
"149": " rescue RequestTimeoutException => e # will actually hardly ever get to this point because frameworks tend to catch this. see README for more\n",
"150": " raise RequestTimeoutError.new(env), e.message, e.backtrace # but in case it does get here, re-raise RequestTimeoutException as RequestTimeoutError\n"
},
"context": "all"
},
{
"number": "19",
"file": "[GEM_ROOT]/gems/rack-timeout-0.6.3/lib/rack/timeout/support/timeout.rb",
"method": "timeout",
"source": {
"17": " thr = Thread.current # reference to current thread to be used in timeout thread\n",
"18": " job = @scheduler.run_in(secs) { @on_timeout.call thr } # schedule this thread to be timed out; should get cancelled if block completes on time\n",
"19": " return block.call # do what you gotta do\n",
"20": " ensure #\n",
"21": " job.cancel! if job # cancel the scheduled timeout job; if the block completed on time, this\n"
},
"context": "all"
},
{
"number": "147",
"file": "[GEM_ROOT]/gems/rack-timeout-0.6.3/lib/rack/timeout/core.rb",
"method": "call",
"source": {
"145": " end\n",
"146": "\n",
"147": " response = timeout.timeout(info.timeout) do # perform request with timeout\n",
"148": " begin @app.call(env) # boom, send request down the middleware chain\n",
"149": " rescue RequestTimeoutException => e # will actually hardly ever get to this point because frameworks tend to catch this. see README for more\n"
},
"context": "all"
},
{
"number": "41",
"file": "[GEM_ROOT]/gems/judoscale-ruby-1.4.1/lib/judoscale/request_middleware.rb",
"method": "call",
"source": {
"39": " end\n",
"40": "\n",
"41": " @app.call(env)\n",
"42": " end\n",
"43": " end\n"
},
"context": "all"
},
{
"number": "29",
"file": "[GEM_ROOT]/gems/activesupport-7.0.7.2/lib/active_support/cache/strategy/local_cache_middleware.rb",
"method": "call",
"source": {
"27": " def call(env)\n",
"28": " LocalCacheRegistry.set_cache_for(local_cache_key, LocalStore.new)\n",
"29": " response = @app.call(env)\n",
"30": " response[2] = ::Rack::BodyProxy.new(response[2]) do\n",
"31": " LocalCacheRegistry.set_cache_for(local_cache_key, nil)\n"
},
"context": "all"
},
{
"number": "24",
"file": "[GEM_ROOT]/gems/rack-rewrite-1.5.1/lib/rack/rewrite.rb",
"method": "call",
"source": {
"22": " return rack_response unless rack_response === true\n",
"23": " end\n",
"24": " @app.call(env)\n",
"25": " end\n",
"26": " \n"
},
"context": "all"
},
{
"number": "14",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/executor.rb",
"method": "call",
"source": {
"12": " state = @executor.run!(reset: true)\n",
"13": " begin\n",
"14": " response = @app.call(env)\n",
"15": " returned = response << ::Rack::BodyProxy.new(response.pop) { state.complete! }\n",
"16": " rescue => error\n"
},
"context": "all"
},
{
"number": "23",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/static.rb",
"method": "call",
"source": {
"21": "\n",
"22": " def call(env)\n",
"23": " @file_handler.attempt(env) || @app.call(env)\n",
"24": " end\n",
"25": " end\n"
},
"context": "all"
},
{
"number": "110",
"file": "[GEM_ROOT]/gems/rack-2.2.8/lib/rack/sendfile.rb",
"method": "call",
"source": {
"108": "\n",
"109": " def call(env)\n",
"110": " status, headers, body = @app.call(env)\n",
"111": " if body.respond_to?(:to_path)\n",
"112": " case type = variation(env)\n"
},
"context": "all"
},
{
"number": "77",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/ssl.rb",
"method": "call",
"source": {
"75": "\n",
"76": " if request.ssl?\n",
"77": " @app.call(env).tap do |status, headers, body|\n",
"78": " set_hsts_header! headers\n",
"79": " flag_cookies_as_secure! headers if @secure_cookies && !@exclude.call(request)\n"
},
"context": "all"
},
{
"number": "131",
"file": "[GEM_ROOT]/gems/actionpack-7.0.7.2/lib/action_dispatch/middleware/host_authorization.rb",
"method": "call",
"source": {
"129": "\n",
"130": " def call(env)\n",
"131": " return @app.call(env) if @permissions.empty?\n",
"132": "\n",
"133": " request = Request.new(env)\n"
},
"context": "all"
},
{
"number": "58",
"file": "[GEM_ROOT]/gems/scout_apm-5.3.5/lib/scout_apm/instruments/middleware_summary.rb",
"method": "call",
"source": {
"56": " layer = ScoutApm::Layer.new(\"Middleware\", \"Summary\")\n",
"57": " req.start_layer(layer)\n",
"58": " @app.call(env)\n",
"59": " ensure\n",
"60": " req.stop_layer\n"
},
"context": "all"
},
{
"number": "530",
"file": "[GEM_ROOT]/gems/railties-7.0.7.2/lib/rails/engine.rb",
"method": "call",
"source": {
"528": " def call(env)\n",
"529": " req = build_request env\n",
"530": " app.call req.env\n",
"531": " end\n",
"532": "\n"
},
"context": "all"
},
{
"number": "270",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/configuration.rb",
"method": "call",
"source": {
"268": " def call(env)\n",
"269": " env[Const::PUMA_CONFIG] = @config\n",
"270": " @app.call(env)\n",
"271": " end\n",
"272": " end\n"
},
"context": "all"
},
{
"number": "100",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/request.rb",
"method": "block in handle_request",
"source": {
"98": " if @supported_http_methods == :any || @supported_http_methods.key?(env[REQUEST_METHOD])\n",
"99": " status, headers, app_body = @thread_pool.with_force_shutdown do\n",
"100": " @app.call(env)\n",
"101": " end\n",
"102": " else\n"
},
"context": "all"
},
{
"number": "344",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/thread_pool.rb",
"method": "with_force_shutdown",
"source": {
"342": " t[:with_force_shutdown] = true\n",
"343": " end\n",
"344": " yield\n",
"345": " ensure\n",
"346": " t[:with_force_shutdown] = false\n"
},
"context": "all"
},
{
"number": "99",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/request.rb",
"method": "handle_request",
"source": {
"97": " begin\n",
"98": " if @supported_http_methods == :any || @supported_http_methods.key?(env[REQUEST_METHOD])\n",
"99": " status, headers, app_body = @thread_pool.with_force_shutdown do\n",
"100": " @app.call(env)\n",
"101": " end\n"
},
"context": "all"
},
{
"number": "443",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/server.rb",
"method": "process_client",
"source": {
"441": " while true\n",
"442": " @requests_count += 1\n",
"443": " case handle_request(client, requests + 1)\n",
"444": " when false\n",
"445": " break\n"
},
"context": "all"
},
{
"number": "245",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/server.rb",
"method": "block in run",
"source": {
"243": " @status = :run\n",
"244": "\n",
"245": " @thread_pool = ThreadPool.new(thread_name, @options) { |client| process_client client }\n",
"246": "\n",
"247": " if @queue_requests\n"
},
"context": "all"
},
{
"number": "151",
"file": "[GEM_ROOT]/gems/puma-6.3.1/lib/puma/thread_pool.rb",
"method": "block in spawn_thread",
"source": {
"149": "\n",
"150": " begin\n",
"151": " @out_of_band_pending = true if block.call(work)\n",
"152": " rescue Exception => e\n",
"153": " STDERR.puts \"Error reached top of thread-pool: #{e.message} (#{e.class})\"\n"
},
"context": "all"
}
],
"application_trace": [
{
"number": "69",
"file": "[PROJECT_ROOT]/app/controllers/application_controller.rb",
"method": "check_redirect",
"source": {
"67": "\n",
"68": " def check_redirect\n",
"69": " return unless (redirect = Redirect.find_by(slug: request.path.sub(%r{^/}, \"\")))\n",
"70": " redirect_to redirect.url\n",
"71": " end\n"
},
"application_file": "app/controllers/application_controller.rb",
"context": "app"
}
],
"web_environment": {
"SERVER_SOFTWARE": "puma 6.3.1 Mugi No Toki Itaru",
"GATEWAY_INTERFACE": "CGI/1.2",
"REQUEST_METHOD": "GET",
"SERVER_PROTOCOL": "HTTP/1.1",
"HTTP_HOST": "example.com",
"HTTP_CONNECTION": "close",
"HTTP_USER_AGENT": "Amazon CloudFront",
"HTTP_X_AMZ_CF_ID": "yai2eezeewaipahthieN-Yt3y0gAunRuwBHH8A==",
"HTTP_IF_NONE_MATCH": "W/\"fde6ca645252fa81edfdae38dbeef178\"",
"HTTP_ACCEPT": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7",
"HTTP_X_FORWARDED_FOR": "199.175.219.155, 64.252.73.106",
"HTTP_VIA": "2.0 yai2eezeewaipahthieN.cloudfront.net (CloudFront), 1.1 vegur",
"HTTP_ACCEPT_ENCODING": "gzip",
"HTTP_IF_MODIFIED_SINCE": "Wed, 11 Oct 2023 20:51:58 GMT",
"HTTP_SEC_CH_UA": "\"Google Chrome\";v=\"117\", \"Not;A=Brand\";v=\"8\", \"Chromium\";v=\"117\"",
"HTTP_SEC_CH_UA_MOBILE": "?0",
"HTTP_SEC_CH_UA_PLATFORM": "\"Windows\"",
"HTTP_UPGRADE_INSECURE_REQUESTS": "1",
"HTTP_SEC_PURPOSE": "prefetch;prerender",
"HTTP_PURPOSE": "prefetch",
"HTTP_SEC_FETCH_SITE": "none",
"HTTP_SEC_FETCH_MODE": "navigate",
"HTTP_SEC_FETCH_USER": "?1",
"HTTP_SEC_FETCH_DEST": "document",
"HTTP_X_REQUEST_ID": "fb536bf3-76d0-4936-a354-2a3d023b2cf4",
"HTTP_X_FORWARDED_PROTO": "https",
"HTTP_X_FORWARDED_PORT": "443",
"HTTP_CONNECT_TIME": "1",
"HTTP_X_REQUEST_START": "1697220489932",
"HTTP_TOTAL_ROUTE_TIME": "0",
"SERVER_NAME": "example.com",
"SERVER_PORT": "443",
"REMOTE_ADDR": "10.1.5.53",
"HTTP_VERSION": "HTTP/1.1"
},
"deploy": {
"environment": "production",
"revision": "0eaf61a9ec756be9f4bb511ad71b37baaa9b73ba",
"repository": "https://github.com/spacely/testy-mctestface",
"local_username": "ben@example.com",
"created_at": "2023-10-06T20:52:51.878336Z",
"changelog": [],
"url": "https://github.com/spacely/testy-mctestface/compare/d4f90c876adf4a108ebb9a6f47b5562b59578d97...0eaf61a9ec756be9f4bb511ad71b37baaa9b73ba"
},
"url": "https://app.honeybadger.io/projects/123321/faults/101337516/01HCN3JWWXRQX511BB83WM2X95"
}
}
```
# Error resolved event payload
> Sent when an error is marked as resolved.
Sent when an error is marked as resolved.
```json
{
"event": "resolved",
"message": "[Testy McTestFace/production] ActiveRecord::NoDatabaseError resolved by ",
"fault": {
"project_id": 123321,
"klass": "ActiveRecord::NoDatabaseError",
"component": "pages",
"action": "home",
"environment": "production",
"resolved": false,
"ignored": false,
"created_at": "2023-10-13T18:07:55.692256Z",
"comments_count": 0,
"message": "We could not find your database: d6ipl26lboesdi. Which can be found in the database configuration file located at config/database.yml.\n\nTo resolve this issue:\n\n- Did you create the database for this app, or delete it? You may need to create your database.\n- Has the database name changed? Check your database.yml config has the correct database name.\n\nTo create your database, run:\n\n bin/rails db:create",
"notices_count": 6,
"last_notice_at": "2023-10-13T18:08:10.000000Z",
"tags": [],
"id": 101337516,
"assignee": null,
"url": "https://app.honeybadger.io/projects/123321/faults/101337516",
"deploy": {
"environment": "production",
"revision": "0eaf61a9ec756be9f4bb511ad71b37baaa9b73ba",
"repository": "https://github.com/spacely/testy-mctestface",
"local_username": "ben@example.com",
"created_at": "2023-10-06T20:52:51.878336Z",
"changelog": [],
"url": "https://github.com/spacely/testy-mctestface/compare/d4f90c876adf4a108ebb9a6f47b5562b59578d97...0eaf61a9ec756be9f4bb511ad71b37baaa9b73ba"
}
}
}
```
# Error unresolved event payload
> Sent when a resolved error occurs again.
Sent when a resolved error occurs again.
```json
{
"event": "unresolved",
"message": "[Testy McTestFace/production] ActiveRecord::NoDatabaseError unresolved by ",
"fault": {
"project_id": 123321,
"klass": "ActiveRecord::NoDatabaseError",
"component": "pages",
"action": "home",
"environment": "production",
"resolved": false,
"ignored": false,
"created_at": "2023-10-13T18:07:55.692256Z",
"comments_count": 0,
"message": "We could not find your database: d6ipl26lboesdi. Which can be found in the database configuration file located at config/database.yml.\n\nTo resolve this issue:\n\n- Did you create the database for this app, or delete it? You may need to create your database.\n- Has the database name changed? Check your database.yml config has the correct database name.\n\nTo create your database, run:\n\n bin/rails db:create",
"notices_count": 6,
"last_notice_at": "2023-10-13T18:08:10.000000Z",
"tags": [],
"id": 101337516,
"assignee": null,
"url": "https://app.honeybadger.io/projects/123321/faults/101337516",
"deploy": {
"environment": "production",
"revision": "0eaf61a9ec756be9f4bb511ad71b37baaa9b73ba",
"repository": "https://github.com/spacely/testy-mctestface",
"local_username": "ben@example.com",
"created_at": "2023-10-06T20:52:51.878336Z",
"changelog": [],
"url": "https://github.com/spacely/testy-mctestface/compare/d4f90c876adf4a108ebb9a6f47b5562b59578d97...0eaf61a9ec756be9f4bb511ad71b37baaa9b73ba"
}
}
}
```
# Site up event payload
> Sent when an uptime check succeeds after being down.
Sent when an uptime check succeeds after being down.
```json
{
"event": "up",
"message": "[Testy McTestFace] Heroku is back up after 0m.",
"project": {
"id": 123321,
"name": "Testy McTestFace",
"created_at": "2017-08-30T12:54:33.156695Z",
"disable_public_links": false,
"pivotal_project_id": null,
"asana_workspace_id": null,
"token": "zzz111",
"github_project": "spacely/testy-mctestface",
"environments": [
{
"id": 68210,
"project_id": 123321,
"name": "production",
"notifications": true,
"created_at": "2017-09-05T06:10:19.057794Z",
"updated_at": "2017-09-05T06:10:19.057794Z"
},
{
"id": 68074,
"project_id": 123321,
"name": "development",
"notifications": true,
"created_at": "2017-08-30T12:55:29.297392Z",
"updated_at": "2017-08-30T12:55:29.297392Z"
}
],
"owner": {
"id": 1,
"email": "ben@example.com",
"name": "Spacely Sprockets"
},
"last_notice_at": "2023-10-30T19:29:08.000000Z",
"earliest_notice_at": "2023-05-03T19:38:14.971778Z",
"unresolved_fault_count": 102,
"fault_count": 925,
"active": true,
"users": [
{
"id": 1,
"email": "ben@example.com",
"name": "Ben"
},
{
"id": 99,
"email": "george@example.com",
"name": "George Jetson"
}
],
"sites": [
{
"id": "c42c4c0a-6e3d-4303-9769-549ed2a5818e",
"active": true,
"last_checked_at": "2023-10-30T19:34:08.150725Z",
"name": "Heroku",
"state": "up",
"url": "https://example.com"
}
],
"team_id": 1
},
"site": {
"id": "c42c4c0a-6e3d-4303-9769-549ed2a5818e",
"name": "Heroku",
"url": "https://example.com",
"frequency": 5,
"match_type": "success",
"match": null,
"state": "up",
"active": true,
"last_checked_at": "2023-10-30T19:34:08.150725Z",
"retries": 0,
"proxy": 4,
"cert_will_expire_at": null,
"details_url": "https://app.honeybadger.io/projects/123321/sites/c42c4c0a-6e3d-4303-9769-549ed2a5818e"
},
"outage": {
"down_at": "2023-07-17T15:46:52.384701Z",
"up_at": "2023-07-17T15:51:56.063948Z",
"status": null,
"reason": "Connection timed out",
"headers": null,
"details_url": "https://app.honeybadger.io/projects/123321/sites/c42c4c0a-6e3d-4303-9769-549ed2a5818e"
}
}
```
# Redmine
> Connect Honeybadger to Redmine to automatically create issues from errors and track bug fixes in your project.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Redmine integration
[Section titled “1. Select the Redmine integration”](#1-select-the-redmine-integration)
 
### 2. Set the server & API key
[Section titled “2. Set the server & API key”](#2-set-the-server--api-key)
The server URL is the full URL of your server - including `https://`.
You can find your API key on your account page when logged into Redmine
### 3. Configure transitions (optional)
[Section titled “3. Configure transitions (optional)”](#3-configure-transitions-optional)
You can specify the ids of transitions to be run when issues are resolved and reopened.
### 4. Save
[Section titled “4. Save”](#4-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# Rootly
> Connect Honeybadger to Rootly to automatically trigger incidents from critical errors and application events, and streamline your response workflow.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Create a generic webhook alert source in Rootly.
[Section titled “1. Create a generic webhook alert source in Rootly.”](#1-create-a-generic-webhook-alert-source-in-rootly)
Navigate to the [Alert Sources](https://rootly.com/account/alerts?tab=alert-sources) page in your Rootly account. Locate the **Generic Webhook** alert source and click **Add Source**.
Set the Alert Source Name to “Honeybadger”.
### 2. Locate the authorization header - credentials
[Section titled “2. Locate the authorization header - credentials”](#2-locate-the-authorization-header---credentials)
Rootly will generate a webhook token. Copy this value.
### 3. In Honeybadger, locate the Rootly integration.
[Section titled “3. In Honeybadger, locate the Rootly integration.”](#3-in-honeybadger-locate-the-rootly-integration)
In the project settings, click on the **Integrations** tab where you’ll find the Rootly integration.
### 4. Fill in the required fields and save.
[Section titled “4. Fill in the required fields and save.”](#4-fill-in-the-required-fields-and-save)
Fill in the Webhook authorization token field with the generated token you copied from step 2. You may optionally specify a target type and target ID. Save the integration.
### 5. Test the integration.
[Section titled “5. Test the integration.”](#5-test-the-integration)
Click on the “Test this integration” button to send a test notification to your Rootly account. This will send a test payload to the Rootly webhook alert source.
### 6. Configure the Rootly alert source.
[Section titled “6. Configure the Rootly alert source.”](#6-configure-the-rootly-alert-source)
Now that Rootly has a sample payload, you can easily configure the alert. In your Rootly account, find the configuration settings for the Webhook alert source. Edit the Alert Content and set the following values:
* Alert Title: `{{ alert.data.title }}`
* Alert Description: `{{ alert.data.description }}`
* Link to Alert: `{{ alert.data.url }}`
# Shortcut
> Connect Honeybadger to Shortcut to automatically create stories from errors and track bug fixes in your project workflow.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
 
## Setup
[Section titled “Setup”](#setup)
### 1. Set the organization
[Section titled “1. Set the organization”](#1-set-the-organization)
This is the name of the organization that you created when you set up your account. You can find this immediately after the domain name in the URL: e.g., for the organization name is honeybadger.
### 2. Set the API token
[Section titled “2. Set the API token”](#2-set-the-api-token)
Your API Token can be found in the Shortcut UI by clicking on the gear icon for settings, choosing the Your Account link, then choosing the API Tokens link. Choose a name for your token (like Honeybadger) and click Generate Token. Copy the highlighted token, and paste that in the API Token field.
### 3. Fetch custom fields and workflow data
[Section titled “3. Fetch custom fields and workflow data”](#3-fetch-custom-fields-and-workflow-data)
Click the Fetch custom fields and workflow data button to make a request to the Shortcut API to get your list of teams, custom fields, and workflow states. This will populate and enable the remaining dropdowns on the form.
### 4. Choose the team, custom fields, and workflow states
[Section titled “4. Choose the team, custom fields, and workflow states”](#4-choose-the-team-custom-fields-and-workflow-states)
Each Honeybadger project is associated with one Shortcut team, and you can make that choice here. In addition, you may also specify custom field choices to apply to your stories. You can also choose which of your Shortcut workflow states will be chosen for stories when they are marked as resolved or unresolved. The stories will be updated to those states if you also enable the respective Error Events options.
## Creating stories from the UI
[Section titled “Creating stories from the UI”](#creating-stories-from-the-ui)
Users can create stories in Shortcut by clicking the Create Story button on the error detail page in the Honeybadger UI. By default, these stories will be created as the Shortcut user whose API Token is configured in the integration settings. Users can have stories associated with their own Shortcut account by getting an API Token as described previously and adding it to their [authentication settings](https://app.honeybadger.io/users/edit#authentication).
# Slack
> Connect Honeybadger to Slack to receive real-time application monitoring alerts and resolve issues directly from your team's channels.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the integration for Slack
[Section titled “1. Select the integration for Slack”](#1-select-the-integration-for-slack)
When you click on the link to add Slack to your project, you will be redirected to Slack to approve the connection to your Slack team. After you choose the channel to receive Honeybadger messages and click the Authorize button, you will be redirected back to Honeybadger to finish editing the optional channel settings.
### 2. Save
[Section titled “2. Save”](#2-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
## Interactive messages
[Section titled “Interactive messages”](#interactive-messages)
Messages about errors include a button to resolve or reopen the error:
The first time you click one of the buttons, you will be given a link that will allow you to connect your Slack account to your Honeybadger account. This connection only needs to be done once, and then you will be able to use the buttons and interact with the bot.
## Using the bot
[Section titled “Using the bot”](#using-the-bot)
Once you have installed the Honeybadger app for Slack, you will have a Honeybadger bot available to your Slack team. You can message the bot directly or you can invite it to join a channel and address it… either way, it understands the following commands:
| Command | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------- |
| **help** | Get help :) |
| **show project *\*** | Returns a list of faults that occurred recently in the *Project Name* project. |
| **show fault *\*** | See details about the requested fault. The fault number can be found in the Honeybadger UI. |
| **resolve fault *\*** | Mark the specified fault as resolved. |
| **reopen fault *\*** | Mark the specified fault as reopened. |
# Splunk On-Call
> Connect Honeybadger to Splunk On-Call to route critical errors and application monitoring alerts through your incident response and on-call workflow.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Splunk On-Call integration
[Section titled “1. Select the Splunk On-Call integration”](#1-select-the-splunk-on-call-integration)
 
### 2. Set the API key
[Section titled “2. Set the API key”](#2-set-the-api-key)
You can generate a Splunk On-Call API key on the Splunk On-Call integrations page.
### 3. Set the routing key (optional)
[Section titled “3. Set the routing key (optional)”](#3-set-the-routing-key-optional)
If you like, you can specify an arbitrary routing key for use by Splunk On-Call.
### 4. Save
[Section titled “4. Save”](#4-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# Sprintly
> Connect Honeybadger to Sprintly to automatically create defects from errors and track bug fixes in your workflow.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Sprintly integration
[Section titled “1. Select the Sprintly integration”](#1-select-the-sprintly-integration)
 
### 2. Set the email & API key
[Section titled “2. Set the email & API key”](#2-set-the-email--api-key)
You can get your Sprintly API key by logging into Sprintly and going to your Profile page. The key is at the bottom.
### 3. Set the product ID
[Section titled “3. Set the product ID”](#3-set-the-product-id)
You can find your product’s id by examining the URL. If your product’s url is `sprint.ly/product/777` then the product id is “777”.
### 4. Save
[Section titled “4. Save”](#4-save)
That’s it! You can test the integration by clicking “Test”. Otherwise, just save it and you’re ready to go.
# Trello
> Connect Honeybadger to Trello to automatically create cards from errors and track bug fixes on your Trello boards.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Trello integration
[Section titled “1. Select the Trello integration”](#1-select-the-trello-integration)
 
### 2. Connect your Trello account
[Section titled “2. Connect your Trello account”](#2-connect-your-trello-account)
Just click the button to connect to trello via OAuth.
### 3. Select the board and list
[Section titled “3. Select the board and list”](#3-select-the-board-and-list)
These two dropdowns will be populated when you connect your account.
### 4. Save
[Section titled “4. Save”](#4-save)
That’s it! Hit save and you’re good to go.
# Webhook
> Configure custom webhooks to send Honeybadger error notifications and events to any third-party service or API.
Honeybadger sends webhooks when certain events occur in your Honeybadger projects. Each event type has a specific payload structure with relevant data about the event.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. Select the Webhook integration
[Section titled “1. Select the Webhook integration”](#1-select-the-webhook-integration)
 
### 2. Set the URL for your webhook
[Section titled “2. Set the URL for your webhook”](#2-set-the-url-for-your-webhook)
We’ll post notifications to this URL. Make sure to include the protocol: e.g., `https://mysite.com/hook`.
Make sure you have a service running that can accept POST requests, and hopefully do something interesting with JSON payloads like this one:
```plaintext
{
"event":"occurred",
"message":"[Crywolf/test] RuntimeError - oops",
"fault":{
"id":3151009,
"project_id":1717,
"klass":"RuntimeError",
"component":null,
"action":null,
"environment":"development",
"resolved":true,
"ignored":false,
"created_at":"2014-01-08T18:55:48Z",
"comments_count":1,
"message":"oops",
"notices_count":9,
"last_notice_at":"2014-01-08T19:02:21Z"
}
}
```
See [Event Payloads](#payload-structure) for all available events and their structure.
### 3. Save
[Section titled “3. Save”](#3-save)
That’s it! Hit save and you’re good to go.
## Payload structure
[Section titled “Payload structure”](#payload-structure)
Each event payload is sent as a JSON object with the following properties:
* `event` - The type of event (e.g., `occurred`, `resolved`, `deployed`)
* `message` - A human-readable description of the event
* Additional event-specific data (varies by event type)
## Event payloads
[Section titled “Event payloads”](#event-payloads)
The following events are supported by the Webhook integration:
### [`assigned`](/guides/integrations/payloads/assigned/)
[Section titled “assigned”](#assigned)
Sent when an error is assigned to a user.
**Top-level properties:** `event`, `message`, `actor`, `fault`, `assignee`
### [`cert_will_expire`](/guides/integrations/payloads/cert_will_expire/)
[Section titled “cert\_will\_expire”](#cert_will_expire)
Sent when an SSL certificate is about to expire.
**Top-level properties:** `event`, `message`, `project`, `site`
### [`check_in_missing`](/guides/integrations/payloads/check_in_missing/)
[Section titled “check\_in\_missing”](#check_in_missing)
Sent when an expected check-in is missing.
**Top-level properties:** `event`, `message`, `project`, `check_in`
### [`check_in_reporting`](/guides/integrations/payloads/check_in_reporting/)
[Section titled “check\_in\_reporting”](#check_in_reporting)
Sent when a check-in reports successfully.
**Top-level properties:** `event`, `message`, `project`, `check_in`
### [`commented`](/guides/integrations/payloads/commented/)
[Section titled “commented”](#commented)
Sent when a comment is added to an error.
**Top-level properties:** `event`, `message`, `actor`, `fault`, `comment`
### [`deployed`](/guides/integrations/payloads/deployed/)
[Section titled “deployed”](#deployed)
Sent when a deployment is recorded.
**Top-level properties:** `event`, `message`, `project`, `deploy`
### [`down`](/guides/integrations/payloads/down/)
[Section titled “down”](#down)
Sent when an uptime check fails.
**Top-level properties:** `event`, `message`, `project`, `site`, `outage`
### [`occurred`](/guides/integrations/payloads/occurred/)
[Section titled “occurred”](#occurred)
Sent when an error occurs.
**Top-level properties:** `event`, `message`, `project`, `fault`, `notice`
### [`rate_exceeded`](/guides/integrations/payloads/rate_exceeded/)
[Section titled “rate\_exceeded”](#rate_exceeded)
Sent when error rate threshold is exceeded.
**Top-level properties:** `event`, `message`, `project`, `fault`
### [`resolved`](/guides/integrations/payloads/resolved/)
[Section titled “resolved”](#resolved)
Sent when an error is marked as resolved.
**Top-level properties:** `event`, `message`, `project`, `fault`
### [`unresolved`](/guides/integrations/payloads/unresolved/)
[Section titled “unresolved”](#unresolved)
Sent when a resolved error occurs again.
**Top-level properties:** `event`, `message`, `project`, `fault`
### [`up`](/guides/integrations/payloads/up/)
[Section titled “up”](#up)
Sent when an uptime check succeeds after being down.
**Top-level properties:** `event`, `message`, `project`, `site`, `outage`
# Zulip
> Connect Honeybadger to Zulip to receive real-time application monitoring alerts directly in your team's streams.
Users with administrative privileges can find this integration below the list of personal alert integrations on the Alerts & Integrations tab of the Project Settings page.
## Setup
[Section titled “Setup”](#setup)
### 1. In Zulip, create a new incoming webhook bot.
[Section titled “1. In Zulip, create a new incoming webhook bot.”](#1-in-zulip-create-a-new-incoming-webhook-bot)
You’ll need to create a new Incoming Webhook Bot in Zulip. This is done by going to the **Settings** page of your Zulip organization and selecting **Bots** from the left-hand menu.
### 2. In Honeybadger, locate the Zulip integration.
[Section titled “2. In Honeybadger, locate the Zulip integration.”](#2-in-honeybadger-locate-the-zulip-integration)
In the project settings, click on the **Integrations** tab where you’ll find the Zulip integration.
### 3. Fill in the required fields and save.
[Section titled “3. Fill in the required fields and save.”](#3-fill-in-the-required-fields-and-save)
Fill in the required fields which you generated in step 1. Configure which notifications you wish to receive and then save.
You can also click on the “Test this integration” button to send a test notification to your Zulip stream. This is a great way to ensure that everything is set up correctly before you start receiving real notifications.
# Projects
> Projects contain your errors, check-ins & uptime.
Almost everything in Honeybadger is scoped to a project. We have some powerful configuration features to help you manage your errors.
At the top of the project page, there are tabs for the windows containing all aspects of the project.
## General project settings
[Section titled “General project settings”](#general-project-settings)
The General tab of the project settings page includes changing the name of the project and how long error occurrence data is retained. You can also enable or disable notifications by project environment. Environments are added to this list as errors are reported to our API from those environments.
The *Resolve errors on deploy* setting automatically marks all errors “resolved” when you [report a deployment](/api/reporting-deployments/), causing new alerts to be sent for any errors that re-occur. When turned off, you can resolve individual errors on the next deploy from the [actions area](/guides/errors/#resolve-on-deploy) on the error page.
Below that is the project delete button - deleting a project cannot be undone!
## Insights
[Section titled “Insights”](#insights)
The Insights tab shows your current Insights data limits and has a link to the Insights stats page, which can also be found by navigating to the API stats for a project.
To read more about configuring Insights, check out the [Insights](/guides/insights) documentation page.
## Users
[Section titled “Users”](#users)
From the Users settings tab, you can see and manage which users have access to the project and what teams are assigned to the project. This page also lets you see the members of each team currently assigned to the project.
Users can have admin privileges for a project if you add them individually while specifying the admin permission or if they have admin privileges on a team that is assigned to the project. Users having admin privileges at the account level (managed via the Users tab of the Account Settings page) will also have admin rights on the project.
To read more about user management, check out the [User Management](/guides/user-management) documentation page.
## Alerts & integrations
[Section titled “Alerts & integrations”](#alerts--integrations)
The Alerts and Integrations tab allows you to edit the notifications you receive as a user for the project. If you have admin privileges for the project, you can also manage the integrations (such as GitHub, Slack, etc.) that are connected to the project.
To read more about managing integrations, check out the [Integrations](/guides/integrations) documentation page.
## API keys
[Section titled “API keys”](#api-keys)
Project API keys grant access to our reporting APIs. The list of reporting endpoints is in our [API docs](/api/). If an API key is leaked or misused, you can rotate your key by adding a new key and removing the old one.
Note
Project API keys don’t grant access to our REST API. You will need to use your [personal token](/api/getting-started/#authentication) for that.
## Project actions
[Section titled “Project actions”](#project-actions)
Project Actions let you customize your errors as we receive them. Through actions, you can automatically:
* Assign errors to yourself or another team member
* Add tags
* Pause notifications
* Share errors publicly
One exciting usage example for Project Actions is assigning errors to specific code owners.
For example, Ben takes care of most of the billing code here at Honeybadger. It would make sense that he should be assigned any errors related to billing. Here is a simple setup to route `StripeController` errors to Ben:
You can run all your incoming errors through the actions, or you can use the query box to constrain which errors have actions applied to them. The query box works identically to the search box when navigating on the error tab.
## Source maps
[Section titled “Source maps”](#source-maps)
Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. The tab for Source Maps in Project Settings allows you to choose whether or not to download your source maps. It also contains a list of the currently stored source maps and a debugging tool that you can use to diagnose problems with source map processing.
For more on source maps, check out the [Source Maps](/lib/javascript/guides/using-source-maps/) documentation page.
## Advanced settings
[Section titled “Advanced settings”](#advanced-settings)
Here you can manage some settings that modify the Honeybadger UI and the processing of your errors.
The User URL field can be used to add a link in the Honeybadger UI to a URL you specify (such as an internal admin tool) with the user ID populated from the `context.user_id` data in your error report. When this field is populated and an error notification includes the user\_id data, a button labeled “View user” is added to the error detail page that you can use to click through to the User URL:
If your context includes the user ID in a field other than `context.user_id`, you can use the User search field setting to specify where in your payload the user ID exists. You can also use this to override what field should be used as your user ID — e.g., you could specify `context.user_email` if you’d prefer to use email addresses rather than IDs. Regardless of the field you use, that field’s value will be stored as the **user** in the search index and displayed in the notice timeline list and elsewhere in the UI.
The throttle field allows you to set a limit for the number of errors the project can receive per minute. This can be useful for preventing a noisy project (like one dedicated to a QA or staging environment) from consuming too much of your quota.
### Public error pages
[Section titled “Public error pages”](#public-error-pages)
You can make an error public by clicking “Share URL” in the [actions area](/guides/errors/#error-actions) of the error you want to share. We provide you with a unique URL to give to collaborators. This is great but can be cumbersome when sharing multiple errors. Public Error Pages are a place where collaborators can view shared errors.
Once you enable the Public Error Page (**Project Settings > Advanced > Enable public dashboard**), collaborators can find shared errors in a similar view as the error listing page (with some restrictions). This can be especially useful if you pair this feature with [Project Actions](#project-actions).
## One language per project
[Section titled “One language per project”](#one-language-per-project)
We often get asked if users can have multiple programming languages in a project. While it is technically possible, we recommend that you create a separate project for each application or repository.
# Reports
> Viewing and understanding reports.
The Reports page of a project includes summary charts of error data grouped by location, class, day, and affected user, as well as a summary of the project’s uptime checks.
Clicking on a bar in one of the bar charts will take you to a search for errors matching the selected location, class, or user.
# Status pages
> Give users insight into your system status.
Your Honeybadger account comes with customizable status pages. Give your users insights into the working state of your system by connecting uptime checks or providing updates during problems via incidents.
Here’s a [live example](https://uptime.honeybadger.io/) of our Honeybadger status page.
Tip
You can find your status pages and create a new one [here](https://app.honeybadger.io/status_pages).
## Customizing your status page
[Section titled “Customizing your status page”](#customizing-your-status-page)
You can customize your status page with your company logo and favicon from *Status Pages* → *Your Status Page* → *Edit*. If you upload a dark logo variant, we’ll use that version with our built-in dark mode theme.
For more control over the look and feel of your status page, see the “Custom CSS” option under *Customization* at the bottom of the settings form.
## Adding a custom domain
[Section titled “Adding a custom domain”](#adding-a-custom-domain)
To add a custom domain, enter the domain (without the http(s)://) when editing your status page. To verify your domain, add a CNAME DNS record with a value of **status.hbuptime.com**. For example, if your domain is status.example.com, then you should add the following CNAME through your DNS provider (Google Domains, Amazon Route 53, GoDaddy, etc.):
| Record type | Label/Host field | Time To Live (TTL) | Destination/value |
| ----------- | ------------------ | --------------------------- | ------------------- |
| CNAME | status.example.com | default is fine (i.e. 3600) | status.hbuptime.com |
**Once the record has been created, click the “Verify” button under your status page back in Honeybadger:**
Now you can visit your domain in a browser. We automatically generate SSL certificates; it should be ready to go on the first visit, but in some cases you may need to refresh a few times. If you have trouble, don’t hesitate to [get in touch](https://www.honeybadger.io/contact/).
## Uptime checks
[Section titled “Uptime checks”](#uptime-checks)
Connect any currently running uptime checks to your status page if you’d like to share your uptime status with the world. Status pages may include uptime checks across all of the projects in your account.
### Connecting checks
[Section titled “Connecting checks”](#connecting-checks)
While editing your status page, toggle which uptime checks you would like included with your status page.
Give each uptime check an optional display name if you want to customize the name displayed publicly.
That’s it! We will show each uptime check’s current status and history on your public status page.
## Incidents
[Section titled “Incidents”](#incidents)
An incident is an effective way to communicate system issues to your users. It can also inform your users of upcoming planned maintenance or downtime.
Conceptually, an incident is a container for timestamped updates that describe the context surrounding a problem affecting your system. An incident can be as simple as a single update that explains some minor downtime, or it can span multiple days with many updates, each representing the changing severity and status of the incident.
### Creating incidents
[Section titled “Creating incidents”](#creating-incidents)
We provide three scenarios when creating incidents: `Current`, `Scheduled Maintenance`, and `Retroactive`:
#### Current
[Section titled “Current”](#current)
Current incidents start with one update and are typically open after creation (meaning you would not select “Resolved” as the starting status.)
#### Scheduled maintenance
[Section titled “Scheduled maintenance”](#scheduled-maintenance)
Scheduled Maintenance incidents are notable because you can queue updates for later posting.
Note
This is the only place you can submit an update to post in the future.
You can create up to three future updates, which we will post at the supplied `Start Time`. Typically you will send out a `Maintenance scheduled` update that describes the type of maintenance you will perform and when. After that, we have both `In Maintenance` and `Maintenence complete` statuses that you can queue up as individual updates. It’s up to you how much lead time to give your users, based on how you stagger the timing of each update.
If you complete your maintenance sooner than expected, you can always edit the queued update and use the “send now?” button to post the update immediately.
#### Retroactive
[Section titled “Retroactive”](#retroactive)
Retroactive incidents give you a tool to create multiple incident updates in one operation. You can create a closed incident from months ago or an open incident that started minutes ago. If you don’t end with a [closing update](#open-and-closed-incidents), the incident will be considered open.
A retroactive incident also allows you to craft a single [announcement](#announcing-updates) message to accompany your incident updates. This way, you have the option to summarize the incident yet keep each event as separate updates.
Note
You can not announce each update individually via a retroactive incident.
### Posting an update
[Section titled “Posting an update”](#posting-an-update)
When you are ready to inform your users with an update to your incident, click the button in the incident header and fill in your update inline.
### Severity and status
[Section titled “Severity and status”](#severity-and-status)
When you create an incident or post a new update, you choose a `status` and `severity`. `status` describes where you are in the process of resolving your incident and `severity` describes how your system is currently affected by the incident.
Scheduled maintenance incidents have a special set of statuses. You can, however, post an update during scheduled maintenance with an incident status, say if things go awry.
### Open and closed incidents
[Section titled “Open and closed incidents”](#open-and-closed-incidents)
Note
An incident update with a `Resolved` or `Maintenance complete` status will close the containing incident.
An incident, when created, is considered “open.” It will be prominently displayed on your internal status page and made visible as an “active incident” on your public status page. When you provide an update containing a status that closes the incident, it will be “closed” and moved to the historical list of closed incidents.
Even if you have closed an incident with an update, you can always re-open it by posting an update with a new status. While this is possible and useful if something comes up right after closing an incident, we recommend you open a new incident if a significant amount of time has passed.
### Announcing updates
[Section titled “Announcing updates”](#announcing-updates)
We provide the option to connect your status page to a Twitter account (while editing the status page). Linking your Twitter enables us to announce your incident updates to the world. Once connected, a new “Announce” option will be available while crafting any incident updates.
## Password protection
[Section titled “Password protection”](#password-protection)
Honeybadger status pages can be configured to require a username and password before they can be viewed. This is useful for private or internal status pages that only those in your company should be able to view.
To enable password protection, edit your status page and check the “Require a username and password” checkbox. Set your desired username and password in the fields below. If you are using a password manager, be sure you don’t overwrite your login information for the Honeybadger app itself.
## Embedding status updates
[Section titled “Embedding status updates”](#embedding-status-updates)
Incident management often requires communicating outages with your customers. With the status page embed feature, you can keep your users up to date when they visit your website.
### Setup and usage
[Section titled “Setup and usage”](#setup-and-usage)
Each of your status pages will have their own unique installation instructions, go to your status page info page, you’ll find the link towards the bottom of the page.
Copy the snippet of code and paste it anywhere in the HTML of your site.
Like the status page, when you start an incident, the embed feature will always display the latest update to your users.
### Customization
[Section titled “Customization”](#customization)
The embed pop-up can be customized to better fit the look and feel of your site. Use the customization tool to adjust how you want it too look. When you are ready, copy and paste the HTML snippet onto your site. Here are some of the options you can customize:
* **Position** — Change where the popup will appear: bottom left (default), bottom right, top left, or top right.
* **Font color** — Set the font color of the text. Any valid CSS font color value can be used.
* **Background color** — Set the background color of the pop up. Any valid CSS color value can be used.
* **Close button behavior** — By default, the pop up will always show on page load. You can enable the persist feature so that when your visitor closes the pop-up, a browser cookie will be set so that it doesn’t pop up again until your next update. The cookie gets set to expire upon browser or session close.
### Displaying scheduled maintenance
[Section titled “Displaying scheduled maintenance”](#displaying-scheduled-maintenance)
The status page embed works great with the schedule maintenance feature. Create your scheduled maintenance messages as noted above. Once the “Start Time” for your messages have passed, your visitors will see the latest update on your site via the embed pop up.
### Displaying non-incident messages
[Section titled “Displaying non-incident messages”](#displaying-non-incident-messages)
If you have both an ongoing incident and a non-incident message enabled at the same time, the incident update messages will take precendence over the non-incident message.
### Password protected status pages
[Section titled “Password protected status pages”](#password-protected-status-pages)
If your account has the password protected feature and you have enabled the feature for your status page, the embed feature will become disabled. To use the embed feature, you’ll need to disable the password protection feature.
## SEO and analytics
[Section titled “SEO and analytics”](#seo-and-analytics)
### Search engine indexing
[Section titled “Search engine indexing”](#search-engine-indexing)
By default, search engines can find and index your status pages—meaning they can end up in search results. You can turn off this behavior by checking the “Do not allow search engines to index my search page” checkbox. Search engines may take time to update their results if your status page is already indexed.
If you want added protection and privacy, look at our [Password Protection](#password-protection) feature to prevent unwanted access to your Status Page.
### Google Analytics
[Section titled “Google Analytics”](#google-analytics)
You can also add your Google Analytics ID to enable Google Analytics tracking for your Status Page.
# Uptime monitoring
> Get notified when your API is unresponsive.
Your Honeybadger account comes with uptime monitoring. Our geographically distributed network of friendly robots will ping your site every few minutes. If a check fails, we’ll let you know.
You can set up fairly sophisticated checks based on the HTTP status code, or the response body.
## Setup
[Section titled “Setup”](#setup)
Note
Enabling bot protection on Cloudflare-hosted websites may prevent uptime checks from working.
When creating an uptime check, just tell us what URL you want monitored. You can choose what counts as a success response from these options:
* **Success** - notifies you that your site is down when your server responds with a non-20x status code. When in doubt, this is the one you probably want.
* **Exact** - prompts you to enter an HTTP status code. If you entered 302 it would ensure that the server responds with a 302 status code.
* **Response body includes string** - prompts you for a string (i.e. “Error”) and notifies you when the response body matches.
* **Response body excludes string** - prompts you for a string and notifies you if the response body does *not* match.
* **Response body matches JMESPath expression** - allows you to specify a [JMESPath](https://jmespath.org) expression that is evaluated against the JSON returned in the response. For example, an expression like ``queue.depth < `10` ``will evaluate to true for a JSON response like `{"queue":{"depth":2}}`.
You have the option to specify response header checks. For example, you can check if the response header `Content-Type` contains `application/json`, or whether the `location` header redirects to the correct URL. All response header checks must evaluate to true for the check to be considered successful, and the check values are case-sensitive.
You can also choose to send custom request headers or a custom request body, check the validity of the SSL certificate, and select which locations should be used for monitoring.
You can optionally give each of your uptime checks a custom name, which will be the default label for when included on a Status Page.
Hit “save” and you’re done!
### Timeouts
[Section titled “Timeouts”](#timeouts)
Each uptime check has a timeout of 30 seconds by default. If your URL does not respond within this time, it will be marked as failed for that location.
Business and Enterprise customers can customize the timeout setting for their uptime checks. The timeout field allows you to specify how long the uptime check will wait for a response before reporting the site as down. The default is 30 seconds and the maximum is 120 seconds.
## Outage notifications
[Section titled “Outage notifications”](#outage-notifications)
When your site goes down, we’ll notify you with all the details about what went wrong, including how your check failed. For example, you will see receive a notification like this one when the uptime check expected a successful status code but returned a 500.
By default, the notification is sent after half of the locations report a failing check. This means that if you are using five locations, there would need to be three failures in a row before you would receive an alert. You can override this default by specifying a value for the Outage Threshold field.
## Outage details
[Section titled “Outage details”](#outage-details)
When you get a notification that a check has failed, we’ll also link you to a web page with details. This detailed view can be accessed by clicking the “View” link for any particular uptime check in the UI.
At the top, the average load time over the past week will be displayed, as well as the uptime check itself.
Scrolling down, you can see the uptime on a percentage-monthly basis.
Finally, the most recent checks will be displayed, and below that, a list of the uptime check’s most recent outages.
## SSL certificate warnings
[Section titled “SSL certificate warnings”](#ssl-certificate-warnings)
We’ll send you a daily warning when your SSL certificates are about to expire. To enable warnings, check the “Check SSL certificate” option when editing your uptime check:
You should also check the “When my SSL certificates are about to expire” event when editing [alerts and integrations](/guides/integrations/):
## Status page integration
[Section titled “Status page integration”](#status-page-integration)
Check out our [Status pages](/guides/status-pages/#uptime-checks) feature for presenting your uptime checks to your users.
# User management
> User membership for projects, teams, and accounts.
Honeybadger is much more fun when you bring some friends to the party. The easiest way to do so is to assign projects to a team, then [invite users to join your team](#how-to-invite-a-team-user).
## What can users do?
[Section titled “What can users do?”](#what-can-users-do)
Our paid plans let you invite your co-workers to collaborate on your projects. The table below gives examples of what different kinds of users can do.
| | Account Owner | Admin | Member |
| --------------------------------------------------------- | :-----------: | :---: | :----: |
| Work with errors, uptime, check-ins, etc. | ✅ | ✅ | ✅ |
| Configure personal alerts, like email | ✅ | ✅ | ✅ |
| Configure chat, issue tracker and repository integrations | ✅ | ✅ | |
| Invite and manage users | ✅ | ✅ | |
| Assign projects to teams | ✅ | ✅ | |
| Manage account billing | ✅ | ✅ | |
| Transfer projects to another account | ✅ | | |
| Cancel subscription and delete account | ✅ | | |
## Inviting users
[Section titled “Inviting users”](#inviting-users)
You have three options when inviting users. You can invite them…
* **To a project:** Inviting a user directly to your project is the easiest route, as long as you only have one or two projects.
* **To a team, which has been assigned the project:** This is the best route if you have more than a handful of users and projects.
* **To an account:** Users are automatically added to an account when added to a project or team, but adding users to an account is the way to go when you want those users to have the Owner role.
### How to invite a project user
[Section titled “How to invite a project user”](#how-to-invite-a-project-user)
To invite a project user, go to the “Settings” tab when viewing a project and click on “Users” in the sidebar. Use the form to enter their email address and choose their permissions for the project.
Your invitee will get an email with instructions on how to proceed.
### How to invite a team user
[Section titled “How to invite a team user”](#how-to-invite-a-team-user)
View the Users tab on the team detail page to invite a team user. You’ll see a form where you can enter their email address and choose their permissions for the team.
If you’re not sure which team is associated with a project, you can see the list of teams that are connected to a project on the Users tab of the Project Settings page.
### How to invite an account user
[Section titled “How to invite an account user”](#how-to-invite-an-account-user)
Go to the Users tab of the [account settings](/guides/accounts/#account-settings) page to add a new user to your account:
When adding a user, you can choose which role the user should have (Owner, Admin, or Member), and which teams that user will be able to access. As with project and team invitations, users will receive an email with a link to join the account.
## SAML SSO
[Section titled “SAML SSO”](#saml-sso)
You can optionally provide single-sign on (SSO) to your team members via one of our supported SSO providers: Google Apps for Work, Okta, or OneLogin. Provider-specific configuration instructions are found on the Authentication tab in [account settings](/guides/accounts/#account-settings). Generally speaking, the configuration process goes like this:
1. Create a custom SAML app in your provider’s admin dashboard.
2. Download the IdP metadata from your provider and add it to your Honeybadger SAML configuration.
3. Configure the custom SAML app with the information provided on the SAML configuration page in the app.
After those steps are completed, your team members can log in through your SSO provider’s dashboard, or they can enter the SSO name provided in the SAML configuration when signing in to Honeybadger.
## Restricted authentication
[Section titled “Restricted authentication”](#restricted-authentication)
We provide more control over your users’ login sources when enabling “Restricted Authentication” for your account. You can manage restricted authentication from the Authentication tab in [account settings](/guides/accounts/#account-settings). A common use case is to require users to use SSO instead of being able to log in with a password.
#### Auth sources
[Section titled “Auth sources”](#auth-sources)
You can select which authentication sources are allowed to access your account.
If you require only SAML login, you can disable all other available sources. When a user accesses your account via password, we will redirect them to your custom sign-in page with a link to your SAML provider.
#### Session duration
[Section titled “Session duration”](#session-duration)
You also have control of your users’ session duration, per auth source. For example, daily reauthentication with your SAML provider can be achieved by updating the “Session expire duration” for your SAML auth source.
#### Custom sign-in page
[Section titled “Custom sign-in page”](#custom-sign-in-page)
Restricted auth accounts have access to a custom sign-in page. We will only show your active auth sources as sign-in options.
## Multi-factor authentication
[Section titled “Multi-factor authentication”](#multi-factor-authentication)
Honeybadger supports multi-factor authentication (also known as two-factor authentication, 2FA, or MFA) via Google Authenticator, Authy, and similar 2FA providers. Account owners can require multi-factor authentication for all users from the Authentication tab in [account settings](/guides/accounts/#account-settings).
When enabled, we’ll notify the users who need to set it up via email, and prompt them to enable it on their next login.
# User settings
> Your personal preferences.
Note
For information about inviting users to your projects or teams, check out our [User Management Guide](/guides/user-management/). This guide is meant to help people configure their personal preferences when they’ve already joined a project.
User accounts in Honeybadger are very similar to those in GitHub. Each user is his or her own person. While project admins can configure project-level integrations like Slack, each individual user has complete control over their personal alerts and other user settings on the [User Settings](https://app.honeybadger.io/users/edit) page.
Here are some examples of “personal settings”:
* Name and connected email
* Localized date and time preferences
* Connection to GitHub and other 3rd-party accounts
* Daily and weekly digest email settings for all projects
* Local editor selection for links displayed on backtraces
The user settings page is also where you can:
* Add or remove connections for mobile devices
* Leave projects where you are not the sole owner
* Set up local editors for your projects
* Cancel the user account
## Configuring personal alerts
[Section titled “Configuring personal alerts”](#configuring-personal-alerts)
Alerts sent via email, SMS and our mobile apps are considered “personal” integrations. You and only you control which personal integrations are enabled and which events they receive. As you log in to the mobile apps on new devices, they are added to the personal integrations list for all the projects you can access.
You have a separate set of alert preferences for each project you work with. One way to edit them is by going to each project’s settings page and clicking on the “Alerts” tab. There’s a section for “Personal Alerts.”
While the account owner can see what notifications other users in the accounts have enabled, they cannot customize them.
### Mobile device connections
[Section titled “Mobile device connections”](#mobile-device-connections)
From the User Settings page, you can customize your connected mobile devices via the “Mobile Devices” tab on the sidebar. Here you will find links to download the Honeybadger app so you can connect your devices to receive important alerts on the go.
### SMS phone numbers
[Section titled “SMS phone numbers”](#sms-phone-numbers)
Honeybadger sends SMS alerts from a pool of phone numbers. To ensure that you receive alerts, download our vCard and add it to your contacts on your desktop or smartphone:
[Download Honeybadger Outgoing Numbers vCard](/Honeybadger%20Outgoing%20Numbers.vcf)
In iOS you can optionally [configure a custom text tone and enable the *Emergency Bypass* option](https://support.apple.com/guide/iphone/allow-or-silence-notifications-for-a-focus-iph21d43af5b/17.0/ios/17.0#iph68077cc0d) for the Honeybadger contact. Android has a [similar option](https://support.google.com/android/thread/219866813?hl=en\&msgid=220251463). This will ensure that you receive alerts even when your phone is in *Do Not Disturb* mode.
Our current outgoing numbers (from the [vCard](/Honeybadger%20Outgoing%20Numbers.vcf)) are:
* (206) 535-1618
* (206) 203-4914
* (206) 203-6150
* (206) 203-8212
* (206) 203-1222
* (206) 203-5571
Please note that these numbers are subject to change. We recommend checking this page periodically for updates.
*Last updated: 2024-03-20*
### Configuring alerts across multiple projects
[Section titled “Configuring alerts across multiple projects”](#configuring-alerts-across-multiple-projects)
If you work with lots of projects, it can be a hassle to visit each settings page. That’s why we’ve added a single page UI where you can enable/disable all personal notifications in one place. This is available on the [Notifications tab](https://app.honeybadger.io/users/edit#notifications) of the [User Settings](https://app.honeybadger.io/users/edit) page.
To access the detailed project notification options, click the project links displayed on this page to customize what kind of alerts you can receive.
## Connected apps
[Section titled “Connected apps”](#connected-apps)
The Connected Apps tab allows you to configure personal connections to Slack and project management tools such as GitHub. These connections enable Honeybadger to create and manage issues as your user account on the platforms you connect.
### GitHub sign in
[Section titled “GitHub sign in”](#github-sign-in)
To be able to sign in with GitHub, you’ll need to connect your Honeybadger and GitHub accounts. To do this:
1. Log in to Honeybadger
2. Go to the [User Settings](https://app.honeybadger.io/users/edit) page
3. Click on “Connect your GitHub Account”
4. Tell GitHub to allow Honeybadger to use your account for sign in
> Note that this only sets up GitHub login. It doesn’t connect your projects to GitHub. You’ll have to do that in project settings.
## Cancel user
[Section titled “Cancel user”](#cancel-user)
You are immediately removed from all accounts, teams, and projects when you cancel your user account. Your user info will be deleted, and all accounts for which you are the only owner will also be immediately deleted. This action cannot be undone.
# Honeybadger client libraries
> Official Honeybadger client libraries for error tracking and application monitoring across all major platforms.
[ Ruby ](/lib/ruby/)
[ JavaScript ](/lib/javascript/)
[ PHP ](/lib/php/)
[ Python ](/lib/python/)
[ Elixir ](/lib/elixir/)
[ Java ](/lib/java/)
[ Go ](/lib/go/)
[ Cocoa ](/lib/cocoa/)
[ .NET/C# ](/lib/dotnet/)
[ Crystal ](/lib/crystal/)
[ Clojure ](/lib/clojure/)
[ Other platforms ](/lib/other/)
# Honeybadger for Clojure
> Honeybadger monitors your Clojure applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** \~5 minutes
Hi there! You’ve found Honeybadger’s guide to **Clojure exception and error tracking**. Once installed, Honeybadger will report errors in your Clojure application.
[Source Code](https://github.com/camdez/honeybadger)
## Getting started
[Section titled “Getting started”](#getting-started)
The library only has one public endpoint: `notify`. You can pass `notify` a `String`, or anything which inherits from [`Throwable`](https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html) (e.g. [`Exception`](https://docs.oracle.com/javase/7/docs/api/java/lang/Exception.html)):
```clj
(require '[honeybadger.core :as hb])
(def hb-config
{:api-key "PROJECT_API_KEY"
:env "development"})
(hb/notify hb-config "Something happened")
(hb/notify hb-config (Exception. "Things ain't good"))
(hb/notify hb-config (ex-info "99 problems" {:yet "Clojure isn't one of them"}))
```
* `:api-key` is the only required entry in the configuration map.
* `notify` returns a [Manifold deferred](https://github.com/ztellman/manifold#deferreds) wrapping the ID (`String`) of the newly-created Honeybadger fault—or `nil` if a filter (see below) caused the data not to be sent to Honeybadger. Because a deferred is used, the call returns immediately, not blocking your (e.g., web server) thread. This comes with the typical [Clojure caveats about exceptions thrown on background threads](http://stuartsierra.com/2015/05/27/clojure-uncaught-exceptions), so I strongly recommend dereferencing these calls on the main thread unless / until you have an async error handling plan in place.
* Honeybadger fault IDs can be handy—log them, pass them to other systems, or display them to your users as incident identifiers they can send to your support team. [Manifold](https://github.com/ztellman/manifold) offers ways of receiving this data asynchronously, but for a simple (synchronous) approach, simply [`deref`](https://clojuredocs.org/clojure.core/deref) the return value:
```clj
(try
("kaboom") ; Strings aren't functions
(catch Exception e
(let [hb-id @(hb/notify hb-config e)]
(println (str "Exception! Learn more here:\n"
"https://www.honeybadger.io/notice/" hb-id)))))
;; (Output)
;; Exception! Learn more here:
;; https://www.honeybadger.io/notice/12345678-669c-4178-b456-be3d0feb1551
```
### Metadata
[Section titled “Metadata”](#metadata)
The optional third parameter to `notify` can be used to pass all manner of additional Honeybadger metadata. The following example shows all possible metadata values:
```clj
(hb/notify hb-config
(Exception. "Vapor Lock")
{:tags [:serious :business]
:component "robot-brain" ; ~= a Rails controller
:action "think" ; ~= a Rails action
:context {:name "Winston"
:power 42
:grease 12}
:request {:method :get
:url "http://camdez.com"
:params {"robot" "true"}
:session {"session-id" "d34dc0d3"}}})
```
All metadata is optional, so pick and choose what is useful for your project. Keys and tags can be strings or keywords. `:context` and `:request` support nested values. If you’re working with Ring, use the corresponding [ring-honeybadger](https://github.com/camdez/ring-honeybadger) library and the `:request` metadata will be populated for you.
### Filters
[Section titled “Filters”](#filters)
For more advanced behavior, the library allows us to provide a sequence of functions which will be invoked with all key details (viz. exception + configuration) prior to reporting to Honeybadger. These functions can be used to transform the data in arbitrary ways, or they can return `nil`, halting the function chain and indicating that nothing should be reported.
For maximum flexibility we can provide a custom function, but we can handle many common cases with the preexisting filters / filter combinators in `honeybadger.filter`:
```clj
(require '[honeybadger.core :as hb]
'[honeybadger.filter :as hbf])
(def hb-config
{:api-key "PROJECT_API_KEY"
:env "development"
:filters [(hbf/only (hbf/env? :production))
(hbf/except (hbf/instance? ArithmeticException))
(hbf/obscure-params [[:config :password]])]})
(hb/notify hb-config "dag, yo")
```
In this example, the first two filters are used to control which errors get reported to Honeybadger, and the third is used to transform the data we *do* send.
More precisely, the first two filter lines say *only report errors in the production environment, and don’t report errors of type `ArithmeticException`*. The third filter uses the `obscure-params` convenience function to replace parameters at the given keypaths with a fixed string so that sensitive parameters are not sent to be stored in Honeybadger. (Of course there isn’t a param at `[:config :password]` in this case as we haven’t provided any request metadata, so the filter won’t change anything here).
To make filtering both possible and convenient, all details about the error / config / metadata / etc. are bundled up in a consistent format which filters are expected to consume and produce (with the sole exception of filters which return `nil` to suppress reporting of an error). You can see the details of that format at `honeybadger.schemas/Event`, and if you use [Prismatic/schema](https://github.com/Prismatic/schema) in your own project, then you can use the provided schemas to enforce correctness. One detail worth calling out is that all map keys are normalized to keywords so that filters don’t have to handle variations.
Here’s an example of a fully-custom filter, applying a `logged-in` tag to all exception reports where we have a `session-id`:
```clj
(defn tag-logged-in [e]
(if (get-in e [:metadata :request :session :session-id])
(update-in e [:metadata :tags] conj :logged-in)
e))
```
Using that is as simple as adding `tag-logged-in` to the list of filters.
Filters that suppress certain errors can typically be written with a simple predicate function over `Event`s which is passed to `only?` or `except?`:
```clj
(defn logged-in? [e]
(get-in e [:metadata :request :session :session-id]))
(def hb-config
{;; ...
:filters [(hbf/only logged-in?)]})
```
Last but not least, note that the (deferred) value returned by `notify` allows us to ascertain whether or not a given error was reported because it will be `nil` iff the error reporting was filtered out. We can use this to take conditional actions:
```clj
(if-let [hb-id @(hb/notify {:api-key "PROJECT_API_KEY"
:filters [(hbf/only (constantly nil))]}
"chunky bacon")]
(str "Reported error with ID " hb-id)
"Error reporting suppressed by filter")
```
### Ring
[Section titled “Ring”](#ring)
If you’d like to use this project with Ring, check out [camdez/ring-honeybadger](https://github.com/camdez/ring-honeybadger).
# Honeybadger for iOS and MacOS
> Honeybadger monitors your iOS and macOS apps for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** \~5 minutes
Hi there! You’ve found Honeybadger’s guide to **Cocoa exception and error tracking for iOS and MacOS**. Once installed, Honeybadger will automatically report errors in your iOS/macOS application.
## Getting started
[Section titled “Getting started”](#getting-started)
### CocoaPods
[Section titled “CocoaPods”](#cocoapods)
To install via CocoaPods, create/open your **Pods** file and add a pod entry for **‘Honeybadger’**. Make sure **use\_frameworks!** is specified.
```shell
use_frameworks!
target 'MyApp' do
pod 'Honeybadger'
end
```
### Swift Package Manager
[Section titled “Swift Package Manager”](#swift-package-manager)
Open your app in Xcode, then go to **File** > **Swift Packages** > **Add Package Dependency**, and specify the Honeybadger Cocoa GitHub repo: ****
### Initialization
[Section titled “Initialization”](#initialization)
You will need your Honeybadger API key to initialize the Honeybadger library. You can log into your [Honeybadger](https://honeybadger.io) account to obtain your API key.
In your App Delegate, import the Honeybadger library:
#### Swift
[Section titled “Swift”](#swift)
```swift
import Honeybadger
```
#### Objective-C
[Section titled “Objective-C”](#objective-c)
```objc
@import Honeybadger;
```
In your `didFinishLaunchingWithOptions` method, add the following code to initialize Honeybadger:
#### Swift
[Section titled “Swift”](#swift-1)
```swift
Honeybadger.configure(apiKey:"PROJECT_API_KEY")
```
#### Objective-C
[Section titled “Objective-C”](#objective-c-1)
```objc
[Honeybadger configureWithAPIKey:@"PROJECT_API_KEY"];
```
## Usage examples
[Section titled “Usage examples”](#usage-examples)
Errors and exceptions will be automatically handled by the Honeybadger library, but you can also use the following API to customize error handling in your application.
### notify
[Section titled “notify”](#notify)
You can use the **notify** methods to manually send an error as a string or Error/NSError object. If available, the Honeybadger library will attempt to extract a stack trace and any relevant information that might be useful. You can also optionally provide **context**, to include any relevant information about the error.
#### Swift
[Section titled “Swift”](#swift-2)
```swift
Honeybadger.notify(
errorString: "My error"
);
Honeybadger.notify(
errorString: "My error",
context: ["user_id" : "123abc"]
);
Honeybadger.notify(
error: MyError("This is my custom error.")
);
Honeybadger.notify(
error: MyError("This is my custom error."),
context: ["user_id" : "123abc"]
);
```
#### Objective-C
[Section titled “Objective-C”](#objective-c-2)
```objc
[Honeybadger notifyWithString:@"My error"];
[Honeybadger
notifyWithString:@"My error"
context:@{ @"user_id" : @"123abc" }
];
[Honeybadger notifyWithError:
[[NSError alloc] initWithDomain:@"my.test.error" code:-1 userInfo: @{}]
];
[Honeybadger
notifyWithError:[[NSError alloc] initWithDomain:@"my.test.error" code:-1 userInfo: @{}]
context:@{ @"user_id" : @"123abc" }
];
```
### setContext
[Section titled “setContext”](#setcontext)
If you have data that you would like to include whenever an error or an exception occurs, you can provide that data using the **setContext** method. You can call **setContext** as many times as needed. New context data will be merged with any previously-set context data.
#### Swift
[Section titled “Swift”](#swift-3)
```swift
Honeybadger.setContext(context: ["user_id" : "123abc"]);
```
#### Objective-C
[Section titled “Objective-C”](#objective-c-3)
```objc
[Honeybadger setContext:@{@"user_id" : @"123abc"}];
```
### resetContext
[Section titled “resetContext”](#resetcontext)
If you’ve used **setContext** to store data, you can use **resetContext** to clear that data.
#### Swift
[Section titled “Swift”](#swift-4)
```swift
Honeybadger.resetContext();
```
#### Objective-C
[Section titled “Objective-C”](#objective-c-4)
```objc
[Honeybadger setContext];
```
# 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
# Honeybadger for .NET
> Honeybadger monitors your .NET applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** \~5 minutes
Hi there! You’ve found Honeybadger’s guide to **.NET exception and error tracking**. Once installed, Honeybadger will automatically report errors from your .NET or C# application.
## Getting started
[Section titled “Getting started”](#getting-started)
[Source Code](https://github.com/honeybadger-io/honeybadger-dotnet)
### Configuration
[Section titled “Configuration”](#configuration)
The Honeybadger Notifier can be configured using the `HoneybadgerOptions` class. Honeybadger can be configured by passing the options when registering the service, or through your `appsettings.json` file.
Honeybadger will attempt to automatically figure out the `ProjectRoot` directory, which should be the root of your project or solution. A valid `ProjectRoot` directory will allow Honeybadger to classify stack frames as either *application* code or *all* other code (e.g. framework code) and hence provide better error reports.
See below for examples on how to configure Honeybadger for different types of applications.
### For .NET Core web app
[Section titled “For .NET Core web app”](#for-net-core-web-app)
#### 1. Install Honeybadger.DotNetCore from NuGet
[Section titled “1. Install Honeybadger.DotNetCore from NuGet”](#1-install-honeybadgerdotnetcore-from-nuget)
```sh
dotnet add package Honeybadger.DotNetCore
```
#### 2. Register the Honeybadger middleware:
[Section titled “2. Register the Honeybadger middleware:”](#2-register-the-honeybadger-middleware)
```c#
var builder = WebApplication.CreateBuilder(args);
builder.AddHoneybadger(configure =>
{
configure.ApiKey = "PROJECT_API_KEY";
});
```
Or you can configure Honeybadger through your `appsettings.json` file, by adding a `Honeybadger` section:
```json
{
"Honeybadger": {
"ApiKey": "PROJECT_API_KEY",
"AppEnvironment": "Development",
"ReportData": true
}
}
```
Note
You should probably set your API key through environment variables or use the Secrets Manager, instead of hardcoding it in the `appsettings.json` file.
You can read the [official documentation](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) for more information on how to do that in a .Net Core app.
And simply call `AddHoneybadger` without any parameters:
```c#
var builder = WebApplication.CreateBuilder(args);
builder.AddHoneybadger();
```
#### Usage
[Section titled “Usage”](#usage)
You can access the *Honeybadger Client* using *DI*:
```c#
app.MapGet("/", ([FromServices] IHoneybadgerClient honeybadger) =>
{
honeybadger.AddBreadcrumb("reached index route", "route", new Dictionary());
return "Hello World!";
});
```
Any unhandled exceptions should be reported to Honeybadger automatically (unless `ReportUnhandledExceptions` is set to `false`):
```c#
app.MapGet("/debug", () =>
{
throw new Exception("hello from .Net Core Web App!");
});
```
See example project in `examples/Honeybadger.DotNetCoreWebApp`.
### As a custom logging provider
[Section titled “As a custom logging provider”](#as-a-custom-logging-provider)
#### 1. Install Honeybadger.Extensions.Logging from Nuget
[Section titled “1. Install Honeybadger.Extensions.Logging from Nuget”](#1-install-honeybadgerextensionslogging-from-nuget)
```sh
dotnet add package Honeybadger.Extensions.Logging
```
#### 2. Register Honeybadger and additionally the custom logging provider:
[Section titled “2. Register Honeybadger and additionally the custom logging provider:”](#2-register-honeybadger-and-additionally-the-custom-logging-provider)
```c#
var builder = WebApplication.CreateBuilder(args);
// or set the configuration in the appsettings.json file
builder.AddHoneybadger(configure =>
{
configure.ApiKey = "PROJECT_API_KEY";
});
builder.Logging.AddHoneybadger();
```
You should also configure the minimum log level as you would configure other log providers in .Net Core. The following would report only logged errors:
```json
{
"Logging": {
"Honeybadger": {
"Default": "Error"
}
}
}
```
And simply call `AddHoneybadger` and `Logging.AddHoneybadger` without any parameters:
```c#
var builder = WebApplication.CreateBuilder(args);
builder.AddHoneybadger();
builder.Logging.AddHoneybadger();
```
#### Usage
[Section titled “Usage”](#usage-1)
Errors from the `logger` will be reported to Honeybadger:
```c#
app.MapGet("/notify", ([FromServices] ILogger logger) =>
{
logger.LogError("hello from Honeybadger.Logger!");
return "Log reported to Honeybadger. Check your dashboard!";
});
```
See example project in `examples/Honeybadger.DotNetCoreWebApp.Logger`.
### Send a test notification
[Section titled “Send a test notification”](#send-a-test-notification)
Note
Honeybadger, by default, will not report errors in development environments.
You can override the development environments by setting the `DevelopmentEnvironments` property in the options.
Alternatively, you can set the `ReportData` property to `true` to report errors in all environments.
You can send a test notification to Honeybadger to verify that the configuration is working. Add the following to your `Program.cs` file:
```c#
// ...
builder.AddHoneybadger();
// ...
var app = builder.Build();
var honeybadger = app.Services.GetRequiredService();
await honeybadger.NotifyAsync("Hello from .Net!");
```
Run the app. If the configuration is correctly set, you should see the notification in your Honeybadger dashboard.
### Automatic error reporting
[Section titled “Automatic error reporting”](#automatic-error-reporting)
Automatic error reporting is enabled by default, but you can disable it by setting the `ReportUnhandledExceptions` property to `false` in `HoneybadgerOptions`:
```json
{
"Honeybadger": {
"ApiKey": "PROJECT_API_KEY",
"AppEnvironment": "Development",
"ReportData": true,
"ReportUnhandledExceptions": false
}
}
```
### Using the SDK manually
[Section titled “Using the SDK manually”](#using-the-sdk-manually)
#### 1. Install the [Honeybadger Nuget](https://www.nuget.org/packages/Honeybadger).
[Section titled “1. Install the Honeybadger Nuget.”](#1-install-the-honeybadger-nuget)
```sh
dotnet add package Honeybadger
```
#### 2. Initialize the Honeybadger client:
[Section titled “2. Initialize the Honeybadger client:”](#2-initialize-the-honeybadger-client)
```c#
using Microsoft.Extensions.Options;
var options = new HoneybadgerOptions("PROJECT_API_KEY");
var honeybadger = new HoneybadgerClient(Options.Create(options));
```
#### 3. Call `notify` to report to Honeybadger:
[Section titled “3. Call notify to report to Honeybadger:”](#3-call-notify-to-report-to-honeybadger)
```c#
// fire and forget
honeybadger.Notify("hello from .Net !");
// or async
await honeybadger.NotifyAsync("hello from .Net !");
```
See example project in `examples/Honeybadger.Console`.
## Supported .NET versions
[Section titled “Supported .NET versions”](#supported-net-versions)
All modern .Net Core applications are supported, up to .Net 9.0.
# Honeybadger for Elixir
> Honeybadger monitors your Elixir applications for errors and performance bottlenecks so that you can fix them wicked fast.
Hi there! You’ve found Honeybadger’s guide to **Elixir error tracking and performance monitoring**. Once installed, Honeybadger will automatically report errors and telemetry in your Elixir application.
## How you should read the docs
[Section titled “How you should read the docs”](#how-you-should-read-the-docs)
* If you’re installing Honeybadger in your **Phoenix** application for the first time, check out the **[Phoenix Integration Guide](/lib/elixir/integrations/phoenix/)**. If you use a different framework, start with the **[General Integration Guide](/lib/elixir/integrations/other/)** instead.
* The **How-To Guides** (in the left-hand navigation menu) are general guides on how to do things with the library, and should apply to all types of applications.
* There is a wealth of additional knowledge about Honeybadger in the **Package Reference** and **Support** sections.
## Getting support
[Section titled “Getting support”](#getting-support)
If you’re having trouble working with the package (such as you aren’t receiving error reports when you should be):
1. Read [Frequently asked questions](/lib/elixir/support/faq/)
2. Upgrade to the latest package version if possible (you can find a list of bugfixes and other changes in the [CHANGELOG](https://github.com/honeybadger-io/honeybadger-elixir/blob/master/CHANGELOG.md))
3. Run through our [Troubleshooting guide](/lib/elixir/support/troubleshooting/)
4. If you believe you’ve found a bug, [submit an issue on GitHub](https://github.com/honeybadger-io/honeybadger-elixir/issues/)
For all other problems, contact support for help:
# Breadcrumbs
> Add breadcrumbs to Elixir error reports to track events leading up to errors and improve debugging.
Breadcrumbs are a useful debugging tool that give you the ability to record contextual data as an event called a `breadcrumb`. When your Project reports an Error (Notice), we send along the breadcrumbs recorded during the execution (request, job, task, etc…).
[Context](/lib/elixir/errors/context/) is another way to store extra data to help with debugging. Context is still a great way to attach global data to an error, however, there are scenarios where Breadcrumbs might be a better choice:
* You want to record metadata that contains duplicate keys
* You want to group related data
* You care about when an event happened in relation to an error
`Honeybadger.add_breadcrumb/2` appends a breadcrumb to the notice. Use this when you want to add some custom data to your breadcrumb trace in effort to help debugging. If a notice is reported to Honeybadger, all breadcrumbs within the execution path will be appended to the notice. You will be able to view the breadcrumb trace in the Honeybadger interface to see what events led up to the notice.
```elixir
Honeybadger.add_breadcrumb("Email sent", metadata: %{
user: user.id,
message: message
})
```
# Adding context to errors
> Add context to Elixir error reports with custom metadata to improve debugging and error resolution.
Honeybadger can display additional custom key/value metadata — or “context” — with each error report. Context is what you’re looking for if:
* You want to record the current user’s id or email address at the time of an exception
* You need to send raw POST data for use in debugging
* You have any other metadata you’d like to send with an exception
There are two ways to add context to errors in your code: [global](#global-context) and [local](#local-context). While you can add any key/value data to context, a few keys [have a special meaning in Honeybadger](#special-context-keys).
## Global context
[Section titled “Global context”](#global-context)
`Honeybadger.context/1` is provided for adding extra data to the notification that gets sent to Honeybadger. You can make use of this in places such as a Plug in your Phoenix Router or Controller to ensure useful debugging data is sent along.
```elixir
def MyPhoenixApp.Controller
use MyPhoenixApp.Web, :controller
plug :set_honeybadger_context
def set_honeybadger_context(conn, _opts) do
user = get_user(conn)
Honeybadger.context(user_id: user.id, account: user.account.name)
conn
end
end
```
`Honeybadger.context/1` stores the context data in the process dictionary, so it will be sent with errors/notifications on the same process. The following `Honeybadger.notify/1` call will not see the context data set in the previous line.
```elixir
Honeybadger.context(user_id: 5)
Task.start(fn ->
# this notify does not see the context set earlier
# as this runs in a different elixir/erlang process.
Honeybadger.notify(%RuntimeError{message: "critical error"})
end)
```
## Local context
[Section titled “Local context”](#local-context)
You can also add context to a manual error report using the `metadata` option, like this:
```elixir
context = %{user_id: 5, account_name: "Foo"}
Honeybadger.notify(exception, metadata: context, stacktrace: __STACKTRACE__)
```
Local context always overrides any global values when the error is reported.
## Special context keys
[Section titled “Special context keys”](#special-context-keys)
While you can add any key/value data to context, a few keys have special meaning in Honeybadger:
| Option | Description |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| `user_id` | The `String` user ID used by Honeybadger to aggregate user data across occurrences on the error page. |
| `user_email` | Same as `user_id`, but for email addresses |
## Limits
[Section titled “Limits”](#limits)
Honeybadger uses the following limits to ensure the service operates smoothly for everyone:
* Nested objects have a max depth of 20
* Context values have a max size of 64Kb
When an error notification includes context data that exceed these limits, the context data will be truncated, and the notification will still be processed.
# Customizing error grouping
> Customize how errors are grouped in Elixir applications to better organize and prioritize error reports.
Honeybadger groups similar exceptions together using rules which we’ve found to work the best in most cases. The default information we use to group errors is:
1. The file name, method name, and line number of the error’s location
2. The class name of the error
3. The component/controller name
We use this information to construct a “fingerprint” of the exception. Exceptions with the same fingerprint are treated as the same error in Honeybadger.
You can customize the grouping for each exception by changing the error class name, component, or stack trace—or by sending a custom fingerprint.
See the [Error Monitoring Guide](https://docs.honeybadger.io/guides/errors/#error-grouping) for more information about how honeybadger groups similar exception together. You can customize the grouping for each exception in Elixir by sending a custom *fingerprint* when the exception is reported.
To customize the fingerprint for all exceptions that are reported from your app, use the `fingerprint_adapter` configuration option in `config.ex`:
```elixir
config :honeybadger, fingerprint_adapter: MyApp.CustomFingerprint
```
Then, implement the `Honeybadger.FingerprintAdapter` behaviour in your module:
```elixir
defmodule MyApp.CustomFingerprint do
@behaviour Honeybadger.FingerprintAdapter
def parse(notice) do
notice.notifier.language <> "-" <> notice.notifier.name
end
end
```
You can also customize the fingerprint for individual exceptions when calling `Honeybadger.notify`:
```elixir
Honeybadger.notify(%RuntimeError{}, fingerprint: "culprit_id-123")
```
# Environments
> Configure environment-specific error tracking settings for Elixir applications across development, staging, and production.
Honeybadger groups errors by the environment they belong to. You don’t have to set an environment, but it can be useful if you’re running your app in different locations, such as “production” and “staging”.
The best way to set the environment is to use [Elixir’s `config_env()` function](https://hexdocs.pm/elixir/main/Config.html#config_env/0) in your `config.exs` file:
```elixir
config :honeybadger,
environment_name: config_env()
```
You can also configure Honeybadger for each of your Mix environments—for example, by adding the following to each of your `config/#{env}.exs` files in Phoenix:
config/dev.exs
```elixir
config :honeybadger,
environment_name: :dev
# config/test.exs
config :honeybadger,
environment_name: :test
# config/prod.exs
config :honeybadger,
environment_name: :prod
```
Tip
Honeybadger’s `environment_name` setting takes precedence over `Mix.env()`.
If `environment_name` is not set we will fall back to the value of `Mix.env()`. `Mix.env()` uses the atomized value of the `MIX_ENV` environment variable and defaults to `:prod` when the environment variable is not set. If you want to have an `environment_name` which is different from `Mix.env()` (`:dev`, for example), you should set `environment_name` in your `config.exs` as described above. This ensures that we can give you accurate environment information at compile time.
## Development environments
[Section titled “Development environments”](#development-environments)
Some environments should usually not report errors at all, such as when you are developing on your local machine or running your test suite (locally or in CI). The *honeybadger* package has an internal list of environment names which it considers development environments:
```plaintext
dev
test
```
Honeybadger **does not** report errors in these environments. To send data to all environments, you can set the `exclude_envs` configuration option to an empty list:
```elixir
config :honeybadger,
exclude_envs: []
```
# Filtering sensitive data
> Filter sensitive data from Elixir error reports to protect user privacy and comply with security requirements.
You have complete control over the data that Honeybadger reports when an error occurs. Before data is sent to Honeybadger, it is passed through a filter to remove sensitive fields and do other processing on the data. The default configuration is equivalent to:
```elixir
config :honeybadger,
filter: Honeybadger.Filter.Default,
filter_keys: [:password, :credit_card]
```
This will remove any entries in the `context`, `session`, `cgi_data` and `params` that match one of the filter keys. The filter is case insensitive and matches atoms or strings.
If `Honeybadger.Filter.Default` does not suit your needs, you can implement your own filter. See the `Honeybadger.Filter.Mixin` module doc for details on implementing your own filter.
## Filtering arguments
[Section titled “Filtering arguments”](#filtering-arguments)
Honeybadger can show arguments in the stacktrace for `FunctionClauseError` exceptions. To enable argument reporting, set `filter_args` to `false`:
```elixir
config :honeybadger, filter_args: false
```
# Reducing noise
> Reduce error noise in Elixir applications by ignoring specific errors and filtering unwanted notifications.
Sometimes there are errors that you would rather not send to Honeybadger because they are not actionable or are handled internally. By default Honeybadger will be notified when any error occurs. To override this configuration in order not to send out errors to Honeybadger, set `exclude_errors` option in `config/config.exs`.
This can be done by passing a list of errors to be excluded:
```elixir
config :honeybadger,
exclude_errors: ["RuntimeError"]
```
or
```elixir
config :honeybadger,
exclude_errors: [RuntimeError]
```
Also you can implement the `Honeybadger.ExcludeErrors` behaviour function `exclude_error?/1`, which receives the full `Honeybadger.Notice` and returns a boolean signalling the error exclusion or not.
```elixir
defmodule ExcludeFunClauseErrors do
alias Honeybadger.ExcludeErrors
@behaviour ExcludeErrors
@impl ExcludeErrors
def exclude_error?(notice) do
notice.error.class == "FunctionClauseError"
end
end
```
```elixir
config :honeybadger,
exclude_errors: ExcludeFunClauseErrors
```
# Reporting errors
> Report errors from Elixir applications to Honeybadger with automatic notifications and custom error handling.
Honeybadger reports uncaught errors automatically. In all other cases, use `Honeybadger.notify/1,2` to send errors to Honeybadger.
Use the `Honeybadger.notify/2` function to send exception information to the [Exceptions API](/api/reporting-exceptions/). The first parameter is the exception and the second parameter is the context/metadata/fingerprint.
```elixir
try do
File.read! "this_file_really_should_exist_dang_it.txt"
rescue
exception ->
Honeybadger.notify(exception, metadata: %{}, stacktrace: __STACKTRACE__, fingerprint: "")
end
```
There is also a `Honeybadger.notify/1` which doesn’t require the second parameter.
```elixir
Honeybadger.notify("Send this to Honeybadger")
```
# Tagging errors
> Add tags to Elixir error reports to categorize and filter errors for better organization and analysis.
Each error in Honeybadger has tags. Tags can be used to filter results when searching and can even apply to integrations so that only errors with a combination of certain tags trigger an email or a Slack message, for example.
Tags can be used to create custom workflows, such as:
* Find all errors tagged “badgers” and resolve them.
* Tag critical errors as “critical” and configure PagerDuty to alert you only when a critical error happens.
* If you have errors which aren’t actionable (but you still want to know about them), you could tag them with “low\_priority” and exclude those errors when automatically creating issues via the GitHub integration.
* Tag all errors that happen in an area of your app with the name of the team that is responsible for them, then notify their Slack channel for only those errors.
These are just examples: you can use tags however you want!
While you can always add tags to existing errors through the Honeybadger UI, they are most useful when you add them programmatically as the exceptions happen. There are two ways to add tags to errors from your Elixir app:
## Tagging errors in global context
[Section titled “Tagging errors in global context”](#tagging-errors-in-global-context)
Every exception which is reported within the current context will have the tags “critical” and “badgers” added:
```elixir
Honeybadger.context(tags: "critical, badgers")
```
## Tagging errors in `Honeybadger.notify`
[Section titled “Tagging errors in Honeybadger.notify”](#tagging-errors-in-honeybadgernotify)
The tags will be added for just the current error being reported:
```elixir
context = %{tags: "critical, badgers"}
Honeybadger.notify(exception, metadata: context, stacktrace: __STACKTRACE__)
```
# Tracking deployments
> Track deployments from Elixir applications to correlate errors with releases and identify problematic code changes.
Honeybadger has an API to keep track of project deployments. Whenever you deploy, all errors for that environment will be resolved automatically. You can choose to enable or disable the auto-resolve feature from your Honeybadger project settings page.
## Deploying with GitHub Actions
[Section titled “Deploying with GitHub Actions”](#deploying-with-github-actions)
If your CI/CD pipeline is hosted with GitHub Actions, you can use the [Honeybadger Deploy Action](https://github.com/marketplace/actions/honeybadger-deploy-action) to notify our API about deployments.
## Deploying with `curl`
[Section titled “Deploying with curl”](#deploying-with-curl)
```sh
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
&& curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"
```
If you are using our EU stack, you should use `eu-api.honeybadger.io` instead of `api.honeybadger.io` for the domain name.
# Capturing logs and events
> Send logs and custom events from Elixir applications to Honeybadger Insights for monitoring and debugging.
Honeybadger’s Elixir package can be used to send events to [Honeybadger Insights](/guides/insights/).
## Automatic instrumentation
[Section titled “Automatic instrumentation”](#automatic-instrumentation)
Honeybadger Insights allows you to automatically track various events in your application. To enable Insights automatic instrumentation, add the following to your configuration:
```elixir
config :honeybadger,
insights_enabled: true
```
Honeybadger automatically instruments the following libraries when they are available:
* **Ecto**: Database queries
* **Plug/Phoenix**: HTTP requests
* **LiveView**: Phoenix LiveView lifecycle events
* **Oban**: Background job processing
* **Absinthe**: GraphQL query execution
* **Finch**: HTTP client requests, often used by other libraries like Req
* **Tesla**: HTTP client requests
## Instrumented libraries
[Section titled “Instrumented libraries”](#instrumented-libraries)
Each instrumented library has its own configuration options. You can customize the telemetry events that are captured, as well as the data that is sent to Honeybadger.
***
### Ecto
[Section titled “Ecto”](#ecto)
Captures database query telemetry events from Ecto repositories.
#### Default configuration
[Section titled “Default configuration”](#default-configuration)
By default, this module listens for telemetry events from all configured Ecto repositories. It reads the `:ecto_repos` configuration to identify repositories and their telemetry prefixes:
```elixir
config :honeybadger,
ecto_repos: [MyApp.Repo]
```
#### Custom configuration
[Section titled “Custom configuration”](#custom-configuration)
You can customize this module’s behavior with the following configuration options:
```elixir
config :honeybadger, insights_config: %{
ecto: %{
# Disable Ecto telemetry events
disabled: false,
# A list of strings or regex patterns of queries to exclude
excluded_queries: [
~r/^(begin|commit)( immediate)?( transaction)?$/i,
~r/SELECT pg_notify/,
~r/schema_migrations/
],
# Format & include the stacktrace with each query. You must also
# update your repo config to enable:
#
# config :my_app, MyApp.Repo,
# stacktrace: true
#
# Can be a boolean to enable for all or a list of sources to enable.
include_stacktrace: true
# Alternative source whitelist example:
# include_stacktrace: ["source_a", "source_b"],
# Format & include the query parameters with each query. Can be a
# boolean to enable for all or a list of sources to enable.
include_params: true
# Alternative source whitelist example:
# include_params:["source_a", "source_b"],
# A list of table/source names to exclude
excluded_sources: [
"schema_migrations",
"oban_jobs",
"oban_peers"
]
}
}
```
By default, transaction bookkeeping queries and schema migration checks are excluded, as well as queries to common background job tables.
***
### Plug/Phoenix
[Section titled “Plug/Phoenix”](#plugphoenix)
Captures telemetry events from HTTP requests processed by Plug and Phoenix.
#### Default configuration
[Section titled “Default configuration”](#default-configuration-1)
By default, this module listens for the standard Phoenix endpoint telemetry event:
phoenix.endpoint.stop
This is compatible with the default Phoenix configuration that adds telemetry via `Plug.Telemetry`:
plug Plug.Telemetry, event\_prefix: \[:my, :prefix]
#### Custom configuration
[Section titled “Custom configuration”](#custom-configuration-1)
You can customize the telemetry events to listen for by updating the insights\_config:
```elixir
config :honeybadger, insights_config: %{
plug: %{
# Disable Plug/Phoenix telemetry events
disabled: false,
telemetry_events: [[:my, :prefix, :stop]]
}
}
```
***
### LiveView
[Section titled “LiveView”](#liveview)
Captures telemetry events from Phoenix LiveView.
#### Default configuration
[Section titled “Default configuration”](#default-configuration-2)
By default, this module listens for the following LiveView telemetry events:
phoenix.live\_view\.mount.stop phoenix.live\_view\.handle\_params.stop phoenix.live\_view\.handle\_event.stop
phoenix.live\_component.update.stop phoenix.live\_component.handle\_event.stop
#### Custom configuration
[Section titled “Custom configuration”](#custom-configuration-2)
You can customize the telemetry events to listen for by updating the insights\_config:
```elixir
config :honeybadger, insights_config: %{
live_view: %{
# Disable LiveView telemetry events
disabled: false,
telemetry_events: [
[:phoenix, :live_view, :mount, :stop],
[:phoenix, :live_component, :handle_event, :stop],
[:phoenix, :live_component, :update, :stop]
[:phoenix, :live_view, :handle_event, :stop],
[:phoenix, :live_view, :handle_params, :stop],
[:phoenix, :live_view, :update, :stop]
]
}
}
```
***
### Oban
[Section titled “Oban”](#oban)
Captures telemetry events from Oban job processing.
#### Default configuration
[Section titled “Default configuration”](#default-configuration-3)
By default, this module listens for the following Oban telemetry events:
oban.job.stop oban.job.exception
#### Custom configuration
[Section titled “Custom configuration”](#custom-configuration-3)
You can customize the telemetry events to listen for by updating the insights\_config:
```elixir
config :honeybadger, insights_config: %{
oban: %{
# Disable Oban telemetry events
disabled: false,
telemetry_events: [
[:oban, :job, :stop],
[:oban, :job, :exception],
[:oban, :engine, :start]
]
}
}
```
***
### Absinthe
[Section titled “Absinthe”](#absinthe)
Captures telemetry events from GraphQL operations executed via Absinthe.
#### Default configuration
[Section titled “Default configuration”](#default-configuration-4)
By default, this module listens for the following Absinthe telemetry events:
absinthe.execute.operation.stop absinthe.execute.operation.exception
#### Custom configuration
[Section titled “Custom configuration”](#custom-configuration-4)
You can customize the telemetry events to listen for by updating the insights\_config:
```elixir
config :honeybadger, insights_config: %{
absinthe: %{
# Disable Absinthe telemetry events
disabled: false,
telemetry_events: [
[:absinthe, :execute, :operation, :stop],
[:absinthe, :execute, :operation, :exception],
[:absinthe, :resolve, :field, :stop]
]
}
}
```
Note that adding field-level events like “absinthe.resolve.field.stop” can significantly increase the number of telemetry events generated.
***
### Finch
[Section titled “Finch”](#finch)
Captures telemetry events from HTTP requests made using Finch.
#### Default configuration
[Section titled “Default configuration”](#default-configuration-5)
By default, this module listens for the standard Finch request telemetry event:
finch.request.stop
#### Custom configuration
[Section titled “Custom configuration”](#custom-configuration-5)
You can customize the telemetry events to listen for by updating the insights\_config:
```elixir
config :honeybadger, insights_config: %{
finch: %{
# Disable Finch telemetry events
disabled: false,
telemetry_events: ["finch.request.stop", "finch.request.exception"],
# Include full URLs in telemetry events (default: false - only hostname is included)
full_url: false
}
}
```
By default, only the hostname from URLs is captured for security and privacy reasons. If you need to capture the full URL including paths (but not query parameters), you can enable the `full_url` option.
***
#### Default configuration
[Section titled “Default configuration”](#default-configuration-6)
By default, this module listens for the standard Tesla request telemetry events:
tesla.request.stop tesla.request.exception
#### Custom configuration
[Section titled “Custom configuration”](#custom-configuration-6)
This module can be configured in the application config:
```elixir
config :honeybadger, insights_config: %{
tesla: %{
# Disable Tesla telemetry events
disabled: false,
# Include full URLs in telemetry events (default: false - only hostname is included)
full_url: false,
# Custom telemetry event patterns to listen for (optional)
telemetry_events: [
[:tesla, :request, :stop],
[:tesla, :request, :exception]
]
}
}
```
#### Job event context
[Section titled “Job event context”](#job-event-context)
We attempt to automatically inject `request_id` and any other event context into events emitted from a Job. The method for inheriting event context might not work in all cases, so you can explicitly add event context to a job by using the `add_event_context/1` function:
```elixir
MyApp.Worker.new()
|> Honeybadger.Insights.Oban.add_event_context()
|> Oban.insert()
```
Ensure that the event context is avaliable in the caller’s process dictionary before inserting into the job.
## Manually sending events
[Section titled “Manually sending events”](#manually-sending-events)
Use the `Honeybadger.event/1` function to send event data to the events API. A `ts` field with the current timestamp will be added to the data if it isn’t provided. You can also use `Honeybadger.event/2`, which accepts a string as the first parameter and adds that value to the `event_type` field in the map before being sent to the API.
```elixir
Honeybadger.event(%{
event_type: "user_created",
user: user.id
})
Honeybadger.event("project_deleted", %{
project: project.name
})
```
## Sending logs from your infrastructure
[Section titled “Sending logs from your infrastructure”](#sending-logs-from-your-infrastructure)
Honeybadger isn’t just for errors and application data! You can use our [syslog](/guides/insights/integrations/systemd/), [Vector](/guides/insights/integrations/log-files/), or [PaaS integrations](/guides/insights/#adding-data-from-other-sources) to send additional data from your infrastructure to [Honeybadger Insights](/guides/insights/), where you can query, visualize, and analyze all of your production data in one place.
# Event context
> Add contextual data to Insights events in Elixir to improve debugging and understanding of application behavior.
You can add custom metadata to the events sent to Honeybadger Insights by using the `event_context/1` function. This metadata will be included in each event call within the same process.
Note: This will add the metadata to all events sent, so be careful not to include too much data. Try to keep it to simple key/value pairs.
For example, you can add user ID information to all events (via plug):
```elixir
defmodule MyAppWeb.Plug.UserContext do
import Plug.Conn
def init(opts), do: opts
def call(conn, _opts) do
user = get_session(conn, :user)
Honeybadger.event_context(%{user_id: user.id})
conn
end
end
```
Event context is not automatically propagated to other processes. If you want to add context to events in a different process, you can use the `Honeybadger.event_context/0` function to get the current context and pass it to the `Honeybadger.event/1` function:
```elixir
defmodule MyApp.MyGenServer do
use GenServer
def set(value) do
GenServer.cast(__MODULE__, {:set, value, Honeybadger.event_context()})
end
def handle_cast({:set, value, hb_context}, _state) do
Honeybadger.event_context(hb_context)
Honeybadger.event("set_value", %{value: value})
{:noreply, value}
end
end
```
## Inheriting context
[Section titled “Inheriting context”](#inheriting-context)
If you know the parent process is alive and part of the process tree, you can use `Honeybadger.inherit_event_context/0` to inherit the context from the parent process. This method works best if you are running OTP 25+.
```elixir
Task.async(fn ->
Honeybadger.inherit_event_context()
# Do some work here
Honeybadger.event("work", %{did: "some_work"})
end)
```
Scenarios when inheriting context is useful include:
* Direct process spawning (`spawn`, `spawn_link`)
* `Task.async/1`, `Task.await/1`, etc.
* Other scenarios where direct parent-child relationships are maintained
When explicit passing is needed:
* GenServer
* Supervised processes
* Processes started through other OTP abstractions
# Filtering events
> Filter Insights events in Elixir applications to reduce noise and focus on relevant data.
You can filter out or customize events sent to Honeybadger Insights by using the `Honeybadger.EventFilter.Mixin` module. You can customize both the event built from telemetry data (`filter_telemetry_event/3`) and the event right before it is sent to Honeybadger (`filter_event/1`):
```elixir
defmodule MyApp.MyFilter do
use Honeybadger.EventFilter.Mixin
# Drop analytics events by returning nil
def filter_event(%{event_type: "analytics"} = _event), do: nil
# Anonymize user data in login events
def filter_event(%{event_type: "login"} = event) do
event
|> update_in([:data, :user_email], fn _ -> "[REDACTED]" end)
|> put_in([:metadata, :filtered], true)
end
# Remove query field for a specific repo
def filter_event(%{event_type: "my_app.repo.query"} = event) do
Map.delete(event, :query)
|> put_in([:metadata, :filtered], true)
end
# For telemetry events, you can customize while still applying default filtering
def filter_telemetry_event(data, raw, event) do
# First apply default filtering
filtered_data = apply_default_telemetry_filtering(data)
# Then apply custom logic
case event do
[:auth, :login, :start] ->
Map.put(filtered_data, :security_filtered, true)
_ ->
filtered_data
end
end
# Keep all other events as they are
def filter_event(event), do: event
end
```
Then configure the filter in your application’s configuration:
```elixir
config :honeybadger, event_filter: MyApp.EventFilter
```
# Sampling events
> Configure event sampling in Elixir to control Insights data volume while maintaining statistical accuracy.
You can enable event sampling to reduce the number of events sent to Honeybadger. This is especially useful if you are hitting your daily event quota limit:
```elixir
config :honeybadger,
# Sample 50% of events
insights_sample_rate: 50
```
The `insights_sample_rate` option accepts a whole percentage value between 0 and 100, where 0 means no events will be sent and 100 means all events will be sent. The default is no sampling (100%).
Events are sampled by hashing the `request_id` if available in the event payload, otherwise random sampling is used. This deterministic approach ensures that related events from the same request are consistently sampled together.
## Per-event sampling
[Section titled “Per-event sampling”](#per-event-sampling)
The sample rate is applied to all events sent to Honeybadger Insights, including automatic instrumentation events. You can also set the sample rate per event by adding the `sample_rate` key to the event metadata map:
```elixir
Honeybadger.event("user_created", %{
user_id: user.id,
_hb: %{sample_rate: 100}
})
```
The event sample rate can also be set within the `event_context/1` function. This can be handy if you want to set an overall sample rate for a process or ensure that specific instrumented events get sent:
```elixir
# Set a higher sampling rate for this entire process
Honeybadger.event_context(%{_hb: %{sample_rate: 100}})
# Now all events from this process, including automatic instrumentation,
# will use the 100% sample rate
Ecto.Repo.insert!(%MyApp.User{}) # This instrumented event will be sent
```
Remember that context is process-bound and applies to all events sent from the same process after the `event_context/1` call, until it’s changed or the process terminates.
When setting sample rates below the global setting, be aware that this affects how events with the same `request_id` are sampled. Since sampling is deterministic based on the `request_id` hash, all events sharing the same `request_id` will either all be sampled or all be skipped together. This ensures consistency across related events.
With that in mind, it’s recommended to default to the global sample rate and use per-event sampling for specific cases where you want to ensure events are sent regardless of the global setting, or you are setting the sample rate in the context where all events with the same `request_id` will also share the same sampling rate.
# Elixir integration guide
> Install and configure Honeybadger error tracking and application monitoring for Elixir applications outside of Phoenix and Plug frameworks.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **Elixir error tracking and performance monitoring**. If you use *Phoenix* or *Plug*, go check out the [Phoenix Integration Guide](../phoenix/). If not, then read on.
This guide will teach you how to install the `honeybadger` Hex package in your Elixir project and use it to manually report errors to Honeybadger. You can also enable some [automatic logging and performance insights](/lib/elixir/insights/capturing-logs-and-events/) (via telemetry) by setting the `insights_enabled` option to `true` in your configuration.
On this page:
## Installing the package
[Section titled “Installing the package”](#installing-the-package)
Add the Honeybadger package to `deps/0` in your application’s `mix.exs`:
```elixir
defp deps do
[{:honeybadger, "~> 0.22"}]
end
```
Then run:
```sh
mix do deps.get, deps.compile
```
Finally, update your app’s `config.exs` file to include the Honeybadger configuration:
```elixir
config :honeybadger,
api_key: "PROJECT_API_KEY",
environment_name: config_env(),
insights_enabled: true # Enable logging and performance insights
```
Tip
You can also configure your API key using the `HONEYBADGER_API_KEY` environment variable:
```sh
export HONEYBADGER_API_KEY="PROJECT_API_KEY"
```
If you use this method, you can omit the `api_key` option from your configuration.
See the [Configuration reference](/lib/elixir/reference/configuration/) for additional info.
## Testing your installation
[Section titled “Testing your installation”](#testing-your-installation)
Note
Honeybadger does not report errors in `dev` and `test` environments by default. To enable reporting in development environments, temporarily add `exclude_envs: []` to your Honeybadger config.
To test your installation, fire up `iex -S mix`, then run:
```elixir
Honeybadger.notify("Hello Elixir!")
```
If Honeybadger is configured correctly, you should see a new error report in your Honeybadger project dashboard.
## Configuring Elixir’s logger
[Section titled “Configuring Elixir’s logger”](#configuring-elixirs-logger)
When configured, Honeybadger will report errors for any [SASL](http://www.erlang.org/doc/apps/sasl/error_logging.html)-compliant processes when they crash. Just set the `use_logger` option to `true` in your application’s `config.exs` and you’re good to go:
```elixir
config :honeybadger,
use_logger: true
```
## Manually reporting errors
[Section titled “Manually reporting errors”](#manually-reporting-errors)
You can use the `Honeybadger.notify/2` function to manually report rescued exceptions:
```elixir
try do
# Buggy code goes here
rescue
exception ->
Honeybadger.notify(exception, stacktrace: __STACKTRACE__)
end
```
You can also pass a string message to the `notify` function (the second argument is optional):
```elixir
Honeybadger.notify("Sign in failed", metadata: %{
user_id: current_user.id
})
```
See [Reporting Errors](/lib/elixir/errors/reporting-errors/) for more information.
## Reporting custom events
[Section titled “Reporting custom events”](#reporting-custom-events)
Use the `Honeybadger.event/1` and `Honeybadger.event/2` functions to send events to [Honeybadger Insights](/guides/insights/) for logging and performance monitoring:
```elixir
Honeybadger.event(%{
event_type: "user_created",
user: user.id
})
# Honeybadger.event/2 is a shorthand that automatically adds the event_type
# property to the event:
Honeybadger.event("project_deleted", %{
project: project.name
})
```
See [Capturing Logs and Events](/lib/elixir/insights/capturing-logs-and-events/) for more details.
## Sending logs from your infrastructure
[Section titled “Sending logs from your infrastructure”](#sending-logs-from-your-infrastructure)
Honeybadger isn’t just for errors and application data! You can use our [syslog](/guides/insights/integrations/systemd/), [Vector](/guides/insights/integrations/log-files/), or [PaaS integrations](/guides/insights/#adding-data-from-other-sources) to send additional data from your infrastructure to [Honeybadger Insights](/guides/insights/), where you can query, visualize, and analyze all of your production data in one place.
## Version requirements
[Section titled “Version requirements”](#version-requirements)
See [Supported Versions](/lib/elixir/reference/supported-versions/).
# Phoenix and Plug integration guide
> Install and configure Honeybadger application monitoring for Phoenix and Plug applications with automatic error reporting.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **Phoenix error tracking and performance monitoring**. Once installed, Honeybadger will automatically report errors and performance insights from your Phoenix application.
## Installing the package
[Section titled “Installing the package”](#installing-the-package)
Add the Honeybadger package to `deps/0` in your application’s `mix.exs`:
```elixir
defp deps do
[{:honeybadger, "~> 0.22"}]
end
```
Then run:
```sh
mix do deps.get, deps.compile
```
Finally, update your app’s `config.exs` file to include the Honeybadger configuration:
```elixir
config :honeybadger,
api_key: "PROJECT_API_KEY",
environment_name: config_env(),
insights_enabled: true # Enable logging and performance insights
```
Tip
You can also configure your API key using the `HONEYBADGER_API_KEY` environment variable:
```sh
export HONEYBADGER_API_KEY="PROJECT_API_KEY"
```
If you use this method, you can omit the `api_key` option from your configuration.
See the [Configuration reference](/lib/elixir/reference/configuration/) for additional info.
## Testing your installation
[Section titled “Testing your installation”](#testing-your-installation)
Note
Honeybadger does not report errors in `dev` and `test` environments by default. To enable reporting in development environments, temporarily add `exclude_envs: []` to your Honeybadger config.
To test your installation, fire up `iex -S mix`, then run:
```elixir
Honeybadger.notify("Hello Elixir!")
```
If Honeybadger is configured correctly, you should see a new error report in your Honeybadger project dashboard.
After you’ve tested your Honeybadger installation, you may want to configure one or more of the following integrations to automatically report errors.
## Enabling automatic error reporting
[Section titled “Enabling automatic error reporting”](#enabling-automatic-error-reporting)
The Honeybadger package can be used as a Plug alongside your Phoenix applications, as a logger backend, and/or as a standalone client for sprinkling in exception notifications where they are needed.
The Honeybadger Plug adds a [Plug.ErrorHandler](https://github.com/elixir-lang/plug/blob/master/lib/plug/error_handler.ex) to your pipeline. Simply `use` the `Honeybadger.Plug` module inside of a Plug or Phoenix.Router and any crashes will be automatically reported to Honeybadger. It’s best to `use Honeybadger.Plug` **after the Router plugs** so that exceptions due to non-matching routes are not reported to Honeybadger.
### Phoenix example
[Section titled “Phoenix example”](#phoenix-example)
```elixir
defmodule MyPhoenixApp.Router do
use MyPhoenixApp.Web, :router
use Honeybadger.Plug
pipeline :browser do
[...]
end
end
```
### Plug example
[Section titled “Plug example”](#plug-example)
```elixir
defmodule MyPlugApp do
use Plug.Router
use Honeybadger.Plug
[... the rest of your plug ...]
end
```
### Configuring Elixir’s logger
[Section titled “Configuring Elixir’s logger”](#configuring-elixirs-logger)
When configured, Honeybadger will report errors for any [SASL](http://www.erlang.org/doc/apps/sasl/error_logging.html)-compliant processes when they crash. Just set the `use_logger` option to `true` in your application’s `config.exs` and you’re good to go:
```elixir
config :honeybadger,
use_logger: true
```
## Manually reporting errors
[Section titled “Manually reporting errors”](#manually-reporting-errors)
You can use the `Honeybadger.notify/2` function to manually report rescued exceptions:
```elixir
try do
# Buggy code goes here
rescue
exception ->
Honeybadger.notify(exception, stacktrace: __STACKTRACE__)
end
```
You can also pass a string message to the `notify` function (the second argument is optional):
```elixir
Honeybadger.notify("Sign in failed", metadata: %{
user_id: current_user.id
})
```
See [Reporting Errors](/lib/elixir/errors/reporting-errors/) for more information.
## Reporting custom events
[Section titled “Reporting custom events”](#reporting-custom-events)
Use the `Honeybadger.event/1` and `Honeybadger.event/2` functions to send events to [Honeybadger Insights](/guides/insights/) for logging and performance monitoring:
```elixir
Honeybadger.event(%{
event_type: "user_created",
user: user.id
})
# Honeybadger.event/2 is a shorthand that automatically adds the event_type
# property to the event:
Honeybadger.event("project_deleted", %{
project: project.name
})
```
See [Capturing Logs and Events](/lib/elixir/insights/capturing-logs-and-events/) for more details.
## Sending logs from your infrastructure
[Section titled “Sending logs from your infrastructure”](#sending-logs-from-your-infrastructure)
Honeybadger isn’t just for errors and application data! You can use our [syslog](/guides/insights/integrations/systemd/), [Vector](/guides/insights/integrations/log-files/), or [PaaS integrations](/guides/insights/#adding-data-from-other-sources) to send additional data from your infrastructure to [Honeybadger Insights](/guides/insights/), where you can query, visualize, and analyze all of your production data in one place.
## Version requirements
[Section titled “Version requirements”](#version-requirements)
See [Supported Versions](/lib/elixir/reference/supported-versions/).
# Configuration
> Complete configuration reference for Honeybadger's Elixir library with all available options and settings.
You can set configuration options in `config.exs`. It looks like this:
```elixir
config :honeybadger,
api_key: "PROJECT_API_KEY",
environment_name: :prod
```
If you’d rather read, eg., `environment_name` from the OS environment, you can do like this:
```elixir
config :honeybadger,
environment_name: {:system, "HONEYBADGER_ENV"},
revision: {:system, "HEROKU_SLUG_COMMIT"}
```
*NOTE: This works only for the string options, and `environment_name`.*
Here are all of the options you can pass in the keyword list:
| Name | Description | Default |
| -------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `app` | Name of your app’s OTP Application as an atom | `Mix.Project.config[:app]` |
| `api_key` | Your application’s Honeybadger API key | `System.get_env("HONEYBADGER_API_KEY"))` |
| `environment_name` | (required) The name of the environment your app is running in. | `:prod` |
| `exclude_errors` | Filters out errors from being sent to Honeybadger | `[]` |
| `exclude_envs` | Environments that you want to disable Honeybadger notifications | `[:dev, :test]` |
| `hostname` | Hostname of the system your application is running on | `:inet.gethostname` |
| `origin` | URL for the Honeybadger API | `"https://api.honeybadger.io"` |
| `project_root` | Directory root for where your application is running | `System.cwd/0` |
| `revision` | The project’s git revision | `nil` |
| `filter` | Module implementing `Honeybadger.Filter` to filter data before sending to Honeybadger.io | `Honeybadger.Filter.Default` |
| `filter_keys` | A list of keywords (atoms) to filter. Only valid if `filter` is `Honeybadger.Filter.Default` | `[:password, :credit_card, :__changed__, :flash, :_csrf_token]` |
| `filter_args` | If true, will remove function arguments in backtraces | `true` |
| `filter_disable_url` | If true, will remove the request url | `false` |
| `filter_disable_session` | If true, will remove the request session | `false` |
| `filter_disable_params` | If true, will remove the request params | `false` |
| `filter_disable_assigns` | If true, will remove the live\_view event assigns | `false` |
| `fingerprint_adapter` | Implementation of FingerprintAdapter behaviour | |
| `notice_filter` | Module implementing `Honeybadger.NoticeFilter`. If `nil`, no filtering is done. | `Honeybadger.NoticeFilter.Default` |
| `sasl_logging_only` | If true, will notifiy for SASL errors but not Logger calls | `true` |
| `use_logger` | Enable the Honeybadger Logger for handling errors outside of web requests | `true` |
| `ignored_domains` | Add domains to ignore Error events in `Honeybadger.Logger`. | `[:cowboy]` |
| `breadcrumbs_enabled` | Enable breadcrumb event tracking | `false` |
| `ecto_repos` | Modules with implemented Ecto.Repo behaviour for tracking SQL breadcrumb events | `[]` |
| `event_filter` | Module implementing `Honeybadger.EventFilter`. If `nil`, no filtering is done. | `Honeybadger.EventFilter.Default` |
| `insights_enabled` | Enable sending automatic events to Honeybadger Insights | `false` |
| `insights_config` | Specific library Configuration for Honeybadger Insights. | `%{}` |
| `http_adapter` | Module implementing `Honeybadger.HttpAdapter` to send data to Honeybadger.io | Any available adapter (`Req`, `hackney`) |
| `events_worker_enabled` | Enable sending events in a separate process | `true` |
| `events_max_batch_retries` | Maximum number of retries for sending events | `3` |
| `events_batch_size` | Maximum number of events to send in a single batch | `1000` |
| `events_max_queue_size` | Maximum number of events to queue before dropping | `10000` |
| `events_timeout` | Timeout in milliseconds for sending events | `5000` |
| `events_throttle_wait` | Time in milliseconds to wait before retrying a failed batch | `60000` |
## HTTP adapters
[Section titled “HTTP adapters”](#http-adapters)
The HTTP client used to send data to Honeybadger can be customized. We will use either `Req` or `hackney` (in that order) by default if they are loaded. If you want to use a different HTTP client, you can set the `http_adapter` configuration option to any of our pre-built adapter modules.
```elixir
config :honeybadger,
# Without options
http_adapter: Honeybadger.HTTPAdapter.Hackney
# With options
http_adapter: {Honeybadger.HTTPAdapter.Hackney, [...]}
```
You can also implement your own HTTP adapter to send data to Honeybadger. The adapter must implement the `Honeybadger.HttpAdapter` behaviour.
# Supported Versions
> View supported Elixir and Phoenix versions for Honeybadger's error tracking and application monitoring library.
The support tables below are for the latest version of the Honeybadger package, which aims to support all maintained (non-EOL) versions of Elixir and supported frameworks. If you’re using an older version of Elixir or your framework, you may need to install an older version of the package.
| Library | Supported Version | Notes |
| ------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| Erlang | >= 24.0 | |
| Elixir | >= 1.15 | |
| Plug | >= 1.10 | |
| Phoenix | >= 1.0 | This is an optional dependency and the version requirement applies only if you are using Phoenix. |
# Frequently asked questions
> Find answers to frequently asked questions about Honeybadger's Elixir library for error tracking and application monitoring.
## Why aren’t my errors being reported?
[Section titled “Why aren’t my errors being reported?”](#why-arent-my-errors-being-reported)
The most common reason for errors not being reported is that the app is in a development environment. See the [Environments](/lib/elixir/errors/environments/#development-environments) chapter in the **Error Tracking** guide for more information.
The second most common reason is that the error being reported is covered by the [exclude\_errors list](/lib/elixir/errors/reducing-noise/).
If neither of these is the issue, check out the [Troubleshooting guide](/lib/elixir/support/troubleshooting/#all-errors-are-not-reported).
## Why aren’t I getting notifications?
[Section titled “Why aren’t I getting notifications?”](#why-arent-i-getting-notifications)
By default we only send notifications the first time an exception happens, and when it re-occurs after being marked resolved. If an exception happens 100 times, but was never resolved you’ll only get 1 email about it.
# Troubleshooting
> Troubleshoot common issues with Honeybadger's Elixir error tracking and application monitoring library and resolve integration problems.
Common issues/workarounds for [`honeybadger-elixir`](https://github.com/honeybadger-io/honeybadger-elixir) are documented here. If you don’t find a solution to your problem here or in our [support documentation](/lib/elixir/#getting-support), email and we’ll assist you!
## Before you start troubleshooting
[Section titled “Before you start troubleshooting”](#before-you-start-troubleshooting)
1. Make sure you are on the latest version of [honeybadger-elixir](https://hexdocs.pm/honeybadger/).
### All errors are not reported
[Section titled “All errors are not reported”](#all-errors-are-not-reported)
If *no* errors are reported (even [manually via `Honeybadger.notify`](/lib/elixir/errors/reporting-errors/)):
1. [Is the `api_key` config option configured?](/lib/elixir/reference/configuration/)
2. [Are you in an excluded environment configured by `exclude_envs`?](/lib/elixir/errors/environments/#development-environments)
### Some errors are not reported
[Section titled “Some errors are not reported”](#some-errors-are-not-reported)
1. [Is the error ignored via config?](/lib/elixir/errors/reducing-noise/)
# Honeybadger for Go
> Honeybadger monitors your Go applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** \~5 minutes
Hi there! You’ve found Honeybadger’s guide to **Go exception and error tracking**. Once installed, Honeybadger will automatically report errors from your Go application.
## Getting started
[Section titled “Getting started”](#getting-started)
[Source Code](https://github.com/honeybadger-io/honeybadger-go)
### 1. Install the library
[Section titled “1. Install the library”](#1-install-the-library)
To install, grab the package from GitHub:
```sh
go get github.com/honeybadger-io/honeybadger-go
```
Then add an import to your application code:
```go
import "github.com/honeybadger-io/honeybadger-go"
```
### 2. Set your API key
[Section titled “2. Set your API key”](#2-set-your-api-key)
Finally, configure your API key:
```go
honeybadger.Configure(honeybadger.Configuration{APIKey: "PROJECT_API_KEY"})
```
You can also configure Honeybadger via environment variables. See [Configuration](#configuration) for more information.
### 3. Enable automatic panic reporting
[Section titled “3. Enable automatic panic reporting”](#3-enable-automatic-panic-reporting)
#### Panics during HTTP requests
[Section titled “Panics during HTTP requests”](#panics-during-http-requests)
To automatically report panics which happen during an HTTP request, wrap your `http.Handler` function with `honeybadger.Handler`:
```go
log.Fatal(http.ListenAndServe(":8080", honeybadger.Handler(handler)))
```
Request data such as cookies and params will automatically be reported with errors which happen inside `honeybadger.Handler`. Make sure you recover from panics after honeybadger’s Handler has been executed to ensure all panics are reported.
#### Unhandled panics
[Section titled “Unhandled panics”](#unhandled-panics)
To report all unhandled panics which happen in your application the following can be added to `main()`:
```go
func main() {
defer honeybadger.Monitor()
// application code...
}
```
#### Manually reporting errors
[Section titled “Manually reporting errors”](#manually-reporting-errors)
To report an error manually, use `honeybadger.Notify`:
```go
if err != nil {
honeybadger.Notify(err)
}
```
## Configuration
[Section titled “Configuration”](#configuration)
To set configuration options, use the `honeybadger.Configuration` method, like so:
```go
honeybadger.Configure(honeybadger.Configuration{
APIKey: "PROJECT_API_KEY",
Env: "staging"
})
```
The following options are available to you:
| Name | Type | Default | Example | Environment variable |
| -------- | --------------------- | ----------------------------------- | ------------------------------------ | ----------------------------------- |
| APIKey | `string` | `""` | `"badger01"` | `HONEYBADGER_API_KEY` |
| Root | `string` | The current working directory | `"/path/to/project"` | `HONEYBADGER_ROOT` |
| Env | `string` | `""` | `"production"` | `HONEYBADGER_ENV` |
| Hostname | `string` | The hostname of the current server. | `"badger01"` | `HONEYBADGER_HOSTNAME` |
| Endpoint | `string` | `"https://api.honeybadger.io"` | `"https://honeybadger.example.com/"` | `HONEYBADGER_ENDPOINT` |
| Sync | `bool` | false | `true` | `HONEYBADGER_SYNC` |
| Timeout | `time.Duration` | 3 seconds | `10 * time.Second` | `HONEYBADGER_TIMEOUT` (nanoseconds) |
| Logger | `honeybadger.Logger` | Logs to stderr | `CustomLogger{}` | n/a |
| Backend | `honeybadger.Backend` | HTTP backend | `CustomBackend{}` | n/a |
## Public interface
[Section titled “Public interface”](#public-interface)
### `honeybadger.Notify()`: Send an error to Honeybadger.
[Section titled “honeybadger.Notify(): Send an error to Honeybadger.”](#honeybadgernotify-send-an-error-to-honeybadger)
If you’ve handled a panic in your code, but would still like to report the error to Honeybadger, this is the method for you.
#### Examples:
[Section titled “Examples:”](#examples)
```go
if err != nil {
honeybadger.Notify(err)
}
```
You can also add local context using an optional second argument when calling `honeybadger.Notify`:
```go
honeybadger.Notify(err, honeybadger.Context{"user_id": 2})
```
Honeybadger uses the error’s class name to group similar errors together. If your error classes are often generic (such as `errors.errorString`), you can improve grouping by overriding the default with something more unique:
```go
honeybadger.Notify(err, honeybadger.ErrorClass{"CustomClassName"})
```
To override grouping entirely, you can send a custom fingerprint. All errors with the same fingerprint will be grouped together:
```go
honeybadger.Notify(err, honeybadger.Fingerprint{"A unique string"})
```
To tag errors in Honeybadger:
```go
honeybadger.Notify(err, honeybadger.Tags{"timeout", "http"})
```
***
### `honeybadger.SetContext()`: Set metadata to be sent if an error occurs
[Section titled “honeybadger.SetContext(): Set metadata to be sent if an error occurs”](#honeybadgersetcontext-set-metadata-to-be-sent-if-an-error-occurs)
This method lets you set context data that will be sent if an error should occur.
For example, it’s often useful to record the current user’s ID when an error occurs in a web app. To do that, just use `SetContext` to set the user id on each request. If an error occurs, the id will be reported with it.
**Note**: This method is currently shared across goroutines, and therefore may not be optimal for use in highly concurrent use cases, such as HTTP requests. See [issue #35](https://github.com/honeybadger-io/honeybadger-go/issues/35).
#### Examples:
[Section titled “Examples:”](#examples-1)
```go
honeybadger.SetContext(honeybadger.Context{
"user_id": 1,
})
```
***
### `defer honeybadger.Monitor()`: Automatically report panics from your functions
[Section titled “defer honeybadger.Monitor(): Automatically report panics from your functions”](#defer-honeybadgermonitor-automatically-report-panics-from-your-functions)
To automatically report panics in your functions or methods, add `defer honeybadger.Monitor()` to the beginning of the function or method you wish to monitor.
#### Examples:
[Section titled “Examples:”](#examples-2)
```go
func risky() {
defer honeybadger.Monitor()
// risky business logic...
}
```
**Important:** `honeybadger.Monitor()` will re-panic after it reports the error, so make sure that it is only called once before recovering from the panic (or allowing the process to crash).
***
### `honeybadger.BeforeNotify()`: Add a callback to skip or modify error notification.
[Section titled “honeybadger.BeforeNotify(): Add a callback to skip or modify error notification.”](#honeybadgerbeforenotify-add-a-callback-to-skip-or-modify-error-notification)
Sometimes you may want to modify the data sent to Honeybadger right before an error notification is sent, or skip the notification entirely. To do so, add a callback using `honeybadger.BeforeNotify()`.
#### Examples:
[Section titled “Examples:”](#examples-3)
```go
honeybadger.BeforeNotify(
func(notice *honeybadger.Notice) error {
if notice.ErrorClass == "SkippedError" {
return fmt.Errorf("Skipping this notification")
}
// Return nil to send notification for all other classes.
return nil
}
)
```
To modify information:
```go
honeybadger.BeforeNotify(
func(notice *honeybadger.Notice) error {
// Errors in Honeybadger will always have the class name "GenericError".
notice.ErrorClass = "GenericError"
return nil
}
)
```
***
### `honeybadger.NewNullBackend()`: Disable data reporting.
[Section titled “honeybadger.NewNullBackend(): Disable data reporting.”](#honeybadgernewnullbackend-disable-data-reporting)
`NewNullBackend` creates a backend which swallows all errors and does not send them to Honeybadger. This is useful for development and testing to disable sending unnecessary errors.
#### Examples:
[Section titled “Examples:”](#examples-4)
```go
honeybadger.Configure(honeybadger.Configuration{Backend: honeybadger.NewNullBackend()})
```
***
## Sample application
[Section titled “Sample application”](#sample-application)
If you’d like to see the library in action before you integrate it with your apps, check out our [sample application](https://github.com/honeybadger-io/crywolf-go).
You can deploy the sample app to your Heroku account by clicking this button:
[](https://heroku.com/deploy?template=https://github.com/honeybadger-io/crywolf-go)
Don’t forget to destroy the Heroku app after you’re done so that you aren’t charged for usage.
The code for the sample app is [available on Github](https://github.com/honeybadger-io/crywolf-go), in case you’d like to read through it, or run it locally.
# Honeybadger for Java
> Honeybadger monitors your Java applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** \~10 minutes
Hi there! You’ve found Honeybadger’s guide to **Java exception and error tracking**. Once installed, Honeybadger will automatically report errors from your Java application.
## Getting started
[Section titled “Getting started”](#getting-started)
[Source Code](https://github.com/honeybadger-io/honeybadger-java) • [Maven](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.honeybadger%22)
Honeybadger works out of the box with many popular Java frameworks. Installation is just a matter of including the jar library and setting your API key. In this section, we’ll cover the basics. More advanced installations are covered later.
### 1. Install the jar
[Section titled “1. Install the jar”](#1-install-the-jar)
The first step is to add the honeybadger jar to your dependency manager (Maven, SBT, Gradle, Ivy, etc). In the case of Maven, you would add it as so:
```xml
io.honeybadger
honeybadger-java
LATEST
```
In the case of SBT:
```plaintext
libraryDependencies += "io.honeybadger" % "honeybadger-java" % "]1,)"
```
For other dependency managers an example is provided on the [Maven Central site](https://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22io.honeybadger%22%20AND%20a%3A%22honeybadger-java%22).
If you are not using a dependency manager, download the jar directly and add it to your classpath.
### 2. Install a slf4j compatible logging library or binding in your project
[Section titled “2. Install a slf4j compatible logging library or binding in your project”](#2-install-a-slf4j-compatible-logging-library-or-binding-in-your-project)
*Note*: If you are using [Spring Boot](http://projects.spring.io/spring-boot/) or the [Play Framework](https://www.playframework.com/), a slf4j compatible logger is installed by default.
All dependencies needed for running are included in the distributed JAR with one exception - slf4j-api. We expect that you are using some logging library and that you have imported the sl4j-api in order to provide a common interface for the logger to imported libraries.
Almost every logging library provides a means for it to be compatible with the slf4j API. These are two good candidates if you aren’t sure about which one to choose:
* [Logback](http://logback.qos.ch/)
* [log4j2](http://logging.apache.org/log4j/2.x/log4j-slf4j-impl/index.html)
### 3. Set your API key and configuration parameters
[Section titled “3. Set your API key and configuration parameters”](#3-set-your-api-key-and-configuration-parameters)
Next, you’ll set the API key and some configuration parameters for this project.
#### Stand-alone usage
[Section titled “Stand-alone usage”](#stand-alone-usage)
If you want to send all unhandled errors to Honeybadger and have them logged to slf4j via the error log level, you will need to set the correct system properties (or provide a [ConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/ConfigContext.java)) and add a single line to the thread in which you want to register the error handler.
A typical stand-alone implementation may look like:
```java
import io.honeybadger.reporter.HoneybadgerUncaughtExceptionHandler;
public class MyApp {
public static void main(String argv[]) {
HoneybadgerUncaughtExceptionHandler.registerAsUncaughtExceptionHandler();
// The rest of the application goes here
}
}
```
You would invoke it with the `-Dhoneybadger.api_key=` system parameter and any other configuration values via system parameters it would load with the correct state. It would then register itself as the default error handler.
#### Servlet usage
[Section titled “Servlet usage”](#servlet-usage)
A servlet based implementation may look like:
In your web.xml file:
```xml
HoneybadgerFilter
io.honeybadger.reporter.servlet.HoneybadgerFilter
honeybadger.api_key
PROJECT_API_KEY
honeybadger.excluded_sys_props
bonecp.password,bonecp.username
honeybadger.excluded_exception_classes
org.apache.catalina.connector.ClientAbortException
honeybadger.display_feedback_form
false
HoneybadgerFilter
/*
```
Note
If you have other code executing in your servlet-based application that doesn’t go through the servlet interface, you will want to register an exception handler for it in order to report errors to Honeybadger. See the *Stand-alone Usage* section.
#### Play Framework usage
[Section titled “Play Framework usage”](#play-framework-usage)
This library has been tested against Play 2.4.2. After adding Hondeybadger as a dependency to your dependency manager as explained in the [Install the jar section](#1-install-the-jar), you can enable Honeybadger as an error handler by adding the following lines to your conf/application.conf file:
```plaintext
honeybadger.api_key = [Your project API key]
# You can add any of the Honeybadger configuration parameters here directly
# honeybadger.excluded_exception_classes = com.myorg.AnnoyingException
play.http.errorHandler = io.honeybadger.reporter.play.HoneybadgerErrorHandler
```
This will allow the library to wrap the default error handler implementation and pass around Honeybadger error ids instead of the default Play error ids.
#### Spring Framework usage
[Section titled “Spring Framework usage”](#spring-framework-usage)
This library has been tested against Spring 4.2.2 using Spring Boot. After adding Honeybadger as a dependency to your dependency manager as explained in the [Install the jar section](#1-install-the-jar), you can enable Honeybadger as an error handler by adding the `honeybadger.api_key` configuration parameter to your [Spring configuration](http://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html). Spring allows for many different vectors of configuration and it is beyond the scope of this document to describe all of them. For example, if you were using a file-based application configuration, you would need to add your Honeybadger configuration parameters as follows:
```plaintext
ENV = production
honeybadger.api_key = [Your project API key]
honeybadger.excluded_exception_classes = com.myorg.AnnoyingException
```
*Note*: Spring doesn’t support the concept of a single environment name. Rather, it supports [a pattern of using multiple profiles](http://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-profiles.html) to determine the runtime configuration. This pattern doesn’t map nicely to Honeybadger’s configuration, so you will need to define `ENV` or `JAVA_ENV` within your configuration in order for it to map properly to Honeybadger’s way of doing things.
## Configuration
[Section titled “Configuration”](#configuration)
### Advanced configuration
[Section titled “Advanced configuration”](#advanced-configuration)
There are a few ways to configure the Honeybadger library. Each one of the ways is implemented as a [ConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/ConfigContext.java) that can be passed in the constructor of the [HoneybadgerReporter](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/HoneybadgerReporter.java) class. The implementations available are:
* [DefaultsConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/DefaultsConfigContext.java) - This configuration context provides defaults that can be read by other context implementations.
* [MapConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/MapConfigContext.java) - This reads configuration from a Map that is supplied to its constructor.
* [PlayConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/PlayConfigContext.java) - This reads configuration from the Play Framework’s internal configuration mechanism.
* [ServletFilterConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/ServletFilterConfigContext.java) - This reads configuration from a servlet filter configuration.
* [SpringConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/SpringConfigContext.java) - This reads configuration from the Spring framework’s internal configuration mechanism.
* [StandardConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/StandardConfigContext.java) - This reads configuration from the system parameters, environment variables and defaults and is **the default configuration provider**.
* [SystemSettingsConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/SystemSettingsConfigContext.java) - This reads configuration purely from system settings.
#### Configuring with environment variables or system properties (12-factor style)
[Section titled “Configuring with environment variables or system properties (12-factor style)”](#configuring-with-environment-variables-or-system-properties-12-factor-style)
All configuration options can also be read from environment variables or [Java system properties](https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html) when using the default [StandardConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/StandardConfigContext.java). Framework specific configuration contexts use of environment variables or system properties depends on the framework’s implementation.
### Configuration options
[Section titled “Configuration options”](#configuration-options)
\| Option Details | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | --- | | **CORE** | | | | | **Name**: `ENV` or `JAVA_ENV`\
**Type**: String\
**Required**: No\
**Default**: `unknown`\
**Sample Value**: `production` | String sent to Honeybadger indicating running environment (eg development, test, staging, production, etc). | | **Name**: `honeybadger.api_key` or `HONEYBADGER_API_KEY`\
**Type**: String\
**Required**: Yes\
**Default**: N/A\
**Sample Value**: `29facd41` | The API key found in the settings tab in the Honeybadger UI. | | **Name**: `honeybadger.application_package`\
**Type**: String\
**Required**: No\
**Default**: N/A\
**Sample Value**: `my.app.package` | Java application package name used to indicate to Honeybadger what stacktraces are within the calling application’s code base. | | **Name**: `honeybadger.excluded_exception_classes`\
**Type**: CSV\
**Required**: No\
**Default**: N/A\
**Sample Value**: `co.foo.Exception`,\
`com.myorg.AnnoyingException` | CSV of Java classes in which errors are never sent to Honeybadger. This is useful for errors that are bubbled up from underlying frameworks or application servers like Tomcat. If you are using Tomcat, you may want to include `org.apache.catalina.connector.ClientAbortException`. | | **Name**: `honeybadger.excluded_sys_props`\
**Type**: CSV\
**Required**: No\
**Default**: `honeybadger.api_key`,\
`honeybadger.read_api_key`,\
`honeybadger.excluded_sys_props`,\
`honeybadger.url`\
**Sample Value**: `bonecp.password`,`bonecp.username` | CSV of Java system properties to exclude from being logged to Honeybadger. This is useful for excluding authentication information. Default values are automatically added. | | **Name**: `honeybadger.excluded_params`\
**Type**: CSV\
**Required**: No\
**Default**: N/A\
**Sample Value**: `auth_token`,\
`session_data`,\
`credit_card_number` | CSV of HTTP GET/POST query parameter values that will be excluded from the data sent to Honeybadger. This is useful for excluding authentication information, parameters that are too long or sensitive. | | **Name**: `honeybadger.maximum_retry_attempts`\
**Type**: Integer\
**Required**: No\
**Default**: 3\
**Sample Value:** 3 (must be >= 0) | Number of times HoneybadgerReporter will retry delivering an error report if the first attempt fails. (If set to 3, retries up to 3 times before giving up; if set to 0, tries once and gives up). | | | | | | | **FEEDBACK\_FORM** | | | | | **Name**: `honeybadger.display_feedback_form`\
**Type**: Boolean\
**Required**: No\
**Default**: `true`\
**Sample Value**: `false` | Displays the feedback form or JSON output when an error is thrown via a servlet call. | | **Name**: `honeybadger.feedback_form_template_path`\
**Type**: String\
**Required**: No\
**Default**: `templates/feedback-form.mustache`\
**Sample Value**: `templates/my-company.mustache` | Path within the class path to the mustache template that is displayed when an error occurs in a servlet request. | | | | | | | **NETWORK** | | | | | **Name**: `http.proxyHost`\
**Type**: String\
**Required**: No\
**Default**: N/A\
**Sample Value**: `localhost` | Standard Java system property for specifying the host to proxy all HTTP traffic through. | | **Name**: `http.proxyPort`\
**Type**: Integer\
**Required**: No\
**Default**: N/A\
**Sample Value**: `8888` | Standard Java system property for specifying the port to proxy all HTTP traffic through. | | **Name**: `honeybadger.socket_timeout`\
**Type**: Integer\
**Required**: No\
**Default**: N/A\
**Sample Value**: `60000` | Duration in milliseconds the HTTP socket can be open. | | **Name**: `honeybadger.connect_timeout`\
**Type**: Integer\
**Required**: No\
**Default**: N/A\
**Sample Value**: `60000` | Duration in milliseconds the HTTP socket is allowed to be in the connecting phase. | | | | | | | **DEVELOPMENT** | | | | | **Name**: `honeybadger.read_api_key` or `HONEYBADGER_READ_API_KEY`\
**Type**: String\
**Required**: When testing\
**Default**: N/A\
**Sample Value**: `qjcp6c7Nv9yR-bsvGZ77` | API key used to access the Read API. | | **Name**: `honeybadger.url`\
**Type**: String\
**Required**: No\
**Default**: `https://api.honeybadger.io`\
**Sample Value**: `https://other.hbapi.com` | URL to the Honeybadger API endpoint. You may want to access it without TLS in order to test with a proxy utility. |
## Custom error pages
[Section titled “Custom error pages”](#custom-error-pages)
The Honeybadger library has a few parameters that it looks for whenever it renders an error page. These can be used to display extra information about the error, or to ask the user for information about how they triggered the error. Most of the parameters just link to a resource file that can provide translations for the strings displayed to the user.
| Parameter | Description |
| ------------------------------------- | -------------------- |
| `honeybadger.feedback.error_title` | Title of page |
| `honeybadger.feedback.thanks` | Thank you message |
| `honeybadger.feedback.heading` | Prompt for feedback |
| `honeybadger.feedback.labels.name` | Explanation query |
| `honeybadger.feedback.labels.phone` | Phone number label |
| `honeybadger.feedback.labels.email` | Email label |
| `honeybadger.feedback.labels.comment` | Comments label |
| `honeybadger.feedback.submit` | Submit button label |
| `honeybadger.link` | HB link label |
| `honeybadger.powered_by` | Powered by HB text |
| `action` | Form POST URI |
| `error_id` | Honeybadger Error ID |
| `error_msg` | Error message |
The default template is setup to collect user feedback and to suppress the display of the error message. This behavior can be changed by placing a new [mustache template](https://mustache.github.io/) in your classpath and specifying its path via the `honeybadger.feedback_form_template_path` configuration option.
## Collecting user feedback (ServletFilter)
[Section titled “Collecting user feedback (ServletFilter)”](#collecting-user-feedback-servletfilter)
When an error is sent to Honeybadger, an HTML form can be generated so users can fill out relevant information that led up to that error. Feedback responses are displayed inline in the comments section on the fault detail page.
This behavior is enabled by default. To disable it set the configuration option `honeybadger.display_feedback_form` to `false`.
## Using tags
[Section titled “Using tags”](#using-tags)
This version of honeybadger-java supports sending tags, but it requires invoking a new overload of
```plaintext
NoticeReporter.reportError(Throwable error, Object request, String message, Iterable tags);
```
The existing error handler/filter implementations for Play, Spring, and Servlets do not currently invoke this variant. Those implementations can be overridden to customize the tagging behavior for your application.
## Supported JVM
[Section titled “Supported JVM”](#supported-jvm)
| JVM | Supported Version |
| ---------------- | ---------------------------- |
| Oracle (Java SE) | 1.7, 1.8, 9, \[10, 11, 12]\* |
| OpenJDK JDK/JRE | 1.7, 1.8, 9, 10, 11, 12 |
*Limitations*: We don’t currently test on Oracle’s commercially licensed VMs, due to new licensing rules. Accordingly, Oracle JDK after version 9 is supported on a best-effort basis only. If you discover a defect specific to their commercially-licensed VM, please [submit an issue](https://github.com/honeybadger-io/honeybadger-java/issues/new).
## Supported frameworks
[Section titled “Supported frameworks”](#supported-frameworks)
| Framework | Version | Notes |
| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| Servlet API | 4.0.1 | |
| Play Framework | 2.7.2 | We still call one deprecated API. See [Issue #110](https://github.com/honeybadger-io/honeybadger-java/issues/110) |
| Spring Framework | 5.1.7 | |
The Play Framework Spring are supported natively (install/configure the library and your done). For the Servlet API, you will need to configure a [servlet filter](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/servlet/HoneybadgerFilter.java) and enable it in your application. As for manual invocation of the API, you will need to configure your application to directly call the [reporter class](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/HoneybadgerReporter.java). You can find more information about this in the stand-alone usage section.
# Honeybadger for Node.js and JavaScript
> Complete guide to Honeybadger's JavaScript error tracking and application monitoring platform for browser and Node.js applications.
Hi there! You’ve found Honeybadger’s docs on **Universal JavaScript exception tracking**. In these guides we’re going to discuss [`honeybadger.js`](https://github.com/honeybadger-io/honeybadger-js) and how to use it to track exceptions in your **Client-side JavaScript and Node.js applications**.
## How you should read the docs
[Section titled “How you should read the docs”](#how-you-should-read-the-docs)
* For **client-side** JavaScript, start with the [Browser Integration Guide](/lib/javascript/integration/browser/).
* For **server-side** JavaScript, start with the [Node.js Integration Guide](/lib/javascript/integration/node/).
* The **How-To Guides** (in the left-hand navigation menu) are general guides on how to do things with the library, and should apply to all types of applications.
## Getting support
[Section titled “Getting support”](#getting-support)
If you’re having trouble working with the library (such as you aren’t receiving error reports when you should be):
1. Upgrade to the latest version if possible (you can find a list of bugfixes and other changes in the [CHANGELOG](https://github.com/honeybadger-io/honeybadger-js/blob/master/CHANGELOG.md))
2. Check out our [Frequently Asked Questions](/lib/javascript/support/faq/)
3. Run through the [Troubleshooting guide](/lib/javascript/support/troubleshooting/)
4. If you believe you’ve found a bug, [submit an issue on GitHub](https://github.com/honeybadger-io/honeybadger-js/issues/)
For all other problems, contact support for help:
# Capturing events with breadcrumbs
> Add breadcrumbs to JavaScript error reports to track events and user actions leading up to errors.
**Breadcrumbs** are events that happen right before an error occurs. Honeybadger captures [many types of breadcrumbs](#automatic-breadcrumbs) automatically, such as click events, console logs, and Ajax requests. You can enhance your ability to rapidly understand and fix your errors by capturing additional breadcrumbs throughout your application.
## Capturing breadcrumbs
[Section titled “Capturing breadcrumbs”](#capturing-breadcrumbs)
To capture a breadcrumb anywhere in your application:
```js
Honeybadger.addBreadcrumb("Sent Email", {
metadata: { user_id: user.id, body: body },
});
```
The first argument (`message`) is the only required data. In the UI, `message` is front and center in your breadcrumbs list, so we prefer a more terse description accompanied by rich metadata.
Here are the supported options when adding breadcrumbs:
| Option name | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `metadata` | A (*optional*) `Object` that contains any contextual data to help debugging. Must be a single-level object with simple primitives (strings, numbers, booleans) as values. |
| `category` | An (*optional*) `string` key used to group specific types of events. We primarily use this key to display a corresponding icon, however, you can use it for your own categorization if you like. |
### Categories
[Section titled “Categories”](#categories)
A Breadcrumb category is a top level property. It’s main purpose is to allow for display differences (icons & styling) in the UI. You may give a breadcrumb any category you wish. Unknown categories will default to the “custom” styling.
Here are the current categories and a brief description of how you might categorize certain activity:
| Category | Description |
| -------- | ------------------------------------------- |
| custom | Any other kind of breadcrumb |
| error | A thrown error |
| query | Access or Updates to any data or file store |
| job | Queueing or Working via a job system |
| request | Outbound / inbound requests |
| render | Any output or serialization via templates |
| log | Any messages logged |
| notice | A Honeybadger Notice |
## Automatic breadcrumbs
[Section titled “Automatic breadcrumbs”](#automatic-breadcrumbs)
Honeybadger captures the following breadcrumbs automatically by instrumenting browser features:
* Clicks
* Console logs
* Errors
* History/location changes
* Network requests (XHR and fetch)
## Enabling/disabling breadcrumbs
[Section titled “Enabling/disabling breadcrumbs”](#enablingdisabling-breadcrumbs)
Breadcrumbs are enabled by default. To disable breadcrumbs in your project:
```js
Honeybadger.configure({
// ...
breadcrumbsEnabled: false,
});
```
You can also enable/disable specific types of breadcrumbs:
```js
Honeybadger.configure({
breadcrumbsEnabled: {
dom: true,
network: true,
navigation: true,
console: true,
},
});
```
*Note: This configuration applies only on the first call to `Honeybadger.configure`.*
# Capturing cross-domain script errors
> Capture errors from cross-domain scripts in JavaScript applications with proper CORS configuration.
Honeybadger ignores cross-domain script errors by default because they contain no useful information. You can fix this by loading your scripts with [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
To enable CORS on your cross-domain scripts, add the CORS header to your web-server:
```plaintext
Access-Control-Allow-Origin: *
```
Then add the [`crossorigin`](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) attribute to your script tag:
```plaintext
```
Note
Errors that happen in development and test environments are not reported by default. To always report errors or to change the defaults, see [Environments and Versions](/lib/javascript/guides/environments-and-versions/#development-environments).
Here’s a video walkthrough of a basic, global installation:
[](https://honeybadger.wistia.com/medias/8wkvbipxxj)
### Installing via NPM/YARN
[Section titled “Installing via NPM/YARN”](#installing-via-npmyarn)
```plaintext
# npm
npm install @honeybadger-io/js --save
# yarn
yarn add @honeybadger-io/js
```
You can include *honeybadger.js* from the `node_modules` directory.
#### Bundling with ESM (esbuild), CommonJS (Browserify/Webpack), etc.
[Section titled “Bundling with ESM (esbuild), CommonJS (Browserify/Webpack), etc.”](#bundling-with-esm-esbuild-commonjs-browserifywebpack-etc)
```sh
// ES module
import Honeybadger from '@honeybadger-io/js';
// CommonJS
var Honeybadger = require("path/to/honeybadger");
Honeybadger.configure({
apiKey: 'PROJECT_API_KEY',
environment: 'production',
revision: 'git SHA/project version'
});
```
* See an [example browserify + honeybadger.js project](https://github.com/honeybadger-io/honeybadger-js/tree/master/examples/browserify).
* See an [example webpack + honeybadger.js project](https://github.com/honeybadger-io/honeybadger-js/tree/master/examples/webpack).
#### RequireJS (AMD)
[Section titled “RequireJS (AMD)”](#requirejs-amd)
```sh
requirejs(["path/to/honeybadger"], function(Honeybadger) {
Honeybadger.configure({
apiKey: 'PROJECT_API_KEY',
environment: 'production',
revision: 'git SHA/project version'
});
});
```
* See an [example requirejs + honeybadger.js project](https://github.com/honeybadger-io/honeybadger-js/tree/master/examples/requirejs).
## Reporting errors
[Section titled “Reporting errors”](#reporting-errors)
By default Honeybadger will report all uncaught exceptions automatically using our `window.onerror` handler.
You can also manually notify Honeybadger of errors and other events in your application code:
```javascript
try {
// ...error producing code...
} catch (error) {
Honeybadger.notify(error);
}
```
## 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 with `Honeybadger.context`:
```javascript
Honeybadger.setContext({
user_id: 123,
user_email: "user@example.com",
});
```
## Tracking deploys
[Section titled “Tracking deploys”](#tracking-deploys)
Honeybadger can also keep track of application deployments, and link errors to the version which the error occurred in. Here’s a simple `curl` script to record a deployment:
```sh
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
&& curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"
```
Be sure that the same revision is also configured in the *honeybadger.js* library. Read more about deploy tracking in the [API docs](/api/deployments/).
### Tracking deploys from Netlify
[Section titled “Tracking deploys from Netlify”](#tracking-deploys-from-netlify)
If you are deploying your site to Netlify, you can notify Honeybadger of deployments via Netlify’s webhooks. Go to the **Deploy notifications** section of the **Build & deploy** tab for your site settings, and choose to add an Outgoing webhook notification. Choose `Deploy succeeded` as the event to listen for, and use this format for your URL:
`https://api.honeybadger.io/v1/deploys/netlify?api_key=YOUR_HONEYBADGER_API_KEY_HERE`
The environment that will be reported to Honeybadger defaults to the Netlify environment that was deployed, but you can override that with `&environment=CUSTOM_ENV` in the webhook URL, if you like.
## Source map support
[Section titled “Source map support”](#source-map-support)
Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. See our [Source Map Guide](/lib/javascript/guides/using-source-maps/) for details.
## Collect user feedback
[Section titled “Collect user feedback”](#collect-user-feedback)
When an error occurs, a form can be shown to gather feedback from your users. Read more about this feature [here](/lib/javascript/guides/collecting-user-feedback/).
# Chrome Extension integration guide
> Honeybadger monitors your Chrome extensions for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **JavaScript error and exception tracking for your chrome extensions**. Once installed, Honeybadger will automatically report errors from your chrome extension.
## Installation
[Section titled “Installation”](#installation)
Code in Chrome extensions can run in different execution contexts, such as background scripts, content scripts, and popup or options pages. To monitor errors in all these contexts, you need to include the Honeybadger.js library in each of them.
Download the minified version of honeybadger.js to your source code from Honeybadger’s CDN (i.e. ) and save under in your extension’s source code (i.e. `/vendor`).
### Options and popup pages
[Section titled “Options and popup pages”](#options-and-popup-pages)
For the html (`options` or `popup`) pages, place the following code between the `` tags of your page:
```html
```
### Background scripts
[Section titled “Background scripts”](#background-scripts)
For background scripts, add the following code at the top of your background script:
```javascript
importScripts(chrome.runtime.getURL("vendor/honeybadger.ext.min.js"));
Honeybadger.configure({
apiKey: "PROJECT_API_KEY",
environment: "production",
revision: "git SHA/project version",
});
```
### Content scripts
[Section titled “Content scripts”](#content-scripts)
Finally, for content scripts, the manifest file should also be updated to include the Honeybadger library:
```json
{
"content_scripts": [
{
"matches": [""],
"js": ["vendor/honeybadger.ext.min.js", "content-script.js"]
}
]
}
```
Then, inside the `content-script.js` file, configure Honeybadger:
```javascript
Honeybadger.configure({
apiKey: "PROJECT_API_KEY",
environment: "production",
revision: "git SHA/project version",
});
```
Note
Errors that happen in development and test environments are not reported by default. To always report errors or to change the defaults, see [Environments and Versions](/lib/javascript/guides/environments-and-versions/#development-environments).
See an [example chrome extension + honeybadger.js project](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/js/examples/chrome-extension).
## Reporting errors
[Section titled “Reporting errors”](#reporting-errors)
By default Honeybadger will report all uncaught exceptions automatically using our `window.onerror` handler.
You can also manually notify Honeybadger of errors and other events in your application code:
```javascript
try {
// ...error producing code...
} catch (error) {
Honeybadger.notify(error);
}
```
## 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 with `Honeybadger.context`:
```javascript
Honeybadger.setContext({
user_id: 123,
user_email: "user@example.com",
});
```
## Tracking deploys
[Section titled “Tracking deploys”](#tracking-deploys)
Honeybadger can also keep track of application deployments, and link errors to the version which the error occurred in. Here’s a simple `curl` script to record a deployment:
```sh
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
&& curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"
```
Be sure that the same revision is also configured in the *honeybadger.js* library. Read more about deploy tracking in the [API docs](/api/deployments/).
## Source map support
[Section titled “Source map support”](#source-map-support)
Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. See our [Source Map Guide](/lib/javascript/guides/using-source-maps/) for details.
## Limitations
[Section titled “Limitations”](#limitations)
Google’s recent extension review policies forced us to remove the feature to [Collect User Feedback](/lib/javascript/guides/collecting-user-feedback/) in Chrome Extensions. If you are already using Honeybadger in your chrome extensions, please note that Google may reject your extension when you update it. In that case, please download a new build build from our [CDN](https://js.honeybadger.io/v6.12/honeybadger.ext.min.js) and replace the existing build in your extension. If you are using the Collect User Feedback feature in your extension and would like to have it in the future, please let us know!
# Ember integration guide
> Honeybadger monitors your Ember applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **Ember error and exception tracking**. Once installed, Honeybadger will automatically report errors from your Ember application.
## Installation
[Section titled “Installation”](#installation)
First, install *honeybadger.js*:
```plaintext
# npm
npm add @honeybadger-io/js --save
# yarn
yarn add @honeybadger-io/js
```
Then, configure Ember’s [`onerror`](https://guides.emberjs.com/release/configuring-ember/debugging/#toc_miscellaneous) handler to report errors to Honeybadger:
```js
// Import honeybadger.js
import * as Honeybadger from "@honeybadger-io/js";
// Configure honeybadger.js
Honeybadger.configure({
apiKey: "PROJECT_API_KEY",
environment: "production",
revision: "git SHA/project version",
});
// Configure Ember's onerror handler
Ember.onerror = function (error) {
Honeybadger.notify(error);
};
```
Note
Errors that happen in development and test environments are not reported by default. To always report errors or to change the defaults, see [Environments and Versions](/lib/javascript/guides/environments-and-versions/#development-environments).
## Reporting errors
[Section titled “Reporting errors”](#reporting-errors)
In addition to Ember’s `onerror` handler, Honeybadger will report all uncaught exceptions automatically using our `window.onerror` handler. To disable uncaught error reporting:
```js
Honeybadger.configure({ enableUncaught: false });
```
You can also manually notify Honeybadger of errors and other events in your application code:
```javascript
try {
// ...error producing code...
} catch (error) {
Honeybadger.notify(error);
}
```
See the [Reporting Errors How-to Guide](/lib/javascript/guides/reporting-errors/) for more info.
## 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 with `Honeybadger.context`:
```javascript
Honeybadger.setContext({
user_id: 123,
user_email: "user@example.com",
});
```
## Tracking deploys
[Section titled “Tracking deploys”](#tracking-deploys)
As with vanilla JavaScript applications, you can notify Honeybadger when you’ve deployed a new build. Honeybadger will associate an error report with a specific revision number (matching the ‘revision’ field in your *honeybadger.js* configuration).
Here’s a simple `curl` script to record a deployment:
```sh
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
&& curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"
```
Be sure that the same revision is also configured in the *honeybadger.js* library. Read more about deploy tracking in the [API docs](/api/deployments).
### Tracking deploys from Netlify
[Section titled “Tracking deploys from Netlify”](#tracking-deploys-from-netlify)
If you are deploying your site to Netlify, you can notify Honeybadger of deployments via Netlify’s webhooks. Go to the **Deploy notifications** section of the **Build & deploy** tab for your site settings, and choose to add an Outgoing webhook notification. Choose `Deploy succeeded` as the event to listen for, and use this format for your URL:
`https://api.honeybadger.io/v1/deploys/netlify?api_key=YOUR_HONEYBADGER_API_KEY_HERE`
The environment that will be reported to Honeybadger defaults to the Netlify environment that was deployed, but you can override that with `&environment=CUSTOM_ENV` in the webhook URL, if you like.
## Source map support
[Section titled “Source map support”](#source-map-support)
Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. See our [Source Map Guide](/lib/javascript/guides/using-source-maps/) for details.
## Collect user feedback
[Section titled “Collect user feedback”](#collect-user-feedback)
When an error occurs, a form can be shown to gather feedback from your users. Read more about this feature [here](/lib/javascript/guides/collecting-user-feedback/).
# Next.js integration guide
> Honeybadger monitors your Next.js applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 7 minutes
Hi there! You’ve found Honeybadger’s guide to **Next.js error and exception tracking**. Once installed, Honeybadger will automatically report errors from your Next.js application.
The `@honeybadger-io/nextjs` package utilizes the packages `@honeybadger-io/js`, `@honeybadger-io/react` and `@honeybadger-io/webpack` under the hood to provide a simplified integration package for Next.js applications. You can always refer to these packages’ documentation for more information and advanced configuration.
## Features
[Section titled “Features”](#features)
* App Router support (added with Next.js 13)
* Automatic reporting of uncaught exceptions (see [Limitations](#limitations))
* Breadcrumbs
* Source map upload to Honeybadger
* CLI command to generate Honeybadger configuration files for Next.js runtimes
## Installation
[Section titled “Installation”](#installation)
Add `@honeybadger-io/nextjs` and `@honeybadger-io/react` as dependencies.
```plaintext
# npm
npm add @honeybadger-io/react @honeybadger-io/nextjs --save
# yarn
yarn add @honeybadger-io/react @honeybadger-io/nextjs
```
## Configuration
[Section titled “Configuration”](#configuration)
Note
Honeybadger needs a configuration file for each Next.js runtime. Additionally, some more configuration in `next.config.js` is required to setup the runtime and upload source maps to Honeybadger. Even though you can configure each file separately, we recommend to use Honeybadger’s environment variables to set configuration values once: `NEXT_PUBLIC_HONEYBADGER_API_KEY` (Honeybadger API key), `NEXT_PUBLIC_HONEYBADGER_REVISION` (Revision of current deployment) and `NEXT_PUBLIC_HONEYBADGER_ASSETS_URL` (URL to your public assets).
Run the following command, which generates configuration files in your project root for each Next.js runtime:
```plaintext
npx honeybadger-copy-config-files
```
The following files will added to your project:
* `honeybadger.server.config.js` - Configuration file for Next.js server runtime
* `honeybadger.client.config.js` - Configuration file for Next.js client runtime
* `honeybadger.edge.config.js` - Configuration file for Next.js Edge runtime
* `pages/_error.[js|tsx]` - Next.js Pages Router custom error component - if *pages* folder exists
* `app/error.[js|tsx]` - Next.js App Router custom error component - if *app* folder exists
* `app/global-error.[js|tsx]` - Next.js App Router global error component - if *app* folder exists
**Note**: The `honeybadger.edge.config.js` file is necessary if you deploy your Next.js application to Vercel and use [Vercel Edge Functions](https://vercel.com/features/edge-functions). If not, you can safely remove this file.
**Note**: The script will create backups of any existing files.
In your `next.config.js`:
```javascript
const { setupHoneybadger } = require("@honeybadger-io/nextjs");
const moduleExports = {
// ... Your existing module.exports object goes here
};
// Showing default values
const honeybadgerNextJsConfig = {
// Disable source map upload (optional)
disableSourceMapUpload: false,
// Hide debug messages (optional)
silent: true,
// More information available at @honeybadger-io/webpack: https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/webpack
webpackPluginOptions: {
// Required if you want to upload source maps to Honeybadger
apiKey: process.env.NEXT_PUBLIC_HONEYBADGER_API_KEY,
// Required if you want to upload source maps to Honeybadger
assetsUrl: process.env.NEXT_PUBLIC_HONEYBADGER_ASSETS_URL,
revision: process.env.NEXT_PUBLIC_HONEYBADGER_REVISION,
endpoint: "https://api.honeybadger.io/v1/source_maps",
ignoreErrors: false,
retries: 3,
workerCount: 5,
deploy: {
environment:
process.env.NEXT_PUBLIC_VERCEL_ENV ||
process.env.VERCEL_ENV ||
process.env.NODE_ENV,
repository: "https://url.to.git.repository",
localUsername: "username",
},
},
};
module.exports = setupHoneybadger(moduleExports, honeybadgerNextJsConfig);
```
**Note**: If you want to upload source maps to Honeybadger, ensure that `disableSourceMapUpload` is set to `false` and that `apiKey` and `assetsUrl` properties are set in `webpackPluginOptions`.
**Note**: The value of `assetsUrl` should be the URL to your domain suffixed with `_next`. For example if you app is deployed on Vercel and has the domain `my-app.vercel.app`, the value of `assetsUrl` should be `https://my-app.vercel.app/_next`.
Optionally, you can use Honeybadger’s Error Boundary component to collect additional React contextual information for errors that occur in your React components. Simply wrap the `Component` prop in your `_app.js` file:
```jsx
import { Honeybadger, HoneybadgerErrorBoundary } from "@honeybadger-io/react";
function MyApp({ Component, pageProps }) {
return (
);
}
export default MyApp;
```
You can read more about Error Boundaries in the [React documentation](https://reactjs.org/docs/error-boundaries.html).
Note
Errors that happen in development and test environments are not reported by default. To always report errors or to change the defaults, see [Environments and Versions](/lib/javascript/guides/environments-and-versions/#development-environments).
## Reporting errors
[Section titled “Reporting errors”](#reporting-errors)
The above configuration will automatically report errors to Honeybadger in most cases (see [Limitations](#limitations)), but you can also report errors manually:
```javascript
import { Honeybadger } from "@honeybadger-io/react";
Honeybadger.notify(error);
```
## Identifying users
[Section titled “Identifying users”](#identifying-users)
Honeybadger can track which users have encountered each error. To identify the current user in error reports, add a user identifier and/or email address with `Honeybadger.setContext`:
```javascript
import { Honeybadger } from "@honeybadger-io/react";
Honeybadger.setContext({
user_id: 123,
user_email: "user@example.com",
});
```
## Sending additional context
[Section titled “Sending additional context”](#sending-additional-context)
Sometimes additional application state may be helpful for diagnosing errors. You can arbitrarily specify additional key/value pairs when you invoke `setContext`.
```javascript
import { Honeybadger } from "@honeybadger-io/react";
Honeybadger.setContext({
active_organization: 55,
custom_configuration: false,
});
```
## Clearing context
[Section titled “Clearing context”](#clearing-context)
If your user logs out or if your context changes during the React component lifetime, you can set new values as appropriate by invoking `setContext` again.
Additionally, if needed, you can clear the context by invoking `clear`:
```javascript
import { Honeybadger } from "@honeybadger-io/react";
// Set the context to {}
Honeybadger.clear();
```
## Advanced usage
[Section titled “Advanced usage”](#advanced-usage)
`@honeybadger-io/nextjs` is built on [@honeybadger-io/js](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/js) and [@honeybadger-io/react](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/react).
See the [Honeybadger JavaScript integration documentation](/lib/javascript/) for additional customization options, as well as the dedicated [React integration guide](/lib/javascript/integration/react/).
## Source map upload and tracking deploys
[Section titled “Source map upload and tracking deploys”](#source-map-upload-and-tracking-deploys)
Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. See our [Source Map Guide](/lib/javascript/guides/using-source-maps/) for details.
Fill in the values under `webpackPluginOptions` in your `next.config.js` file to upload source maps to Honeybadger.
You can notify Honeybadger when you’ve deployed a new build. Honeybadger will associate an error report with a specific revision number (matching the `revision` field in the configuration passed to `Honeybadger.configure`, found in one of your honeybadger.\[server|client|edge].config.js files). Set deploy information in your Honeybadger’s Next.js configuration under the `webpackPluginOptions.deploy` key.
For more information, see [@honeybadger-io/webpack](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/webpack) documentation.
## Collect User Feedback
[Section titled “Collect User Feedback”](#collect-user-feedback)
When an error occurs, a form can be shown to gather feedback from your users. Honeybadger can automatically show the form by setting the `showUserFeedbackFormOnError` prop to `true`:
```javascript
```
Read more about this feature [here](/lib/javascript/guides/collecting-user-feedback/).
## Limitations
[Section titled “Limitations”](#limitations)
The following limitations are known to exist and will be tackled in future releases:
* [Issue link](https://github.com/honeybadger-io/honeybadger-js/issues/1055): A custom error component is used to report uncaught exceptions to Honeybadger. This is necessary because Next.js does not provide a way to hook into the error handler. This is not a catch-all errors solution. If you are using the *Pages Router*, there are some caveats to this approach, as reported [here](https://nextjs.org/docs/advanced-features/custom-error-page#caveats). This is a limitation of Next.js, not Honeybadger’s Next.js integration. Errors thrown in middlewares or API routes will not be reported to Honeybadger, since when they reach the error component, the response status code is 404 and no error information is available. Additionally, there is an open [issue](https://github.com/vercel/next.js/issues/45535) about 404 being reported with Next.js apps deployed on Vercel, when they should be reported as 500. If you are using the *App Router*, these limitations do not apply, because errors thrown in middlewares or API routes do not reach the custom error component but are caught by the global `window.onerror` handler. However, some other server errors (i.e. from data fetching methods) will be reported with minimal information, since Next.js will send a [generic error message](https://nextjs.org/docs/app/building-your-application/routing/error-handling#handling-server-errors) to this component for better security.
* [Issue link](https://github.com/honeybadger-io/honeybadger-js/issues/1056): Source maps for the [Edge runtime](https://vercel.com/docs/concepts/functions/edge-functions/edge-runtime) are not supported yet.
## Sample applications
[Section titled “Sample applications”](#sample-applications)
Two sample applications are available in the [*examples*](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/nextjs/examples) folder. Follow the README instructions to run them.
# Node.js integration guide
> Honeybadger monitors your Node.js applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 3 minutes
Hi there! You’ve found Honeybadger’s guide to **Node.js error and exception tracking**. Once installed, Honeybadger will automatically report errors from your Node.js application.
Heads up!
Between callbacks, promises, event emitters, and timers, error-handling in Node.js is a complex and difficult field, but we’re here to help! Our Node.js library tries to catch as many different kinds of errors as possible with minimal configuration; if you encounter problems setting it up or find any gaps, feel free to [open an issue](https://github.com/honeybadger-io/honeybadger-js/issues/new).
## Installation
[Section titled “Installation”](#installation)
First, install the npm package:
```sh
npm install @honeybadger-io/js --save
```
Then, require the honeybadger module and configure your API key:
```javascript
const Honeybadger = require("@honeybadger-io/js");
Honeybadger.configure({
apiKey: "[ YOUR API KEY HERE ]",
});
```
By default Honeybadger will be notified automatically of all unhandled errors which crash your node processes. Many applications catch errors, however, so you may want to set up some additional framework integrations.
## Framework integrations
[Section titled “Framework integrations”](#framework-integrations)
### Express and Express-style frameworks
[Section titled “Express and Express-style frameworks”](#express-and-express-style-frameworks)
Errors which happen in [Express](http://expressjs.com/) or [Connect](https://github.com/senchalabs/connect#readme) apps can be automatically reported to Honeybadger by installing our middleware. The `requestHandler` middleware must be added before your other app middleware, while the `errorHandler` must be added after all app middleware and routes, but before any custom error handling middleware:
```javascript
app.use(Honeybadger.requestHandler); // Use *before* all other app middleware.
// Any other middleware and routes
app.use(myMiddleware);
app.get("/", (req, res) => {...});
app.use(Honeybadger.errorHandler); // Use *after* all other app middleware
// Your custom error handling middleware
app.use(myErrorMiddleware);
```
You can follow a similar pattern for most frameworks which use Express-style middleware:
#### Restify
[Section titled “Restify”](#restify)
```js
const server = restify.createServer();
server.use(Honeybadger.requestHandler);
// Other middleware and routes...
server.on("restifyError", Honeybadger.errorHandler);
```
#### Sails.js
[Section titled “Sails.js”](#sailsjs)
For Sails.js, use `Honeybadger.errorHandler` to report errors from within your [custom `serverError` response](https://sailsjs.com/documentation/concepts/extending-sails/custom-responses).
```js
const Honeybadger = require("@honeybadger-io/js");
module.exports = function serverError(optionalData) {
if (_.isError(optionalData)) {
Honeybadger.errorHandler(optionalData, this.req);
return res.status(500).send(optionalData.stack);
}
};
```
You should also add the `Honeybadger.requestHandler` at the start of your middleware chain so asynchronous context can be correctly tracked between requests:
```js
// in config/http.js
module.exports.http = {
middleware: {
order: [
"honeybadgerContext",
// other middleware...
],
honeybadgerContext: Honeybadger.requestHandler,
},
};
```
### Non-Express-style frameworks
[Section titled “Non-Express-style frameworks”](#non-express-style-frameworks)
For frameworks that don’t use Express-style middleware, Honeybadger will still capture unhandled exceptions automatically, but you may need to add a few lines of code to capture other kinds of errors and use the context feature properly. See the section on [Tracking Context](#tracking-context) below.
### AWS Lambda
[Section titled “AWS Lambda”](#aws-lambda)
To automatically report errors which happen in your [AWS Lambda](https://aws.amazon.com/lambda/) functions, wrap your Lambda handlers in `Honeybadger.lambdaHandler()`:
```javascript
async function myHandler(event, context) {
// ...
}
exports.handler = Honeybadger.lambdaHandler(myHandler);
```
Check out our [example AWS Lambda project](https://github.com/honeybadger-io/honeybadger-js/tree/master/examples/aws-lambda) for a list of handlers with different settings.
##### Timeout warning
[Section titled “Timeout warning”](#timeout-warning)
If your Lambda function hits its [time limit](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html#w329aad109b7b9), it will get killed by AWS Lambda without completing. Honeybadger can notify you when your function is about time out. By default, this will be when there are only 50 milliseconds left to reach the limit. You can override this with the `timeoutWarningThresholdMs` setting:
```javascript
Honeybadger.configure({
timeoutWarningThresholdMs: 1000,
});
```
You can disable the timeout warning with the `reportTimeoutWarning` setting:
```javascript
Honeybadger.configure({
reportTimeoutWarning: false,
});
```
To manually report errors in a serverless environment, use `Honeybadger.notifyAsync`. Read more below.
## Manually reporting errors
[Section titled “Manually reporting errors”](#manually-reporting-errors)
Honeybadger reports unhandled exceptions by default. You can also manually notify Honeybadger of errors and other events in your application code:
```javascript
try {
// ...error producing code...
} catch (error) {
Honeybadger.notify(error);
}
```
`Honeybadger.notify` implements a *fire-and-forget* approach, which means that you can call the function and continue execution in your application code without waiting for the error to be reported. This is OK for most applications, but in some environments this can cause problems when the execution environment could be terminated before the report is sent to Honeybadger. For this reason, you may use `Honeybadger.notifyAsync` which is a promise-based implementation of `notify` and will resolve only after the report is sent:
```javascript
async function doSomething() {
try {
// ...error producing code...
} catch (error) {
await Honeybadger.notifyAsync(error);
}
}
```
See the [full documentation](/lib/javascript/) for more options.
## Tracking context
[Section titled “Tracking context”](#tracking-context)
You can add contextual information to your error reports to make debugging easier:
```javascript
Honeybadger.setContext({
query: searchQuery,
});
```
When an error is captured (manually or automatically), the context will be sent along in the error report and displayed in the Context section of the Honeybadger UI.
Important
In apps like web servers that handle multiple requests at the same time, you need to properly isolate each request’s context. For middleware-based frameworks like Express, this is done automatically when you use the `requestHandler` middleware. For other frameworks, you’ll need to wrap your request and error handlers in `Honeybadger.withRequest()` method and pass in the request object. Here are examples in some popular frameworks:
### Fastify
[Section titled “Fastify”](#fastify)
Fastify doesn’t support middleware by default, but you can use the `preHandler` hook instead. You’ll also need to add a custom error handler (and be sure to wrap it in `Honeybadger.withRequest`):
```js
fastify.addHook("preHandler", Honeybadger.requestHandler);
fastify.setErrorHandler((err, req, reply) =>
Honeybadger.withRequest(req, () => {
Honeybadger.notify(err);
reply.send({ message: "error" });
}),
);
```
### AdonisJS
[Section titled “AdonisJS”](#adonisjs)
For AdonisJS, you’ll need to do three (easy) steps:
* Create a middleware that wraps your request handlers with `withRequest()`). You can generate a middleware with `adonis make:middleware HoneybadgerContext` (v4) or `node ace make:middleware HoneybadgerContext` (v5):
app/Middleware/HoneybadgerContext.js
```js
// Adonis v5: app/Middleware/HoneybadgerContext.ts
class HoneybadgerContext {
async handle({ request, response }, next) {
await Honeybadger.withRequest(request, next);
}
}
```
* Register the middleware:
```js
// Adonis v4: in start/kernel.js
const globalMiddleware = ["App/Middleware/HoneybadgerContext"];
// Adonis v5: in start/kernel.ts
Server.middleware.register([() => import("App/Middleware/HoneybadgerContext")]);
```
* In your exception handler’s `report()` method, make sure to use `withRequest()`. (On Adonis v4, you may need to generate an exception handler with `adonis make:ehandler`):
app/Exceptions/Handler.js
```js
// Adonis v5: app/Exceptions/Handler.ts
class ExceptionHandler extends BaseExceptionHandler {
// ...
async report(error, { request }) {
Honeybadger.withRequest(request, () => Honeybadger.notify(error));
}
}
```
### Hapi
[Section titled “Hapi”](#hapi)
In Hapi, you’ll need to wrap your request handlers in `withRequest`, as well as add an `onPreResponse` extension to report errors.
```javascript
server.route({
method: 'POST',
path: '/search',
handler: async (request, h) => Honeybadger.withRequest(request, () => {
Honeybadger.setContext({ query: request.payload.searchQuery });
return ...;
})
});
server.ext('onPreResponse', (request, h) => Honeybadger.withRequest(request, () => {
if (!request.response.isBoom) {
return h.continue;
}
Honeybadger.notify(request.response);
return h.continue;
}));
```
## 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 with `Honeybadger.setContext`:
```javascript
Honeybadger.setContext({
user_id: 123,
user_email: "user@example.com",
});
```
We’ll surface this info in a special “Affected Users” section in the Honeybadger UI.
## Tracking deploys
[Section titled “Tracking deploys”](#tracking-deploys)
Honeybadger can also keep track of application deployments, and link errors to the version which the error occurred in. Here’s a simple `curl` script to record a deployment:
```sh
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
&& curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"
```
Be sure that the same revision is also configured in the honeybadger.js library. Read more about deploy tracking in the [API docs](/api/deployments/).
## Uncaught exceptions
[Section titled “Uncaught exceptions”](#uncaught-exceptions)
Honeybadger’s default uncaught exception handler logs the error and exits the process after notifying Honeybadger of the uncaught exception. You can change the default handler by replacing the `afterUncaught` config callback with a new handler function. Honeybadger will still be notified before your handler is invoked. Note that it’s important to exit the process cleanly if you replace the handler; see [Warning: using ‘uncaughtException’ correctly](https://nodejs.org/api/process.html#process_warning_using_uncaughtexception_correctly) for additional information.
### Examples
[Section titled “Examples”](#examples)
```javascript
Honeybadger.configure({
afterUncaught: (err) => {
doSomethingWith(err);
process.exit(1);
},
});
```
### Disable Honeybadger’s uncaught error handler
[Section titled “Disable Honeybadger’s uncaught error handler”](#disable-honeybadgers-uncaught-error-handler)
To disable Honeybadger’s handler entirely (restoring Node’s default behavior for uncaught exceptions), use the `enableUncaught` option when calling `Honeybadger.configure`:
```javascript
Honeybadger.configure({
apiKey: '[ YOUR API KEY HERE ]'
enableUncaught: false
});
```
## Source map support
[Section titled “Source map support”](#source-map-support)
Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. See our [Source Map Guide](/lib/javascript/guides/using-source-maps/) for details.
Honeybadger also supports Node’s [experimental `--source-map-support` flag](https://nodejs.org/dist/latest-v14.x/docs/api/cli.html#cli_enable_source_maps) as of **version 14+**. If you run `node` with `--source-map-support` (and are generating source maps in your build), your stack traces should be automatically translated *before* they are sent to Honeybadger.
## Sample application
[Section titled “Sample application”](#sample-application)
If you’d like to see the library in action before you integrate it with your apps, check out our [sample Node.js/Express application](https://github.com/honeybadger-io/crywolf-node).
You can deploy the sample app to your Heroku account by clicking this button:
[](https://heroku.com/deploy?template=https://github.com/honeybadger-io/crywolf-node)
Don’t forget to destroy the Heroku app after you’re done so that you aren’t charged for usage.
The code for the sample app is [available on Github](https://github.com/honeybadger-io/crywolf-node), in case you’d like to read through it, or run it locally.
# React integration guide
> Honeybadger monitors your React applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **React error and exception tracking**. Once installed, Honeybadger will automatically report errors from your React application.
## Installation
[Section titled “Installation”](#installation)
Add *@honeybadger-io/react* as a dependency.
```plaintext
# npm
npm add @honeybadger-io/js @honeybadger-io/react --save
# yarn
yarn add @honeybadger-io/js @honeybadger-io/react
```
In your main.js:
```javascript
import React from "react";
import ReactDOM from "react-dom";
import "./index.css";
import App from "./App";
import { Honeybadger, HoneybadgerErrorBoundary } from "@honeybadger-io/react";
const config = {
apiKey: "PROJECT_API_KEY",
environment: "production",
revision: "git SHA/project version",
};
const honeybadger = Honeybadger.configure(config);
ReactDOM.render(
,
document.getElementById("root"),
);
```
Note
Errors that happen in development and test environments are not reported by default. To always report errors or to change the defaults, see [Environments and Versions](/lib/javascript/guides/environments-and-versions/#development-environments).
### `HoneyBadgerErrorBoundary` props
[Section titled “HoneyBadgerErrorBoundary props”](#honeybadgererrorboundary-props)
* `honeybadger`
The Honeybadger config object.
* `children`
Your root `` component.
* `ErrorComponent` (optional — default: “DefaultErrorComponent”)
The component that will be rendered in `ErrorBoundary` children’s place when an error is thrown during React rendering. The default value for this prop is the `DefaultErrorComponent`.
#### DefaultErrorComponent
[Section titled “DefaultErrorComponent”](#defaulterrorcomponent)
```jsx
class DefaultErrorComponent extends Component {
render() {
return (
An Error Occurred
{this.error}
{this.info}
);
}
}
```
## Reporting errors
[Section titled “Reporting errors”](#reporting-errors)
Using the example configuration above, you’ll install *@honeybadger-io/react* as React’s error handler.
Additionally, by default, an error handler for all JavaScript errors will be attached to the `window.onerror` handler for JavaScript errors that may originate from React components or other JavaScript on the page.
Because React doesn’t intercept all errors that may occur within a React component, errors that bubble up to the `window.onerror` handler may be missing some React component contextual information, but the stack trace will be available.
If, for some reason, you do not wish to install Honeybadger’s error handler on the global `window.onerror` handler, you may add `{ enableUncaught: false }` to the configuration you’re passing to `Honeybadger.configure`.
You may also manually report errors by directly invoking the [honeybadger.js](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/js) API.
```javascript
honeybadger.notify(error);
```
See the [full documentation](/lib/javascript/) for more options.
Note
React handles exceptions slightly differently in development mode than in production. As a result, in development mode only, the error boundary component you create will capture the error and add React context, but React will essentially re-throw the error and it will bubble up to the window\.onerror handler (without the React context data). This behavior will not occur when your React application is built for production.
## Identifying users
[Section titled “Identifying users”](#identifying-users)
Honeybadger can track which users have encountered each error. To identify the current user in error reports, add a user identifier and/or email address with `honeybadger.setContext`:
```javascript
honeybadger.setContext({
user_id: 123,
user_email: "user@example.com",
});
```
## Sending additional context
[Section titled “Sending additional context”](#sending-additional-context)
Sometimes additional application state may be helpful for diagnosing errors. You can arbitrarily specify additional key/value pairs when you invoke `setContext`.
```javascript
honeybadger.setContext({
active_organization: 55,
custom_configuration: false,
});
```
## Clearing context
[Section titled “Clearing context”](#clearing-context)
If your user logs out or if your context changes during the React component lifetime, you can set new values as appropriate by invoking `setContext` again.
Additionally, if needed, you can clear the context by invoking `clear`:
```javascript
// Set the context to {}
honeybadger.clear();
```
## Advanced usage
[Section titled “Advanced usage”](#advanced-usage)
*@honeybadger-io/react* is built on [honeybadger.js](https://github.com/honeybadger-io/honeybadger-js).
See the [Honeybadger JavaScript integration documentation](/lib/javascript/) for additional customization options.
## Tracking deploys
[Section titled “Tracking deploys”](#tracking-deploys)
As with vanilla JavaScript applications, you can notify Honeybadger when you’ve deployed a new build. Honeybadger will associate an error report with a specific revision number (matching the ‘revision’ field in the configuration passed to `Honeybadger.configure`).
Here’s a simple `curl` script to record a deployment:
```sh
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
&& curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"
```
Be sure that the same revision is also configured in the *@honeybadger-io/react* library. Read more about deploy tracking in the [API docs](/api/deployments/).
### Tracking deploys from Netlify
[Section titled “Tracking deploys from Netlify”](#tracking-deploys-from-netlify)
If you are deploying your site to Netlify, you can notify Honeybadger of deployments via Netlify’s webhooks. Go to the **Deploy notifications** section of the **Build & deploy** tab for your site settings, and choose to add an Outgoing webhook notification. Choose `Deploy succeeded` as the event to listen for, and use this format for your URL:
`https://api.honeybadger.io/v1/deploys/netlify?api_key=YOUR_HONEYBADGER_API_KEY_HERE`
The environment that will be reported to Honeybadger defaults to the Netlify environment that was deployed, but you can override that with `&environment=CUSTOM_ENV` in the webhook URL, if you like.
## Source map support
[Section titled “Source map support”](#source-map-support)
Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. See our [Source Map Guide](/lib/javascript/guides/using-source-maps/) for details.
## Collect user feedback
[Section titled “Collect user feedback”](#collect-user-feedback)
When an error occurs, a form can be shown to gather feedback from your users. Honeybadger can automatically show the form by setting the `showUserFeedbackFormOnError` prop to `true`:
```javascript
```
Read more about this feature [here](/lib/javascript/guides/collecting-user-feedback/).
## Sample application
[Section titled “Sample application”](#sample-application)
A minimal implementation is included in the [*example*](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/react/example) folder in the *@honeybadger-io/react* repository.
To run it from the command line, enter the following commands in your shell:
```bash
cd example
yarn install
REACT_APP_HONEYBADGER_API_KEY=yourkey yarn start
```
Observe the command-line output to determine the appropriate URL to connect to in your browser (usually `http://localhost:3000/`).
# Honeybadger for React Native
> Honeybadger monitors your React Native applications for errors and exceptions so that you can fix them wicked fast.
Note
This documentation is for version **6** or later. If you are using an earlier version, please see the [v5 documentation](/lib/javascript/integration/react-native-v5/).
Hi there! You’ve found Honeybadger’s guide to **React Native exception and error tracking**. Once installed, Honeybadger will automatically report errors from your React Native application.
## Installation
[Section titled “Installation”](#installation)
From the root directory of your React Native project, add *@honeybadger-io/react-native* as a dependency:
```shell
npm install "@honeybadger-io/react-native"
cd ios && pod install
```
The iOS step is required to properly add the library to the Xcode project through CocoaPods. Android doesn’t require a separate step.
Add the following to your **App.js** file to initialize the Honeybadger library.
```js
import Honeybadger from "@honeybadger-io/react-native";
export default function App() {
Honeybadger.configure({
apiKey: "[ YOUR API KEY HERE ]",
});
// ...
}
```
You can log into your [Honeybadger](https://app.honeybadger.io/) account to obtain your API key.
See the [Configuration Reference](/lib/javascript/reference/configuration/) for a full list of config options.
Note
Errors that happen in development and test environments are not reported by default. To always report errors or to change the defaults, see [Environments and Versions](/lib/javascript/guides/environments-and-versions/#development-environments).
## Reporting errors
[Section titled “Reporting errors”](#reporting-errors)
Uncaught iOS, Android, and JavaScript errors will be automatically reported to Honeybadger by default.
You may also manually report errors by directly invoking the [honeybadger.js](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/js) API.
```javascript
Honeybadger.notify(error);
```
See the [full documentation](/lib/javascript/guides/reporting-errors/) for more options.
## Identifying users
[Section titled “Identifying users”](#identifying-users)
Honeybadger can track which users have encountered each error. To identify the current user in error reports, add a user identifier and/or email address with `Honeybadger.setContext`:
```javascript
Honeybadger.setContext({
user_id: 123,
user_email: "user@example.com",
});
```
## Sending additional context
[Section titled “Sending additional context”](#sending-additional-context)
Sometimes additional application state may be helpful for diagnosing errors. You can arbitrarily specify additional key/value pairs when you invoke `setContext`.
```javascript
Honeybadger.setContext({
active_organization: 55,
custom_configuration: false,
});
```
## Clearing context
[Section titled “Clearing context”](#clearing-context)
If your user logs out or if your context changes during the React component lifetime, you can set new values as appropriate by invoking `setContext` again.
Additionally, if needed, you can clear the context by invoking `clear`:
```javascript
// Set the context to {}
Honeybadger.clear();
```
## Advanced usage
[Section titled “Advanced usage”](#advanced-usage)
*@honeybadger-io/react-native* is built on [honeybadger.js](https://github.com/honeybadger-io/honeybadger-js).
See the [Honeybadger JavaScript integration documentation](/lib/javascript/) for additional customization options.
## Source map support
[Section titled “Source map support”](#source-map-support)
To generate and upload source maps to Honeybadger, use the following command:
```shell
npx honeybadger-upload-sourcemaps --apiKey --revision
```
The `--apiKey` param is your Honeybadger API key for the project. The `--revision` param should match the revision param of the `Honeybadger.init` call inside your application. This is done so that reported errors are correctly matched up against the generated source maps.
As of version 0.70, React Native uses Hermes as the default JavaScript engine. The source maps tool assumes that your project uses Hermes. If you are building against an earlier version of React Native, or are explicitly not using Hermes, add the `--no-hermes` flag to the source maps tool, like so:
```shell
npx honeybadger-upload-sourcemaps --no-hermes --apiKey --revision
```
If your React Native project uses Expo, include the `--expo` param.
```shell
npx honeybadger-upload-sourcemaps --apiKey --revision --expo
```
If you just want to generate the source maps without uploading them to Honeybadger, you can use the `--skip-upload` flag.
```shell
npx honeybadger-upload-sourcemaps --skip-upload --apiKey --revision
```
## Sample applications
[Section titled “Sample applications”](#sample-applications)
The [*examples*](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/react-native/examples) folder contains two minimal React Native projects, demonstrating the use of the Honeybadger library. See the [README](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/react-native#example-projects) for details.
# Honeybadger for React Native version <=5
> Honeybadger monitors your React Native applications for errors and exceptions so that you can fix them wicked fast.
Note
This documentation is for **version 5** or earlier. If you are using a more recent version, please see the [latest documentation](/lib/javascript/integration/react-native/).
## Installation
[Section titled “Installation”](#installation)
From the root directory of your React Native project:
```shell
npm install "@honeybadger-io/react-native"
cd ios && pod install
```
The above will download the Honeybadger React Native library and add it as a dependency of your project. The iOS step is required to properly add the library to the Xcode project through CocoaPods. Android doesn’t require a separate step.
## Initialization
[Section titled “Initialization”](#initialization)
Add the following to your **App.js** file to initialize the Honeybadger library.
```js
import Honeybadger from "@honeybadger-io/react-native";
export default function App() {
Honeybadger.configure("PROJECT_API_KEY");
// ...
}
```
You can log into your [Honeybadger](https://honeybadger.io) account to obtain your API key.
## Configuration
[Section titled “Configuration”](#configuration)
The configure method takes additional configuration options.
| Name | Type | Required | Default | Example |
| ------------ | ------- | -------- | ------- | -------------------- |
| apiKey | String | YES | `""` | `"hb-api-key-1234"` |
| reportErrors | Boolean | NO | true | |
| revision | String | NO | `""` | `"8afb34a"` |
| projectRoot | String | NO | `""` | `"/path/to/project"` |
```js
Honeybadger.configure("hb-api-key-1234", "8afb34a", "/path/to/project");
```
The **reportErrors** parameter determines if errors are to be sent to Honeybadger. This is set to **true** by default. In certain environments, say, during development, it could be useful to set **reportErrors** to **false** to prevent errors from being posted to your Honeybadger account.
## Usage examples
[Section titled “Usage examples”](#usage-examples)
iOS, Android, and JavaScript errors will be automatically handled by the Honeybadger React Native library, by default. But you can also use the following API to customize error handling in your application.
### Honeybadger.notify(error, additionalData)
[Section titled “Honeybadger.notify(error, additionalData)”](#honeybadgernotifyerror-additionaldata)
You can use the **notify** method to send any kind of error, exception, object, String, etc. If sending an error or exception, the Honeybadger React Native library will attempt to extract a stack trace and any relevant information that might be useful. You can also optionally provide **additionalData** to the **notify** method, as either a string or an object, to include any relevant information.
### Honeybadger.setContext(context)
[Section titled “Honeybadger.setContext(context)”](#honeybadgersetcontextcontext)
If you have data that you would like to include whenever an error or an exception occurs, you can provide that data using the **setContext** method. Provide an object as an argument. You can call **setContext** as many times as needed. New context data will be merged with any previously-set context data.
```js
Honeybadger.setContext({
user_id: "123abc",
more: "some additional data",
});
```
### Honeybadger.resetContext()
[Section titled “Honeybadger.resetContext()”](#honeybadgerresetcontext)
If you’ve used **Honeybadger.setContext()** to store context data, you can use **Honeybadger.resetContext()** to clear that data.
### Honeybadger.setLogLevel(logLevel)
[Section titled “Honeybadger.setLogLevel(logLevel)”](#honeybadgersetloglevelloglevel)
Sets the logging level for the Honeybadger library.
```js
Honeybadger.setLogLevel("debug");
```
The following values are accepted:
| Value | Meaning |
| --------- | ---------------------------------------- |
| ”debug” | Everything will be logged to console. |
| ”warning” | Only warnings will be logged to console. |
| ”error” | Only errors will be logged to console. |
The default logging level is “warning”.
# Stimulus integration guide
> Honeybadger monitors your Stimulus applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **Stimulus error and exception tracking**. Once installed, Honeybadger will automatically report errors from your Stimulus application.
## Installation
[Section titled “Installation”](#installation)
First, install *honeybadger.js*:
```plaintext
# npm
npm add @honeybadger-io/js --save
# yarn
yarn add @honeybadger-io/js
```
Then, configure Stimulus to report errors to Honeybadger:
```js
// In a Rails app this code typically resides in app/javascript/packs/application.js
// In a non-Rails app, usually src/application.js
// Import honeybadger.js
import { Application } from "stimulus";
import * as Honeybadger from "@honeybadger-io/js";
// Configure honeybadger.js
Honeybadger.configure({
apiKey: "PROJECT_API_KEY",
environment: "production",
revision: "git SHA/project version",
});
// Start Stimulus application
const application = Application.start();
// Set up error handler
application.handleError = (error, message, detail) => {
console.warn(message, detail);
Honeybadger.notify(error);
};
// Perform your other Stimulus setup here
```
Note
Errors that happen in development and test environments are not reported by default. To always report errors or to change the defaults, see [Environments and Versions](/lib/javascript/guides/environments-and-versions/#development-environments).
## Reporting errors
[Section titled “Reporting errors”](#reporting-errors)
Honeybadger also reports all uncaught exceptions outside of Stimulus controllers using our `window.onerror` handler. To disable uncaught error reporting:
```js
Honeybadger.configure({ enableUncaught: false });
```
You can also manually notify Honeybadger of errors and other events in your application code:
```javascript
try {
// ...error producing code...
} catch (error) {
Honeybadger.notify(error);
}
```
See the [Reporting Errors How-to Guide](/lib/javascript/guides/reporting-errors/) for more info.
## 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 with `Honeybadger.context`:
```javascript
Honeybadger.setContext({
user_id: 123,
user_email: "user@example.com",
});
```
## Tracking deploys
[Section titled “Tracking deploys”](#tracking-deploys)
As with vanilla JavaScript applications, you can notify Honeybadger when you’ve deployed a new build. Honeybadger will associate an error report with a specific revision number (matching the ‘revision’ field in your *honeybadger.js* configuration).
Here’s a simple `curl` script to record a deployment:
```sh
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
&& curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"
```
Be sure that the same revision is also configured in the *honeybadger.js* library. Read more about deploy tracking in the [API docs](/api/deployments).
### Tracking deploys from Netlify
[Section titled “Tracking deploys from Netlify”](#tracking-deploys-from-netlify)
If you are deploying your site to Netlify, you can notify Honeybadger of deployments via Netlify’s webhooks. Go to the **Deploy notifications** section of the **Build & deploy** tab for your site settings, and choose to add an Outgoing webhook notification. Choose `Deploy succeeded` as the event to listen for, and use this format for your URL:
`https://api.honeybadger.io/v1/deploys/netlify?api_key=YOUR_HONEYBADGER_API_KEY_HERE`
The environment that will be reported to Honeybadger defaults to the Netlify environment that was deployed, but you can override that with `&environment=CUSTOM_ENV` in the webhook URL, if you like.
## Source map support
[Section titled “Source map support”](#source-map-support)
Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. See our [Source Map Guide](/lib/javascript/guides/using-source-maps/) for details.
## Collect user feedback
[Section titled “Collect user feedback”](#collect-user-feedback)
When an error occurs, a form can be shown to gather feedback from your users. Read more about this feature [here](/lib/javascript/guides/collecting-user-feedback/).
# Vue.js 2.x integration guide
> Honeybadger monitors your Vue.js applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **Vue.js 2.x error and exception tracking**. Once installed, Honeybadger will automatically report errors from your Vue.js application.
## Installation
[Section titled “Installation”](#installation)
Add *@honeybadger-io/js* and *@honeybadger-io/vue* as dependencies and configure.
```plaintext
# npm
npm add @honeybadger-io/js @honeybadger-io/vue --save
# yarn
yarn add @honeybadger-io/js @honeybadger-io/vue
```
In your main.js:
```javascript
import Vue from "vue";
import HoneybadgerVue from "@honeybadger-io/vue";
const config = {
apiKey: "PROJECT_API_KEY",
environment: "production",
revision: "git SHA/project version",
};
Vue.use(HoneybadgerVue, config);
```
Note
Errors that happen in development and test environments are not reported by default. To always report errors or to change the defaults, see [Environments and Versions](/lib/javascript/guides/environments-and-versions/#development-environments).
## Reporting errors
[Section titled “Reporting errors”](#reporting-errors)
Using the example configuration above, you’ll install *@honeybadger-ui/vue* as Vue’s error handler.
Depending on the Vue version you’re using, the errors that Vue propagates through its own error handler may vary. Generally, rendering errors are passed in *Vue 2.0.0* and above, errors in component lifecycle hooks are handled in *Vue 2.2.0* and above, and errors in Vue custom event handlers will be passed through to `errorHandler` in *Vue 2.4.0* and above.
Additionally, by default, an error handler for all JavaScript errors will be attached to the `window.onerror` handler for JavaScript errors that may originate from Vue components or other JavaScript on the page.
Because Vue doesn’t intercept all errors that may occur within a Vue component, errors that bubble up to the `window.onerror` handler may be missing some Vue component contextual information, but the stack trace will be available.
If, for some reason, you do not wish to install Honeybadger’s error handler on the global `window.onerror` handler, you may add `{ enableUncaught: false }` to the configuration when you’re registering `HoneybadgerVue`.
You may also manually report errors by directly invoking the [honeybadger.js](https://github.com/honeybadger-io/honeybadger-js) API.
```javascript
Vue.$honeybadger.notify(error);
```
See the [full documentation](/lib/javascript/) for more options.
## Identifying users
[Section titled “Identifying users”](#identifying-users)
Honeybadger can track which users have encountered each error. To identify the current user in error reports, add a user identifier and/or email address with `Vue.$honeybadger.setContext`:
```javascript
Vue.$honeybadger.setContext({
user_id: 123,
user_email: "user@example.com",
});
```
## Sending additional context
[Section titled “Sending additional context”](#sending-additional-context)
Sometimes additional application state may be helpful for diagnosing errors. You can arbitrarily specify additional key/value pairs when you invoke `setContext`.
```javascript
Vue.$honeybadger.setContext({
active_organization: 55,
custom_configuration: false,
});
```
## Clearing context
[Section titled “Clearing context”](#clearing-context)
If your user logs out or if your context changes during the Vue component lifetime, you can set new values as appropriate by invoking `setContext` again.
Additionally, if needed, you can clear the context by invoking `clear`:
```javascript
// Set the context to {}
Vue.$honeybadger.clear();
```
## Advanced usage
[Section titled “Advanced usage”](#advanced-usage)
*@honeybadger-io/vue* is built on [honeybadger.js](https://github.com/honeybadger-io/honeybadger-js). Most configuration options can be passed in to the `config` object you pass when registering the `HoneybadgerVue` component with your Vue app instance. As of this release, there are no Vue-specific configuration options, but that may change as we learn more about Vue users’ unique needs.
In general, configuration and context options supported by the JavaScript version of the library should work as is, aside from needing to reference `Vue.$honeybadger` instead of a global `Honeybadger` variable.
See the [Honeybadger JavaScript integration documentation](/lib/javascript/) for additional customization options.
## Tracking deploys
[Section titled “Tracking deploys”](#tracking-deploys)
As with vanilla JavaScript applications, you can notify Honeybadger when you’ve deployed a new build. Honeybadger will associate an error report with a specific revision number (matching the `revision` field in the configuration when registering the `HoneybadgerVue` component).
Here’s a simple `curl` script to record a deployment:
```sh
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
&& curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"
```
Be sure that the same revision is also configured in the *@honeybadger-io/vue* library. Read more about deploy tracking in the [API docs](/api/deployments/).
### Tracking deploys from Netlify
[Section titled “Tracking deploys from Netlify”](#tracking-deploys-from-netlify)
If you are deploying your site to Netlify, you can notify Honeybadger of deployments via Netlify’s webhooks. Go to the **Deploy notifications** section of the **Build & deploy** tab for your site settings, and choose to add an Outgoing webhook notification. Choose `Deploy succeeded` as the event to listen for, and use this format for your URL:
`https://api.honeybadger.io/v1/deploys/netlify?api_key=YOUR_HONEYBADGER_API_KEY_HERE`
The environment that will be reported to Honeybadger defaults to the Netlify environment that was deployed, but you can override that with `&environment=CUSTOM_ENV` in the webhook URL, if you like.
## Source map support
[Section titled “Source map support”](#source-map-support)
Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. See our [Source Map Guide](/lib/javascript/guides/using-source-maps/) for details.
## Collect user feedback
[Section titled “Collect user feedback”](#collect-user-feedback)
When an error occurs, a form can be shown to gather feedback from your users. Read more about this feature [here](/lib/javascript/guides/collecting-user-feedback/).
## Sample applications
[Section titled “Sample applications”](#sample-applications)
Two sample applications are included in the `examples/` folder in the honeybadger-vue repository, one for vue 2.x and one for vue 3.x.
You can follow the README.md inside each app to run them.
# Vue.js 3.x integration guide
> Honeybadger monitors your Vue.js applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **Vue.js 3.x error and exception tracking**. Once installed, Honeybadger will automatically report errors from your Vue.js application.
## Installation
[Section titled “Installation”](#installation)
Add *@honeybadger-io/js* and *@honeybadger-io/vue* as dependencies and configure.
```shell
# npm
npm add @honeybadger-io/js @honeybadger-io/vue --save
# yarn
yarn add @honeybadger-io/js @honeybadger-io/vue
```
In your main.js (or main.ts):
```javascript
import HoneybadgerVue from "@honeybadger-io/vue";
import { createApp } from "vue";
import App from "./App"; //your root component
const app = createApp(App);
const config = {
apiKey: "PROJECT_API_KEY",
environment: "production",
revision: "git SHA/project version",
};
app.use(HoneybadgerVue, config);
app.mount("#app");
```
Note
Errors that happen in development and test environments are not reported by default. To always report errors or to change the defaults, see [Environments and Versions](/lib/javascript/guides/environments-and-versions/#development-environments).
## Using Vite for development
[Section titled “Using Vite for development”](#using-vite-for-development)
If you are using Vite for local development, you may get CORS errors in your browser console. To work around that, you can apply the following in your vite.config.js (or vite.config.ts):
```javascript
export default defineConfig({
// ...
server: {
cors: false,
},
});
```
## Reporting errors
[Section titled “Reporting errors”](#reporting-errors)
Using the example configuration above, you’ll install *@honeybadger-io/vue* as Vue’s error handler.
By default, an error handler for all JavaScript errors will be attached to the `window.onerror` handler for JavaScript errors that may originate from Vue components or other JavaScript on the page.
Because Vue doesn’t intercept all errors that may occur within a Vue component, errors that bubble up to the `window.onerror` handler may be missing some Vue component contextual information, but the stack trace will be available.
If, for some reason, you do not wish to install Honeybadger’s error handler on the global `window.onerror` handler, you may add `{ enableUncaught: false }` to the configuration when you’re registering `HoneybadgerVue`.
You may also manually report errors by directly invoking the [honeybadger.js](https://github.com/honeybadger-io/honeybadger-js) API.
### Composition API
[Section titled “Composition API”](#composition-api)
To access the Honeybadger instance when using the Composition API, use the `useHoneybadger` function:
```javascript
```
### Options API
[Section titled “Options API”](#options-api)
To access the Honeybadger instance when using the Options API, use `this.$honeybadger`:
```javascript
// inside a component
this.$honeybadger.notify(error);
```
See the [full documentation](/lib/javascript/) for more options on how to call `notify()`.
## Identifying users
[Section titled “Identifying users”](#identifying-users)
Honeybadger can track which users have encountered each error. To identify the current user in error reports, add a user identifier and/or email address with `$honeybadger.setContext`:
```javascript
// inside a component
this.$honeybadger.setContext({
user_id: 123,
user_email: "user@example.com",
});
```
## Sending additional context
[Section titled “Sending additional context”](#sending-additional-context)
Sometimes additional application state may be helpful for diagnosing errors. You can arbitrarily specify additional key/value pairs when you invoke `setContext`.
```javascript
// inside a component
this.$honeybadger.setContext({
active_organization: 55,
custom_configuration: false,
});
```
## Clearing context
[Section titled “Clearing context”](#clearing-context)
If your user logs out or if your context changes during the Vue component lifetime, you can set new values as appropriate by invoking `setContext` again.
Additionally, if needed, you can clear the context by invoking `clear`:
```javascript
// inside a component
this.$honeybadger.clear();
```
## Advanced usage
[Section titled “Advanced usage”](#advanced-usage)
*@honeybadger-io/vue* is built on [honeybadger.js](https://github.com/honeybadger-io/honeybadger-js). Most configuration options can be passed in to the `config` object you pass when registering the `HoneybadgerVue` component with your Vue app instance. As of this release, there are no Vue-specific configuration options, but that may change as we learn more about Vue users’ unique needs.
In general, configuration and context options supported by the JavaScript version of the library should work as is, aside from needing to reference `this.$honeybadger` (or `app.$honeybadger` if you have access to your vue `app` instance) instead of a global `Honeybadger` variable.
See the [Honeybadger JavaScript integration documentation](/lib/javascript/) for additional customization options.
## Tracking deploys
[Section titled “Tracking deploys”](#tracking-deploys)
As with vanilla JavaScript applications, you can notify Honeybadger when you’ve deployed a new build. Honeybadger will associate an error report with a specific revision number (matching the `revision` field in the configuration when registering the Honeybadger component).
Here’s a simple `curl` script to record a deployment:
```sh
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
&& curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"
```
Be sure that the same revision is also configured in the *@honeybadger-io/vue* library. Read more about deploy tracking in the [API docs](/api/deployments).
### Tracking deploys from Netlify
[Section titled “Tracking deploys from Netlify”](#tracking-deploys-from-netlify)
If you are deploying your site to Netlify, you can notify Honeybadger of deployments via Netlify’s webhooks. Go to the **Deploy notifications** section of the **Build & deploy** tab for your site settings, and choose to add an Outgoing webhook notification. Choose `Deploy succeeded` as the event to listen for, and use this format for your URL:
`https://api.honeybadger.io/v1/deploys/netlify?api_key=YOUR_HONEYBADGER_API_KEY_HERE`
The environment that will be reported to Honeybadger defaults to the Netlify environment that was deployed, but you can override that with `&environment=CUSTOM_ENV` in the webhook URL, if you like.
## Source map support
[Section titled “Source map support”](#source-map-support)
Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. See our [Source Map Guide](/lib/javascript/guides/using-source-maps/) for details.
## Collect user feedback
[Section titled “Collect user feedback”](#collect-user-feedback)
When an error occurs, a form can be shown to gather feedback from your users. Read more about this feature [here](/lib/javascript/guides/collecting-user-feedback/).
## Sample applications
[Section titled “Sample applications”](#sample-applications)
Two sample applications are included in the `examples/` folder in the honeybadger-vue repository, one for vue 2.x and one for vue 3.x.
You can follow the README.md inside each app to run them.
To create your own standalone Vue application, simply follow the [Quick Start](https://vuejs.org/guide/quick-start.html#with-build-tools) guide in Vue.js documentation. Remember to install Honeybadger Vue:
```bash
npm add @honeybadger-io/js @honeybadger-io/vue
```
Then, in your `main.js`, you can follow the pattern in the source code in `examples/vue3/src/main.js`:
```javascript
import { createApp } from "vue";
import App from "./App";
import router from "./router";
import HoneyBadgerVue from "@honeybadger-io/vue";
const app = createApp(App);
app.use(HoneyBadgerVue, { apiKey: "your_api_key" });
app.use(router).mount("#app");
```
# Configuration
> Complete configuration reference for Honeybadger's JavaScript library with all available options and settings.
## Configuration file (server-side only)
[Section titled “Configuration file (server-side only)”](#configuration-file-server-side-only)
When using the JavaScript client in a Node.js environment, you can configure Honeybadger using a configuration file in your project’s root directory, such as `honeybadger.config.js` or `honeybadger.config.ts`. The configuration file should export an object with the configuration.
An example configuration file is shown below:
honeybadger.config.js
```javascript
module.exports = {
apiKey: process.env.HONEYBADGER_API_KEY,
environment: process.env.NODE_ENV,
revision: process.env.HONEYBADGER_REVISION,
// etc.
};
```
## Configuration options
[Section titled “Configuration options”](#configuration-options)
All of the available configuration options are shown below:
```javascript
Honeybadger.configure({
// Honeybadger API key (required)
apiKey: "",
// The revision of the current deploy
revision: "",
// Project root
projectRoot: "http://my-app.com",
// Environment
environment: "production",
// Defaults to the server's hostname in Node.js
hostname: "badger01",
// Environments which will not report data
developmentEnvironments: ["dev", "development", "test"],
// Override `developmentEnvironments` to explicitly enable/disable error reporting
// reportData: true,
// Key values to filter from request data. Matches are partial, so "password"
// and "password_confirmation" will both be filtered
filters: ["creditcard", "password"],
// Component (optional)
component: "",
// Action (optional)
action: "",
// Should unhandled errors be reported?
// This option uses `window.onerror` in browsers and `uncaughtException` in Node.js
enableUncaught: true,
// Executed after `uncaughtException` in Node.js
// afterUncaught: ->(error) {},
// Should unhandled Promise rejections be reported?
enableUnhandledRejection: true,
// Enable breadcrumbs collection
breadcrumbsEnabled: true,
// Automatically send console logs to Honeybadger Insights
eventsEnabled: true,
// Collector Host
// If you are using our EU stack, this should be set to "https://eu-api.honeybadger.io".
endpoint: "https://api.honeybadger.io",
// The maximum number of breadcrumbs to include with error reports
maxBreadcrumbs: 40,
// The maximum depth allowed in deeply-nested objects
maxObjectDepth: 8,
// The logger to use. Should behave like `console`
logger: console,
// Output Honeybadger debug messages to the logger
debug: false,
});
```
The following additional options are available in **browser environments**:
```javascript
Honeybadger.configure({
// Send notifications asynchronously
async: true,
// Endpoint to submit user feedback for errors. See "Collecting User Feedback".
// If you are using our EU stack, this should be set to "https://eu-api.honeybadger.io/v2/feedback".
userFeedbackEndpoint: "https://api.honeybadger.io/v2/feedback",
// Limit the maximum number of errors the client will send to Honeybadger
// after page load. Default is unlimited (undefined)
maxErrors: 20,
// Enable breadcrumbs collection
breadcrumbsEnabled: true,
// You can also selectively configure these types of breadcrumbs:
// breadcrumbsEnabled: {
// dom: true,
// network: true,
// navigation: true,
// console: true
// }
});
```
## Configuring with environment variables
[Section titled “Configuring with environment variables”](#configuring-with-environment-variables)
Unlike some of our other client libraries, *honeybadger.js* does **not** automatically read configuration from environment variables; to use environment variables, you must configure Honeybadger like this:
```javascript
Honeybadger.configure({
apiKey: process.env.HONEYBADGER_API_KEY,
environment: process.env.NODE_ENV,
revision: process.env.HONEYBADGER_REVISION,
// etc.
});
```
Note that `process.env` may not be available outside of Node.js by default (it depends on your JavaScript build system). For example, [in Webpack you need to use `environmentPlugin`](https://webpack.js.org/plugins/environment-plugin/) to make `process.env` keys available in source files.
## `beforeNotify` handlers
[Section titled “beforeNotify handlers”](#beforenotify-handlers)
`beforeNotify` handlers run before each notice (error report) is sent to Honeybadger. There are two cases this might be useful:
1. Filtering out unwanted error reports by returning `false` from a handler
2. Sanitizing or enhancing notice data before being sent to Honeybadger
### Usage examples
[Section titled “Usage examples”](#usage-examples)
Sanitizing notice data:
```javascript
Honeybadger.beforeNotify((notice) => {
if (/creditCard/.test(notice.url)) {
notice.url = "[FILTERED]";
}
});
```
Adding additional context to notice data:
```javascript
Honeybadger.beforeNotify((notice) => {
notice.context.session_id = MyApp.sessionId;
});
```
Adding additional context to notice data from an async source:
```javascript
Honeybadger.beforeNotify(async (notice) => {
notice.context.state = await MyApp.getState();
});
```
Skipping a notice:
```javascript
Honeybadger.beforeNotify((notice) => {
if (/third-party-domain/.test(notice.stack)) {
return false;
}
});
```
## `afterNotify` handlers
[Section titled “afterNotify handlers”](#afternotify-handlers)
`afterNotify` handlers run *after* each notice (error report) is sent to Honeybadger. Here are two cases where this is useful:
1. Displaying the ID of the Honeybadger notice to users
2. Handling errors if the Honeybadger API rejects the notice
### Usage examples
[Section titled “Usage examples”](#usage-examples-1)
Log a URL to the error report in Honeybadger:
```javascript
Honeybadger.afterNotify((err, notice) => {
if (err) {
return console.log(`Honeybadger notification failed: ${err}`);
}
console.log(
`Honeybadger notice: https://app.honeybadger.io/notice/${notice.id}`,
);
});
```
An `afterNotify` handler can also be attached to a single error report:
```javascript
Honeybadger.notify("testing", {
afterNotify: (err, notice) => console.log(err || notice.id),
});
```
### Notice properties
[Section titled “Notice properties”](#notice-properties)
The following notice properties are available in `notice` objects:
* `notice.stack` - The stack trace (read only)
* `notice.backtrace` - The parsed backtrace object
* `notice.name` - The exception class name
* `notice.message` - The error message
* `notice.url` - The current url
* `notice.projectRoot` - The root url
* `notice.environment` - Name of the environment. example: “production”
* `notice.component` - Similar to a rails controller name. example: “users”
* `notice.action` - Similar to a rails action name. example: “create”
* `notice.fingerprint` - A unique fingerprint, used to customize grouping of errors in Honeybadger
* `notice.context` - The context object
* `notice.tags` - A string comma-separated list of tags
* `notice.params` - An object of request parameters
* `notice.session` - An object of request session key/values
* `notice.headers` - An object of request headers
* `notice.cookies` - An object of cookie key/values. May also be sent as a string in the document.cookie “foo=bar;bar=baz” format.
The following additional notice properties are available in `afterNotify` handlers:
* `notice.id` - The UUID of the error in Honeybadger
# Supported versions
> View supported browsers and Node.js versions for Honeybadger's JavaScript error tracking and application monitoring library.
## Browser
[Section titled “Browser”](#browser)
* [`@honeybadger-io/js`](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/js) works in **all modern browsers** and is tested back to the following versions:
| Chrome | Edge | Firefox | Safari |
| ------ | ---- | ------- | ------ |
| 49.0 | 15.0 | 58.0 | 12.1 |
* [`@honeybadger-io/webpack`](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/webpack) supports Webpack **v3+**.
* [`@honeybadger-io/rollup-plugin`](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/rollup-plugin) supports Rollup **v3+**.
## Node.js
[Section titled “Node.js”](#nodejs)
* [`@honeybadger-io/js`](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/js) supports all [currently maintained Node.js releases](https://nodejs.org/en/about/releases/).
# Frequently asked questions
> Find answers to frequently asked questions about Honeybadger's JavaScript error tracking and application monitoring library.
## How do I ignore certain errors?
[Section titled “How do I ignore certain errors?”](#how-do-i-ignore-certain-errors)
Return `false` to a `Honeybadger.beforeNotify` handler:
```js
Honeybadger.beforeNotify(function (notice) {
if (/third-party-domain/.test(notice.stack)) {
return false;
}
});
```
For more information, see [Reducing Noise](/lib/javascript/guides/reducing-noise/).
## Why aren’t my Source Maps working?
[Section titled “Why aren’t my Source Maps working?”](#why-arent-my-source-maps-working)
Check out the [Troubleshooting](/lib/javascript/support/troubleshooting/#source-map-is-not-working) section.
# Troubleshooting
> Troubleshoot common issues with Honeybadger's JavaScript library and resolve integration problems.
Common issues/workarounds for [`honeybadger.js`](https://github.com/honeybadger-io/honeybadger-js) are documented here. If you don’t find a solution to your problem here or in our [support documentation](/lib/javascript/#getting-support), email and we’ll assist you!
## Before you start troubleshooting
[Section titled “Before you start troubleshooting”](#before-you-start-troubleshooting)
1. Make sure you are on the latest version of [*honeybadger.js*](https://github.com/honeybadger-io/honeybadger-js)
2. Enable the [`debug` config option](/lib/javascript/reference/configuration/)
## All errors are not reported
[Section titled “All errors are not reported”](#all-errors-are-not-reported)
If *no* errors are reported (even manually via `Honeybadger.notify`):
1. Is the [`apiKey` config option](/lib/javascript/reference/configuration/) configured?
2. Is the error ignored in a [`beforeNotify` callback](/lib/javascript/guides/reducing-noise/)?
## Uncaught errors are not reported
[Section titled “Uncaught errors are not reported”](#uncaught-errors-are-not-reported)
If you can report errors using `Honeybadger.notify`, but uncaught errors are not automatically reported:
1. Is the [`enableUncaught` config option](/lib/javascript/reference/configuration/#configuration-options) enabled? It must be enabled for uncaught errors to be reported. It is enabled by default.
2. Is Honeybadger’s `window.onerror` callback installed? Check `window.onerror` in the console and make sure it originates in honeybadger.js or honeybadger.min.js (or wherever you are hosting our JavaScript). If it doesn’t, it’s possible some 3rd-party code is overriding our callback.
3. If the error originates in a file hosted on a different domain, is CORs enabled? If you host your assets on a CDN (or if the domain is different from where your HTML is served) you may need to enable CORS on your asset domain for the `window.onerror` errors to be reported. See for more info. If this is the issue, you should see logs similar to this:
```plaintext
[Log] [Honeybadger] Ignoring cross-domain script error.
```
4. Does your application or framework handle errors internally? If you’re using a framework, search the documentation for “error handling”. For example, Ember provides its own `Ember.onerror` callback which you must configure in order for uncaught errors to be reported:
```js
Ember.onerror = function (error) {
Honeybadger.notify(error);
};
```
## Errors are reported twice
[Section titled “Errors are reported twice”](#errors-are-reported-twice)
1. If it’s a React app, are you running in dev mode? React’s [Strict Mode](https://reactjs.org/docs/strict-mode.html#detecting-unexpected-side-effects) may cause double rendering, causing Honeybadger to report multiple errors. This shouldn’t be a problem in your production build. For more info, see [github.com/honeybadger-io/honeybadger-react#247](https://github.com/honeybadger-io/honeybadger-react/issues/247)
## Source map is not working
[Section titled “Source map is not working”](#source-map-is-not-working)
Note
These steps are supplemental to the **Source Maps Debug Tool**. If you haven’t checked it out yet, start there first! You can find it by visiting *Project Settings → Source Maps → Debug Tool* in your Honeybadger project (if you don’t see the “Source Maps” tab, you may need to go to *Project Settings → Edit* and change the language to “Client-side JavaScript”, “Node.js”, etc.).
### Did the error happen *before* the source map was uploaded?
[Section titled “Did the error happen before the source map was uploaded?”](#did-the-error-happen-before-the-source-map-was-uploaded)
Honeybadger **does not** apply source maps to errors that have already occurred. If the error in question first occurred before the source map was uploaded, that’s likely the problem—look for a newer version of the error. You may also want to delete the old error in the Honeybadger UI to avoid confusion.
### Did the build process modify the output *after* it generated your source map?
[Section titled “Did the build process modify the output after it generated your source map?”](#did-the-build-process-modify-the-output-after-it-generated-your-source-map)
If a source map is available but translation is not working, **make sure that your build process did not add extra lines/comments to the top of your minified JavaScript file**, which could throw off the mapping information. For example, line 1 column 123 would become line 2 column 123, which would not translate.
Likewise, **ensure that your build process or CDN does not minify the file twice.** Some CDN providers (such as Cloudflare) can auto-minify your JavaScript files after you upload them—such options should be disabled.
### If you are hosting your source map
[Section titled “If you are hosting your source map”](#if-you-are-hosting-your-source-map)
In some cases a few minified errors may get through before we have the chance to download and process your hosted source map. If your source map is not being applied to your errors after the first few minutes:
1. Is your minified file publicly accessible? Try downloading it with `curl`:
```sh
curl https://www.example.com/assets/application.min.js
```
2. Does the [`minified_url`](https://docs.honeybadger.io/lib/javascript/guides/using-source-maps/#uploading-your-source-map) point to the correct URL? If you are using [@honeybadger-io/webpack](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/webpack) or [@honeybadger-io/rollup-plugin](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/rollup), this parameter is built using the [`assetsUrl`](https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/webpack#plugin-parameters) parameter.
3. Does your minified file have [the `sourceMappingURL` comment](/lib/javascript/guides/using-source-maps/#hosting-your-source-map)?
4. Is your Source Map file publicly accessible? Try downloading it with `curl`:
```sh
curl https://www.example.com/assets/application.min.js.map
```
5. If using [Authentication](/lib/javascript/guides/using-source-maps/#authentication), is the `Honeybadger-Token` header validated correctly? Try downloading with `curl`:
```sh
curl -H"Honeybadger-Token: token" https://www.example.com/assets/application.min.js.map
```
### If you are uploading your source map
[Section titled “If you are uploading your source map”](#if-you-are-uploading-your-source-map)
1. Navigate to **Project Settings** -> **Source Maps** -> **Uploaded Source Maps**, then:
2. Does the **Minified URL** for your source map match the minified URL in your JavaScript stack trace? The URLs must match exactly, with the exception of [wildcards](/api/reporting-source-maps/#wildcards) and query strings (which are ignored).
3. Does the **revision** match the `revision` key in the **Application Environment** section of the error page? If it doesn’t, [make sure the `revision` of your uploaded source map is the same as the `revision` configured in `honeybadger.js`](/lib/javascript/guides/using-source-maps/#versioning-your-project).
4. Was the source map uploaded **before** the first error for that revision occurred? Source mappings are cached, meaning that uploading the source map after the error occurred has no effect. The only way to get a new mapping in this case is to deploy a new revision, making sure the source map upload completes before the code is live.
5. If your build process includes compression, make sure your source map files are not compressed (such as with gzip compression) when you upload them.
6. Can you parse your source map as JSON? Source map files must be valid JSON.
## Error in `beforeNotify` handler
[Section titled “Error in beforeNotify handler”](#error-in-beforenotify-handler)
If you’re using *honeybadger.js* < 1.0.4, upgrade to a more recent version. [1.0.4 fixed a bug in `beforeNotify`](https://github.com/honeybadger-io/honeybadger-js/blob/master/CHANGELOG.md#104---2019-06-12) which prevented some properties from being available on the notice object (which would most likely result in `ReferenceError` in certain use cases).
# Upgrading to @honeybadger-io/js v3.0
> Upgrade guide for migrating to Honeybadger JavaScript library v3 with breaking changes and new features.
The new [@honeybadger-io/js](https://www.npmjs.com/package/@honeybadger-io/js) package is a universal/isomorphic JavaScript package combining the deprecated [honeybadger-js for browsers](https://www.npmjs.com/package/honeybadger-js) and the [honeybadger for Node.js](https://www.npmjs.com/package/honeybadger) NPM packages.
**Moving forward, development for both platforms will happen on @honeybadger-io/js** ([source code on GitHub](https://github.com/honeybadger-io/honeybadger-js)).
The new API is mostly the same as the old packages, with a few small changes.
## Upgrading from honeybadger-js v2.x (client-side)
[Section titled “Upgrading from honeybadger-js v2.x (client-side)”](#upgrading-from-honeybadger-js-v2x-client-side)
If you currently use the [honeybadger-js](https://www.npmjs.com/package/honeybadger-js) package, this section is for you.
The changes between *honeybadger-js* and *@honeybadger-io/js* are minimal. First, replace the old package with the new one:
```sh
npm uninstall honeybadger-js
npm install @honeybadger-io/js
```
Next, replace any `require`/`import` statements that reference “honeybadger-js”:
```js
const Honeybadger = require("@honeybadger-io/js");
// Or:
// import Honeybadger from '@honeybadger-io/js';
Honeybadger.configure({
apiKey: "project api key",
environment: "production",
revision: "git SHA/project version",
});
```
Finally, review this list of changes:
* Previously deprecated snake case config options such as `api_key`, `project_root`, etc. are no longer supported. Use `apiKey`, `projectRoot` instead.
* Stack traces are now parsed client-side; `notice.stack` is now read-only in [`beforeNotify` handlers](/lib/javascript/reference/configuration/#beforenotify-handlers), and a new `notice.backtrace` object has been added.
* The `max_depth` config option is now `maxObjectDepth`
* The `host` and `port` config options are now `endpoint`
* `onerror` is now `enableUncaught`
* The `onunhandledrejection` config option is now `enableUnhandledRejection`
* The `ignorePatterns` config option has been removed. Use a [`beforeNotify` handler](/lib/javascript/reference/configuration/#beforenotify-handlers) instead:
```js
const ignorePatterns = [/NoisyError/i, /unwanted error message/i];
Honeybadger.beforeNotify(function (notice) {
if (ignorePatterns.some((p) => p.test(notice.message))) {
return false;
}
});
```
* `Honeybadger.wrap` [has been removed](https://github.com/honeybadger-io/honeybadger-js/pull/506). If you used this functionality, you can recreate it like so:
```js
Honeybadger.wrap = function (func) {
try {
func.apply(this, arguments);
} catch (error) {
Honeybadger.notify(error);
throw error;
}
};
```
See [configuration](/lib/javascript/reference/configuration/) for an up-to-date list of available config options. Feel free to [email support](mailto:support@honeybadger.io?subject=honeybadger-js%20v3%20upgrade) if you run into issues not mentioned here.
### CDN users
[Section titled “CDN users”](#cdn-users)
If you use the CDN instead of the NPM package, replace your current script tag with the **v3.0** script tag:
```html
```
## Upgrading from honeybadger 1.x (Node.js)
[Section titled “Upgrading from honeybadger 1.x (Node.js)”](#upgrading-from-honeybadger-1x-nodejs)
If you currently use the [honeybadger](https://www.npmjs.com/package/honeybadger) package, this section is for you.
First, replace the old package with the new one:
```sh
npm uninstall honeybadger
npm install @honeybadger-io/js
```
Next, replace any `require` statements that reference “honeybadger-js”:
```js
const Honeybadger = require("@honeybadger-io/js");
Honeybadger.configure({
apiKey: "project api key",
environment: "production",
revision: "git SHA/project version",
});
```
Finally, review this list of changes:
* Environment variables are no longer configured by default; you must explicitly call `Honeybadger.configure`, i.e.:
```js
Honeybadger.configure({
apiKey: process.env.HONEYBADGER_API_KEY,
environment: process.env.HONEYBADGER_ENVIRONMENT,
});
```
* [`Honeybadger.logger`](https://github.com/honeybadger-io/honeybadger-node#configuring-the-default-logger) is now the [`logger` config option](/lib/javascript/reference/configuration/#configuration-options).
* [`Honeybadger.onUncaughtException`](https://github.com/honeybadger-io/honeybadger-node#honeybadgeronuncaughtexception-configure-the-uncaught-exception-handler) is now the [`afterUncaught` config option](/lib/javascript/reference/configuration/#configuration-options).
* [Events](https://github.com/honeybadger-io/honeybadger-node#events) are no longer emitted. Use [`beforeNotify` and `afterNotify` handlers instead](/lib/javascript/reference/configuration/#beforenotify-handlers).
See [configuration](/lib/javascript/reference/configuration/) for an up-to-date list of available config options. Feel free to [email support](mailto:support@honeybadger.io?subject=honeybadger-js%20v3%20upgrade) if you run into issues not mentioned here.
# Unofficial client libraries
> Are you using a language or framework that we don't officially support yet? You still have a few options!
Are you using a language or framework that we don’t officially support yet? You still have a few options:
* Try one of our [community packages](#community-packages)
* Report errors using our [exceptions API](/api/reporting-exceptions/)
## Community packages
[Section titled “Community packages”](#community-packages)
Here are some unofficial client libraries that were created by the Honeybadger community. We can’t guarantee that they’re up to date or that they’ll work for you, but we’re happy to link to them here. To add your project, [send us an email](mailto:support@honeybadger.io).
### Go (golang)
[Section titled “Go (golang)”](#go-golang)
* [agonzalezro/goneybadger (Go)](https://github.com/agonzalezro/goneybadger)
* [DavidHuie/gobadger (Go)](https://github.com/DavidHuie/gobadger)
* [remind101/pkg (Go)](https://github.com/remind101/pkg/tree/master/reporter/hb2)
### Java
[Section titled “Java”](#java)
* [styleseek/honeybadger-java (Java)](https://github.com/styleseek/honeybadger-java)
* [dekobon/honeybadger-jvm-client-v2 (Java)](https://github.com/dekobon/honeybadger-jvm-client-v2)
* [Workable/honeybadger-java (Java)](https://github.com/Workable/honeybadger-java)
### Elixir/Erlang
[Section titled “Elixir/Erlang”](#elixirerlang)
* [barsoom/content\_translator (Elixir)](https://github.com/barsoom/content_translator/blob/master/lib/error_reporting_backend.ex)
* [fyler/lager\_honeybadger\_backend (Erlang)](https://github.com/fyler/lager_honeybadger_backend)
### Scala
[Section titled “Scala”](#scala)
* [alno’s gist (Scala)](https://gist.github.com/alno/fd2eadfd776bad03ee3d)
### C\#
[Section titled “C#”](#c)
* [webnuts/Honeybadger.ErrorReporter (C#)](https://github.com/webnuts/Honeybadger.ErrorReporter)
# Honeybadger for PHP
> Documentation for Honeybadger's PHP error tracking library.
Hi there! You’ve found Honeybadger’s docs on **PHP exception tracking**. In these guides we’re going to discuss [`honeybadger-php`](https://github.com/honeybadger-io/honeybadger-php) and how to use it to track exceptions in your PHP applications.
## How you should read the docs
[Section titled “How you should read the docs”](#how-you-should-read-the-docs)
* If you’re installing Honeybadger in your **Laravel** application for the first time, check out the **[Laravel Integration Guide](/lib/php/integration/laravel/)**. If you use a different framework, start with the **[General Integration Guide](/lib/php/integration/other/)** instead.
* The **How-To Guides** (in the left-hand navigation menu) are general guides on how to do things with the library, and should apply to all types of applications.
* There is a wealth of additional knowledge about Honeybadger in the **Library Reference** and **Support** sections.
## Getting support
[Section titled “Getting support”](#getting-support)
If you’re having trouble working with the library (such as you aren’t receiving error reports when you should be):
1. Upgrade to the latest version if possible (you can find a list of bugfixes and other changes in the [CHANGELOG](https://github.com/honeybadger-io/honeybadger-php/blob/master/CHANGELOG.md))
2. Check out our [Frequently Asked Questions](/lib/php/support/faq/)
3. Run through the [Troubleshooting guide](/lib/php/support/troubleshooting/)
4. If you believe you’ve found a bug, [submit an issue on GitHub](https://github.com/honeybadger-io/honeybadger-php/issues/)
For all other problems, contact support for help:
# Capturing events with breadcrumbs
> Learn how to use breadcrumbs to track events leading up to errors.
When your application encounters an error, it’s often helpful to know what events occurred leading up to that. Honeybadger lets you do that with *breadcrumbs*.
Breadcrumbs are records of events that happened within your application — external API calls, job dispatches, database queries, or anything that you think might be relevant. When we capture an error, we display these breadcrumbs in your dashboard to provide extra debugging information.
Use [context](/lib/php/guides/customizing-error-reports/#custom-metadata-context) to record request-global data like the current user ID; use breadcrumbs to record specific events within the request and their custom metadata.
## Automatic breadcrumbs
[Section titled “Automatic breadcrumbs”](#automatic-breadcrumbs)
If you’re using Laravel or Lumen, Honeybadger can automatically capture breadcrumbs from your app. By default, we’ll record:
* [Log events](https://laravel.com/docs/logging)
* [View renders](https://laravel.com/docs/views)
* [Email dispatches](https://laravel.com/docs/mail)
* [Job dispatches](https://laravel.com/docs/queues)
* [Notification dispatches](https://laravel.com/docs/notifications)
* [Database queries](https://laravel.com/docs/queries)
* [Redis commands](https://laravel.com/docs/redis)
* Incoming requests
You can customise this with the `breadcrumbs` option in your `config/honeybadger.php`:
```php
'breadcrumbs' => [
'enabled' => true,
'automatic' => [
Breadcrumbs\DatabaseQueryExecuted::class,
Breadcrumbs\DatabaseTransactionStarted::class,
Breadcrumbs\DatabaseTransactionCommitted::class,
Breadcrumbs\DatabaseTransactionRolledBack::class,
Breadcrumbs\CacheHit::class,
Breadcrumbs\CacheMiss::class,
Breadcrumbs\JobQueued::class,
Breadcrumbs\MailSending::class,
Breadcrumbs\MailSent::class,
Breadcrumbs\MessageLogged::class,
Breadcrumbs\NotificationSending::class,
Breadcrumbs\NotificationSent::class,
Breadcrumbs\NotificationFailed::class,
Breadcrumbs\RedisCommandExecuted::class,
Breadcrumbs\RouteMatched::class,
Breadcrumbs\ViewRendered::class,
],
],
```
The `breadcrumbs.automatic` key contains the list of the events Honeybadger tracks by default. You can disable a specific event by removing or commenting out the appropriate line.
## Custom breadcrumbs
[Section titled “Custom breadcrumbs”](#custom-breadcrumbs)
You can also record breadcrumb events manually. This can be helpful if you aren’t using a supported framework, or there are additional events in your application that Honeybadger doesn’t recognize.
To add a breadcrumb, use `$honeybadger->addBreadcrumb($message, $metadata, $category)`:
```php
$honeybadger = Honeybadger\Honeybadger::new(['api_key' => 'PROJECT_API_KEY']);
$honeybadger->addBreadcrumb("Notification sent", ['user_id' => $user->id, 'type' => 'welcome']);
$honeybadger->addBreadcrumb("Payment webhook received", ['service' => 'Stripe'], 'webhooks');
// If you're using Laravel or Lumen, you can also use the Facade or service container
app('honeybadger')->addBreadcrumb("Notification sent", ['user_id' => $user->id, 'type' => 'welcome']);
Honeybadger::addBreadcrumb("Notification sent", ['user_id' => $user->id, 'type' => 'welcome'], 'notifications');
```
The `addBreadcrumb()` method has one required parameter, `message`. The message should be a terse summary of the event, which we’ll display prominently in the UI for each breadcrumb.
You can also provide:
* `metadata`, a key-value array of contextual data about the event. The metadata should be a single-level array with simple primitives as values (strings, integers, floats, or booleans).
* `category`, a string key used to classify and group events. See [Categories](#categories) for more details.
For each event, the Honeybadger client will automatically add a timestamp, so you don’t need to include that yourself.
## Categories
[Section titled “Categories”](#categories)
A `category` is a top level property of a breadcrumb. Categories are helpful so events can be presented differently on your project dashboard; for instance, `error` breadcrumbs are styled with a red “error” icon.
Feel free to give a breadcrumb any category you wish. Any categories we don’t recognize will use the default ‘custom’ styling.
Here are the recognized categories and a description of how you might categorize certain activity:
| Category | Description |
| -------- | ------------------------------------------- |
| custom | Any other kind of breadcrumb |
| error | A thrown error |
| query | Access or Updates to any data or file store |
| job | Queueing or Working via a job system |
| request | Outbound / inbound requests |
| render | Any output or serialization via templates |
| log | Any messages logged |
| notice | A Honeybadger Notice |
## Disabling breadcrumbs
[Section titled “Disabling breadcrumbs”](#disabling-breadcrumbs)
To turn off collection of breadcrumbs, use the `breadcrumbs.enabled` configuration option:
```php
$honeybadger = \Honeybadger\Honeybadger::new([
'api_key' => 'PROJECT_API_KEY',
'breadcrumbs' => [
'enabled' => false,
],
]);
```
When you do this, the Honeybadger client will stop any automatic collection of breadcrumbs and the `addBreadcrumb()` method will do nothing.
## Limits
[Section titled “Limits”](#limits)
We use the following limits on breadcrumbs to ensure the service operates smoothly for everyone:
* We only store & transmit the last 40 breadcrumb events for any error.
* Metadata can only hold scalar values (no objects, arrays or PHP resources)
* String values have a maximum size of 64Kb
# Capturing function call arguments
> Configure PHP to include function arguments in error backtraces.
Sometimes it’s helpful to see what arguments a function was called with, so you can replicate the issue and figure out the cause of the error. By default, Honeybadger will automatically include function arguments when rendering the backtrace on your dashboard. However, on some versions of PHP, you may need to enable this.
PHP 7.4 and later comes with the [zend.exception\_ignore\_args](https://www.php.net/manual/en/ini.core.php#ini.zend.exception-ignore-args) setting in the `php.ini` file. This setting is designed to protect you from accidentally divulging sensitive information to the outside world. When this setting is set to “On”, function arguments won’t be included in traces.
If you expose your stack traces to outside users, you may want to keep this as “On”. However, if your traces are only sent to your logs and trusted services like Honeybadger, it’s typically safe to set this to “Off”. If you’d like Honeybadger to capture function arguments, you’ll need to set this to “Off”.
To do this:
* Locate your ini file by running `php --ini`.
* Open the ini file and change the value of `zend.exception_ignore_args` to “Off”
```ini
; Allows to include or exclude arguments from stack traces generated for exceptions
; Default: Off
; In production, it is recommended to turn this setting on to prohibit the output
; of sensitive information in stack traces
zend.exception_ignore_args = Off
```
# Collecting user feedback
> Learn how to display error IDs and collect user feedback on Laravel error pages.
We don’t want our users to be interrupted by errors, but sometimes it does happen. Honeybadger helps you work with your users to fix errors by linking user requests to error occurrences and allowing users to leave relevant feedback on errors.
If you’re using Laravel, the `honeybadger-io/honeybadger-laravel` package comes with a few handy Blade directives to make your error pages more proactive.
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
First off, you’ll need to [publish Laravel’s inbuilt error pages](https://laravel.com/docs/errors#custom-http-error-pages) or create your own. Then you can add our directives to the Blade template. If you’re using Laravel’s error views, the default base template is `minimal.blade.php`.
Note that if you’re on development, you’ll only see [the Ignition error page](https://github.com/facade/ignition). To see the production error views, set `APP_DEBUG` in your `.env` file to `false`.
## Displaying the error ID
[Section titled “Displaying the error ID”](#displaying-the-error-id)
Whenever you send an error to Honeybadger, we return a unique UUID for that occurrence. You can easily jump to the error details at any time by visiting [https://app.honeybadger.io/notice/{the-error-uuid}](https://app.honeybadger.io/notice/%7Bthe-error-uuid%7D). You can also set the UUID to be automatically displayed on error pages, to serve as a reference.
To do this, use the `@honeybadgerError` directive in your Blade error template:
```php
@yield('code')
@yield('message')
@honeybadgerError
```
You can place the directive anywhere you wish on your page, and we’ll replace it with
```plaintext
Error ID: {the error ID}
```
If you wish to style the error view or customize the text, you can also pass `class` or `text` arguments to the directive:
```php
@honeybadgerError(["class" => "uppercase text-gray-500", "text" => "Your error ID is: "])
```
## Displaying a feedback form
[Section titled “Displaying a feedback form”](#displaying-a-feedback-form)
Honeybadger comes with an HTML form so users can provide additional helpful information about what led up to that error. Feedback responses are displayed inline in the Comments section on the error detail page.
To include the feedback form on your error page, use the `@honeybadgerFeedback` directive.
You can change the text displayed in the form via the [Laravel localization system](https://laravel.com/docs/localization). Here’s an example:
resources/lang/vendor/honeybadger/en/feedback.php
```php
return [
'thanks' => 'Thanks for the feedback!',
'heading' => 'Care to help us fix this?',
'explanation' => 'Any information you can provide will help our technical team get to the bottom of this issue.',
'labels' => [
'name' => 'Your name',
'phone' => 'Your phone number',
'email' => 'Your email address',
'comment' => 'Comment (required)',
],
'submit' => 'Send',
];
```
## Advanced customization
[Section titled “Advanced customization”](#advanced-customization)
We’ve optimized the error ID and feedback form so they render well in the default Laravel error template (`minimal.blade.php`), but your setup might be different from that. In that case, you can publish the corresponding views and customize them as you like:
```bash
php artisan vendor:publish --tag honeybadger-views
```
The views will be published to `resources/views/vendor/honeybadger`, where you can customize them as you wish, and Laravel will load your customized version.
# Configuring check-ins
> Configure Check-Ins for PHP and Laravel applications.
Note
For Laravel specific integration information, see the [Laravel](/lib/php/integration/laravel/#check-ins) page. For Lumen specific information, see the [Lumen](/lib/php/integration/lumen/) page.
Honeybadger’s PHP and Laravel packages allow configuring [Check-Ins](https://www.honeybadger.io/check-ins) via the `checkins` configuration key. Create, update or even remove check-ins for your project(s) by defining them in your configuration file. If you are using Laravel or Lumen, this should be in your `config/honeybadger.php` file.
```php
'api_key' => env('HONEYBADGER_API_KEY'),
'personal_auth_token' => env('HONEYBADGER_PERSONAL_AUTH_TOKEN'),
'checkins' => [
[
'schedule_type' => 'simple',
'name' => 'Hourly clean up',
'slug' => 'hourly-clean-up',
'grace_period' => '5 minutes',
'report_period' => '1 hour'
],
[
'schedule_type' => 'cron',
'name' => 'Hourly check',
'slug' => 'hourly-check',
'cron_schedule' => '30 * * * *',
'cron_timezone' => 'UTC'
]
]
```
## Prerequisites
[Section titled “Prerequisites”](#prerequisites)
Note
Check-ins are project specific, so you need to set the `api_key` of the project you want to create check-ins for. A `personal_auth_token` is required to create, update or remove check-ins. You can find this token under the [authentication tab in your User Settings page](https://app.honeybadger.io/users/edit#authentication).
## Check-in options
[Section titled “Check-in options”](#check-in-options)
| Field name | Required |
| --------------- | ---------------------------------------------------------- |
| `name` | No. |
| `slug` | Yes. This is the identifier used to synchronize check-ins. |
| `schedule_type` | Yes. |
| `report_period` | Only when `'schedule_type' => 'simple'`. |
| `cron_schedule` | Only when `'schedule_type' => 'cron'`. |
| `cron_timezone` | Only when `'schedule_type' => 'cron'`. |
| `grace_period` | No. |
You can find more details in the [Checkins API](/api/check-ins) page.
## Synchronization
[Section titled “Synchronization”](#synchronization)
Once you have configured your check-ins, they need to be synchronized with Honeybadger. Usually you would do this as part of your deployment pipeline.
If you are on Laravel or Lumen, you can do this by adding the `honeybadger:checkins:sync` command as an additional step to your deployment. Otherwise, you can manually create a script and run it:
```php
sync($config['checkins']);
```
The output of the command will print out created, updated or removed check-ins:
```shell
$ php artisan honeybadger:checkins:sync
Checkins were synchronized with Honeybadger.
+--------+---------------------------------------+---------------+--------------+-----------------+
| Id | Name | Schedule Type | Grace Period | Status |
+--------+---------------------------------------+---------------+--------------+-----------------+
| yaI6Pr | Weekly Exports | simple | 5 minutes | ✅ Synchronized |
| b3Ip54 | Hourly Notifications | simple | 5 minutes | ✅ Synchronized |
| l2Ie8Q | Hourly SMS Notifications (deprecated) | simple | 5 minutes | ❌ Removed |
+--------+---------------------------------------+---------------+--------------+-----------------+
```
### Validation
[Section titled “Validation”](#validation)
The synchronization process will validate the check-ins before sending them to Honeybadger. If any of the check-ins are invalid, the synchronization will fail and most probably the deployment pipeline will fail. If you want to avoid this behavior, you can ignore the result of the artisan command:
```bash
php artisan honeybadger:checkins:sync || true
```
## Troubleshooting
[Section titled “Troubleshooting”](#troubleshooting)
If you are receiving invalid API key errors, make sure you have set both `api_key` and `personal_auth_token` in your configuration file. If you are still receiving invalid API key errors, it is possible that you have reached your check-in limit or you are trying to create a check-in that is not supported by your plan.
# Customizing error grouping
> Learn how to customize how errors are grouped in Honeybadger.
Honeybadger groups similar exceptions together using rules which we’ve found to work the best in most cases. The default information we use to group errors is:
1. The file name, method name, and line number of the error’s location
2. The class name of the error
3. The component/controller name
We use this information to construct a “fingerprint” of the exception. Exceptions with the same fingerprint are treated as the same error in Honeybadger.
You can customize the grouping for each exception by changing the error class name, component, or stack trace—or by sending a custom fingerprint.
The `fingerprint` option can be used to override the fingerprint for an exception reported with the `notify()` method:
```php
$honeybadger->notify(exception, $request, ['fingerprint' => 'a unique string'])
```
# Customizing error reports
> Learn how to customize error reports with metadata and request information.
Honeybadger has several ways to customize the data reported with each error to add custom metadata and request information.
## Custom metadata (context)
[Section titled “Custom metadata (context)”](#custom-metadata-context)
Honeybadger can display additional custom key/value metadata — or “context” — with each error report. Context data can be anything, but a few keys have a special meaning in Honeybadger.
Use `$honeybadger->context();` to add global context to error reports:
```php
$honeybadger->context('user_id', 123);
// Add multiple context items:
$honeybadger->context([
'user_id' => 123,
'user_email' => 'homer@simpsons.com',
]);
```
***
While you can add any key/value data to context, a few keys have special meaning in Honeybadger:
| Option | Description |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| `user_id` | The `String` user ID used by Honeybadger to aggregate user data across occurrences on the error page. |
| `user_email` | Same as `user_id`, but for email addresses |
## Sending request information
[Section titled “Sending request information”](#sending-request-information)
Honeybadger automatically includes request information for error reports in Laravel/Lumen. In other frameworks which rely on Symphony’s HttpFoundation component, you can include request information when reporting exceptions:
```php
$honeybadger->notify($error, $request);
```
# Environments
> Configure environments in Honeybadger for PHP applications.
Honeybadger groups errors by the environment they belong to. You don’t have to set an environment, but it can be useful if you’re running your app in different locations, such as “production” and “staging”.
To set the environment in Honeybadger, add the `environment_name` setting to your [configuration](/lib/php/reference/configuration/):
```php
[
'environment_name' => 'production',
]
```
Honeybadger reports errors in all environments that also have an API key configured.
# Filtering sensitive data
> Learn how to filter sensitive data from error reports.
When Honeybadger includes request or environment data in error reports, you may want to exclude sensitive keys. We try to provide sane defaults, but you should always review the data you’re reporting to make sure you aren’t leaking sensitive information.
There are two types of potentially sensitive data in Honeybadger: [Request Parameters](#request-parameters) and [Environment Keys](#environment-keys).
## Request parameters
[Section titled “Request parameters”](#request-parameters)
You can filter sensitive request parameters using the [`request['filter']` configuration option](/lib/php/reference/configuration/). The value should be an array of keys to filter. Honeybadger filters the following keys by default:
```php
[
'request' => [
'filter' => [
'password',
'password_confirmation'
],
],
]
```
## Environment keys
[Section titled “Environment keys”](#environment-keys)
Honeybadger maintains a [whitelist of environment keys](/lib/php/reference/configuration/#environment-whitelist), so you don’t usually have to worry about leaking sensitive configuration such as API keys or passwords to 3rd-party services.
If you *do* need to filter some of the default keys, Honeybadger has you covered with the `environment['filter']` configuration option. You can also add additional keys to the whitelist with the `environment['include']` option, if you’re sure you always want to report them:
```php
[
'environment' => [
// Environment keys to filter before the payload sent to Honeybadger
'filter' => [],
// Additional environment keys to include
'include' => [],
],
]
```
# Reducing noise
> Learn how to ignore exceptions and reduce alert fatigue in your php applications.
Sometimes there are errors that you would rather not send to Honeybadger because they are not actionable or are handled internally.
In Honeybadger, you can [ignore exceptions by type](#ignoring-exceptions-by-type) using the built-in `excluded_exceptions` configuration option, as well as the `$dontReport` option in [Laravel](#laravel). You can also disable error reporting in all or some environments.
## Ignoring exceptions by type
[Section titled “Ignoring exceptions by type”](#ignoring-exceptions-by-type)
There may be some types of exceptions which you never want to report. To ignore them, use the `excluded_exceptions` [configuration option](/lib/php/reference/configuration/):
```php
[
'excluded_exceptions' => [
SomeException::class,
AnotherException::class,
],
]
```
### Laravel
[Section titled “Laravel”](#laravel)
If you’re using [Laravel](/lib/php/integration/laravel/), Honeybadger respects the `$dontReport` property of Laravel’s [exception handler](https://laravel.com/docs/5.6/errors/#the-exception-handler) when automatically reporting exceptions during web requests. This means that any exceptions which are ignored by Laravel will also be ignored by Honeybadger. You may add other exception types to this array as needed:
app/Exceptions/Handler.php
```php
/**
* A list of the exception types that should not be reported.
*
* @var array
*/
protected $dontReport = [
\Illuminate\Auth\AuthenticationException::class,
\Illuminate\Auth\Access\AuthorizationException::class,
\Symfony\Component\HttpKernel\Exception\HttpException::class,
\Illuminate\Database\Eloquent\ModelNotFoundException::class,
\Illuminate\Validation\ValidationException::class,
];
```
Keep in mind that Honeybadger will still report exceptions on this list if they are reported *outside* of Laravel’s exception handler, such as when [reporting handled exceptions](/lib/php/guides/reporting-errors#reporting-handled-exceptions/).
## Ignoring exceptions programmatically
[Section titled “Ignoring exceptions programmatically”](#ignoring-exceptions-programmatically)
You can use the `beforeNotify` callback to ignore exceptions programmatically. This callback is called before an exception is sent to Honeybadger. If the callback returns `false`, the exception will not be reported.
For example, you can ignore exceptions based on the exception message:
```php
$honeybadger->beforeNotify(function (&$notice) {
if (strpos($notice['error']['message'], 'Ignore this exception') !== false) {
return false;
}
});
```
Or, you may modify the fingerprint of the exception to group it with other similar exceptions:
```php
$honeybadger->beforeNotify(function (&$notice) {
$notice['error']['fingerprint'] = 'MyFingerprint';
});
```
**Note**: You can register multiple `beforeNotify` callbacks. If any of them return `false`, the exception will not be reported.
### Notice properties
[Section titled “Notice properties”](#notice-properties)
The `$notice` parameter is an associative array that contains the following keys:
* `breadcrumbs`
* `enabled`: Indicates if breadcrumbs are enabled, fetched from the configuration
* `trail`: The breadcrumb trail converted to an array of associative arrays, each containing:
* `message`: The message of the breadcrumb
* `category`: The category of the breadcrumb
* `metadata`: An associative array of metadata for the breadcrumb
* `timestamp`: The timestamp of the breadcrumb
* `error`
* `class`: The type of the exception.
* `message`: The exception message.
* `backtrace`: The backtrace of the exception.
* `causes`: The previous exceptions in the backtrace.
* `fingerprint`: A grouping identifier for the error, if provided.
* `tags`: Tags associated with the error, wrapped in an array.
* `request`
* `cgi_data`: CGI data from the environment, or an empty object if not available.
* `params`: Request parameters, or an empty object if not available.
* `session`: Session data, or an empty object if not available.
* `url`: The request URL.
* `context`: Context data or an empty object if not available.
* `component`: The component name, either from additional parameters or context.
* `action`: The action name, either from additional parameters or context.
* `server`
* `pid`: The process ID.
* `version`: The application version.
* `hostname`: The hostname of the server.
* `project_root`: The root directory of the project.
* `environment_name`: The name of the environment.
## Disabling error reporting
[Section titled “Disabling error reporting”](#disabling-error-reporting)
You can disable error reporting completely by setting the `report_data` config option to false. For example, the default Laravel config has this as:
```php
'report_data' => ! in_array(env('APP_ENV'), ['local', 'testing']),
```
This means exceptions won’t be reported to Honeybadger in `local` and `testing` environments. If you want to change that, you can easily add or remove environments or set `report_data` to `true`.
# Reporting errors
> Learn how to report errors to Honeybadger in PHP applications.
Honeybadger reports uncaught exceptions automatically. In all other cases, use `$honeybadger->notify()` and `$honeybadger->customNotification()` to send errors to Honeybadger.
## Reporting unhandled exceptions
[Section titled “Reporting unhandled exceptions”](#reporting-unhandled-exceptions)
By default, `honeybadger-php` registers global error and exception handlers which automatically report all unhandled exceptions to Honeybadger. These handlers can be disabled via the following [configuration options](/lib/php/reference/configuration/#default-configuration):
```php
[
'handlers' => [
// Enable global exception handler
'exception' => true,
// Enable global error handler
'error' => true,
]
]
```
## Reporting handled exceptions
[Section titled “Reporting handled exceptions”](#reporting-handled-exceptions)
To catch an exception and notify Honeybadger without re-throwing:
```php
try {
throw new Exception('Whoops!');
} catch (Exception $e) {
$honeybadger->notify($e);
}
```
You can call `$honeybadger->notify()` anywhere in your code where you have an `Exception` to report.
### Including request data
[Section titled “Including request data”](#including-request-data)
You can optionally include a `\Symfony\Component\HttpFoundation\Request::class` request as the second argument to `$honeybadger->notify()`:
```php
$honeybadger->notify($e, $app->request());
```
When the request is included, HTTP information such as params, headers, and session data will be sent to Honeybadger.
## Sending custom notifications
[Section titled “Sending custom notifications”](#sending-custom-notifications)
To notify Honeybadger of other types of errors:
```php
$honeybadger->customNotification([
'title' => 'Special Error',
'message' => 'Special Error: a special error has occurred',
]);
```
### Options
[Section titled “Options”](#options)
| Option Name | Description |
| ----------- | ------------------------------------------------- |
| title | The title of the error (normally the class name). |
| message | The error message. |
# Sending events to Insights
> Learn how to send events to Honeybadger Insights from PHP applications.
Honeybadger’s PHP (v2.19+) and Laravel (v4.1+) packages can be used to send events to [Insights](/guides/insights/).
## Automatic instrumentation
[Section titled “Automatic instrumentation”](#automatic-instrumentation)
If you’re using Laravel or Lumen, Honeybadger provides automatic instrumentation to capture events from your apps. By default, we’ll record:
* [Log events](https://laravel.com/docs/logging)
* [View renders](https://laravel.com/docs/views)
* [Email dispatches](https://laravel.com/docs/mail)
* [Job dispatches](https://laravel.com/docs/queues)
* [Notification dispatches](https://laravel.com/docs/notifications)
* [Database queries](https://laravel.com/docs/queries)
* [Redis commands](https://laravel.com/docs/redis)
* Incoming requests
You can customise this with the `events` option in your `config/honeybadger.php`:
```php
'events' => [
'enabled' => true,
'automatic' => [
Events\DatabaseQueryExecuted::class,
Events\DatabaseTransactionStarted::class,
Events\DatabaseTransactionCommitted::class,
Events\DatabaseTransactionRolledBack::class,
Events\CacheHit::class,
Events\CacheMiss::class,
Events\JobQueued::class,
Events\MailSending::class,
Events\MailSent::class,
Events\MessageLogged::class,
Events\NotificationSending::class,
Events\NotificationSent::class,
Events\NotificationFailed::class,
Events\RedisCommandExecuted::class,
Events\RouteMatched::class,
Events\ViewRendered::class,
],
],
```
The `events.automatic` key contains the list of the events Honeybadger tracks by default. You can disable a specific event by removing or commenting out the appropriate line.
## Manually sending events
[Section titled “Manually sending events”](#manually-sending-events)
You can also send events manually. Start by configuring Honeybadger and enabling events:
```php
$honeybadger = Honeybadger\Honeybadger::new([
'api_key' => 'my-api-key',
'events' => [
'enabled' => true
]
]);
```
Then you can send events using the `$honeybadger->event` method:
```php
$honeybadger->event('user_activity', [
'action' => 'registration',
'user_id' => 123
])
```
The first argument is the type of the event (`event_type`) and the second argument is an object containing any additional data you want to include.
`$honeybadger->event` can also be called with a single argument as an object containing the data for the event:
```php
$honeybadger->event([
'event_type' => 'user_activity',
'action' => 'registration',
'user_id' => 123
])
```
A timestamp field (`ts`) will be automatically added to the event data if it is not provided, regardless of the method used to send the event.
These events may be found using the following BadgerQL query:
```plaintext
fields @ts, @preview
| filter event_type::str == "user_activity"
| filter action::str == "registration"
| sort @ts
```
## Automatic log instrumentation
[Section titled “Automatic log instrumentation”](#automatic-log-instrumentation)
You can send your application logs to Insights either by sending them to Honeybadger from your [infrastructure](/guides/insights/integrations/log-files/) **or** if you are using Monolog, you can register Honeybadger’s `LogEventHandler` class as a handler:
```php
$logger = new Monolog\Logger('my-logger');
$honeybadger = Honeybadger\Honeybadger::new([
'api_key' => 'my-api-key'
]);
$logger->pushHandler(new Honeybadger\LogEventHandler($honeybadger));
$logger->info('An info message');
$logger->info('An info message with context data', ["some-key" => "some-value"]);
$logger->error('An error message');
```
You can send an optional second argument to the `LogEventHandler` constructor to specify the minimum log level to be sent to Honeybadger. The default is `Monolog\Logger::INFO`.
```php
new Honeybadger\LogEventHandler($honeybadger, Monolog\Logger::DEBUG);
```
This will send all log messages to Insights, where they will be displayed in the [Insights](https://www.honeybadger.io/tour/logging-observability) section of your dashboard.
### Using Laravel or Lumen
[Section titled “Using Laravel or Lumen”](#using-laravel-or-lumen)
If you are using Laravel or Lumen, [register a custom channel](https://laravel.com/docs/11.x/logging#creating-custom-channels-via-factories) in your `config/logging.php`, making use of the `HoneybadgerLogEventDriver`:
config/logging.php
```php
'channels' => [
// ...
'honeybadger' => [
'driver' => 'custom',
'via' => Honeybadger\HoneybadgerLaravel\HoneybadgerLogEventDriver::class,
'name' => 'honeybadger',
'level' => 'info',
],
],
```
Now you can write log messages as normal with Laravel’s log facade, and they’ll show up in Honeybadger Insights:
```php
Log::channel('honeybadger')->info('An info message');
Log::channel('honeybadger')->error('An error message with context', ["some-key" => "some-value"]);
```
Add this custom channel to your default stack and voilà, all your log messages will appear in Honeybadger Insights:
config/logging.php
```php
'channels' => [
'stack' => [
'driver' => 'stack',
'channels' => ['single', 'honeybadger'],
'ignore_exceptions' => false,
],
// ...
],
```
## Ignoring events
[Section titled “Ignoring events”](#ignoring-events)
You can ignore events programmatically using the `beforeEvent` callback. This callback is called before an event is sent to Honeybadger. If the callback returns `false`, the event will not be sent.
For example, you can ignore events based on the event type:
```php
$honeybadger->beforeEvent(function (&$event) {
if ($event['event_type'] === 'user_activity' && $event['action'] === 'registration') {
return false;
}
});
```
Or, you may modify the event data before it is sent:
```php
$honeybadger->beforeEvent(function (&$event) {
$event['user_id'] = 456;
});
```
**Note**: You can register multiple `beforeEvent` callbacks. If any of them return `false`, the event will not be sent.
## Sampling events
[Section titled “Sampling events”](#sampling-events)
If you find that you’d like to report fewer events in order to minimize your quota consumption, you can update your configuration in `config/honeybadger.php` to conditionally send a certain percentage of events:
```php
'events' => [
'enabled' => true,
'sample_rate' => 10
]
```
This will send 10% of events not associated with a request, and all events for 10% of requests.
# Tracking deploys
> Learn how to use Honeybadger to track deployments in your PHP application.
Honeybadger can keep track of application deployments, and link errors to the version which the error occurred in. Here’s a simple `curl` script to record a deployment:
```sh
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
&& curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"
```
Be sure that the same revision is also configured in the honeybadger-js library. Read more about deploy tracking in the [API docs](/api/deployments/).
If you are using our EU stack, you should use `eu-api.honeybadger.io` instead of `api.honeybadger.io` for the `curl` command.
### Tracking deploys from Laravel Forge
[Section titled “Tracking deploys from Laravel Forge”](#tracking-deploys-from-laravel-forge)
If you are deploying your site with [Laravel Forge](https://forge.laravel.com), you can notify Honeybadger of deployments via Deployment Notifications. Use this format for your webhook URL:
`https://api.honeybadger.io/v1/deploys/forge?api_key=YOUR_HONEYBADGER_API_KEY_HERE&environment=production`
If you are using our EU stack, you should use `eu-api.honeybadger.io` instead of `api.honeybadger.io` in the webhook URL.
### Deploying with GitHub Actions
[Section titled “Deploying with GitHub Actions”](#deploying-with-github-actions)
If your CI/CD pipeline is hosted with GitHub Actions, you can use the [Honeybadger Deploy Action](https://github.com/marketplace/actions/honeybadger-deploy-action) to notify our API about deployments.
# Laravel integration guide
> Honeybadger monitors your Laravel applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **Laravel error and exception tracking**. Once installed, Honeybadger will automatically report errors wherever they may happen:
* During a web request
* In a scheduled command
* In a background task
* When a process crashes
## Installation
[Section titled “Installation”](#installation)
First, install the [honeybadger-laravel](https://github.com/honeybadger-io/honeybadger-laravel) package via composer:
```bash
composer require honeybadger-io/honeybadger-laravel
```
### Laravel version support
[Section titled “Laravel version support”](#laravel-version-support)
Install the version of our package based on the version of Laravel you are using:
| Laravel Version | Honeybadger Laravel Version |
| --------------- | --------------------------- |
| 12.x | 4.x (current) |
| 11.x | 4.x (current) |
| 10.x | 4.x (current) |
| 9.x | 3.13.x |
| 8.x | 3.2.x |
| 7.x | 3.x |
| 6.x | 2.x |
| 5.x | 1.x |
***
Note
This package uses Laravel’s [package discovery](https://laravel.com/docs/12.x/packages#package-discovery) to register the service provider and facade to the framework. If you are using an older version of Laravel or do not use package discovery, you may need to [manually register those components](/lib/php/integration/laravel-advanced/).
***
Next, add Honeybadger reporting to Laravel 11 and later by adding the following to `bootstrap/app.php` ():
bootstrap/app.php
```php
->withExceptions(function (Exceptions $exceptions) {
$exceptions->report(static function (Throwable $e) {
if (app()->bound('honeybadger')) {
app('honeybadger')->notify($e, app('request'));
}
});
})
```
In Laravel 8.5 to 10, the default handler comes with a [`register()` method](https://laravel.com/docs/10.x/errors#reporting-exceptions); you should add the Honeybadger client within the `reportable()` callback.
app/Exceptions/Handler.php
```php
public function register()
{
$this->reportable(function (Throwable $e) {
if (app()->bound('honeybadger')) {
app('honeybadger')->notify($e, app('request'));
}
});
}
```
On earlier versions of Laravel, add the client within the `report($exception)` method:
```php
public function report(Throwable $exception)
{
if (app()->bound('honeybadger') && $this->shouldReport($exception)) {
app('honeybadger')->notify($exception, app('request'));
}
parent::report($exception);
}
```
Finally, run the `honeybadger:install` artisan command.
```bash
php artisan honeybadger:install [Your project API key]
```
If you are using our EU stack, add the `--endpoint` and the `--appEndpoint` flags to the `honeybadger:install` command:
```bash
php artisan honeybadger:install [Your project API key] --endpoint=https://eu-api.honeybadger.io --appEndpoint=https://eu-app.honeybadger.io
```
The `honeybadger:install` command does three things:
1. Adds `HONEYBADGER_API_KEY` to `.env` and `.env.example`
2. If you added the `--endpoint` and `--appEndpoint` flags, it also adds `HONEBADGER_ENDPONT` and `HONEYBADGER_APP_ENDPOINT` to `.env` and `.env.example`.
3. Creates Honeybadger’s `config/honeybadger.php` configuration file
4. Sends a test notification to your Honeybadger project
If everything is set up correctly, you should now have an error report in Honeybadger!
Note
The default config for Laravel won’t report errors to Honeybadger on `local` and `testing` environments. You can change that with the [`report_data` option](/lib/php/guides/reducing-noise/#disabling-error-reporting).
## Identifying users and controller/action
[Section titled “Identifying users and controller/action”](#identifying-users-and-controlleraction)
Honeybadger automatically captures details about the current logged-in user, as well as the controller and method name. No extra configuration needed. We only capture the user ID, so no sensitive information is transmitted.
When an error occurs, you’ll see an **Affected Users** section on your dashboard, where we’ll list the user IDs and how many times they encountered the error.
## Adding context
[Section titled “Adding context”](#adding-context)
[Context](/lib/php/guides/customizing-error-reports/) can be added by either the provided Facade or by resolving from the service container.
### Facade
[Section titled “Facade”](#facade)
```php
Honeybadger::context('key', $value);
```
### DI resolution
[Section titled “DI resolution”](#di-resolution)
```php
use Honeybadger\Honeybadger;
public function __construct(Honeybadger $honeybadger)
{
$honeybadger->context('key', $value);
}
```
### Helper resolution
[Section titled “Helper resolution”](#helper-resolution)
```php
use Honeybadger\Honeybadger;
public function __construct()
{
app('honeybadger')->context('key', $value);
app(Honeybadger::class)->context('key', $value)
}
```
## Check-Ins
[Section titled “Check-Ins”](#check-ins)
`honeybadger-laravel` integrates with [Honeybadger’s Check-In feature](https://www.honeybadger.io/check-ins) to help you know when your scheduled tasks and background jobs go missing or silently fail.
To get started, create a new check-in in the Check-Ins tab of your project dashboard. You’ll be given a check-in URL that looks like this: . Take note of the check-in ID; it’s the last part of the check-in URL. In this example, it’s **Jiy63Xw**. Alternatively, you can setup your [check-ins entirely within your configuration file](/lib/php/guides/configuring-checkins/). If you follow this method, you don’t need the check-in ID anymore and instead you can use the check-in slug.
#### Run a one-off check-in
[Section titled “Run a one-off check-in”](#run-a-one-off-check-in)
To run a one-off check-in, use the `honeybadger:checkin` command with your check-in ID. This will let Honeybadger know that your app is alive.
```bash
php artisan honeybadger:checkin Jiy63Xw
```
Or if you have configured your check-ins in your configuration file:
```bash
php artisan honeybadger:checkin "my-checkin"
```
#### Scheduled command
[Section titled “Scheduled command”](#scheduled-command)
You can schedule the check-in command to run at an interval. This method is great for ensuring your application is up and running.
app/Console/Kernel.php
```php
protected function schedule(Schedule $schedule)
{
$schedule->command('honeybadger:checkin Jiy63Xw')->everyFiveMinutes();
// or using the check-in slug
$schedule->command('honeybadger:checkin "my-checkin"')->everyFiveMinutes();
}
```
#### After a scheduled command
[Section titled “After a scheduled command”](#after-a-scheduled-command)
You can use the `thenPingHoneybadger($checkInId)` macro to check-in after certain scheduled commands are run. This method is great for making sure specific scheduled commands are running on time.
app/Console/Kernel.php
```php
protected function schedule(Schedule $schedule)
{
$schedule->command(SendEmails::class)->daily()
->thenPingHoneybadger('Jiy63Xw');
// or using the check-in slug
->thenPingHoneybadger('my-checkin');
}
```
In this example, if `SendEmails` fails to run for some reason, Honeybadger will notify you.
You can also specify the environments where the check-in is allowed to run:
app/Console/Kernel.php
```php
protected function schedule(Schedule $schedule)
{
$schedule->command(SendEmails::class)->daily()
->thenPingHoneybadger('Jiy63Xw', 'production');
// or using the check-in slug
->thenPingHoneybadger('my-checkin', 'production');
$schedule->command(CheckStatus::class)->daily()
->thenPingHoneybadger('Jiy63Xw', ['production', 'staging']);
// or using the check-in slug
->thenPingHoneybadger('my-checkin', ['production', 'staging']);
}
```
#### After a successful scheduled command
[Section titled “After a successful scheduled command”](#after-a-successful-scheduled-command)
You can use the `pingHoneybadgerOnSuccess($checkInId)` macro to ensure that a certain command was run and completed successfully. This method is great for making sure specific scheduled commands are running on time **only if it was successful**. Like the `thenPingHoneybadger` method, you can also restrict it to specific environments.
app/Console/Kernel.php
```php
protected function schedule(Schedule $schedule)
{
$schedule->command(SendEmails::class)->daily()
->pingHoneybadgerOnSuccess('Jiy63Xw', 'production');
// or using the check-in slug
->pingHoneybadgerOnSuccess('my-checkin', 'production');
}
```
## Using Honeybadger as a logger
[Section titled “Using Honeybadger as a logger”](#using-honeybadger-as-a-logger)
Note
If you want to send your logs to Honeybadger, consider sending them to Insights instead. You can [learn more here](/guides/insights/) and enable the integration by following the instructions [here](/lib/php/guides/sending-events-to-insights/).
If you prefer, you can also use Honeybadger as a log channel in your Laravel app. To do this, you’ll need to [register a custom channel](https://laravel.com/docs/11.x/logging#creating-custom-channels-via-factories) in your `config/logging.php`, making use of the `HoneybadgerLogDriver`:
config/logging.php
```php
'channels' => [
// ...
'honeybadger' => [
'driver' => 'custom',
'via' => Honeybadger\HoneybadgerLaravel\HoneybadgerLogDriver::class,
'name' => 'honeybadger',
'level' => 'error',
],
],
```
Now you can write log messages as normal with Laravel’s log facade, and they’ll show up on your Honeybadger dashboard.
```php
Log::channel('honeybadger')->error('An error message');
Log::channel('honeybadger')->error('An error message with context', ["some-key" => "some-value"]);
Log::channel('honeybadger')->error($exception);
```
If you include an `exception` context item in your error messages, we’ll automatically format them for easy viewing:
```php
$e = new \Exception('Something happened');
Log::channel('honeybadger')->error('An error message', ['exception' => $e]);
```
You can also add the custom channel to your default stack so you can automatically have exceptions logged to Honeybadger as well:
config/logging.php
```php
'channels' => [
'stack' => [
'driver' => 'stack',
'channels' => ['single', 'honeybadger'],
'ignore_exceptions' => false,
],
// ...
],
```
# Manual Laravel integration
> Learn how to manually integrate Honeybadger with older Laravel versions or when package discovery is disabled.
The
[`honeybadger-laravel` package](https://github.com/honeybadger-io/honeybadger-laravel) uses Laravel’s [package discovery](https://laravel.com/docs/5.6/packages#package-discovery) to register the service provider and facade to the framework. If you are using an older version of Laravel or do not use package discovery see below.
### Step 1: Register the provider with the framework
[Section titled “Step 1: Register the provider with the framework”](#step-1-register-the-provider-with-the-framework)
config/app.php
```php
'providers' => [
/*
* Package Service Providers...
*/
\Honeybadger\HoneybadgerLaravel\HoneybadgerServiceProvider::class,
]
```
### Step 2: Register the facade with the framework
[Section titled “Step 2: Register the facade with the framework”](#step-2-register-the-facade-with-the-framework)
config/app.php
```php
'aliases' => [
'Honeybadger' => \Honeybadger\HoneybadgerLaravel\Facades\Honeybadger::class,
]
```
# Lumen integration guide
> Honeybadger monitors your Lumen applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **Lumen error and exception tracking**. Once installed, Honeybadger will automatically report errors wherever they may happen:
* During a web request
* In a scheduled command
* In a background task
* When a process crashes
## Installation
[Section titled “Installation”](#installation)
First, install the [honeybadger-laravel](https://github.com/honeybadger-io/honeybadger-laravel) package via composer:
```bash
composer require honeybadger-io/honeybadger-laravel
```
…and add the following line to `bootstrap/app.php` under the “Register Service Providers” section:
```php
$app->register(\Honeybadger\HoneybadgerLaravel\HoneybadgerServiceProvider::class);
```
Next, add Honeybadger reporting to `app/Exceptions/Handler.php`:
```php
public function report(Exception $exception)
{
if (app()->bound('honeybadger') && $this->shouldReport($exception)) {
app('honeybadger')->notify($exception, app('request'));
}
parent::report($exception);
}
```
Finally, run the `honeybadger:install` artisan command:
```bash
php artisan honeybadger:install [Your project API key]
```
The `honeybadger:install` command does three things:
1. Adds `HONEYBADGER_API_KEY` to `.env` and `.env.example`
2. Creates Honeybadger’s `config/honeybadger.php` configuration file
3. Sends a test notification to your Honeybadger project
If everything is set up correctly, you should now have an error report in Honeybadger!
Note
The default config for Lumen won’t report errors to Honeybadger on `local` and `testing` environments. You can change that with the [`report_data` option](/lib/php/guides/reducing-noise/).
## Identifying users
[Section titled “Identifying users”](#identifying-users)
Honeybadger automatically captures details about the current logged-in user, as well as the controller and method name. No extra configuration needed. We only capture the user ID, so no sensitive information is transmitted.
When an error occurs, you’ll see an **Affected Users** section on your dashboard, where we’ll list the user IDs and how many times they encountered the error.
## Adding context
[Section titled “Adding context”](#adding-context)
[Context](/lib/php/guides/customizing-error-reports/) can be added by either the provided Facade or by resolving from the service container.
### Facade
[Section titled “Facade”](#facade)
```php
Honeybadger::context('key', $value);
```
### DI resolution
[Section titled “DI resolution”](#di-resolution)
```php
use Honeybadger\Honeybadger;
public function __construct(Honeybadger $honeybadger)
{
$honeybadger->context('key', $value);
}
```
### Helper resolution
[Section titled “Helper resolution”](#helper-resolution)
```php
use Honeybadger\Honeybadger;
public function __construct()
{
app('honeybadger')->context('key', $value);
app(Honeybadger::class)->context('key', $value)
}
```
## Using Honeybadger as a logger
[Section titled “Using Honeybadger as a logger”](#using-honeybadger-as-a-logger)
Note
If you want to send your logs to Honeybadger, consider sending them to Insights instead. You can [learn more here](/guides/insights/) and enable the integration by following the instructions [here](/lib/php/guides/sending-events-to-insights/).
If you prefer, you can also use Honeybadger as a log channel in your Lumen app. To do this, you’ll need to [register a custom channel](https://laravel.com/docs/logging#creating-custom-channels-via-factories) in your `config/logging.php`, making use of the `HoneybadgerLogDriver`.
If you don’t have a `config/logging.php` file, you can create one by copying the contents of the one [embedded in Lumen](https://github.com/laravel/lumen-framework/blob/8.x/config/logging.php).
Once you’ve done that, you can add a custom channel called “honeybadger”:
config/logging.php
```php
'channels' => [
// ...
'honeybadger' => [
'driver' => 'custom',
'via' => Honeybadger\HoneybadgerLaravel\HoneybadgerLogDriver::class,
'name' => 'honeybadger'
],
],
```
Now you can write log messages as normal with Lumen’s log facade, and they’ll show up on your Honeybadger dashboard.
```php
Log::channel('honeybadger')->info('An info message');
Log::channel('honeybadger')->('An info message with context data', ["some-key" => "some-value"]);
Log::channel('honeybadger')->error('An error message');
```
If you include an `exception` context item in your error messages, we’ll automatically format them for easy viewing:
```php
$e = new \Exception('Something happened');
Log::channel('honeybadger')->error('An error message', ['exception' => $e]);
```
You can also add the custom channel to your default stack so you can automatically have exceptions logged to Honeybadger as well:
config/logging.php
```php
'channels' => [
'stack' => [
'driver' => 'stack',
'channels' => ['single', 'honeybadger'],
'ignore_exceptions' => false,
],
// ...
],
```
# PHP integration guide
> Honeybadger monitors your PHP applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 3 minutes
Hi there! You’ve found Honeybadger’s guide to **PHP exception and error tracking**. Note: if you use **Laravel**, go check out the **[Laravel Integration Guide](/lib/php/integration/laravel/)**. If not, then read on!
This guide will teach you how to install and configure the default **Honeybadger for PHP** client and use it to manually [report errors to Honeybadger](/lib/php/guides/reporting-errors/).
## Installation
[Section titled “Installation”](#installation)
First, install the [honeybadger-php](https://github.com/honeybadger-io/honeybadger-php) package via composer:
```bash
composer require honeybadger-io/honeybadger-php
```
Then, configure the Honeybadger client in your application:
```php
$honeybadger = Honeybadger\Honeybadger::new([
'api_key' => 'PROJECT_API_KEY'
]);
```
Honeybadger can report exceptions in several ways. To test that the Honeybadger client is working, try sending a custom notification:
```php
$honeybadger->customNotification([
'title' => 'Special Error',
'message' => 'Special Error: a special error has occurred',
]);
```
To catch exceptions in your code and report them to Honeybadger:
```php
try {
throw new Exception('Whoops!');
} catch (Exception $e) {
// You can optionally include your own
// \Symfony\Component\HttpFoundation\Request::class request.
$honeybadger->notify($e, $app->request());
}
```
## Adding context
[Section titled “Adding context”](#adding-context)
In Honeybadger, **context** is a custom array of data that’s displayed with your error reports. You can add context from anywhere in your app, and it will be included automatically when reporting errors. For example, you could include the ID of the currently logged-in user:
```php
$honeybadger->context('user_id', $this->Auth->user('id'));
```
See [Customizing Error Reports](/lib/php/guides/customizing-error-reports/) for more info.
## Handling service exceptions
[Section titled “Handling service exceptions”](#handling-service-exceptions)
When the client is unable to send a report to Honeybadger’s service, it will throw an instance of `\Honeybadger\Exceptions\ServiceException`. To prevent this from crashing your app and hiding the original error, you can set the `service_exception_handler` option to a closure where you can handle the exception yourself:
```php
$honeybadger = Honeybadger\Honeybadger::new([
'api_key' => 'PROJECT_API_KEY',
'service_exception_handler' => function (ServiceException $e) {
$logger->error($e);
},
]);
```
## Using Honeybadger as a logger
[Section titled “Using Honeybadger as a logger”](#using-honeybadger-as-a-logger)
Note
If you want to send your logs to Honeybadger, consider sending them to Insights instead. You can [learn more here](/guides/insights/) and enable the integration by following the instructions [here](/lib/php/guides/sending-events-to-insights/).
If you’re using the PHP logging library [Monolog](https://github.com/Seldaek/monolog) in your app, you can also choose to use Honeybadger as a log handler, by using the `LogHandler` class. Then write log messages as normal with Monolog, and they’ll show up on your Honeybadger dashboard.
```php
$logger = new Monolog\Logger('my-logger');
$honeybadger = Honeybadger\Honeybadger::new([
'api_key' => 'my-api-key'
]);
$logger->pushHandler(new Honeybadger\LogHandler($honeybadger));
$logger->info('An info message');
$logger->info('An info message with context data', ["some-key" => "some-value"]);
$logger->error('An error message');
```
If you include an `exception` context item in your error messages, we’ll automatically format them for easy viewing:
```php
$e = new \Exception('Something happened');
$logger->error('An error message', ['exception' => $e]);
```
# WordPress integration guide
> Honeybadger monitors your WordPress sites for errors and exceptions so that you can fix them quickly.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **WordPress error and exception tracking**. Once installed, Honeybadger will automatically report errors wherever they may happen, both in the front-end (JavaScript) and back-end (PHP) of your WordPress site.
## Installation
[Section titled “Installation”](#installation)
First, install the [Honeybadger Application Monitoring](https://wordpress.org/plugins/honeybadger-application-monitoring) plugin via the WordPress plugin repository:
1. In your WordPress admin panel, go to **Plugins** > **Add New**.
2. Search for “Honeybadger Application Monitoring”.
3. Click **Install Now** next to the Honeybadger plugin.
4. After installation, click **Activate**.
Alternatively, you can install the plugin manually:
1. Download the plugin from the [WordPress plugin repository](https://wordpress.org/plugins/honeybadger-application-monitoring).
2. Upload the plugin files to the `/wp-content/plugins/honeybadger-application-monitoring` directory.
3. Activate the plugin through the **Plugins** page in WordPress.
## Configuration
[Section titled “Configuration”](#configuration)
After activating the plugin, you need to configure it with your Honeybadger API key(s):
1. In your WordPress admin panel, go to **Settings** > **Honeybadger**.
2. Grab your API key(s) from your Honeybadger project settings. It is recommended that you have two separate projects, one for PHP and another for JavaScript error tracking.
3. Enter your Honeybadger API key(s) in the **PHP API Key** and **JS API Key** fields.
4. Ensure that **PHP error reporting enabled** is checked if you want to track PHP errors, as well as **JS error reporting enabled** if you want to track JavaScript errors.
5. (Optional) You can also configure the **Environment** and **Version** settings to better track your errors.
6. Click **Save Changes**.
## Testing the integration
[Section titled “Testing the integration”](#testing-the-integration)
To ensure everything is set up correctly, you can trigger a test error:
1. In your WordPress admin panel, go to **Settings** > **Honeybadger**.
2. Check the **Send test notification from PHP** or **Send test notification from JS** checkboxes.
3. Click **Save Changes**.
If everything is set up correctly, you should now have an error (or two if you checked both checkboxes) reported in Honeybadger!
Note
Make sure to uncheck the test notification checkboxes after testing to avoid unnecessary test errors in your Honeybadger dashboard.
# Configuration
> Configuration options for Honeybadger PHP and Laravel packages.
There are several ways to configure Honeybadger. See [Default Configuration](#default-configuration) for all the options that are available.
## Creating a new client
[Section titled “Creating a new client”](#creating-a-new-client)
In any PHP app, you can configure a new Honeybadger client directly via its constructor function:
```php
$honeybadger = Honeybadger\Honeybadger::new([
'api_key' => 'PROJECT_API_KEY'
]);
```
Using Honeybadger this way is good for creating custom integrations or adding Honeybadger to frameworks which don’t have an official integration yet.
## Laravel/Lumen
[Section titled “Laravel/Lumen”](#laravellumen)
In [Laravel](/lib/php/integration/laravel/) and [Lumen](/lib/php/integration/lumen/) apps, you should add your configuration to `config/honeybadger.php` instead.
In addition to the [default configuration](#default-configuration) below, you can also define the [`middleware`](https://github.com/honeybadger-io/honeybadger-laravel/blob/master/config/honeybadger.php) option to enable or disable middleware that are automatically registered by the package. For example, the [`AssignRequestId`](https://github.com/honeybadger-io/honeybadger-laravel/blob/master/src/Middleware/AssignRequestId.php) middleware is registered by default, which assigns a unique request ID to each request. If you already have a way to assign request IDs in your app, you can disable this middleware.
## Default configuration
[Section titled “Default configuration”](#default-configuration)
The default configuration options are shown below:
```php
[
// Honeybadger API Key
'api_key' => null,
// Personal authentication token (needed to synchronize checkins from this configuration file)
'personal_auth_token' => null,
// The application environment
'environment_name' => 'production',
// To disable exception reporting, set this to false (or an expression that returns false).
'report_data' => ! in_array(env('APP_ENV'), ['local', 'testing']),
'environment' => [
// Environment keys to filter before the payload sent to Honeybadger (see Environment Whitelist)
'filter' => [],
// Additional environment keys to include (see Environment Whitelist)
'include' => [],
],
'request' => [
// Request keys to filter before the payload sent to Honeybadger
'filter' => [
'password',
'password_confirmation'
],
],
// Application version
'version' => '',
// System hostname
'hostname' => gethostname(),
// Project root (/var/www)
'project_root' => '',
'handlers' => [
// Enable global exception handler
'exception' => true,
// Enable global error handler
'error' => true,
// Enable global shutdown handler
'shutdown' => true,
],
// Configure the underlying Guzzle client used
'client' => [
// Request timeout in seconds (default: 15s)
'timeout' => 15,
// Request proxy settings
'proxy' => [
// Use this proxy with 'http' (tcp://username:password@localhost:8125)
'http' => '',
// Use this proxy with 'https' (tcp://username:password@localhost:8125)
'https' => '',
],
],
// Specify a custom endpoint
'endpoint' => 'https://api.honeybadger.io',
// Exclude exceptions from being reported
'excluded_exceptions' => [],
// Enable reporting deprecation warnings.
'capture_deprecations' => false,
// Specify how failures to reach Honeybadger should be handled
'service_exception_handler' => function (\Honeybadger\Exceptions\ServiceException $e) {
throw $e;
},
// Enable breadcrumbs
'breadcrumbs' => [
'enabled' => true,
],
// Define your checkins here and synchronize them to Honeybadger
'checkins' => [],
// Configure Insights events reporting
'events' => [
'enabled' => false,
'bulk_threshold' => BulkEventDispatcher::BULK_THRESHOLD,
'dispatch_interval_seconds' => BulkEventDispatcher::DISPATCH_INTERVAL_SECONDS,
'sample_rate' => 100 // Percentage of events to send
],
]
```
## Environment whitelist
[Section titled “Environment whitelist”](#environment-whitelist)
All keys beginning with `HTTP_` are reported by default, as well as the following whitelisted keys:
```plaintext
'PHP_SELF'
'argv'
'argc'
'GATEWAY_INTERFACE'
'SERVER_ADDR'
'SERVER_NAME'
'SERVER_SOFTWARE'
'SERVER_PROTOCOL'
'REQUEST_METHOD'
'REQUEST_TIME'
'REQUEST_TIME_FLOAT'
'QUERY_STRING'
'DOCUMENT_ROOT'
'HTTPS'
'REMOTE_ADDR'
'REMOTE_HOST'
'REMOTE_PORT'
'REMOTE_USER'
'REDIRECT_REMOTE_USER'
'SCRIPT_FILENAME'
'SERVER_ADMIN'
'SERVER_PORT'
'SERVER_SIGNATURE'
'PATH_TRANSLATED'
'SCRIPT_NAME'
'REQUEST_URI'
'PHP_AUTH_DIGEST'
'PHP_AUTH_USER'
'PHP_AUTH_PW'
'AUTH_TYPE'
'PATH_INFO'
'ORIG_PATH_INFO'
'APP_ENV'
```
## Exceptions
[Section titled “Exceptions”](#exceptions)
If there is an error contacting Honeybadger a `\Honeybadger\Exceptions\ServiceException::class` will be thrown with a relevant exception message.
# Supported versions
> Supported PHP and Laravel versions for Honeybadger packages.
* [`honeybadger-php`](https://github.com/honeybadger-io/honeybadger-php) works with **PHP 7+**.
* [`honeybadger-laravel`](https://github.com/honeybadger-io/honeybadger-laravel) works with **PHP 7+** and **Laravel 7+**.
* Use the latest [2.x release](https://github.com/honeybadger-io/honeybadger-laravel/releases) for Laravel 6 LTS support
# Frequently asked questions
> Common questions about Honeybadger for PHP.
Don’t see your question here? See [Getting Support](/lib/php/#getting-support) for next steps.
### How do I ignore certain errors?
[Section titled “How do I ignore certain errors?”](#how-do-i-ignore-certain-errors)
See [Reducing Noise](/lib/php/guides/reducing-noise/).
### How do I remove sensitive params or other data from error reports?
[Section titled “How do I remove sensitive params or other data from error reports?”](#how-do-i-remove-sensitive-params-or-other-data-from-error-reports)
See [Filtering Sensitive Data](/lib/php/guides/filtering-sensitive-data/).
# Troubleshooting
> Common issues and workarounds for Honeybadger PHP packages.
Common issues/workarounds for [`honeybadger-php`](https://github.com/honeybadger-io/honeybadger-php) and [`honeybadger-laravel`](https://github.com/honeybadger-io/honeybadger-laravel) are documented here. If you don’t find a solution to your problem here or in our [support documentation](/lib/php/#getting-support), email and we’ll assist you!
## Before you start troubleshooting
[Section titled “Before you start troubleshooting”](#before-you-start-troubleshooting)
1. Make sure you are on the latest version of [honeybadger-php](https://packagist.org/packages/honeybadger-io/honeybadger-php) and/or [honeybadger-laravel](https://packagist.org/packages/honeybadger-io/honeybadger-laravel).
### All errors are not reported
[Section titled “All errors are not reported”](#all-errors-are-not-reported)
If *no* errors are reported (even [manually via `$honeybadger->notify()`](/lib/php/guides/reporting-errors/)):
1. [Is the `api_key` config option configured?](/lib/php/reference/configuration/)
2. [Is `report_data` set to `false`?](/lib/php/guides/reducing-noise/)
### Some errors are not reported
[Section titled “Some errors are not reported”](#some-errors-are-not-reported)
1. [Is the error ignored via config?](/lib/php/guides/reducing-noise/)
### Function call arguments aren’t shown in the backtrace
[Section titled “Function call arguments aren’t shown in the backtrace”](#function-call-arguments-arent-shown-in-the-backtrace)
1. [Is `zend.exception_ignore_args` set to “Off”?](/lib/php/guides/capturing-function-call-arguments/)
# Honeybadger for Python
> Honeybadger monitors your Python applications for errors and performance bottlenecks so that you can fix them wicked fast.
Hi there! You’ve found Honeybadger’s guide to Python error tracking, performance monitoring, and observability. Once installed, Honeybadger will automatically report errors and telemetry in your Python application.
## How you should read the docs
[Section titled “How you should read the docs”](#how-you-should-read-the-docs)
* If you’re installing Honeybadger in your application for the first time, start with our **Integrations Guides** for **[Django](/lib/python/integrations/django/)**, **[Flask](/lib/python/integrations/flask/)**, and **[other frameworks](/lib/python/integrations/other/)**.
* The **How-To Guides** (in the left-hand navigation menu) are general guides on how to do things with the library, and should apply to all types of applications.
* There is a wealth of additional knowledge about Honeybadger in the **Package Reference** and **Support** sections.
## Getting support
[Section titled “Getting support”](#getting-support)
If you’re having trouble working with the package (such as you aren’t receiving error reports when you should be):
1. Read [Frequently asked questions](/lib/python/support/faq/)
2. Upgrade to the latest package version if possible (you can find a list of bugfixes and other changes in the [CHANGELOG](https://github.com/honeybadger-io/honeybadger-python/blob/master/CHANGELOG.md))
3. Run through our [Troubleshooting guide](/lib/python/support/troubleshooting/)
4. If you believe you’ve found a bug, [submit an issue on GitHub](https://github.com/honeybadger-io/honeybadger-python/issues/)
For all other problems, contact support for help:
# Adding context to errors
> Learn how to add custom metadata to your Honeybadger error reports in Python.
Honeybadger can display additional custom key/value metadata — or “context” — with each error report. Context is what you’re looking for if:
* You want to record the current user’s id or email address at the time of an exception
* You need to send raw POST data for use in debugging
* You have any other metadata you’d like to send with an exception
There are two ways to add context to errors in your code: [global](#global-context) and [local](#local-context). While you can add any key/value data to context, a few keys [have a special meaning in Honeybadger](#special-context-keys).
## Global context
[Section titled “Global context”](#global-context)
`honeybadger.set_context` allows you to send additional information to the Honeybadger API to assist in debugging. This method sets global context data and is additive - every time you call it, it adds to the existing set unless you call `reset_context`, documented below.
```python
from honeybadger import honeybadger
honeybadger.set_context(my_data='my_value')
```
Context data is thread-local, meaning each thread maintains its own separate context.
`honeybadger.reset_context` clears the global context dictionary.
```python
from honeybadger import honeybadger
honeybadger.reset_context()
```
## Local context
[Section titled “Local context”](#local-context)
What if you don’t want to set global context data? You can use Python context managers to set case-specific contextual information.
```python
# from a Django view
from honeybadger import honeybadger
def my_view(request):
with honeybadger.context(user_email=request.POST.get('user_email', None)):
form = UserForm(request.POST)
# ...
```
## Special context keys
[Section titled “Special context keys”](#special-context-keys)
While you can add any key/value data to context, a few keys have special meaning in Honeybadger:
| Option | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| `_tags` | Any value passed in the `_tags` key will be processed as tags for the error. |
| `user_id` | The user ID used by Honeybadger to aggregate user data across occurrences on the error page. |
| `user_email` | Same as `user_id`, but for email addresses. |
## Automatic context
[Section titled “Automatic context”](#automatic-context)
When using Django, the middleware automatically adds user information to error context:
* `user_id` - from `request.user.id`
* `username` - from `request.user.get_username()`
This happens automatically for authenticated users when an error occurs.
## Limits
[Section titled “Limits”](#limits)
Honeybadger’s servers enforce the following limits to ensure the service operates smoothly for everyone:
* Nested objects have a max depth of 20
* Context values have a max size of 64Kb
When an error notification includes context data that exceed these limits, the context data will be truncated on the server, and the notification will still be processed.
# Customizing error grouping
> Learn how to customize how Honeybadger groups similar errors together.
Honeybadger groups similar exceptions together using rules which we’ve found to work the best in most cases. The default information we use to group errors is:
1. The file name, method name, and line number of the error’s location
2. The class name of the error
3. The component/controller name
We use this information to construct a “fingerprint” of the exception. Exceptions with the same fingerprint are treated as the same error in Honeybadger.
You can customize the grouping for each exception by changing the error class name, component, or stack trace—or by sending a custom fingerprint.
The `fingerprint` parameter can be used to override the fingerprint for an exception reported with the `honeybadger.notify` method. The fingerprint value will be converted to a string if it isn’t already:
```python
from honeybadger import honeybadger
honeybadger.notify(exception, fingerprint="a unique string")
```
All errors with the fingerprint “a unique string” will be grouped together in Honeybadger.
For more information about the `honeybadger.notify` method, see [Reporting Errors](/lib/python/errors/reporting-errors/).
# Environments
> Learn how to configure environments in Honeybadger for Python.
Honeybadger groups errors by the environment they belong to. The default environment is “production”, but you can set it to different values such as “staging” or “development” depending on where your app is running.
You can set the environment by calling the `honeybadger.configure` method:
```python
from honeybadger import honeybadger
honeybadger.configure(api_key='redacted', environment='development')
```
You can also set the environment using the `HONEYBADGER_ENVIRONMENT` environment variable:
```bash
export HONEYBADGER_ENVIRONMENT="staging"
```
## Development environments
[Section titled “Development environments”](#development-environments)
Some environments should usually not report errors at all, such as when you are developing on your local machine or running your test suite (locally or in CI). The *honeybadger* package has an internal list of environment names which it considers development environments:
```text
development
dev
test
```
Honeybadger **does not** report errors in these environments. To always send data regardless of the environment, you can set the `force_report_data` to `True`:
```python
from honeybadger import honeybadger
honeybadger.configure(
api_key='redacted',
environment='development',
force_report_data=True
)
```
If you have development environments that aren’t part of the default list, you can set the `development_environments` configuration option to meet your needs:
```python
from honeybadger import honeybadger
honeybadger.configure(
api_key='redacted',
environment='staging',
development_environments=['development', 'dev', 'test', 'staging']
)
```
This will ensure that errors are not sent in the specified environments.
## Framework defaults
[Section titled “Framework defaults”](#framework-defaults)
When using Django, if `DEBUG = True` is set in your Django settings, Honeybadger will automatically set the environment to “development”. This can be overridden by explicitly setting the environment in your Honeybadger configuration or using the `HONEYBADGER_ENVIRONMENT` environment variable.
For more configuration options, see [Configuration](/lib/python/reference/configuration/).
# Filtering sensitive data
> Learn how to filter sensitive data from error reports sent to Honeybadger.
You have complete control over the data that Honeybadger reports when an error occurs. Before data is sent to Honeybadger, it is passed through a filter to remove sensitive fields and do other processing on the data. The default configuration is equivalent to:
```python
from honeybadger import honeybadger
honeybadger.configure(
params_filters=[
"password",
"password_confirmation",
"credit_card",
"CSRF_COOKIE",
]
)
```
## How it works
[Section titled “How it works”](#how-it-works)
The `params_filters` configuration applies to:
* **Request parameters** (GET/POST data)
* **Session data**
* **Cookies**
* **CGI environment variables**
* **Local variables** (when `report_local_variables` is enabled)
Any field matching a filter key will have its value replaced with `"[FILTERED]"`. Filtering works recursively on nested dictionaries. For example:
```python
# Before filtering
data = {
"username": "alice",
"password": "secret123",
"user_data": {
"credit_card": "1234-5678-9012-3456"
}
}
# After filtering
data = {
"username": "alice",
"password": "[FILTERED]",
"user_data": {
"credit_card": "[FILTERED]"
}
}
```
# Reducing noise
> Learn how to reduce noise and ignore specific errors in Honeybadger.
Sometimes there are errors that you would rather not send to Honeybadger because they are not actionable or are handled internally.
## Ignoring errors by class name
[Section titled “Ignoring errors by class name”](#ignoring-errors-by-class-name)
By default Honeybadger will be notified when any error occurs. To override this configuration in order not to send out errors to Honeybadger, set `excluded_exceptions` in `honeybadger.configure`.
The `excluded_exceptions` configuration accepts a list of exception class names (as strings) to exclude:
```python
from honeybadger import honeybadger
honeybadger.configure(excluded_exceptions=["ZeroDivisionError", "ValueError"])
```
Exceptions are skipped when the exception’s class name is found in the `excluded_exceptions` list.
## Dynamic ignoring errors with before\_notify
[Section titled “Dynamic ignoring errors with before\_notify”](#dynamic-ignoring-errors-with-before_notify)
For more complex scenarios, you can use a `before_notify` handler to conditionally ignore errors:
```python
from honeybadger import honeybadger
def filter_errors(notice):
# Skip connection errors during maintenance windows
if notice.error_class == 'ConnectionError' and is_maintenance_mode():
return False
return notice
honeybadger.configure(before_notify=filter_errors)
```
Returning `False` from the handler will skip the notification entirely.
For more information about configuring `before_notify` and other options, see [Configuration](/lib/python/reference/configuration/#filtering-and-enriching-errors).
# Reporting errors
> Learn how to report errors to Honeybadger from your Python application.
Use `honeybadger.notify()` to send errors to Honeybadger:
```python
from honeybadger import honeybadger
try:
# Buggy code goes here
except Exception as exception:
honeybadger.notify(exception)
```
## Reporting errors without an exception
[Section titled “Reporting errors without an exception”](#reporting-errors-without-an-exception)
You can report any type of error to Honeybadger, not just exceptions. The simplest form is calling `honeybadger.notify` with a custom class and message:
```python
from honeybadger import honeybadger
honeybadger.notify(
error_class='ValueError',
error_message='Something bad happened!'
)
# Or send a simple string message
honeybadger.notify("Something went wrong!")
```
## Passing additional options to `honeybadger.notify`
[Section titled “Passing additional options to honeybadger.notify”](#passing-additional-options-to-honeybadgernotify)
In some cases you will want to override the defaults or add additional information to your error reports. To do so, you can pass more arguments to `honeybadger.notify`.
For example, you could add tags to a notification:
```python
from honeybadger import honeybadger
honeybadger.notify(exception, tags=["my_custom_tag", "another_tag"])
```
These are all the available arguments you can pass to `honeybadger.notify`:
| Parameter | Type | Required | Description |
| --------------- | ----------- | -------- | --------------------------------------------------------- |
| `exception` | `Exception` | \* | An instance of an exception |
| `error_class` | `str` | \*\* | A string representation of a class name |
| `error_message` | `str` | \*\* | An error message |
| `fingerprint` | `str` | No | A unique identifier used to group related errors together |
| `context` | `dict` | No | A dictionary containing additional context information |
| `tags` | `list[str]` | No | A list of tags to associate with the error |
\* Either provide an `exception` object, OR both `error_class` and `error_message`.
\*\* Required when not providing an `exception` object.
The `honeybadger.notify()` method returns a UUID string that uniquely identifies the error notification.
# Tagging errors
> Learn how to use tags to organize and filter errors in Honeybadger.
Each error in Honeybadger has tags. Tags can be used to filter results when searching and can even apply to integrations so that only errors with a combination of certain tags trigger an email or a Slack message, for example.
Tags can be used to create custom workflows, such as:
* Find all errors tagged “badgers” and resolve them.
* Tag critical errors as “critical” and configure PagerDuty to alert you only when a critical error happens.
* If you have errors which aren’t actionable (but you still want to know about them), you could tag them with “low\_priority” and exclude those errors when automatically creating issues via the GitHub integration.
* Tag all errors that happen in an area of your app with the name of the team that is responsible for them, then notify their Slack channel for only those errors.
These are just examples: you can use tags however you want!
While you can always add tags to existing errors through the Honeybadger UI, they are most useful when you add them programmatically as the exceptions happen. There are two ways to add tags to errors from your Python app:
## Tagging errors in global context
[Section titled “Tagging errors in global context”](#tagging-errors-in-global-context)
Every exception which is reported within the current context will have the specified tags added. Use the `_tags` argument to set the tags:
```python
from honeybadger import honeybadger
# Using a comma-separated string
honeybadger.set_context(_tags="critical, badgers")
# Or using a list of strings
honeybadger.set_context(_tags=["critical", "badgers"])
```
## Tagging errors in `honeybadger.notify`
[Section titled “Tagging errors in honeybadger.notify”](#tagging-errors-in-honeybadgernotify)
The tags will be added for just the current error being reported:
```python
from honeybadger import honeybadger
# Using a comma-separated string
honeybadger.notify(exception, tags="critical, badgers")
# Or using a list of strings
honeybadger.notify(exception, tags=["critical", "badgers"])
```
## Tag processing
[Section titled “Tag processing”](#tag-processing)
Tags are processed as follows:
* Comma-separated strings are split into individual tags
* Whitespace is automatically trimmed from each tag
* Tags from context and explicit tags are merged and deduplicated
* Empty tags are ignored
# Tracking deployments
> Learn how to track deployments in Honeybadger for your Python application.
Honeybadger has an API to keep track of project deployments. Whenever you deploy, all errors for that environment will be resolved automatically. You can choose to enable or disable the auto-resolve feature from your Honeybadger project settings page.
## Deploying with GitHub Actions
[Section titled “Deploying with GitHub Actions”](#deploying-with-github-actions)
If your CI/CD pipeline is hosted with GitHub Actions, you can use the [Honeybadger Deploy Action](https://github.com/marketplace/actions/honeybadger-deploy-action) to notify our API about deployments.
## Deploying with `curl`
[Section titled “Deploying with curl”](#deploying-with-curl)
```sh
HONEYBADGER_ENV="production" \
HONEYBADGER_REVISION="$(git rev-parse HEAD)" \
HONEYBADGER_REPOSITORY="$(git config --get remote.origin.url)" \
HONEYBADGER_API_KEY="Your project API key" \
&& curl -g "https://api.honeybadger.io/v1/deploys?deploy[environment]=$HONEYBADGER_ENV&deploy[local_username]=$USER&deploy[revision]=$HONEYBADGER_REVISION&deploy[repository]=$HONEYBADGER_REPOSITORY&api_key=$HONEYBADGER_API_KEY"
```
If you are using our EU stack, you should use `eu-api.honeybadger.io` instead of `api.honeybadger.io` for the domain name.
# Capturing logs and events
> Learn how to automatically capture logs and events from your Python application.
Honeybadger’s Python package (v1.1+) can be used to send events to [Honeybadger Insights](/guides/insights/).
## Automatic instrumentation
[Section titled “Automatic instrumentation”](#automatic-instrumentation)
Honeybadger Insights allows you to automatically track various events in your application. To enable Insights automatic instrumentation, add the following to your configuration:
```python
from honeybadger import honeybadger
honeybadger.configure(insights_enabled=True)
```
## Supported libraries
[Section titled “Supported libraries”](#supported-libraries)
*After integration with our middleware or extensions*, Honeybadger will automatically instrument the following libraries:
* **Django** requests & database queries
* **Flask** requests & database queries
* **ASGI** requests
* **Celery** tasks
You can configure the instrumentation for specific libraries / components by passing a dictionary to a specialized `insights_config` parameter.
By default, all keyword dict params are run through our `params_filters`.
### Django
[Section titled “Django”](#django)
Django instrumentation captures these event types:
django.request db.query
Database events are configured in [their own section](#database), but are emitted automatically by the Django instrumentation.
You can configure the Django instrumentation by passing a dictionary to `insights_config`:
```python
honeybadger.configure(
insights_config={
"django": {
# Disable instrumentation for Django, defaults to False
"disabled": True,
# include GET/POST params in events, defaults to False
"include_params": True,
}
}
)
```
### Flask
[Section titled “Flask”](#flask)
Flask instrumentation captures these event types:
flask.request db.query
Database events are configured in [their own section](#database), but are emitted automatically by the Flask instrumentation.
You can configure the Flask instrumentation by passing a dictionary to `insights_config`:
```python
honeybadger.configure(
insights_config={
"flask": {
# Disable instrumentation for Flask, defaults to False
"disabled": True,
# Include GET/POST params in events, defaults to False
"include_params": True,
}
}
)
```
### ASGI
[Section titled “ASGI”](#asgi)
ASGI instrumentation captures these event types:
asgi.request
You can configure the ASGI instrumentation by passing a dictionary to `insights_config`:
```python
honeybadger.configure(
insights_config={
"asgi": {
# Disable instrumentation for ASGI, defaults to False
"disabled": True,
# Include query params in events, defaults to False
"include_params": True,
}
}
)
```
### Celery
[Section titled “Celery”](#celery)
Celery instrumentation captures these event types:
celery.task\_finished
You can configure the Celery instrumentation by passing a dictionary to `insights_config`:
```python
import re
from honeybadger import honeybadger
honeybadger.configure(
insights_config={
"celery": {
# Disable instrumentation for Celery, defaults to False
"disabled": True,
# Include task args/kwargs, defaults to False
"include_args": True,
# List of task names or regexes to exclude, defaults to []
"exclude_tasks": [
"tasks.cleanup",
re.compile("^internal_"),
],
}
}
)
```
### Database
[Section titled “Database”](#database)
Honeybadger can capture database queries for supported libraries like Django ORM and SQLAlchemy. The event types captured include:
db.query
These events are emitted as a side effect other instrumentation, such as Django or Flask, so you don’t need to enable them separately.
You can configure the database instrumentation by passing a dictionary to `insights_config`:
```python
import re
from honeybadger import honeybadger
from honeybadger.config import default_excluded_queries
honeybadger.configure(
insights_config={
"db": {
# Disable instrumentation for DB, defaults to False
"disabled": True,
# Include SQL params in events, defaults to False
"include_params": True,
# List of queries to exclude (strings or regexes), defaults to
# common system queries
"exclude_queries": [
"django_admin_log", # Matches any query containing this string
re.compile(r".*auth_permission.*"), # Regex pattern
],
# To add to the default excluded queries, import and use the default_excluded_queries function
"exclude_queries": default_excluded_queries() + [
re.compile(r".*my_custom_table.*"),
"my_system_query",
],
}
}
)
```
## Send custom events to Honeybadger Insights
[Section titled “Send custom events to Honeybadger Insights”](#send-custom-events-to-honeybadger-insights)
Use `honeybadger.event` method to send custom events to [Honeybadger Insights](/guides/insights/). This allows you to track and monitor important events in your application.
```python
from honeybadger import honeybadger
# Send a simple event
honeybadger.event('user.signup', {'email': 'user@example.com'})
# Send an event with additional metadata
honeybadger.event(
'order.completed',
{
'order_id': '123',
'total': 49.99,
'items': ['item1', 'item2']
}
)
# Or pass everything as a dictionary
honeybadger.event({
'event_type': 'order.completed',
'order_id': '123',
'total': 49.99,
'items': ['item1', 'item2']
})
```
The `event` method can be called in two ways:
* With two parameters: `event_type` (string) and `data` (dictionary)
* With one parameter: a dictionary containing `event_type` and any additional data
We recommend `event_type` for grouping your events. A `ts` timestamp is automatically added to events if not present, using the current UTC time in ISO 8601 format.
For more information about configuring Insights and events, see [Insights Configuration](/lib/python/reference/configuration/#insights-configuration).
## Sending logs from your infrastructure
[Section titled “Sending logs from your infrastructure”](#sending-logs-from-your-infrastructure)
Honeybadger isn’t just for errors and application data! You can use our [syslog](/guides/insights/integrations/systemd/), [Vector](/guides/insights/integrations/log-files/), or [PaaS integrations](/guides/insights/#adding-data-from-other-sources) to send additional data from your infrastructure to [Honeybadger Insights](/guides/insights/), where you can query, visualize, and analyze all of your production data in one place.
# Event context
> Learn how to add custom metadata to events sent to Honeybadger Insights.
You can add custom metadata to the events sent to Honeybadger Insights by using the `honeybadger.set_event_context` function. This metadata will be included in each event call within the current thread.
Caution
This will add the metadata to all events sent, so be careful not to include too much data. Try to keep it to simple key/value pairs.
```python
from honeybadger import honeybadger
honeybadger.set_event_context(
user_id=user.id,
session_id=session.id
)
```
## Context lifecycle
[Section titled “Context lifecycle”](#context-lifecycle)
Event context is automatically cleared at the beginning of each web request in supported frameworks ([Django](/lib/python/integrations/django/), [Flask](/lib/python/integrations/flask/)). You can also manually clear it:
```python
honeybadger.reset_event_context()
```
## Temporary context
[Section titled “Temporary context”](#temporary-context)
For temporary context that should only apply to specific operations, use the context manager:
```python
with honeybadger.event_context(operation="batch_import"):
# Context is only set within this block
honeybadger.event("import.started")
process_batch()
honeybadger.event("import.completed")
# Context is automatically restored when exiting the block
```
## Precedence
[Section titled “Precedence”](#precedence)
If both event context and event data contain the same key, the event data takes precedence:
```python
honeybadger.set_event_context(service="api")
honeybadger.event("order.created", service="checkout") # service="checkout" is used
```
# Filtering events
> Learn how to filter or customize events sent to Honeybadger Insights.
You can filter out or customize events sent to Honeybadger Insights by using the `before_event` configuration parameter.
```python
from honeybadger import honeybadger
def filter_event(event):
# Skip health check requests
if event.get('path') == '/health':
return False
# Redact sensitive data from custom events
if event.get('event_type') == 'user.signup' and 'email' in event:
event['email'] = '[REDACTED]'
return event
honeybadger.configure(before_event=filter_event)
```
This function will be called for every event before it is sent to Honeybadger.
For more information about configuring `before_event` and other options, see [Configuration](/lib/python/reference/configuration/#filtering-and-enriching-events).
# Sampling events
> Learn how to sample events to reduce the volume sent to Honeybadger Insights.
You can enable event sampling to reduce the number of events sent to Honeybadger. This is especially useful if you are hitting your daily event quota limit:
```python
from honeybadger import honeybadger
honeybadger.configure(events_sample_rate=50) # Sample 50% of events
```
The `events_sample_rate` option accepts a whole percentage value between 0 and 100, where 0 means no events will be sent and 100 means all events will be sent. The default is no sampling (100%).
Events are sampled by hashing the `request_id` if available in the event payload, otherwise a unique UUID is generated for that event. This deterministic approach ensures that related events from the same request are consistently sampled together.
## Per-event sampling
[Section titled “Per-event sampling”](#per-event-sampling)
Note
The `_hb` metadata is automatically removed from events before they are sent to Honeybadger.
The sample rate is applied to all events sent to Honeybadger Insights, including automatic instrumentation events. You can also set the sample rate per event by adding the `_hb` metadata with a `sample_rate` key:
```python
honeybadger.event("user_created", {
"user_id": user.id,
"_hb": {"sample_rate": 100}
})
```
The event sample rate can also be set within the `honeybadger.set_event_context` function. This can be handy if you want to set an overall sample rate for a thread or ensure that specific instrumented events get sent:
```python
# Set a higher sampling rate for this entire thread
honeybadger.set_event_context(_hb={"sample_rate": 100})
# Now all events from this thread, including automatic instrumentation,
# will use the 100% sample rate
```
Remember that event context is thread-local and applies to all events sent from the same thread after the `set_event_context` call, until it’s changed or the thread terminates.
## Sample rate precedence
[Section titled “Sample rate precedence”](#sample-rate-precedence)
Sample rates are determined in the following order (highest to lowest priority):
1. **Event data** - `_hb` metadata passed directly to the event
2. **Event context** - `_hb` metadata set via `set_event_context()`
3. **Global configuration** - `events_sample_rate` config option
When setting sample rates below the global setting, be aware that this affects how events with the same `request_id` are sampled. Since sampling is deterministic based on the `request_id` hash, all events sharing the same `request_id` will either all be sampled or all be skipped together. This ensures consistency across related events.
# Django integration guide
> Set up Django error tracking, performance monitoring, and observability with Honeybadger in 5 minutes.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **Django error tracking and performance monitoring**. Once installed, Honeybadger will automatically report errors and performance insights from your Django application.
## Installing the package
[Section titled “Installing the package”](#installing-the-package)
Install the `honeybadger` Python package with pip (or add it to your `requirements.txt`):
```bash
pip install honeybadger
```
In your Django application, add the Honeybadger Django middleware to *the top* of your `MIDDLEWARE` config variable in `settings.py`:
```python
MIDDLEWARE = [
'honeybadger.contrib.DjangoHoneybadgerMiddleware',
# ... your other middleware
]
```
It’s important that the Honeybadger middleware is at the top, so that it wraps the entire request process, including all other middleware.
Add a new `HONEYBADGER` config variable to your `settings.py`:
```python
HONEYBADGER = {
'API_KEY': 'PROJECT_API_KEY',
'INSIGHTS_ENABLED': True
}
```
Tip
You can also configure Honeybadger with environment variables:
```sh
export HONEYBADGER_API_KEY="PROJECT_API_KEY"
export HONEYBADGER_INSIGHTS_ENABLED=True
```
If you use this method, you can omit the `HONEYBADGER` configuration from `settings.py`.
See the [Configuration reference](/lib/python/reference/configuration/) for additional info.
## Testing your installation
[Section titled “Testing your installation”](#testing-your-installation)
Note
Honeybadger does not report errors in `development` and `test` environments by default. To enable reporting in development environments, temporarily add `'FORCE_REPORT_DATA': True` to your Honeybadger config.
To test that Honeybadger is working, you can create a simple test exception:
```python
from honeybadger import honeybadger
try:
raise Exception("Honeybadger test exception")
except Exception as e:
honeybadger.notify(e)
```
If the installation is working correctly, this error should appear in your Honeybadger dashboard.
## How it works
[Section titled “How it works”](#how-it-works)
The `DjangoHoneybadgerMiddleware` integrates with Django’s request/response cycle to automatically capture errors and performance data. When an exception occurs, it automatically adds the following information to the error report:
* **URL**: The full URL the request was sent to
* **Component**: The Django app name (if available)
* **Action**: The view function name
* **Params**: GET or POST parameters (filtered for sensitive data)
* **Session**: Session data (filtered for sensitive data)
* **CGI data**: Request headers and environment variables (filtered for sensitive data)
* **Context**: Username and user ID when `request.user` is authenticated
### Performance monitoring
[Section titled “Performance monitoring”](#performance-monitoring)
When [Insights is enabled](/lib/python/insights/capturing-logs-and-events/), the middleware automatically tracks:
* **Request performance**: Response times, status codes, and view information
* **Database queries**: Query duration and SQL statements (with configurable filtering)
* **Request correlation**: Generates or captures request IDs for tracing across systems
## Sending logs from your infrastructure
[Section titled “Sending logs from your infrastructure”](#sending-logs-from-your-infrastructure)
Honeybadger isn’t just for errors and application data! You can use our [syslog](/guides/insights/integrations/systemd/), [Vector](/guides/insights/integrations/log-files/), or [PaaS integrations](/guides/insights/#adding-data-from-other-sources) to send additional data from your infrastructure to [Honeybadger Insights](/guides/insights/), where you can query, visualize, and analyze all of your production data in one place.
# Flask integration guide
> Set up Flask error tracking, performance monitoring, and observability with Honeybadger in 5 minutes.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **Flask error tracking and performance monitoring**. Once installed, Honeybadger will automatically report errors and performance insights from your Flask application.
## Installing the package
[Section titled “Installing the package”](#installing-the-package)
Install the `honeybadger` Python package with pip (or add it to your `requirements.txt`):
```bash
pip install honeybadger
```
Flask also requires the `blinker` library for automatic error reporting:
```bash
pip install blinker
```
In your Flask application, initialize the Honeybadger extension:
```python
from flask import Flask
from honeybadger.contrib import FlaskHoneybadger
app = Flask(__name__)
app.config['HONEYBADGER_ENVIRONMENT'] = 'production'
app.config['HONEYBADGER_API_KEY'] = 'PROJECT_API_KEY'
app.config['HONEYBADGER_INSIGHTS_ENABLED'] = True
FlaskHoneybadger(app, report_exceptions=True, reset_context_after_request=True)
```
Tip
`FlaskHoneybadger` checks Flask’s configuration object and automatically configures Honeybadger using [12-factor style config options](/lib/python/reference/configuration/#twelve-factor-configuration). You can also configure Honeybadger with environment variables:
```sh
export HONEYBADGER_ENVIRONMENT="production"
export HONEYBADGER_API_KEY="PROJECT_API_KEY"
export HONEYBADGER_INSIGHTS_ENABLED=True
```
If you use this method, you can omit the `app.config` settings. Environment variables take precedence over Flask configuration settings when both are present.
See the [Configuration reference](/lib/python/reference/configuration/) for additional info.
## Testing your installation
[Section titled “Testing your installation”](#testing-your-installation)
Note
Honeybadger does not report errors in `development` and `test` environments by default. To enable reporting in development environments, temporarily add `app.config['HONEYBADGER_FORCE_REPORT_DATA'] = True` to your Flask config.
To test that Honeybadger is working, you can create a simple test exception:
```python
from honeybadger import honeybadger
try:
raise Exception("Honeybadger test exception")
except Exception as e:
honeybadger.notify(e)
```
If the installation is working correctly, this error should appear in your Honeybadger dashboard.
## How it works
[Section titled “How it works”](#how-it-works)
The `FlaskHoneybadger` extension uses Flask’s signals (via [Blinker](https://github.com/pallets-eco/blinker)) to detect and report exceptions. When an exception occurs, it automatically adds the following information to the error report:
* **URL**: The URL the request was sent to
* **Component**: The module that the view is defined in (or class name for class-based views)
* **Action**: The name of the function called (prefixed with blueprint name if applicable)
* **Params**: Query parameters and form data (filtered for sensitive data)
* **Session**: Session data
* **CGI data**: Request headers and method (filtered for sensitive data)
### Component naming conventions
[Section titled “Component naming conventions”](#component-naming-conventions)
The following conventions are used for component names:
* View functions: `#`
* Class-based views: `#`
* Blueprints: `#.`
### Additional configuration options
[Section titled “Additional configuration options”](#additional-configuration-options)
When initializing `FlaskHoneybadger`, you can pass additional options:
| Name | Type | Default | Description |
| ----------------------------- | ------ | ------- | -------------------------------------------------------------------------------- |
| `report_exceptions` | `bool` | `False` | Automatically report exceptions raised in views (including those from `abort()`) |
| `reset_context_after_request` | `bool` | `False` | Reset [Honeybadger context](/lib/python/errors/context/) after each request |
## Sending logs from your infrastructure
[Section titled “Sending logs from your infrastructure”](#sending-logs-from-your-infrastructure)
Honeybadger isn’t just for errors and application data! You can use our [syslog](/guides/insights/integrations/systemd/), [Vector](/guides/insights/integrations/log-files/), or [PaaS integrations](/guides/insights/#adding-data-from-other-sources) to send additional data from your infrastructure to [Honeybadger Insights](/guides/insights/), where you can query, visualize, and analyze all of your production data in one place.
# Python integration guide
> Set up Python error tracking, performance monitoring, and observability with Honeybadger in 5 minutes.
**Typical installation time:** 5 minutes
Hi there! You’ve found Honeybadger’s guide to **Python error tracking and performance monitoring**. Once installed, Honeybadger will automatically report errors and performance insights from your application.
## Installing the package
[Section titled “Installing the package”](#installing-the-package)
Install the `honeybadger` Python package with pip (or add it to your `requirements.txt`):
```bash
pip install honeybadger
```
See the [framework-specific sections](#supported-frameworks) on this page for how to configure Honeybadger for your application.
For other frameworks (tornado, web2py, etc.) or plain Python scripts, simply import honeybadger and configure it with your API key. Honeybadger uses a global exception hook to automatically report uncaught exceptions:
```python
from honeybadger import honeybadger
honeybadger.configure(
api_key='PROJECT_API_KEY',
insights_enabled=True
)
raise Exception("This will get reported!")
```
Tip
You can also configure Honeybadger with environment variables:
```sh
export HONEYBADGER_API_KEY="PROJECT_API_KEY"
export HONEYBADGER_INSIGHTS_ENABLED=True
```
If you use this method, you can omit explicit configuration in your application code. Environment variables take precedence over programmatic configuration when both are present.
See the [Configuration reference](/lib/python/reference/configuration/) for additional info.
## Testing your installation
[Section titled “Testing your installation”](#testing-your-installation)
Note
Honeybadger does not report errors in `development` and `test` environments by default. To enable reporting in development environments, temporarily add `force_report_data=True` to your Honeybadger config.
To test that Honeybadger is working, you can create a simple test exception:
```python
from honeybadger import honeybadger
try:
raise Exception("Honeybadger test exception")
except Exception as e:
honeybadger.notify(e)
```
If the installation is working correctly, this error should appear in your Honeybadger dashboard.
## Supported frameworks
[Section titled “Supported frameworks”](#supported-frameworks)
### Django
[Section titled “Django”](#django)
See the [Django integration guide](/lib/python/integrations/django/).
### Flask
[Section titled “Flask”](#flask)
See the [Flask integration guide](/lib/python/integrations/flask/).
### AWS Lambda
[Section titled “AWS Lambda”](#aws-lambda)
AWS Lambda environments are auto-detected by Honeybadger with no additional configuration. Here’s an example lambda function with Honeybadger:
```python
from honeybadger import honeybadger
honeybadger.configure(
api_key='PROJECT_API_KEY',
insights_enabled=True
)
def lambda_handler(event, context):
"""
A buggy lambda function that tries to perform a zero division
"""
a = 1
b = 0
return (a/b) # This will be reported
```
### Celery
[Section titled “Celery”](#celery)
A Celery extension is available for initializing and configuring Honeybadger: `honeybadger.contrib.celery.CeleryHoneybadger`. The extension adds the following information to reported exceptions:
* **component**: The module that the task is defined at.
* **action**: The name of the task.
* **params**: The arguments and keyword arguments passed to the task.
* **context**: A dictionary containing the following:
* **task\_id**: The id of the current task.
* **retries**: The number of retries that have been attempted.
* **max\_retries**: The maximum number of retries that will be attempted.
#### Example
[Section titled “Example”](#example)
```python
from celery import Celery
from honeybadger.contrib import CeleryHoneybadger
app = Celery(__name__)
app.conf.update(
HONEYBADGER_API_KEY='PROJECT_API_KEY',
HONEYBADGER_ENVIRONMENT='production',
HONEYBADGER_INSIGHTS_ENABLED=True
)
CeleryHoneybadger(app, report_exceptions=True)
```
### FastAPI
[Section titled “FastAPI”](#fastapi)
[FastAPI](https://fastapi.tiangolo.com/) is based on Starlette, an ASGI application. You use Honeybadger’s ASGI middleware on these types of applications.
```python
from fastapi import FastAPI
from honeybadger import contrib
app = FastAPI()
app.add_middleware(contrib.ASGIHoneybadger)
```
You can pass additional configuration parameters as keyword arguments:
```python
from fastapi import FastAPI
from honeybadger import honeybadger, contrib
honeybadger.configure(
api_key="PROJECT_API_KEY",
insights_enabled=True
)
app = FastAPI()
app.add_middleware(contrib.ASGIHoneybadger, params_filters=["sensitive_data"])
```
#### FastAPI advanced usage
[Section titled “FastAPI advanced usage”](#fastapi-advanced-usage)
Consuming the request body in an ASGI application’s middleware is [problematic and discouraged](https://github.com/encode/starlette/issues/495#issuecomment-494008175). This is the reason why request body data won’t be sent to the web UI.
FastAPI allows overriding the logic used by the `Request` and `APIRoute` classes, by [using custom `APIRoute` classes](https://fastapi.tiangolo.com/advanced/custom-request-and-route/). This gives more control over the request body, and makes it possible to send request body data along with honeybadger notifications.
A custom API Route is available at [`honeybadger.contrib.fastapi`](https://github.com/honeybadger-io/honeybadger-python/blob/master/honeybadger/contrib/fastapi.py):
```python
from fastapi import FastAPI, APIRouter
from honeybadger import honeybadger
from honeybadger.contrib.fastapi import HoneybadgerRoute
honeybadger.configure(
api_key="PROJECT_API_KEY",
insights_enabled=True
)
app = FastAPI()
app.router.route_class = HoneybadgerRoute
router = APIRouter(route_class=HoneybadgerRoute)
```
### Starlette
[Section titled “Starlette”](#starlette)
You can configure Honeybadger to work with [Starlette](https://www.starlette.io/) just like in any other ASGI framework.
```python
from starlette.applications import Starlette
from honeybadger import contrib
app = Starlette()
app.add_middleware(contrib.ASGIHoneybadger)
```
### Other ASGI applications
[Section titled “Other ASGI applications”](#other-asgi-applications)
A generic [ASGI](https://asgi.readthedocs.io/en/latest/) middleware plugin is available for initializing and configuring Honeybadger: [`honeybadger.contrib.asgi`](https://github.com/honeybadger-io/honeybadger-python/blob/master/honeybadger/contrib/asgi.py).
The general pattern for ASGI applications is wrapping your application with the middleware:
```python
from honeybadger import contrib
asgi_application = someASGIApplication()
asgi_application = contrib.ASGIHoneybadger(asgi_application)
```
You can pass configuration parameters (or *additional* configuration parameters) as keyword arguments at plugin’s initialization:
```python
from honeybadger import contrib
asgi_application = someASGIApplication()
asgi_application = contrib.ASGIHoneybadger(
asgi_application,
api_key="PROJECT_API_KEY",
insights_enabled=True,
params_filters=["sensible_data"]
)
```
Or you may want to initialize Honeybadger before your application, and then just register the plugin/middleware:
```python
from honeybadger import honeybadger, contrib
honeybadger.configure(
api_key='PROJECT_API_KEY',
insights_enabled=True
)
# You can track errors happening before your plugin initialization
some_possibly_failing_function()
asgi_application = someASGIApplication()
asgi_application = contrib.ASGIHoneybadger(asgi_application)
```
## Sending logs from your infrastructure
[Section titled “Sending logs from your infrastructure”](#sending-logs-from-your-infrastructure)
Honeybadger isn’t just for errors and application data! You can use our [syslog](/guides/insights/integrations/systemd/), [Vector](/guides/insights/integrations/log-files/), or [PaaS integrations](/guides/insights/#adding-data-from-other-sources) to send additional data from your infrastructure to [Honeybadger Insights](/guides/insights/), where you can query, visualize, and analyze all of your production data in one place.
# Configuration
> Configuration options for the Honeybadger Python library.
You can set configuration options for the Honeybadger client by calling the `honeybadger.configure` method. This can be called in one of your application files such as `settings.py` or `wsgi.py`, or in a custom middleware.
```python
from honeybadger import honeybadger
honeybadger.configure(
api_key="PROJECT_API_KEY",
environment="production",
project_root="/path/to/your/project/root",
excluded_exceptions=["SomeIgnoredException"],
)
```
See [Configuration Options](#configuration-options) for a list of available options.
## Twelve-factor configuration
[Section titled “Twelve-factor configuration”](#twelve-factor-configuration)
Most of Honeybadger’s configuration options can also be set via environment variables with the `HONEYBADGER_` prefix ([12-factor style](https://12factor.net)). For example, the `api_key` option can be set via the `HONEYBADGER_API_KEY` environment variable:
```bash
export HONEYBADGER_API_KEY="PROJECT_API_KEY"
export HONEYBADGER_ENVIRONMENT="production"
```
## Filtering and enriching errors
[Section titled “Filtering and enriching errors”](#filtering-and-enriching-errors)
The `before_notify` handler allows you to filter or modify error notifications before they’re sent to Honeybadger:
```python
def custom_before_notify(notice):
# Skip notifications for specific error types
if notice.error_class == 'MyCustomError':
return False # Skip this notification
# Add custom context
notice.context['custom_data'] = 'example'
# Return the notice to send it
return notice
honeybadger.configure(before_notify=custom_before_notify)
```
Return `False` from the handler to skip the notification. Return the notice object to send it.
## Filtering and enriching events
[Section titled “Filtering and enriching events”](#filtering-and-enriching-events)
The `before_event` handler allows you to filter or modify performance events before they’re sent to Honeybadger:
```python
def custom_before_event(event):
# Skip events from health check endpoints
if event.get('path') == '/health':
return False # Skip this event
# Add custom metadata for slow requests
if event.get('duration', 0) > 1000: # Over 1 second
event['slow_request'] = True
# Return the event to send it
return event
honeybadger.configure(before_event=custom_before_event)
```
Return `False` from the handler to skip the event. Return the event object to send it.
## Configuration options
[Section titled “Configuration options”](#configuration-options)
The following options are available to you:
| Name | Type | Default |
| ------------------------------------ | ---------- | --------------------------------------------------------------------- |
| `api_key` | `str` | `""` |
| `project_root` | `str` | The current working directory |
| `environment`[1](#user-content-fn-1) | `str` | `"production"` |
| `development_environments` | `list` | `['development', 'dev', 'test']` |
| `hostname` | `str` | The hostname of the current server. |
| `endpoint` | `str` | `"https://api.honeybadger.io"` |
| `params_filters` | `list` | `['password', 'password_confirmation', 'credit_card', 'CSRF_COOKIE']` |
| `force_report_data` | `bool` | `False` |
| `excluded_exceptions` | `list` | `[]` |
| `force_sync` | `bool` | `False` |
| `report_local_variables` | `bool` | `False` |
| `insights_enabled` | `bool` | `False` |
| `insights_config` | `dict` | `{}` (see [Insights Configuration](#insights-configuration)) |
| `events_sample_rate` | `int` | `100` (0-100, percentage of events to send) |
| `events_batch_size` | `int` | `1000` |
| `events_max_queue_size` | `int` | `10000` |
| `events_timeout` | `float` | `5.0` |
| `events_max_batch_retries` | `int` | `3` |
| `events_throttle_wait` | `float` | `60.0` |
| `before_notify` | `callable` | `lambda notice: notice` |
| `before_event` | `callable` | `lambda event: event` |
## Insights configuration
[Section titled “Insights configuration”](#insights-configuration)
The `insights_config` option accepts a dictionary with configuration for Honeybadger’s automatic instrumentation:
```python
from honeybadger import honeybadger
honeybadger.configure(
insights_enabled=True,
insights_config={
"django": {"include_params": True},
"db": {"disabled": True},
"celery": {"exclude_tasks": ["cleanup_task"]}
}
)
```
Each instrumented framework has its own set of options:
| Framework | Name | Type | Default | Description |
| :--------- | :---------------- | :------------------- | :------------------------------------ | :---------------------------------------------- |
| **django** | | | | |
| | `disabled` | `bool` | `False` | Disable Django instrumentation |
| | `include_params` | `bool` | `False` | Include GET/POST parameters in request events |
| **flask** | | | | |
| | `disabled` | `bool` | `False` | Disable Flask instrumentation |
| | `include_params` | `bool` | `False` | Include GET/POST parameters in request events |
| **asgi** | | | | |
| | `disabled` | `bool` | `False` | Disable ASGI instrumentation |
| | `include_params` | `bool` | `False` | Include query parameters in request events |
| **celery** | | | | |
| | `disabled` | `bool` | `False` | Disable Celery instrumentation |
| | `include_args` | `bool` | `False` | Include task arguments/kwargs in events |
| | `exclude_tasks` | `list[str or regex]` | `[]` | List of task names or regex patterns to exclude |
| **db** | | | | |
| | `disabled` | `bool` | `False` | Disable database instrumentation |
| | `include_params` | `bool` | `False` | Include SQL parameters in query events |
| | `exclude_queries` | `list[str or regex]` | System queries[2](#user-content-fn-2) | List of queries to exclude |
## Footnotes
[Section titled “Footnotes”](#footnote-label)
1. Honeybadger will try to infer the correct environment when possible. For example, in the case of the Django integration, if Django settings are set to `DEBUG = True`, the environment will default to `development`. [↩](#user-content-fnref-1)
2. Default excluded queries include Django migrations, auth tables, and common system queries. Import `default_excluded_queries` from `honeybadger.config` to see the full list. [↩](#user-content-fnref-2)
# Supported versions
> Supported Python and framework versions for the Honeybadger library.
The support tables below are for the latest version of the Honeybadger package, which aims to support all maintained (non-EOL) versions of Python and supported frameworks. If you’re using an older version of Python or your framework, you may need to install an older version of the package.
| Library | Supported Version |
| ------- | ----------------- |
| Python | >= 3.8 |
| Django | >= 4.2.20 |
| Flask | >= 1.1.4 |
# Frequently asked questions
> Frequently asked questions about the Honeybadger Python library.
## Why aren’t my errors being reported?
[Section titled “Why aren’t my errors being reported?”](#why-arent-my-errors-being-reported)
The most common reason for errors not being reported is that the app is in a development environment. See the [Environments](/lib/python/errors/environments/#development-environments) chapter in the **Error Tracking** guide for more information.
The second most common reason is that the error being reported is covered by the [excluded\_exceptions list](/lib/python/errors/reducing-noise/).
If neither of these is the issue, check out the [Troubleshooting guide](/lib/python/support/troubleshooting/#all-errors-are-not-reported).
## Why aren’t I getting notifications?
[Section titled “Why aren’t I getting notifications?”](#why-arent-i-getting-notifications)
By default we only send notifications the first time an exception happens, and when it re-occurs after being marked resolved. If an exception happens 100 times, but was never resolved you’ll only get 1 email about it.
# Troubleshooting
> Common issues and solutions for the Honeybadger Python library.
Common issues and workarounds for [honeybadger-python](https://github.com/honeybadger-io/honeybadger-python) are documented here. If you don’t find a solution to your problem here or in our support documentation, email and we’ll assist you!
## Before you start troubleshooting
[Section titled “Before you start troubleshooting”](#before-you-start-troubleshooting)
1. Make sure you are on the latest version of [honeybadger-python](https://pypi.org/project/honeybadger/).
## All errors are not reported
[Section titled “All errors are not reported”](#all-errors-are-not-reported)
If *no* errors are reported (even [manually via `honeybadger.notify`](/lib/python/errors/reporting-errors/)):
1. [Is the `api_key` config option configured?](/lib/python/reference/configuration/)
2. [Are you in a development environment?](/lib/python/errors/environments/#development-environments)
## Some errors are not reported
[Section titled “Some errors are not reported”](#some-errors-are-not-reported)
1. [Is the error ignored via config?](/lib/python/errors/reducing-noise/)
# Honeybadger for Ruby
> Ruby exception tracking with the honeybadger Ruby gem.
Hi there! You’ve found Honeybadger’s docs on **Ruby exception tracking**. In this guide we’re going to discuss the **honeybadger Ruby gem** and how to use it to track exceptions in your Ruby applications. If you’re new to Honeybadger, we recommend taking a moment to read through. This guide is also your reference for how to use the gem in the future, so **bookmark it**.
For a refresher on working with exceptions in Ruby, check out the [Honeybadger guide to Ruby exceptions](https://www.exceptionalcreatures.com/guides/what-are-ruby-exceptions.html).
## Getting started
[Section titled “Getting started”](#getting-started)
Getting started is easy! First, see our [installation and configuration guide](/lib/ruby/getting-started/introduction/) for instructions on adding Honeybadger to your app in less than 3 minutes.
Next steps:
* Learn about getting the most out of Honeybadger for your platform or framework with one of our **Integration guides**: [Rails](/lib/ruby/integration-guides/rails-exception-tracking/), [Sinatra](/lib/ruby/integration-guides/sinatra-exception-tracking/), [Rack](/lib/ruby/integration-guides/rack-exception-tracking/), [Heroku](/lib/ruby/integration-guides/heroku-exception-tracking/), [AWS Lambda](/lib/ruby/integration-guides/aws-lambda-exception-tracking/), or [other Ruby apps](/lib/ruby/integration-guides/ruby-exception-tracking/).
* See the **Gem Reference section** for details about the [gem’s configuration](/lib/ruby/gem-reference/configuration/), [public method API](https://www.rubydoc.info/gems/honeybadger), and [CLI](/lib/ruby/gem-reference/cli/) (Command Line Interface).
* Finally, you may also be interested in **other areas of our documentation**, such as our [REST API guide](/api/) or [general product guides](/).
## Getting support
[Section titled “Getting support”](#getting-support)
If you’re having trouble working with the gem (such as you aren’t receiving error reports when you should be):
1. Read [Frequently asked questions](/lib/ruby/support/faq/)
2. Upgrade to the latest gem version if possible (you can find a list of bugfixes and other changes in the [CHANGELOG](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/CHANGELOG.md))
3. Run through our [Troubleshooting guide](/lib/ruby/support/troubleshooting/)
For all other problems, contact support for help:
**If your issue is gem-related**, here are a few items you can send us which will make it easier to spot the problem:
* Run `bundle exec honeybadger test --file=honeybadger_test.txt` from the server having the problem and attach the generated honeybadger\_test.txt file
* Run `bundle exec rake middleware` from the server having the problem and attach the output as plaintext
* Attach your config/honeybadger.yml file
* Attach your Gemfile.lock file
# Honeybadger CLI reference
> Command-line interface reference for Honeybadger's Ruby gem with deployment tracking and testing commands.
The Honeybadger CLI provides a Command Line Interface for various Honeybadger-related programs and utilities. All features are available through the `honeybadger` command and can be used independently of Bundler/Rails.
When using the *honeybadger* gem with Bundler, run `bundle exec honeybadger`.
To use outside of bundler, install the Honeybadger gem with `gem install honeybadger` and then run `honeybadger`.
## Commands
[Section titled “Commands”](#commands)
The following commands are available through the `honeybadger` CLI:
| Command | Description |
| --------------------- | -------------------------------------------------------------------------------- |
| `honeybadger deploy` | Notify Honeybadger of deployment |
| `honeybadger exec` | Execute a command. If the exit status is not 0, report the result to Honeybadger |
| `honeybadger help` | Describe available commands or one specific command |
| `honeybadger heroku` | Manage Honeybadger on Heroku |
| `honeybadger install` | Install Honeybadger into a new project |
| `honeybadger notify` | Notify Honeybadger of an error |
| `honeybadger test` | Send a test notification from Honeybadger |
For additional info about each command, run `honeybadger help`.
## Configuration
[Section titled “Configuration”](#configuration)
The `honeybadger` command optionally reads configuration from the following locations. Each location in the list takes precedence over the previous location:
1. \~/honeybadger.yml
2. ./config/honeybadger.yml
3. ./honeybadger.yml
4. Rails/Ruby configuration (only when called from a Rails app root)
5. Environment variables
6. Command-line flags (i.e. `--api-key`)
The following configuration options are used by the CLI when applicable: `api_key`, `env`. See [Configuration Options](/lib/ruby/gem-reference/configuration/#configuration-options)
All other options must be passed as command-line flags.
### Rails initialization
[Section titled “Rails initialization”](#rails-initialization)
When run from the root of a Rails project, the `honeybadger` command will load the Rails environment so that any framework/programmatic configuration is picked up.
# Configuration
> Complete configuration reference for Honeybadger's Ruby gem with all available options and settings.
There are a few ways to configure the Honeybadger gem. You can use a YAML config file. You can use environment variables. You can use Ruby. Or you can use a combination of the three.
We put together a short video highligting a few of the most common configuration options:
[](https://honeybadger.wistia.com/medias/vv9qq9x39d)
## YAML configuration file
[Section titled “YAML configuration file”](#yaml-configuration-file)
By default, Honeybadger looks for a `honeybadger.yml` configuration file in the root of your project, and then `config/honeybadger.yml` (in that order).
Here’s what the simplest config file looks like:
```yaml
---
api_key: "PROJECT_API_KEY"
```
### Nested options
[Section titled “Nested options”](#nested-options)
Some configuration options are written in YAML as nested hashes. For example, here’s what the `logging.path` and `request.filter_keys` options look like in YAML:
```yaml
---
logging:
path: "/path/to/honeybadger.log"
request:
filter_keys:
- "credit_card"
```
### Environments
[Section titled “Environments”](#environments)
Environment-specific options can be set by name-spacing the options beneath the environment name. For example:
```yaml
---
api_key: "PROJECT_API_KEY"
production:
logging:
path: "/path/to/honeybadger.log"
level: "WARN"
```
### ERB and Regex
[Section titled “ERB and Regex”](#erb-and-regex)
The configuration file is rendered using ERB. That means you can set configuration options programmatically. You can also include regular expressions. Here’s what that looks like:
```yaml
---
api_key: "PROJECT_API_KEY"
request:
filter_keys:
- !ruby/regexp "/credit_card/i"
```
## Configuring with environment variables (12-factor style)
[Section titled “Configuring with environment variables (12-factor style)”](#configuring-with-environment-variables-12-factor-style)
All configuration options can also be read from environment variables (ENV). To do this, uppercase the option name, replace all non-alphanumeric characters with underscores, and prefix with `HONEYBADGER_`. For example, `logging.path` becomes `HONEYBADGER_LOGGING_PATH`:
```plaintext
export HONEYBADGER_LOGGING_PATH=/path/to/honeybadger.log
```
ENV options override other options read from framework or `honeybadger.yml` sources, so both can be used together. For example, if the `HONEYBADGER_ENV` environment variable is present, it will override the `env` configuration option and `RAILS_ENV` environment variable.
## Configuration via Ruby (programmatic)
[Section titled “Configuration via Ruby (programmatic)”](#configuration-via-ruby-programmatic)
To configure Honeybadger from Ruby, use `Honeybadger.configure`:
```ruby
# i.e. config/initializers/honeybadger.rb
Honeybadger.configure do |config|
config.api_key = "PROJECT_API_KEY"
config.exceptions.ignore += [CustomError]
end
```
Note that configuration via Ruby means that until your configuration code is run, Honeybadger will use its default configuration (or the YAML file or environment variables), so for the best experience, this should be as early as possible after startup.
There are also a few special features which can only be configured via Ruby:
### Changing notice data
[Section titled “Changing notice data”](#changing-notice-data)
Use `before_notify` callbacks to modify [notice data](https://www.rubydoc.info/gems/honeybadger/Honeybadger/Notice) before it’s sent to Honeybadger:
```ruby
Honeybadger.configure do |config|
config.before_notify do |notice|
# Use your own error grouping
notice.fingerprint = App.exception_fingerprint(notice)
# Ignore notices with sensitive data
notice.halt! if notice.error_message =~ /sensitive data/
# Avoid using all your quota for non-production errors by allowing
# only 10 errors to be sent per minute
notice.halt! if !Rails.env.production? && Redis.current.incr(key = "honeybadger_errors:#{(Time.now - Time.now.sec).to_i}") > 10
Redis.current.expire(key, 120)
end
end
```
`before_notify` can be called multiple times to add multiple callbacks.
### Changing event data
[Section titled “Changing event data”](#changing-event-data)
Use `before_event` callbacks to modify [event data](https://www.rubydoc.info/gems/honeybadger/Honeybadger/Event) before it’s sent to Honeybadger:
```ruby
Honeybadger.configure do |config|
config.before_event do |event|
# DB-backed job backends can generate a lot of noisy queries
if event.event_type == "sql.active_record" && event[:query]&.match?(/good_job|solid_queue/)
event.halt!
end
# Truncate long queries
if event.event_type == "sql.active_record" && event[:query].present?
event[:query] = event[:query].first(256)
end
# Set some data for each event
if environment = ENV["HONEYBADGER_ENV"] || Rails.env
event[:environment] = environment
end
# See https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html for more info about using Current
event[:user] = { id: Current.user.id, email: Current.user.email } if Current.user
# Avoid using all your quota for non-production events by allowing
# only 10 events to be sent per minute
event.halt! if !Rails.env.production? && Redis.current.incr(key = "honeybadger_event:#{(Time.now - Time.now.sec).to_i}") > 10
Redis.current.expire(key, 120)
end
end
```
`before_event` can be called multiple times to add multiple callbacks.
### Using a custom `logger`
[Section titled “Using a custom logger”](#using-a-custom-logger)
While you can configure the default logger using the provided options, it’s also possible to replace the logger entirely:
```ruby
Honeybadger.configure do |config|
config.logger = MyLogger.new('/path/to/honeybadger.log')
end
```
### Using a custom `backend`
[Section titled “Using a custom backend”](#using-a-custom-backend)
This option allows you to change the backend which handles all reported data. This is an advanced option—you’ll need to [read the code](https://github.com/honeybadger-io/honeybadger-ruby/tree/master/lib/honeybadger/backend) to use it:
```ruby
Honeybadger.configure do |config|
config.backend = CustomBackend.new
end
```
## Configuration options
[Section titled “Configuration options”](#configuration-options)
You can use any of the options below in your config file, or in the environment.
| Option | Type | Description |
| ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key` | String | The API key for your Honeybadger project. *Default: `nil`* |
| `env` | String | The environment the app is running in. In Rails this defaults to `Rails.env`. *Default: `nil`* |
| `report_data` | Boolean | Enable/disable reporting of data. Defaults to false for “test”, “development”, and “cucumber” environments. *Default: `true`* |
| `root` | String | The project’s absolute root path. *Default: `Dir.pwd`* |
| `revision` | String | The project’s git revision. *Default: revision detected from git* |
| `hostname` | String | The hostname of the current box. *Default: `Socket.gethostname`* |
| `backend` | String | An alternate backend to use for reporting data. *Default: `nil`* |
| `debug` | Boolean | Enables verbose debug logging. *Default: `false`* |
| `send_data_at_exit` | Boolean | Prevent the Ruby program from exiting until all queued notices have been delivered to Honeybadger. (This can take a while in some cases; see `max_queue_size`.) *Default: `true`* |
| `max_queue_size` | Integer | Maximum number of notices to queue for delivery at one time; new notices will be dropped if this number is exceeded. *Default: `100`* |
| `config_path` | String | The path of the honeybadger config file. Can only be set via the `$HONEYBADGER_CONFIG_PATH` environment variable |
| `development_environments` | Array | Environments which will not report data by default (use report*data to enable/disable explicitly). \_Default: `["development", "test", "cucumber"]`* |
| `plugins` | Array | An optional list of plugins to load. Default is to load all plugins. *Default: `[]`* |
| `skipped_plugins` | Array | An optional list of plugins to skip. *Default: `[]`* |
| | | |
| **INSIGHTS AND EVENTS** | | |
| `insights.enabled` | Boolean | Enable automatic Insights instrumentation. *Default: `false`* |
| `insights.registry_flush_interval` | Integer | Number of seconds to flush the aggregated metrics registry. Set a higher number for greater resolution but use more data. *Default: `60`* |
| `events.max_queue_size` | Integer | Number of events before the event queue will start dropping events. *Default: `100000`* |
| `events.batch_size` | Integer | Number of events to batch that will trigger the gem to send. *Default: `1000`* |
| `events.timeout` | Integer | Number of milliseconds before the event queue will send events regardless of size. *Default: `30000`* |
| `events.attach_hostname` | Boolean | Attach server hostname to every event sent by the gem. *Default: `true`* |
| `events.ignore` | Array | An list of rules to match against events to be ignored. See [Ignoring Events](/lib/ruby/getting-started/sending-events-to-insights/#ignoring-events) for more information. |
| `events.sample_rate` | Integer | Percentage of events to send. See [Sampling Events](/lib/ruby/getting-started/sending-events-to-insights/#sampling-events) for more information. |
| | | |
| **LOGGING** | | |
| `logging.path` | String | The path (absolute, or relative from config.root) to the log file. Defaults to the rails logger or STDOUT. To log to standard out, use ‘STDOUT’. *Default: `nil`* |
| `logging.level` | String | The log level. Does nothing unless `logging.path` is also set. *Default: `INFO`* |
| `logging.tty_level` | String | Level to log when attached to a terminal (anything < `logging.level` will always be ignored). *Default: `DEBUG`* |
| | | |
| **HTTP CONNECTION** | | |
| `connection.secure` | Boolean | Use SSL when sending data. *Default: `true`* |
| `connection.host` | String | The host to use when sending data. *Default: `api.honeybadger.io`* |
| `connection.port` | Integer | The port to use when sending data. *Default: `443`* |
| `connection.http_open_timeout` | Integer | The HTTP open timeout when connecting to the server. *Default: `2`* |
| `connection.http_read_timeout` | Integer | The HTTP read timeout when connecting to the server. *Default: `5`* |
| `connection.proxy_host` | String | The proxy host to use when sending data. *Default: `nil`* |
| `connection.proxy_port` | Integer | The proxy port to use when sending data. *Default: `nil`* |
| `connection.proxy_user` | String | The proxy user to use when sending data. *Default: `nil`* |
| `connection.proxy_pass` | String | The proxy password to use when sending data. *Default: `nil`* |
| | | |
| **REQUEST DATA FILTERING** | | |
| `request.filter_keys` | Array | A list of keys to filter when sending request data. In Rails, this also includes existing params filters. *Default: `['password', 'password_confirmation']`* |
| `request.disable_session` | Boolean | Prevent session from being sent with request data. *Default: `false`* |
| `request.disable_params` | Boolean | Prevent params from being sent with request data. *Default: `false`* |
| `request.disable_environment` | Boolean | Prevent Rack environment from being sent with request data. *Default: `false`* |
| `request.disable_url` | Boolean | Prevent url from being sent with request data (Rack environment may still contain it in some cases). *Default: `false`* |
| | | |
| **USER INFORMER** | | |
| `user_informer.enabled` | Boolean | Enable the UserInformer middleware. The user informer displays information about a Honeybadger error to your end-users when you display a 500 error page. This typically includes the error id which can be used to reference the error inside your Honeybadger account. [Learn More](/lib/ruby/getting-started/collecting-user-feedback/) *Default: `true`* |
| `user_informer.info` | String | Replacement string for HTML comment in templates. *Default: `'Honeybadger Error {{error_id}}'`* |
| | | |
| **USER FEEDBACK** | | |
| `feedback.enabled` | Boolean | Enable the UserFeedback middleware. Feedback displays a comment form to your-end user when they encounter an error. When the user creates a comment, it is added to the error in Honeybadger, and a notification is sent. [Learn More](/lib/ruby/getting-started/collecting-user-feedback/) *Default: `true`* |
| | | |
| **EXCEPTION REPORTING** | | |
| `exceptions.enabled` | Boolean | Enable error reporting functionality. *Default: `true`* |
| `exceptions.ignore` | Array | A list of exception class names to ignore (appends to defaults). *Default: `['ActionController::RoutingError', 'AbstractController::ActionNotFound', 'ActionController::MethodNotAllowed', 'ActionController::UnknownHttpMethod', 'ActionController::NotImplemented', 'ActionController::UnknownFormat', 'ActionController::InvalidAuthenticityToken', 'ActionController::InvalidCrossOriginRequest', 'ActionDispatch::ParamsParser::ParseError', 'ActionController::BadRequest', 'ActionController::ParameterMissing', 'ActiveRecord::RecordNotFound', 'ActionController::UnknownAction', 'CGI::Session::CookieStore::TamperedWithCookie', 'Mongoid::Errors::DocumentNotFound', 'Sinatra::NotFound']`* |
| `exceptions.ignore_only` | Array | A list of exception class names to ignore (overrides defaults). *Default: `[]`* |
| `exceptions.ignored_user_agents` | Array | A list of user agents to ignore. *Default: `[]`* |
| `exceptions.rescue_rake` | Boolean | Enable rescuing exceptions in rake tasks. *Default: `true` when run in background; `false` when run in terminal.* |
| `exceptions.notify_at_exit` | Boolean | Report unhandled exception when Ruby crashes (at*exit). \_Default: `true`.* |
| `exceptions.source_radius` | Integer | The number of lines before and after the source when reporting snippets. *Default: `2`* |
| `exceptions.local_variables` | Boolean | Enable sending local variables. Requires the [binding\_of\_caller gem](https://rubygems.org/gems/binding_of_caller). *Default: `false`* |
| `exceptions.unwrap` | Boolean | Reports #original*exception or #cause one level up from rescued exception when available. \_Default: `false`* |
| | | |
| **BREADCRUMBS** | | |
| `breadcrumbs.enabled` | Boolean | Enable breadcrumb functionality. *Default: `true`* |
| `breadcrumbs.active_support_notifications` | Hash | Configuration for automatic Active Support Instrumentation events. *Default: `Breadcrumbs::ActiveSupport.default_notifications`* |
| `breadcrumbs.logging.enabled` | Boolean | Enable/Disable automatic breadcrumbs from log messages. *Default: `true`* |
| **ACTIVE JOB** | | |
| `active_job.attempt_threshold` | Integer | The number of attempts before notifications will be sent. *Default: `0`* |
| `active_job.insights.enabled` | Boolean | Enable automatic Insights instrumentation for this plugin. *Default: `true`* |
| **SIDEKIQ** | | |
| `sidekiq.attempt_threshold` | Integer | The number of attempts before notifications will be sent. *Default: `0`* |
| `sidekiq.use_component` | Boolean | Automatically set the component to the class of the job. Helps with grouping. *Default: `true`* |
| `sidekiq.insights.enabled` | Boolean | Enable automatic Insights instrumentation for Sidekiq. *Default: `true`* |
| `sidekiq.insights.collection_interval` | Integer | The frequency, in seconds, in which Sidekiq metrics are sampled. *Default: `60`* |
| `sidekiq.insights.cluster_collection` | Boolean | Enable cluster wide metric collection. If you are using Sidekiq Enterprise, this is configured automatically. *Default: `true`* |
| `sidekiq.insights.events` | Boolean | Enable sending Sidekiq events to Insights. *Default: `true`* |
| `sidekiq.insights.metrics` | Boolean | Enable sending Sidekiq metrics to Insights. *Default: `false`* |
| **SOLID\_QUEUE** | | |
| `solid_queue.insights.enabled` | Boolean | Enable automatic Insights instrumentation for SolidQueue. *Default: `true`* |
| `solid_queue.insights.collection_interval` | Integer | The frequency, in seconds, in which SolidQueue metrics are sampled. *Default: `60`* |
| `solid_queue.insights.cluster_collection` | Boolean | Enable cluster wide metric collection. *Default: `true`* |
| **DELAYED JOB** | | |
| `delayed_job.attempt_threshold` | Integer | The number of attempts before notifications will be sent. *Default: `0`* |
| **SHORYUKEN** | | |
| `shoryuken.attempt_threshold` | Integer | The number of attempts before notifications will be sent. *Default: `0`* |
| **SINATRA** | | |
| `sinatra.enabled` | Boolean | Enable Sinatra auto-initialization. *Default: `true`* |
| **RAILS** | | |
| `rails.subscriber_ignore_sources` | Array | `source`s (strings or regexes) that should be ignored when using the Rails error reporter. *Default: `[]`* |
| `rails.insights.enabled` | Boolean | Enable automatic Insights instrumentation for Rails. *Default: `true`* |
| `rails.insights.events` | Boolean | Enable sending Rails events to Insights. *Default: `true`* |
| `rails.insights.metrics` | Boolean | Enable sending Rails metrics to Insights. *Default: `false`* |
| **Autotuner** | | |
| `autotuner.insights.enabled` | Boolean | Enable automatic Insights data collection for Autotuner. *Default: `true`* |
| **Karafka** | | |
| `karafka.insights.enabled` | Boolean | Enable automatic Insights instrumentation for Karafka. *Default: `true`* |
| `karafka.insights.events` | Boolean | Enable sending Karafka events to Insights. *Default: `true`* |
| `karafka.insights.metrics` | Boolean | Enable sending Karafka metrics to Insights. *Default: `false`* |
| **Net::HTTP** | | |
| `net_http.insights.enabled` | Boolean | Enable automatic Insights instrumentation for `Net::HTTP`. *Default: `true`* |
| `net_http.insights.full_url` | Boolean | Log the request URL instead of just the domain. *Default: `false`* |
| `net_http.insights.events` | Boolean | Enable sending Net::HTTP events to Insights. *Default: `true`* |
| `net_http.insights.metrics` | Boolean | Enable sending Net::HTTP metrics to Insights. *Default: `false`* |
# Integration guide
> Learn how to integrate Honeybadger's Ruby gem with custom frameworks and applications.
This guide will teach you how to integrate your gem, framework, or other Ruby project with the [*honeybadger* Ruby gem](https://github.com/honeybadger-io/honeybadger-ruby).
## Who is this guide for?
[Section titled “Who is this guide for?”](#who-is-this-guide-for)
This guide is for anyone who is interested in extending the capability of the Honeybadger gem in order to share their integration with the Honeybadger community. In addition to covering *how* to create your integration, you’ll learn two ways to package and distribute it:
1. Submit a pull-request (PR) to the official Honeybadger gem
2. Publish your integration as a new gem that you maintain
## What can I build?
[Section titled “What can I build?”](#what-can-i-build)
Honeybadger’s plugin system integrates with popular gems (and even Ruby itself) in order to report exceptions with rich contextual information. Here are some examples of plugins which have been created so far:
* [Report exceptions in Sidekiq jobs](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/lib/honeybadger/plugins/sidekiq.rb), including the job parameters and configuration data
* [Automatically associate errors with users](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/lib/honeybadger/plugins/warden.rb) for any application which uses a Warden-based authentication system (such as Devise)
* Hook into Ruby’s exception system in order to [report Local Variables for all Ruby exceptions](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/lib/honeybadger/plugins/local_variables.rb)
## Getting started
[Section titled “Getting started”](#getting-started)
The Honeybadger gem has a [plugin system](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/lib/honeybadger/plugin.rb) which allows you to step into our initialization process. From there, you can use the full power of Ruby to integrate with Honeybadger in interesting ways.
Honeybadger’s plugin API is simple—there are only a few methods you need to learn. To give you an idea of what this looks like, let’s build a simple plugin.
## Building your plugin
[Section titled “Building your plugin”](#building-your-plugin)
Imagine you’re using a framework which provides the following API for handling exceptions:
```ruby
MyFramework.on_exception do |exception|
# Exception handling code (report the exception, log it, etc.)
end
```
This is a fairly common pattern; for instance, [SuckerPunch has a similar API](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/lib/honeybadger/plugins/sucker_punch.rb#L10).
Here’s a Honeybadger plugin which checks to see if `MyFramework` is available. If it is, it installs an exception handler which reports all exceptions to Honeybadger:
```ruby
require 'honeybadger/plugin'
require 'honeybadger/ruby'
module Honeybadger
module Plugins
# Register your plugin with an optional name. If the name (such as
# "my_framework") is not provided, Honeybadger will try to infer the name
# from the current file.
Plugin.register 'my_framework' do
requirement do
# Check to see if the thing you're integrating with is loaded. Return true
# if it is, or false if it isn't. An exception in this block is equivalent
# to returning false. Multiple requirement blocks are supported.
defined?(MyFramework)
end
execution do
# Write your integration. This code will be executed only if all requirement
# blocks return true. An exception in this block will disable the plugin.
# Multiple execution blocks are supported.
MyFramework.on_exception do |exception|
Honeybadger.notify(exception)
end
end
end
end
end
```
There are three steps which Honeybadger performs when loading your plugin:
1. `Honeybadger::Plugin.register` registers the plugin with Honeybadger.
2. When initializing an application, Honeybadger will attempt to load your plugin, executing every `requirement` block you gave it.
3. If all `requirement` blocks returned `true`, then Honeybadger executes each `execution` block in turn.
### A simple Sidekiq plugin
[Section titled “A simple Sidekiq plugin”](#a-simple-sidekiq-plugin)
[Sidekiq](https://sidekiq.org/) is a good example of a framework which integrates nicely with Honeybadger, providing a lot of rich contextual data with each exception.
*Note: Keep in mind that [we already support Sidekiq natively](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/lib/honeybadger/plugins/sidekiq.rb), so don’t try to actually run this example in a Honeybadger project, or you may get multiple exception reports. :)*
lib/honeybadger/plugins/sidekiq.rb
```ruby
require 'honeybadger/plugin'
require 'honeybadger/ruby'
module Honeybadger
module Plugins
# It's best practice to create your own Honeybadger::Plugins::YourFramework
# namespace, if you need to create additional classes to use when executing
# your plugin.
module Sidekiq
class Middleware
def call(worker, msg, queue)
Honeybadger.context.clear!
yield
end
end
Plugin.register do
requirement { defined?(::Sidekiq) }
execution do
::Sidekiq.configure_server do |sidekiq|
sidekiq.server_middleware do |chain|
chain.prepend Middleware
end
sidekiq.error_handlers << lambda {|ex, params|
job = params[:job]
Honeybadger.notify(ex,
parameters: params,
component: job['wrapped'] || job['class']
)
}
end
end
end
end
end
end
```
## Sharing your plugin
[Section titled “Sharing your plugin”](#sharing-your-plugin)
Once you’ve built your plugin, it’s time to share it with other ‘badgers like you, for fame and glory (or at least a high-five). There are two good ways to share a plugin:
1. Submit a PR to the Honeybadger gem
2. Publish your own Ruby gem, such as “honeybadger-plugins-sidekiq”
We’d love to help you decide which of these is the best way to go. We’re very open to including a wide variety of plugins in the official Honeybadger gem, so that everyone can enjoy them by default. Head over to GitHub and [tell us about your plugin by creating a new issue](https://github.com/honeybadger-io/honeybadger-ruby/issues/new).
Here’s an example issue (this is just how I’d write it—you don’t need to include a link to your plugin if you haven’t finished it yet, or it isn’t on GitHub).
> Hey ‘badgers!
>
> I use Sidekiq a lot in my daily work, and since there is no existing Honeybadger integration, I decided to make one. Would you be interested in including Sidekiq as a default plugin?
>
> Here’s a link to Sidekiq:
>
>
>
> Here’s a link to my plugin:
>
>
>
> Thanks!
We’ll get back to you as soon as possible. If we decide that your plugin is something that would benefit everyone, we’ll ask you to submit a PR (if you aren’t sure how to do this, don’t worry—read on for instructions, and feel free to ask us for help!
If we decided against a PR for some reason, you can publish your plugin as a gem, which is another great way to share it with the community.
### Submitting a PR
[Section titled “Submitting a PR”](#submitting-a-pr)
To submit a PR, you’ll need a few things:
1. A [GitHub account](https://github.com/)
2. [Git](https://help.github.com/articles/set-up-git/) and a [supported Ruby version](../supported-versions/) installed on your computer
3. A fork of the [honeybadger gem](https://github.com/honeybadger-io/honeybadger-ruby) repository
After creating a fork (go to the [honeybadger-ruby repository](https://github.com/honeybadger-io/honeybadger-ruby) and use the **Fork** button, top-right of the page), run the following commands to set up your local copy of the gem:
```sh
git clone https://github.com/your-username/honeybadger-ruby.git
cd honeybadger-ruby
bundle install
```
To make sure everything is set up correctly, try running the unit tests:
```plaintext
bundle exec rake spec:units
```
You should see something like this:
```plaintext
All examples were filtered out; ignoring {:focus=>true}
Randomized with seed 14664
................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
Finished in 0.97639 seconds (files took 0.57739 seconds to load)
512 examples, 0 failures
```
Assuming the tests ran, you should be ready to add your plugin code.
1. Create a file in [*lib/honeybadger/plugins/*](https://github.com/honeybadger-io/honeybadger-ruby/tree/master/lib/honeybadger/plugins). The file name should use [snake\_case](https://en.wikipedia.org/wiki/Snake_case), and have a Ruby (`.rb`) file extension. If your plugin integrates with “MyFramework”, then the file path should be *lib/honeybadger/plugins/my\_framework.rb*.
2. Add your plugin code to the file you created.
3. A good PR should include tests. We use [RSpec](http://rspec.info/) for our test suite. For an example of a simple RSpec plugin test, [check out the tests for the SuckerPunch plugin](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/spec/unit/honeybadger/plugins/sucker_punch_spec.rb).
Use `bundle exec rake spec:units` to run the tests while developing your plugin. After adding some tests and/or verifying that your plugin doesn’t cause issues with Honeybadger, you’re ready to submit your plugin:
1. Add an entry to [CHANGELOG.md](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/CHANGELOG.md):
```plaintext
## [Unreleased]
### Added
- Added a plugin for MyFramework
```
See [Keep a Changelog](http://keepachangelog.com/) for more info on the format of the changelog.
2. Commit your changes:
```sh
git add .
git commit --message "Add a MyFramework plugin."
```
3. Push your changes:
```sh
git push origin master
```
Now that your fork has the changes you want to add, create a pull request to the [honeybadger-io/honeybadger-ruby repository](https://github.com/honeybadger-io/honeybadger-ruby/pulls) on GitHub. If you’re not sure how to create a pull request, [check out GitHub’s guide](https://help.github.com/articles/creating-a-pull-request-from-a-fork/), and feel free to ask us for help!
### Publishing your own gem
[Section titled “Publishing your own gem”](#publishing-your-own-gem)
Before publishing your own gem, read through [the official RubyGems guide](https://guides.rubygems.org/publishing/). Here are some basic steps to create a gem and publish it to [RubyGems.org](https://rubygems.org/). If you get stuck, feel free to ask us for help!
*Fun fact: did you know that Ruby Central uses Honeybadger to monitor RubyGems.org for exceptions?*
#### Creating the gem
[Section titled “Creating the gem”](#creating-the-gem)
Bundler has a handy tool that will create a simple gem for you.
1. Make sure you have the `bundler` gem installed:
```sh
gem install bundler
```
2. Create a new gem using the `bundle gem` command. You should name your gem “honeybadger-plugins-\[name of your plugin]”. For example, if your plugin integrates with MyFramework, name your project: “honeybadger-my\_framework”:
```sh
bundle gem honeybadger-plugins-my_framework
```
Follow the prompts to add tests (we use RSpec), create a license (we like MIT), and add a code of conduct for your gem.
3. Once your gem is created, check out the directory structure, and read the README:
```sh
cd honeybadger-my_framework
ls -l
cat README.md
```
4. Lastly, run the `bundle install` command:
```sh
bundle install
```
It will fail the first time, asking you to edit the *honeybadger-plugins-my\_framework.gemspec* file. Make the requested edits and then re-run `bundle install` until it completes successfully.
*Note: If you added a test framework, run the new test suite with `bundle exec rake`.*
#### Adding your code
[Section titled “Adding your code”](#adding-your-code)
1. Add your plugin code to *lib/honeybadger/plugins/my\_framework.rb*, which should have been created by the `bundle gem` command.
2. If you chose to add a test framework when creating your gem, add some tests.
3. After you verify that your plugin works, commit your changes:
```sh
git add .
git commit --message "Add a MyFramework plugin."
```
#### Pushing to RubyGems.org
[Section titled “Pushing to RubyGems.org”](#pushing-to-rubygemsorg)
To publish your first version (0.1.0) to [RubyGems.org](https://rubygems.org/):
```sh
gem build honeybadger-plugins-my_framework.gemspec
gem push honeybadger-plugins-my_framework-0.1.0.gem
```
You can view your new gem at the following URL:
# Supported versions
> View supported Ruby and Rails versions and compatibility requirements for Honeybadger's Ruby gem.
The support tables below are for the latest version of the Honeybadger gem, which aims to support all maintained (non-EOL) versions of Ruby and supported frameworks. If you’re using an older version of Ruby or your framework, you may need to install an older version of the gem.
## Supported Ruby versions
[Section titled “Supported Ruby versions”](#supported-ruby-versions)
| Ruby Interpreter | Supported Version |
| ---------------- | ----------------- |
| MRI | >= 2.7.0 |
| JRuby | >= 9.2 |
## Supported web frameworks
[Section titled “Supported web frameworks”](#supported-web-frameworks)
| Framework | Version | Native? |
| ------------------------------------------------------------------- | -------- | ---------- |
| [Rails](/lib/ruby/integration-guides/rails-exception-tracking/) | >= 5.2 | yes |
| [Sinatra](/lib/ruby/integration-guides/sinatra-exception-tracking/) | >= 1.2.1 | yes |
| [Rack](/lib/ruby/integration-guides/rack-exception-tracking/) | >= 1.0 | middleware |
Rails and Sinatra are supported natively (install/configure the gem and you’re done). For vanilla Rack apps, we provide a collection of middleware that must be installed manually.
To use Rails 2.x, you’ll need to use an earlier version of the Honeybadger gem. [Go to version 1.x of the gem docs](https://github.com/honeybadger-io/honeybadger-ruby/blob/1.16-stable/docs/index.md).
## Supported job queues
[Section titled “Supported job queues”](#supported-job-queues)
| Library | Version | Native? |
| ------------ | ------- | ------- |
| Active Job | any | yes |
| Delayed Job | any | yes |
| Resque | any | yes |
| Sidekiq | any | yes |
| Shoryuken | any | yes |
| Sucker Punch | any | yes |
For other job queues, you can manually call [`Honeybadger.notify`](https://docs.honeybadger.io/lib/ruby/getting-started/reporting-errors/) in your error handler. For instance, if you’re using GoodJob:
```ruby
config.good_job.on_thread_error = do |ex|
Honeybadger.notify(ex)
end
```
## Other integrations
[Section titled “Other integrations”](#other-integrations)
| Library | Version | Native? | Description |
| ------------- | ------- | ------- | -------------------------------------------------------------- |
| Devise/Warden | any | yes | Exceptions are automatically associated with the current user. |
| Thor | any | yes | Exceptions in commands are automatically reported. |
You can also [integrate Honeybadger into any Ruby script](/lib/ruby/integration-guides/ruby-exception-tracking/) using `Honeybadger.notify`. See the [API reference](https://www.rubydoc.info/gems/honeybadger/Honeybadger/Agent) for a full list of methods available.
# Adding context to errors
> Add context to Ruby error reports with custom data to improve debugging and error resolution.
Sometimes, default exception data just isn’t enough. If you have extra data that will help you in debugging, send it as part of an error’s context. Context is what you’re looking for if:
* You want to record the current user’s id or email address at the time of an exception
* You need to send raw POST data for use in debugging
* You have any other metadata you’d like to send with an exception
Honeybadger supports two types of context: global and local.
## Global context
[Section titled “Global context”](#global-context)
Global context is automatically reported with any exception which occurs after the context has been created:
```ruby
Honeybadger.context({
my_data: 'my value'
})
```
A few other methods are also available when working with context:
```ruby
# Clear the global context:
Honeybadger.context.clear!
# Fetch the global context:
Honeybadger.get_context
```
Global context is stored in a [thread-local variable](https://ruby-doc.org/core-3.0.1/Thread.html#class-Thread-label-Thread+variables+and+scope), which means each thread has its own global context.
## Local context
[Section titled “Local context”](#local-context)
Local context is similar to global context but it is only reported with exceptions that occur within a specific block of code where the local context is set. This is useful when you want to add context data for a specific operation or a set of operations, but you don’t want that context to leak into other parts of your application.
You can set local context by passing a block to the `Honeybadger.context` method:
```ruby
Honeybadger.context({ local_data: 'local value' }) do
# This block of code has access to the local context.
# If an exception occurs here, the local context will be reported with the exception.
end
```
The local context is automatically cleared after the block is executed, even if an exception is raised within the block. This ensures that the local context does not leak into other parts of your application.
To fetch the local context, you can call `Honeybadger.get_context`:
```ruby
# Set global context
Honeybadger.context({ global_data: 'global value' })
# Fetch and print global context
puts Honeybadger.get_context
# Expected output: { global_data: 'global value' }
# Set local context within a block
Honeybadger.context({ local_data: 'local value' }) do
# Fetch and print context within the block
puts Honeybadger.get_context
# Expected output: { global_data: 'global value', local_data: 'local value' }
end
# Fetch and print context outside the block
puts Honeybadger.get_context
# Expected output: { global_data: 'global value' }
```
Calling `Honeybadger.get_context` within a block will return a merged hash of the global and local context. If there are conflicts, the local context will take precedence.
Remember, local context is also stored in a thread-local variable, which means each thread has its own local context.
## Context in `Honeybadger.notify`
[Section titled “Context in Honeybadger.notify”](#context-in-honeybadgernotify)
You can also add context to a manual error report using the `:context` option, like this:
```ruby
Honeybadger.notify(exception, context: {
my_data: 'my local value'
})
```
Local context always overrides any global values when the error is reported.
## Special context values
[Section titled “Special context values”](#special-context-values)
While you can add any key/value data to context, a few keys have special meaning in Honeybadger:
| Option | Description |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `:_action` | This will set the `action` attribute of your error data if not already set. |
| `:_component` | This will set the `component` attribute of your error data if not already set. |
| `:user_id` | The `String` user ID used by Honeybadger to aggregate user data across occurrences on the error page. |
| `:user_email` | Same as `:user_id`, but for email addresses |
| `:tags` | A `String` comma-separated list of tags. When present, tags will be applied to errors with this context. |
Using the `:_action` and `:_component` keys are useful when you are manually reporting errors via `Honeybadger.notify` or `Rails.error.report`.
## Defining context on objects
[Section titled “Defining context on objects”](#defining-context-on-objects)
Context must either be a `Hash`, or it must define the method `#to_honeybadger_context` to return a `Hash`. For example, to pass a `User` instance to `Honeybadger.context`:
```ruby
class User < ApplicationRecord
def to_honeybadger_context
{ user_id: id, user_email: email }
end
end
user = User.last
Honeybadger.context(user)
```
When the `#to_honeybadger_context` method is defined on an `Exception` class, the context will be automatically added when the exception is reported:
```ruby
class CustomError < StandardError
def to_honeybadger_context
{ tags: 'custom' }
end
end
raise CustomError, 'This error will be reported with context'
```
## Limits
[Section titled “Limits”](#limits)
Honeybadger uses the following limits to ensure the service operates smoothly for everyone:
* Nested objects have a max depth of 20
* Context values have a max size of 64Kb
When an error notification includes context data that exceed these limits, the context data will be truncated, and the notification will still be processed.
# Breadcrumbs
> Add breadcrumbs to Ruby error reports to track events and user actions leading up to errors.
Breadcrumbs are a useful debugging tool that give you the ability to record contextual data as an event called a `breadcrumb`. When your Project reports an Error (Notice), we send along the breadcrumbs recorded during the execution (request, job, task, etc…).
[Context](/lib/ruby/getting-started/adding-context-to-errors/) is another way to store extra data to help with debugging. Context is still a great way to attach global data to an error, however, there are scenarios where Breadcrumbs might be a better choice:
* You want to record metadata that contains duplicate keys
* You want to group related data
* You care about when an event happened in relation to an error
## Automatic Rails breadcrumbs
[Section titled “Automatic Rails breadcrumbs”](#automatic-rails-breadcrumbs)
Rails provides a robust [Active Support Instrumentation](https://guides.rubyonrails.org/active_support_instrumentation.html) implementation that allows us to automatically add insights into your errors.
The instrumentation breadcrumbs are very configurable. You can modify a copy of the default config if you want to change the default behavior. Here’s how you might remove all ActiveRecord breadcrumb events:
```ruby
notifications = Honeybadger::Breadcrumbs::ActiveSupport.default_notifications
notifications.delete("sql.active_record")
Honeybadger.configure do |config|
config.breadcrumbs.active_support_notifications = notifications
end
```
Note
Active Record SQL logging is on by default. Seeing what SQL statements have been executed leading up to an error can often give helpful context during debugging. We attempt to strip out any bound params or columns before storing queries, however, if you are executing any raw SQL commands or not using prepared statements, there might be a chance that sensitive data could get into the breadcrumb metadata. If you want to keep the ActiveRecord breadcrumbs but remove the SQL metadtata, you could update the config like this:
```ruby
notifications = Honeybadger::Breadcrumbs::ActiveSupport.default_notifications
notifications["sql.active_record"][:select_keys].delete_if {|k| k == :sql}
Honeybadger.configure do |config|
config.breadcrumbs.active_support_notifications = notifications
end
```
You can set an empty hash to remove ActiveSupport notifications all together:
```ruby
Honeybadger.configure do |config|
config.breadcrumbs.active_support_notifications = {}
end
```
The key for each instrumentation hash is the hook id used for subscribing to the ActiveSupport notification. For example
```ruby
{
"process_action.action_controller" => {
message: "Action Controller Action Process",
select_keys: [:controller, :action, :format, :method, :path, :status, :view_runtime, :db_runtime],
category: "request",
}
}
```
will subscribe to the `process_action.action_controller` instrumentation notification and produce a breadcrumb with the specified `message` and `category` and restrict [the keys](https://guides.rubyonrails.org/active_support_instrumentation.html#process-action-action-controller) passed into the metadata to the set supplied by `select_keys`.
Here are all the options you can pass into an instrumentation hash:
| Option name | Description | |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `:message` | A `String` message that describes the event or you can dynamically build the message by passing a `Proc` that accepts the event metadata. | |
| `:category` | A `String` key used to group specific types of events | |
| `:select_keys` | An (*optional*) `Array` of keys that filters what data we select from the instrumentation data | `Proc` |
| `:exclude_when` | A (*optional*) `Proc` that accepts the data payload. A truthy return value will exclude this event from the payload | `Proc` |
| `:transform` | A (*optional*) `Proc` that accepts the data payload. The return value will replace the current data hash | |
Check out the [config](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/lib/honeybadger/breadcrumbs/active_support.rb). to see what we instrument by default.
Note
Some of these configuration options have `Procs` so you will need to configure `breadcrumbs.active_support_notifications` in the Ruby configuration only.
## Custom breadcrumbs
[Section titled “Custom breadcrumbs”](#custom-breadcrumbs)
You can also add your own custom breadcrumb events:
```ruby
Honeybadger.add_breadcrumb("Email Sent", metadata: { user: user.id, message: message })
```
The first argument (`message`) is the only required data. In the UI, `message` is front and center in your breadcrumbs list, so we prefer a more terse description accompanied by rich metadata.
Here are the options allowed while adding breadcrumbs:
| Option name | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `:metadata` | A (*optional*) `Hash` that contains any contextual data to help debugging. We only accept a single-level hash with simple primitives as values (Strings, Numbers, Booleans & Symbols) |
| `:category` | An (*optional*) `String` key used to group specific types of events. We primarily use this key to display a corresponding icon, however, you can use it for your own categorization if you like |
## Logging breadcrumbs
[Section titled “Logging breadcrumbs”](#logging-breadcrumbs)
All log messages, by default, sent to the `::Logger` class are converted into breadcrumbs.
Breadcrumbs from logging can be disabled within the config:
```yaml
---
breadcrumbs:
logging:
enabled: false
```
## Categories
[Section titled “Categories”](#categories)
A Breadcrumb category is a top level property. It’s main purpose is to allow for display differences (icons & styling) in the UI. You may give a breadcrumb any category you wish. Unknown categories will default to the ‘custom’ styling.
Here are the current categories and a brief description of how you might categorize certain activity:
| Category | Description |
| -------- | ------------------------------------------- |
| custom | Any other kind of breadcrumb |
| error | A thrown error |
| query | Access or Updates to any data or file store |
| job | Queueing or Working via a job system |
| request | Outbound / inbound requests |
| render | Any output or serialization via templates |
| log | Any messages logged |
| notice | A Honeybadger Notice |
## Disabling breadcrumbs
[Section titled “Disabling breadcrumbs”](#disabling-breadcrumbs)
As of version `4.6.0`, Breadcrumbs are enabled by default. You can disable breadcrumbs via the `breadcrumbs.enabled` configuration option (in YAML):
```yaml
---
breadcrumbs:
enabled: false
```
or in the Ruby config:
```ruby
Honeybadger.configure do |config|
config.breadcrumbs.enabled = false
end
```
## Limits
[Section titled “Limits”](#limits)
Honeybadger uses the following limits to ensure the service operates smoothly for everyone:
* We only store & transmit 40 breadcrumb events. The current implementation only keeps the 40 latest breadcrumb events.
* Metadata can only hold scalar values (no nested hashes or arrays)
* String values have a max size of 64Kb
# Collecting and reporting metrics
> Collect and report custom metrics from Ruby applications to Honeybadger for performance monitoring.
Honeybadger’s Ruby gem (v5.11+) can be used to collect metrics and send them to [Insights](https://docs.honeybadger.io/guides/insights/).
## Enabling Insights
[Section titled “Enabling Insights”](#enabling-insights)
To enable collecting of metrics, you’ll first need to enable Insights in your `honeybadger.yml` configuration file:
```yaml
insights:
enabled: true
```
### Enable metrics collection
[Section titled “Enable metrics collection”](#enable-metrics-collection)
You can enable the metrics collection of each plugin by adding the relevant configuration to your `honeybadger.yml` file:
```yaml
rails:
insights:
metrics: true
karafka:
insights:
metrics: true
sidekiq:
insights:
metrics: true
net_http:
insights:
metrics: true
solid_queue:
insights:
metrics: true
puma:
insights:
metrics: true
autotuner:
insights:
metrics: true
```
Enabling this will collect metric data for the following libraries, where they will be displayed in the [Insights](https://docs.honeybadger.io/guides/insights/) section of your project:
| Metric Source (`metric_source::str`) | Metric Name (`metric_name::str`) |
| ------------------------------------ | ----------------------------------------------- |
| `rails` | `duration.sql.active_record` |
| | `duration.process_action.action_controller` |
| | `db_runtime.process_action.action_controller` |
| | `view_runtime.process_action.action_controller` |
| | `duration.cache_read.active_support` |
| | `duration.cache_fetch_hit.active_support` |
| | `duration.cache_write.active_support` |
| | `duration.cache_exist?.active_support` |
| | `duration.render_partial.action_view` |
| | `duration.render_template.action_view` |
| | `duration.render_collection.action_view` |
| | `duration.perform.active_job` |
| `sidekiq` | `active_workers` |
| | `active_processes` |
| | `jobs_processed` |
| | `jobs_failed` |
| | `jobs_scheduled` |
| | `jobs_enqueued` |
| | `jobs_dead` |
| | `jobs_retry` |
| | `queue_latency` |
| | `queue_depth` |
| | `queue_busy` |
| | `capacity` |
| | `utilization` |
| `solid_queue` | `jobs_in_progress` |
| | `jobs_blocked` |
| | `jobs_failed` |
| | `jobs_scheduled` |
| | `jobs_processed` |
| | `active_workers` |
| | `active_dispatchers` |
| | `queue_depth` |
| `autotuner` | `diff.minor_gc_count` |
| | `diff.major_gc_count` |
| | `diff.time` |
| | `request_time` |
| | `heap_pages` |
| `puma` | `pool_capacity` |
| | `max_threads` |
| | `requests_count` |
| | `backlog` |
| | `running` |
| | `worker_index` |
| `net_http` | `duration.request` |
| `karafka` | `messages_consumed` |
| | `messages_consumed_bytes` |
| | `consume_attempts` |
| | `consume_errors` |
| | `receive_errors` |
| | `connection_connects` |
| | `connection_disconnects` |
| | `network_latency_avg` |
| | `network_latency_p95` |
| | `network_latency_p99` |
| | `consumer_lags` |
| | `consumer_lags_delta` |
| | `consumer_aggregated_lag` |
| | `error_occurred` |
| | `listener_polling_time_taken` |
| | `listener_polling_messages` |
| | `consumer_messages` |
| | `consumer_batches` |
| | `consumer_offset` |
| | `consumer_consumed_time_taken` |
| | `consumer_batch_size` |
| | `consumer_processing_lag` |
| | `consumer_consumption_lag` |
| | `consumer_revoked` |
| | `consumer_shutdown` |
| | `consumer_tick` |
| | `worker_total_threads` |
| | `worker_processing` |
| | `worker_enqueued_jobs` |
| | `worker_processing` |
These metrics may be found using the following BadgerQL query:
```plaintext
fields @ts, @preview
| filter event_type::str == "metric.hb"
| filter metric_source::str == "sidekiq"
| filter metric_name::str == "active_workers"
| sort @ts
```
### Customizing Insights for a specific plugin
[Section titled “Customizing Insights for a specific plugin”](#customizing-insights-for-a-specific-plugin)
When Insights is active, all plugins are enabled if the required library is present. For example, if Sidekiq is present in your app, the Sidekiq plugin will be loaded. You can disable automatic Insights instrumentation for a specific plugin by adding a configuration like this:
```yaml
sidekiq:
insights:
enabled: false
```
This will only affect Insights-related data capture and not the error notification portion of the plugin.
Some plugins allow for an easy way to choose if you want to capture events, metrics, or both for a particular plugin. The following configuration options are available:
```yaml
rails:
insights:
events: true
metrics: false
karafka:
insights:
events: true
metrics: false
sidekiq:
insights:
events: true
metrics: false
net_http:
insights:
events: true
metrics: false
solid_queue:
insights:
events: true
metrics: false
puma:
insights:
events: true
metrics: false
autotuner:
insights:
events: true
metrics: false
```
Event options are all true by default. It is recommened to turn off events for plugins that may be producing more data than you actually need. Metric data collection is false by default since most metrics can be calculated from events.
### Customizing cluster metrics collection
[Section titled “Customizing cluster metrics collection”](#customizing-cluster-metrics-collection)
For certain stats, collection is limited by a polling interval. Honeybadger will periodically collect stats. This can be tailored per plugin through a configuration parameter:
```yaml
sidekiq:
insights:
collection_interval: 5
solid_queue:
insights:
collection_interval: 5
puma:
insights:
collection_interval: 1
```
By reducing or increasing the frequency the gem collect stats will all you to fine tune the accuracy of your stats and the resources used to do so.
Some metrics collection methods collect data based on the entire cluster of an application. In these cases, you would only need to collect data from a single instance of the Honeybadger gem. This helps save on unecessary load as well as data usage. Plugins collect data by default, but can be customized through configuration.
```yaml
sidekiq:
insights:
cluster_collection: false
solid_queue:
insights:
cluster_collection: false
```
You can use this configuration paramter to control which instances you want collecting cluster based data. If you are using Sidekiq Enterprise, we automatically detect the leader instance and will enable cluster collection on that instance and disable it on others without any additional configuration.
## Data aggregation
[Section titled “Data aggregation”](#data-aggregation)
When you collect metrics using the Honeybadger gem, the gem will aggregate the data and report the results to Insights every 60 seconds. This allows you to collect data as much and as quickly as you want, while making efficient use of your daily data quota. If you want to tweak the resolution of the timing, you can configure it in the `honeybadger.yml` config file.
```yaml
insights:
registry_flush_interval: 120
```
The above configuration will adjust the metric registry so that it reports every 2 minutes and help save on data usage.
## Manually collecting your own metrics
[Section titled “Manually collecting your own metrics”](#manually-collecting-your-own-metrics)
The Honeybadger gem provides a API for defining and collecting your own metrics to feed into Insights.
### Types of metrics
[Section titled “Types of metrics”](#types-of-metrics)
#### Gauge
[Section titled “Gauge”](#gauge)
A gauge tracks a specific value at a point in time. During aggregation, the metric will record the values: `max`, `min`, `avg`, and `latest`.
```ruby
Honeybadger.gauge('data_size', ->{ file.byte_size })
```
#### Timer
[Section titled “Timer”](#timer)
Timers are similar to gauges in that they track a specific value in time. However, the `time` methods provides a convenient way to measure duration across your ruby operations.
```ruby
Honeybadger.time('process_application', ->{ application.process })
```
#### Counter
[Section titled “Counter”](#counter)
Counters are simple numbers that you can increment or decrement by any value you wish.
```ruby
Honeybadger.increment_counter('add_to_basket', { item_id: item.id })
```
#### Histogram
[Section titled “Histogram”](#histogram)
Histograms allows you to collate data values into predefined bins. The default bins are `[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]`. You can define your own set by passing a `bins` attribute to the metric. You may pass a callable lambda, which will be timed and the duration recorded. Or you may also pass a `duration` keyword argument if you have the value at hand.
```ruby
Honeybadger.histogram('execute_request', ->{ request.execute })
# or
Honeybadger.histogram('execute_request', duration: duration)
```
#### Helper module
[Section titled “Helper module”](#helper-module)
You can also include the helper module `Honeybadger::InstrumentationHelper` into any of your classes. The module provdes shortened forms to create the same metrics as metioned above, as well as other helper methods to customize your metrics.
Here is an example of how we can rewrite the example metrics above, while adding more custom attributes:
```ruby
class MyMetrics
include Honeybadger::InstrumentationHelper
attr_reader :region
def initialize(region)
@region = region
end
def example
metric_source 'custom_metrics'
metric_attributes { region: region }
gauge 'data_size', ->{ file.byte_size }
time 'process_application', ->{ application.process }
increment_counter 'add_to_basket', { item_id: item.id }
histogram 'execute_request', ->{ request.execute }
end
end
```
Aside from a less verbose API, there are two available helper methods that will aid in organizing your metrics. The `metric_source` method accepts the name of where your metrics are coming from. This can be the name of a library, or the class you are calling from. The `metric_attributes` method accepts a hash that will be passed to all metrics that follow.
Then you can find these metrics by using the following BadgerQL query:
```plaintext
fields @ts, @preview
| filter event_type::str == "metric.hb"
| filter metric_source::str == "custom_metrics"
| filter region::str == "some-region"
| sort @ts
```
## Ignoring metrics
[Section titled “Ignoring metrics”](#ignoring-metrics)
You can use the `before_event` callback to inspect or modify metric data, as well as calling `halt!` to prevent the metric from being sent to Honeybadger:
```ruby
Honeybadger.configure do |config|
config.before_event do |event|
if event.event_type == "metric.hb" && event[:metric_name] == "jobs_processed"
event.halt!
end
end
end
```
`before_event` can be called multiple times to add multiple callbacks.
Similarly, you may also ignore metric events by configuring your `honeybadger.yml` config file by specifying a hash object:
```yaml
events:
ignore:
- event_type: "metric.hb"
metric_name: "jobs_processed"
```
## Puma
[Section titled “Puma”](#puma)
Puma has it’s own plugin system and requires a small change to your `puma.rb`. The Honeybadger gem comes with Puma plugin and can be enabled by adding the following to your `puma.rb`:
```ruby
plugin :honeybadger
```
## Autotuner
[Section titled “Autotuner”](#autotuner)
To enable Autotuner, follow the directions in the [README.md](https://github.com/Shopify/autotuner) file. You can skip the parts about setting `Autotuner.reporter` and `Autotuner.metrics_reporter` as the Honeybadger gem will configure this for you.
## More automatic instrumentation
[Section titled “More automatic instrumentation”](#more-automatic-instrumentation)
The Honeybadger Ruby gem provides more instrumentation than just metrics. When you enable Insights, you also enable automatic event logging. Check out [Sending Events to Insights](/lib/ruby/getting-started/sending-events-to-insights/) for more information.
# Collecting user feedback
> Collect user feedback when errors occur in Ruby applications to get context directly from affected users.
The Honeybadger gem has a few special tags that it looks for whenever you render an error page in a Rack-based application. These can be used to display extra information about the error, or to ask the user for information about how they triggered the error.
## Installing the middleware
[Section titled “Installing the middleware”](#installing-the-middleware)
Honeybadger installs the middleware automatically in Rails projects. For all other applications, the middleware must be installed manually:
```ruby
use Honeybadger::Rack::UserInformer
use Honeybadger::Rack::UserFeedback
```
## Displaying the error ID
[Section titled “Displaying the error ID”](#displaying-the-error-id)
When an error is sent to Honeybadger, our API returns a unique UUID for the occurrence within your project. This UUID can be automatically displayed for reference on error pages.
To include the error id, simply place this magic HTML comment on your error page (normally `public/500.html` in Rails):
```html
```
By default, we will replace this tag with:
```plaintext
Honeybadger Error {{error_id}}
```
Where `{{error_id}}` is the UUID. You can customize this output by overriding the `user_informer.info` option in your honeybadger.yml file (you can also enabled/disable the middleware):
config/honeybadger.yml
```yaml
user_informer:
enabled: true
info: "Error ID: {{error_id}}"
```
You can use that UUID to load the error at the site by going to [https://app.honeybadger.io/notice/some-uuid-goes-here](https://app.honeybadger.io/notice/).
## Displaying a feedback form
[Section titled “Displaying a feedback form”](#displaying-a-feedback-form)
When an error is sent to Honeybadger, an HTML form can be generated so users can fill out relevant information that led up to that error. Feedback responses are displayed inline in the comments section on the fault detail page.
To include a user feedback form on your error page, simply add this magic HTML comment (normally `public/500.html` in Rails):
```html
```
You can change the text displayed in the form via the Rails internationalization system. Here’s an example:
config/locales/en.yml
```yaml
en:
honeybadger:
feedback:
heading: "Care to help us fix this?"
explanation:
"Any information you can provide will help us fix the problem."
submit: "Send"
thanks: "Thanks for the feedback!"
labels:
name: "Your name"
email: "Your email address"
comment: "Comment (required)"
```
The feedback form can be enabled and disabled using the `feedback.enabled` config option (defaults to `true`):
config/honeybadger.yml
```yaml
feedback:
enabled: true
```
# Honeybadger on the command line
> Use Honeybadger's command-line tools for Ruby applications to test your integration, track deployments, and more.
The *honeybadger* gem includes a Command Line Interface (CLI) that can be used for a variety of activities from installing Honeybadger in a new project to reporting failed cron jobs.
For a full overview of the CLI and the commands it provides, see the [CLI reference](/lib/ruby/gem-reference/cli/).
In this chapter we’re going to discuss some of the interesting ways to use the CLI in your Ruby project.
## Cron/command line monitoring
[Section titled “Cron/command line monitoring”](#croncommand-line-monitoring)
`honeybadger exec` can be used from the command line/terminal to monitor failed commands. To use it, prefix any normal command with `honeybadger exec` (much like `bundle exec`):
```sh
honeybadger exec my-command --my-flag
```
If the command executes successfully, honeybadger exits with code 0. It prints any output from the command by default. To use with cron’s automatic email feature, use the `--quiet` flag, which will suppress all standard output from the origin command unless the command fails *and* the Honeybadger notification fails, in which case it will dump the output so that cron can send a backup email notification.
To learn more, run `honeybadger help exec`.
## Notify from the command line
[Section titled “Notify from the command line”](#notify-from-the-command-line)
To send a Honeybadger notification from the command line/terminal, use `honeybadger notify`:
```sh
honeybadger notify --message "This is an error from the command line"
```
To learn more, run `honeybadger help notify`.
# Customizing error grouping
> Customize how errors are grouped in Ruby applications to better organize and prioritize error reports.
Honeybadger groups similar exceptions together using rules which we’ve found to work the best in most cases. The default information we use to group errors is:
1. The file name, method name, and line number of the error’s location
2. The class name of the error
3. The component/controller name
We use this information to construct a “fingerprint” of the exception. Exceptions with the same fingerprint are treated as the same error in Honeybadger.
You can customize the grouping for each exception by changing the error class name, component, or stack trace—or by sending a custom fingerprint.
There are two ways you can customize the fingerprint: globally (for all exceptions that are reported from your app), and locally (when calling `Honeybadger.notify`).
## Customizing the grouping for all exceptions
[Section titled “Customizing the grouping for all exceptions”](#customizing-the-grouping-for-all-exceptions)
The `Honeybadger.before_notify` callback in conjunction with the `Notice#fingerprint` method allows you to change the fingerprint of a notice to properly group the same notices.
```ruby
Honeybadger.configure do |config|
config.before_notify do |notice|
notice.fingerprint = [notice.error_class,
notice.component, notice.backtrace.join(',')].join(':')
end
end
```
The `notice` parameter gives you access to useful details about the exception, such as the `url` where it occurred and the `parsed_backtrace`, an array of hashes representing each line in its backtrace. For a full list of available properties, see the [API reference](https://www.rubydoc.info/gems/honeybadger/Honeybadger/Notice).
## Customizing the grouping for `Honeybadger.notify`
[Section titled “Customizing the grouping for Honeybadger.notify”](#customizing-the-grouping-for-honeybadgernotify)
The `:fingerprint` option can be used to override the fingerprint for an exception reported with `Honeybadger.notify`:
```ruby
Honeybadger.notify(exception, fingerprint: 'a unique string')
```
# Customizing object display
> Customize how objects are displayed in Ruby error reports to improve readability and protect sensitive data.
By default, Honeybadger supports displaying the following core Ruby objects (uncoincidentally, these objects are also supported by JSON):
```plaintext
Hash
Array
Set
Numeric
TrueClass
FalseClas
NilClass
String
```
When an object of a different class is sent as data to Honeybadger (via context, request data, local variables, etc.), it’s first converted to a string using the `String()` function.
For instance, given a `User` object which defines the `#to_s` method to return the user’s email address:
```ruby
class User < ApplicationRecord
def to_s
email
end
end
user = User.create(email: "user@example.com")
Honeybadger.context({ user: user })
```
…Honeybadger will display the context as:
```json
{
"user": "user@example.com"
}
```
If this value is undesirable (since there’s no way to know the class of the object), the `#to_honeybadger` method can be defined to customize the value that is reported to Honeybadger:
```ruby
class User < ApplicationRecord
def to_s
email
end
def to_honeybadger
"#"
end
end
```
…now the context will display as:
```json
{
"user": "#"
}
```
Note that while by default the contents of `#inspect` are filtered to prevent leaking sensitive attributes, attributes are **not** filtered when returning `#inspect` from `#to_honeybadger`, so it’s always best to explicitly interpolate the attributes that you want to display unless you know that the inspected output will never contain sensitive information.
# Environments
> Configure environment-specific error tracking settings for Ruby applications across development, staging, and production.
In Honeybadger, errors are grouped by the environment they belong to. You don’t have to set an environment, but it can be useful if you’re running different versions of your app: for instance, you may have a “production” and a “staging” environment.
Our integrations typically set the environment automatically if your framework has an environment (such as `Rails.env`). To set the environment manually, set the `env` configuration option:
```yaml
---
api_key: "your-api-key"
env: "production"
```
Another option for configuring the environment that gets reported to Honyebadger is to set the `HONEYBADGER_ENV` environment variable. If this variable is set, its value will override the `RAILS_ENV` variable.
## Development environments
[Section titled “Development environments”](#development-environments)
Some environments should usually not report errors at all, such as when you are developing on your local machine or running your test suite (locally or in CI). The *honeybadger* gem has an internal list of environment names which it considers development environments:
```plaintext
development
test
cucumber
```
Honeybadger **does not** report errors in these environments unless you explicitly enable data reporting:
```yaml
---
api_key: "your-api-key"
report_data: true
```
# Filtering sensitive data
> Filter sensitive data from Ruby error reports to protect user privacy and comply with security requirements.
You have complete control over the data that Honeybadger reports when an error occurs. You can [filter specific attributes](#filtering-specific-attributes) or [disable the reporting](#disable-data-completely) of entire sections of data.
## Filtering specific attributes
[Section titled “Filtering specific attributes”](#filtering-specific-attributes)
By default, we filter the `password` and `password_confirmation`, as well as any params specified in Rails’ [`filter_parameters`](https://guides.rubyonrails.org/action_controller_overview.html#parameters-filtering).
You can configure the gem to filter additional data from the params, session, environment and cookies hashes. To do so, use the `request.filter_keys` setting.
When you add an attribute name to `request.filter_keys`, that attribute will be removed from any exceptions before they are reported to us.
Here’s an example honeybadger.yml:
```yaml
request:
filter_keys:
- password
- password_confirmation
- credit_card_number
```
The configuration above will filter out `params[:credit_card_number]`, `session[:credit_card_number]`, `cookies[:credit_card_number]`, and `Rails.env["credit_card_number"]`, as well as the password and password\_confirmation attributes.
Regular expressions (regex) are also allowed. The configuration below will filter out any keys that are named anything matching `/credit_card/i`.
```yaml
request:
filter_keys:
- !ruby/regexp "/credit_card/i"
```
## Disable data completely
[Section titled “Disable data completely”](#disable-data-completely)
You can turn off reporting of params, session and environment data entirely. Here are the configuration options to do it:
```yaml
request:
disable_session: true # Don't report session data
disable_params: true # Don't report request params
disable_environment: true # Don't report anything from Rack ENV
disable_url: true # Don't report the request URL
```
# Ignoring errors
> Ignore specific errors in Ruby applications to reduce noise and focus on actionable error reports.
Sometimes there are errors that you would rather not send to Honeybadger because they are not actionable or are handled internally. The *honeybadger* gem has multiple ways to ignore errors, depending on the situation:
* [Ignore by class](#ignore-by-class)
* [Ignore by browser](#ignore-by-browser)
* [Ignore by environment](#ignore-by-environment)
* [Ignore programmatically](#ignore-programmatically)
## Ignore by class
[Section titled “Ignore by class”](#ignore-by-class)
Some exceptions aren’t very useful and are best ignored. By default, we ignore the following:
```ruby
ActionController::RoutingError
AbstractController::ActionNotFound
ActionController::MethodNotAllowed
ActionController::UnknownHttpMethod
ActionController::NotImplemented
ActionController::UnknownFormat
ActionController::InvalidAuthenticityToken
ActionController::InvalidCrossOriginRequest
ActionDispatch::ParamsParser::ParseError
ActionController::BadRequest
ActionController::ParameterMissing
ActiveRecord::RecordNotFound
ActionController::UnknownAction
Rack::QueryParser::ParameterTypeError
Rack::QueryParser::InvalidParameterError
CGI::Session::CookieStore::TamperedWithCookie
Mongoid::Errors::DocumentNotFound
Sinatra::NotFound
```
To ignore additional errors, use the `exceptions.ignore` configuration option. The gem will ignore any exceptions matching the string, regex or class that you add to `exceptions.ignore`.
```yaml
exceptions:
ignore:
- "MyError"
- !ruby/regexp "/Ignored$/"
- !ruby/class "IgnoredError"
```
Subclasses of ignored classes will also be ignored, while strings and regexps are compared with the error class name only.
To override the default ignored exceptions, use the `exceptions.ignore_only` option instead:
```yaml
exceptions:
ignore_only:
- "MyError"
```
In this case *only* the MyError class will be ignored, and all the classes that were ignored by default will no longer be ignored.
## Ignore by browser
[Section titled “Ignore by browser”](#ignore-by-browser)
To ignore certain user agents, use the `exceptions.ignored_user_agents` config option. You can specify strings or regular expressions:
```yaml
exceptions:
ignored_user_agents:
- "Exact User Agent"
- !ruby/regexp "/Bing/i"
```
## Ignore by environment
[Section titled “Ignore by environment”](#ignore-by-environment)
Honeybadger ignores errors in development and test environments by default. You can enable or disable error reporting for a specific environment by using the `[environment name].report_data` configuration option:
```yaml
staging:
report_data: false
```
You may alternatively set `HONEYBADGER_REPORT_DATA=false` in your app’s ENV.
We ask that you not enable error reporting for your test environment. It doesn’t do anyone any good. :)
## Ignore programmatically
[Section titled “Ignore programmatically”](#ignore-programmatically)
To ignore errors with some custom logic, you can use the `before_notify` callback. This method lets you add a callback that will be run every time an exception is about to be reported to Honeybadger. If your callback calls the `notice.halt!` method, the exception won’t be reported:
```ruby
# Here's how you might ignore exceptions based on their error message:
Honeybadger.configure do |config|
config.before_notify do |notice|
notice.halt! if notice.error_message =~ /sensitive data/
end
end
```
You can access any attribute on the `notice` argument by using the `[]` syntax.
```ruby
Honeybadger.configure do |config|
config.before_notify do |notice|
notice.halt! if notice.exception.class < MyError &&
notice.params[:name] =~ "bob" &&
notice.context[:current_user_id] != 1
end
end
```
# Introduction
> Get started with Honeybadger's Ruby gem for error tracking and application monitoring in Ruby and Rails applications.
In this chapter we’re going to cover [the basics of installing the *honeybadger* gem](#installing-the-gem) and [how configuration works](#how-configuration-works). For full instructions and best practices for your framework or platform, see the **Integration guides**.
## Installing the gem
[Section titled “Installing the gem”](#installing-the-gem)
The first step is to add the honeybadger gem to your Gemfile:
```ruby
gem 'honeybadger'
```
Tell bundler to install:
```bash
bundle install
```
Next, you'll set the API key for this project.
```bash
bundle exec honeybadger install [Your project API key]
```
This will do three things:
1. Generate a `honeybadger.yml` file. If you don't like config files, you can place your API key in the `$HONEYBADGER_API_KEY` environment variable.
2. If Capistrano is installed, we'll add a require statement to *Capfile*.
3. Send a test exception to your Honeybadger project.
## How configuration works
[Section titled “How configuration works”](#how-configuration-works)
Honeybadger’s configuration consists of named options. Some are top level options such as `api_key`, while others have nested namespaces (separated with a dot) such as `exceptions.ignore`. The only *required* option is `api_key`.
There are three ways to configure options for the Honeybadger gem:
1. *honeybadger.yml* configuration file
2. Environment variables
3. Programmatically using `Honeybadger.configure`
By default we use the *honeybadger.yml* file, so that’s what most of the examples will use in this guide, but the method you use is a matter of preference. Here’s an example *honeybadger.yml* file:
```yaml
---
api_key: "PROJECT_API_KEY"
```
See the [Configuration reference](/lib/ruby/gem-reference/configuration/) for additional info.
# Multiple projects
> Configure multiple Honeybadger projects in Ruby applications for multi-tenant or complex architectures.
To send errors to another Honeybadger project, configure an additional agent:
```ruby
OtherBadger = Honeybadger::Agent.new
OtherBadger.configure do |config|
config.api_key = "PROJECT_API_KEY"
end
begin
# Failing code
rescue => exception
OtherBadger.notify(exception)
end
```
Agents do not use the global *honeybadger.yml* or environment variable configuration and must be configured manually after they are instantiated.
# Performing check-ins
> Perform check-ins from Ruby applications to monitor rake tasks and cron jobs with Honeybadger.
[Honeybadger supports check-ins](/guides/check-ins/), which allow you to monitor things like cron jobs and other services.
To perform a check-in, call `Honeybadger.check_in` with the ID of the check-in in your Honeybadger project. For example:
```ruby
Honeybadger.check_in('1MqIo1')
```
## Checking in from a Rake task
[Section titled “Checking in from a Rake task”](#checking-in-from-a-rake-task)
Here’s an example of checking in from a rake task:
```ruby
task :my_task do
# your code
Honeybadger.check_in('1MqIo1')
end
```
Now your task will check in when it’s executed periodically by cron, Heroku Scheduler, etc. If it ever stops checking in, Honeybadger will notify you.
# Plain ruby mode
> Use Honeybadger's Ruby gem in plain Ruby applications without Rails or other frameworks.
In the Rails world it’s pretty much expected that when you install a gem it’s going to automatically integrate with your application. For instance, many gems provide their own [Railtie](http://edgeapi.rubyonrails.org/classes/Rails/Railtie.html) to run their own code when Rails initializes. The honeybadger gem fully embraces this approach by automatically detecting and integrating with as many 3rd-party gems as possible when it’s required:
```ruby
require 'honeybadger'
```
Some Rubyists prefer to roll their own integrations, however. They may want to avoid 3rd-party [Monkey patching](https://en.wikipedia.org/wiki/Monkey_patch), while others aren’t using any of the libraries we integrate with and would rather report errors themselves using `Honeybadger.notify`, avoiding unnecessary initialization at runtime.
To use Honeybadger without the integrations, simply `require 'honeybadger/ruby'` instead of the normal `require 'honeybadger'`. You will need to configure the gem from Ruby using `Honeybadger.configure` as *honeybadger.yml* and environment variable initialization are also skipped:
```ruby
require 'honeybadger/ruby'
Honeybadger.configure do |config|
config.api_key = "PROJECT_API_KEY"
end
at_exit do
# Wait for asynchronous error notifications before shutting down.
Honeybadger.stop
end
begin
# Failing code
rescue => exception
Honeybadger.notify(exception)
end
```
See the [API Reference](https://www.rubydoc.info/gems/honeybadger) for additional methods you can use to integrate Honeybadger with your Ruby project manually.
# Reporting errors
> Report errors from Ruby applications to Honeybadger with automatic notifications and custom error handling.
Use `Honeybadger.notify(exception)` to send any exception to Honeybadger. For example, to notify Honeybadger of a rescued exception without re-raising:
controller.rb
```ruby
begin
fail 'oops'
rescue => exception
Honeybadger.notify(exception)
end
```
## Reporting errors without an exception
[Section titled “Reporting errors without an exception”](#reporting-errors-without-an-exception)
You can report any type of error to Honeybadger, not just exceptions. The simplest form is calling `Honeybadger.notify` with an error message:
```ruby
Honeybadger.notify("Something is wrong here")
```
The error’s class name will default to “Notice”, and a backtrace will be generated for you from the location in your code where `Honeybadger.notify` was called.
## Passing additional options to `Honeybadger.notify`
[Section titled “Passing additional options to Honeybadger.notify”](#passing-additional-options-to-honeybadgernotify)
In some cases you will want to override the defaults or add additional information to your error reports. To do so, you can pass a second options `Hash` to `Honeybadger.notify`.
For example, building on the example in [Reporting errors without an exception](#reporting-errors-without-an-exception), you could override the default class name:
```ruby
Honeybadger.notify("Something is wrong here", error_class: "MyError")
```
These are all the available options you can pass to `Honeybadger.notify`:
| Option name | Description | Default value |
| ---------------- | -------------------------------------------------------------- | ------------- |
| `:error_message` | The `String` error message. | `nil` |
| `:error_class` | The `String` class name of the error. | `"Notice"` |
| `:backtrace` | The `Array` backtrace of the error. | `caller` |
| `:fingerprint` | The `String` grouping fingerprint of the exception. | `nil` |
| `:force` | Always report the exception when `true`, even when ignored. | `false` |
| `:sync` | Send data synchronously (skips the worker) when `true`. | `false` |
| `:tags` | The `String` comma-separated list of tags. | `nil` |
| `:context` | The `Hash` context to associate with the exception. | `nil` |
| `:controller` | The `String` controller name (such as a Rails controller). | `nil` |
| `:component` | The `String` component name (such as a Rails controller name). | `nil` |
| `:action` | The `String` action name (such as a Rails controller action). | `nil` |
| `:parameters` | The `Hash` HTTP request paramaters. | `nil` |
| `:session` | The `Hash` HTTP request session. | `nil` |
| `:url` | The `String` HTTP request URL. | `nil` |
## Getting the current backtrace
[Section titled “Getting the current backtrace”](#getting-the-current-backtrace)
There are two ways to get the current backtrace in Ruby:
1. `Thread.current.backtrace` returns the entire backtrace up to and including the current method.
2. `caller` returns the backtrace up to but NOT including the current method.
Either method can be passed to `Honeybadger.notify` using the `backtrace` option. Honeybadger sends the exception backtrace by default, or `caller` if there is no exception object available.
# Sending events to Insights
> Send custom events from Ruby applications to Honeybadger Insights for monitoring and analysis.
Honeybadger’s Ruby gem (v5.11+) can be used to send events to [Insights](/guides/insights/).
## Automatic instrumentation
[Section titled “Automatic instrumentation”](#automatic-instrumentation)
You can instrument your Ruby applications by enabling Insights in your `honeybadger.yml` configuration file:
```yaml
insights:
enabled: true
```
### Event captures
[Section titled “Event captures”](#event-captures)
Enabling automatic instrumentation will send the following events to Honeybadger, where they will be displayed in the [Insights](https://docs.honeybadger.io/guides/insights/) section of your project:
| Plugin | Event Type (`event_type::str`) |
| ------------- | ------------------------------------------ |
| `rails` | `process_action.action_controller` |
| | `send_file.action_controller` |
| | `redirect_to.action_controller` |
| | `halted_callback.action_controller` |
| | `unpermitted_parameters.action_controller` |
| | `write_fragment.action_controller` |
| | `read_fragment.action_controller` |
| | `expire_fragment.action_controller` |
| | `cache_read.active_support` |
| | `cache_read_multi.active_support` |
| | `cache_generate.active_support` |
| | `cache_fetch_hit.active_support` |
| | `cache_write.active_support` |
| | `cache_write_multi.active_support` |
| | `cache_increment.active_support` |
| | `cache_decrement.active_support` |
| | `cache_delete.active_support` |
| | `cache_delete_multi.active_support` |
| | `cache_cleanup.active_support` |
| | `cache_prune.active_support` |
| | `cache_exist?.active_support` |
| | `exist_fragment?.action_controller` |
| | `render_template.action_view` |
| | `render_partial.action_view` |
| | `render_collection.action_view` |
| | `sql.active_record` |
| | `process.action_mailer` |
| | `service_upload.active_storage` |
| | `service_download.active_storage` |
| `active_job` | `enqueue_at.active_job` |
| | `enqueue.active_job` |
| | `enqueue_retry.active_job` |
| | `enqueue_all.active_job` |
| | `perform.active_job` |
| | `retry_stopped.active_job` |
| | `discard.active_job` |
| `sidekiq` | `perform.sidekiq` |
| | `enqueue.sidekiq` |
| | `stats.sidekiq` |
| `solid_queue` | `stats.solid_queue` |
| `karafka` | `consumer.consumed.karafka` |
| | `error.occurred.karafka` |
| | `statistics_emitted.karafka` |
| `net_http` | `request.net_http` |
| `autotuner` | `report.autotuner` |
| | `stats.autotuner` |
| `system` | `report.system` |
| `puma` | `stats.puma` |
To find these events, filter by `event_type::str` using any of the types above. Here’s an example BadgerQL query that you can use:
```plaintext
fields @ts, @preview
| filter event_type::str == "perform.sidekiq"
| sort @ts
```
### Customizing Insights for a specific plugin
[Section titled “Customizing Insights for a specific plugin”](#customizing-insights-for-a-specific-plugin)
When Insights is active, all plugins are enabled if the required library is present. For example, if Sidekiq is present in your app, the Sidekiq plugin will be loaded. You can disable automatic Insights instrumentation for a specific plugin by adding a configuration like this:
```yaml
sidekiq:
insights:
enabled: false
```
This will only affect Insights-related data capture and not the error notification portion of the plugin.
Some plugins allow for an easy way to choose if you want to capture events, metrics, or both for a particular plugin. The following configuration options are available:
```yaml
rails:
insights:
events: true
metrics: false
karafka:
insights:
events: true
metrics: false
sidekiq:
insights:
events: true
metrics: false
net_http:
insights:
events: true
metrics: false
solid_queue:
insights:
events: true
metrics: false
puma:
insights:
events: true
metrics: false
autotuner:
insights:
events: true
metrics: false
```
Event options are all true by default. It is recommened to turn off events for plugins that may be producing more data than you actually need. Metric data collection is false by default since most metrics can be calculated from events.
By default, the `net_http` plugin logs the domain name of any request as part of the event payload. You can enabling logging of the full URL by setting the following configuration:
```plaintext
net_http:
insights:
full_url: true
```
## Ignoring events
[Section titled “Ignoring events”](#ignoring-events)
For some applications, certain default events may be unecessary or excessively data heavy. To specify events to ignore, use the `events.ignore` configuration option. Here you can specify a list of event types for the gem to ignore. They can be either a string or a regex.
```yaml
events:
ignore:
- "enqueue.sidekiq"
- !ruby/regexp "/.*.active_storage/"
```
You may also ignore events based on event data by specifying a hash object.
```yaml
events:
ignore:
- event_type: "chatty_events"
custom_data: "ignore_me"
```
This will ignore events that have been created with the matching `event_type` and key(symbol)/value:
```ruby
Honeybadger.event('chatty_events', custom_data: 'ignore_me') # will not be sent to Insights
```
You can also use the `before_event` callback to inspect or modify event data, as well as calling `halt!` to prevent the event from being sent to Honeybadger:
config/initializers/honeybadger.rb
```ruby
Honeybadger.configure do |config|
config.before_event do |event|
# Ignore health check requests
if event.event_type == "process_action.action_controller" && event[:controller] == "Rails::HealthController"
event.halt!
end
# DB-backed job backends can generate a lot of useless queries
if event.event_type == "sql.active_record" && event[:query].match?(/good_job|solid_queue/)
event.halt!
end
end
end
```
`before_event` can be called multiple times to add multiple callbacks.
## Default ignored events
[Section titled “Default ignored events”](#default-ignored-events)
The gem comes configured to ignore a few events that can be chatty and not useful:
* `sql.active_record` events with queries that contain only “BEGIN” or “COMMIT”.
* `sql.active_record` events for database backed background processing gems (SolidQueue and GoodJob).
* `process_action.action_controller` events for `Rails::HealthController` actions.
## Sampling events
[Section titled “Sampling events”](#sampling-events)
If you find that you’d like to report fewer events in order to minimize your quota consumption, you can conditionally send a certain percentage of events:
config/honeybadger.yml
```yaml
insights:
sample_rate: 10
```
This will send 10% of events not associated with a request, and all events for 10% of requests.
## Manually sending events
[Section titled “Manually sending events”](#manually-sending-events)
You can also send events to Honeybadger using the `Honeybadger.event` method:
```ruby
Honeybadger.event('user_activity', {
action: 'registration',
user_id: 123
})
```
The first argument is the type of the event (`event_type`) and the second argument is an object containing any additional data you want to include.
`Honeybadger.event` can also be called with a single argument as an object containing the data for the event:
```ruby
Honeybadger.event({
event_type: 'user_activity',
action: 'registration',
user_id: 123
})
```
A timestamp field (`ts`) will be automatically added to the event data if it is not provided, regardless of the method used to send the event.
These events may be found using the following BadgerQL query:
```plaintext
fields @ts, @preview
| filter event_type::str == "user_activity"
| filter action::str == "registration"
| sort @ts
```
## Event context
[Section titled “Event context”](#event-context)
You can add custom metadata to the events sent to Honeybadger Insights by using the `Honeybadger.event_context` method. This metadata will be included in each event sent within the same thread.
Caution
This will add the metadata to all events sent, so be careful not to include too much data. Try to keep it to simple key/value pairs.
For example, you can add user ID information to all events (via a Rails controller):
```ruby
class ApplicationController < ActionController::Base
before_action :set_honeybadger_context
private
def set_honeybadger_context
if current_user
Honeybadger.event_context(user_id: current_user.id, user_email: current_user.email)
end
end
end
```
Event context is not automatically propagated to other threads. If you want to add context to events in a different thread, you can use the `Honeybadger.get_event_context` method to get the current context and pass it to the `Honeybadger.event` method:
```ruby
class MyJob < ApplicationJob
def perform(user_id)
# Get context from the main thread
context = Honeybadger.get_event_context
Thread.new do
# Set the context in the new thread
Honeybadger.event_context(context)
# Do some work here
Honeybadger.event("background_work", { user_id: user_id, status: "completed" })
end
end
end
```
### Block-scoped context
[Section titled “Block-scoped context”](#block-scoped-context)
You can also set event context for a specific block of code using a block form:
```ruby
Honeybadger.event_context(user_id: 123) do
# All events within this block will include the user_id context
Honeybadger.event("user_action", { action: "login" })
Honeybadger.event("user_action", { action: "logout" })
end
# Context is automatically cleared after the block
```
### Clearing event context
[Section titled “Clearing event context”](#clearing-event-context)
You can clear the current event context at any time:
```ruby
Honeybadger.event_context.clear!
```
## Metrics
[Section titled “Metrics”](#metrics)
The Honeybadger Ruby gem does more than just send events when they occur in your app. You can also enable metric collection. Check out [Collecting and Reporting Metrics](/lib/ruby/getting-started/collecting-and-reporting-metrics/) for more information.
## Sending Rails logs to Insights
[Section titled “Sending Rails logs to Insights”](#sending-rails-logs-to-insights)
If you are already using the Rails logger to track events in your application, you can send those events to Insights by [using a structured logging gem](/guides/insights/integrations/ruby-and-rails).
# Tagging errors
> Add tags to Ruby error reports to categorize and filter errors for better organization and analysis.
Each error in Honeybadger has tags. Tags can be used to filter results when searching and can even apply to integrations so that only errors with a combination of certain tags trigger an email or a Slack message, for example.
Tags can be used to create custom workflows, such as:
* Find all errors tagged “badgers” and resolve them.
* Tag critical errors as “critical” and configure PagerDuty to alert you only when a critical error happens.
* If you have errors which aren’t actionable (but you still want to know about them), you could tag them with “low\_priority” and exclude those errors when automatically creating issues via the GitHub integration.
* Tag all errors that happen in an area of your app with the name of the team that is responsible for them, then notify their Slack channel for only those errors.
These are just examples: you can use tags however you want!
While you can always add tags to existing errors through the Honeybadger UI, they are most useful when you add them programmatically as the exceptions happen. There are two ways to add tags to errors from your Ruby app:
## Tagging errors in global context
[Section titled “Tagging errors in global context”](#tagging-errors-in-global-context)
Every exception which is reported within the current context will have the tags “critical” and “badgers” added:
```ruby
Honeybadger.context({
tags: 'critical, badgers'
})
```
## Tagging errors in `Honeybadger.notify`
[Section titled “Tagging errors in Honeybadger.notify”](#tagging-errors-in-honeybadgernotify)
The tags will be added for just the current error being reported:
```ruby
Honeybadger.notify(exception,
tags: 'critical, badgers'
)
```
# Tests and Honeybadger
> Test Honeybadger's Ruby gem integration with your application using the included test backend.
It is possible to test Honeybadger’s integration with your application using the included test backend.
The test backend replaces the default server backend with a stub that records error notices rather than sending them, allowing all but the HTTP notification itself to be verified. Alternatively, you could use something like [WebMock](https://github.com/bblimke/webmock) to perform a similar test using the “server” backend.
## Configuring the test backend
[Section titled “Configuring the test backend”](#configuring-the-test-backend)
To use the test backend, set the `backend` configuration option to “test” in honeybadger.yml for your test environment only:
```yaml
api_key: "PROJECT_API_KEY"
test:
backend: test
```
You can also use the *HONEYBADGER\_BACKEND* environment variable to configure the test backend. Note that you must also configure your API key for the test to succeed.
## Writing the integration test
[Section titled “Writing the integration test”](#writing-the-integration-test)
The test backend can be used in any testing framework to test any code which reports an error with `Honeybadger.notify`. A common scenario is to test the Rails-integration which reports exceptions in a Rails controller automatically.
The following example uses RSpec to test error notification in a Rails controller.
First, create the controller:
app/controllers/honeybadger\_test\_controller.rb
```ruby
class HoneybadgerTestController < ApplicationController
ERROR = RuntimeError.new("testing reporting an error to Honeybadger")
def index
raise ERROR
end
end
```
Next, create a route. For security, it’s a good idea to enable the route only in the test environment:
config/routes.rb
```ruby
# ...
get '/test/honeybadger' => 'honeybadger_test#index' if Rails.env.test?
```
Finally, create the integration test:
spec/features/honeybadger\_spec.rb
```ruby
require 'rails_helper'
describe "error notification" do
it "notifies Honeybadger" do
expect {
# Code to test goes here:
expect { visit '/test/honeybadger' }.to raise_error(HoneybadgerTestController::ERROR)
# Important: `Honeybadger.flush` ensures that asynchronous notifications
# are delivered before the test's remaining expectations are verified.
Honeybadger.flush
}.to change(Honeybadger::Backend::Test.notifications[:notices], :size).by(1)
expect(Honeybadger::Backend::Test.notifications[:notices].first.error_message).to eq('testing reporting an error to Honeybadger')
end
end
```
# Tracking deployments
> Track deployments from Ruby applications to correlate errors with releases and identify problematic code changes.
Honeybadger has an API to keep track of project deployments. Whenever you deploy, all errors for that environment will be resolved automatically. You can choose to enable or disable the auto-resolve feature from your Honeybadger project settings page.
## Deploying with GitHub Actions
[Section titled “Deploying with GitHub Actions”](#deploying-with-github-actions)
If your CI/CD pipeline is hosted with GitHub Actions, you can use the [Honeybadger Deploy Action](https://github.com/marketplace/actions/honeybadger-deploy-action) to notify our API about deployments.
## Deployment tracking via command line
[Section titled “Deployment tracking via command line”](#deployment-tracking-via-command-line)
We provide a CLI command to send deployment notifications manually. Try the following command for the available options:
```sh
bundle exec honeybadger help deploy
```
Here’s an example of using the CLI to send a deployment notification:
```sh
bundle exec honeybadger deploy \
--repository https://github.com/myorganization/myrepo \
--revision $(cat REVISION) \
--environment production \
--user $(whoami)
```
## Heroku deployment tracking
[Section titled “Heroku deployment tracking”](#heroku-deployment-tracking)
Deploy tracking via Heroku is implemented using Heroku’s [app webhooks](https://devcenter.heroku.com/articles/app-webhooks). To set up the webhook, run the following CLI command from your project root:
```sh
bundle exec honeybadger heroku install_deploy_notification
```
If the honeybadger CLI command fails for whatever reason, you can add the deploy hook manually by running:
```sh
heroku webhooks:add -i api:release -l notify -u "https://api.honeybadger.io/v1/deploys/heroku?repository=git@github.com/username/projectname&environment=production&api_key=asdf" --app app-name
```
If you are using our EU stack, you should use `eu-api.honeybadger.io` instead of `api.honeybadger.io` in the webhook URL.
For more about manual use of Heroku deploy tracking, see the [Heroku Deployments](/guides/heroku/#heroku-deployment-tracking) guide.
You should replace the `repository`, `api_key`, and `app` options with your own values. You may also want to change the environment (set to production by default).
## Kamal deployment tracking
[Section titled “Kamal deployment tracking”](#kamal-deployment-tracking)
You can use Kamal’s post-deploy hook to send a deployment notification to Honeybadger. Add the following snippet to `.kamal/hooks/post-deploy`:
```bash
bundle exec honeybadger deploy \
--repository https://github.com/your_org/your_repo \
--revision $KAMAL_VERSION \
--environment production \
--user $KAMAL_PERFORMER
```
## Capistrano deployment tracking
[Section titled “Capistrano deployment tracking”](#capistrano-deployment-tracking)
In order to track deployments using Capistrano, simply require Honeybadger’s Capistrano task in your `Capfile` file:
```ruby
require "capistrano/honeybadger"
```
If you ran the `honeybadger install` command in a project that was previously configured with Capistrano, we already added this for you.
Adding options to your *config/deploy.rb* file allows you to customize how the deploy task is executed. The syntax for setting them looks like this:
```ruby
set :honeybadger_env, "preprod"
```
You can use any of the following options when configuring capistrano.
| Option | |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `honeybadger_user` | Honeybadger will report the name of the local user who is deploying (using `whoami` or equivalent). Use this option to to report a different user. |
| `honeybadger_env` | Honeybadger reports the environment supplied by capistrano by default. Use this option to change the reported environment. |
| `honeybadger_api_key` | Honeybadger uses your configured API key by default. Use this option to override. |
| `honeybadger_async_notify` | Run deploy notification task asynchronously using `nohup`. True or False. Defaults to false. |
| `honeybadger_server` | The api endpoint that receives the deployment notification. |
| `honeybadger` | The name of the honeybadger executable. Default: “honeybadger” |
| `honeybadger_skip_rails_load` | Skip loading the Rails environment during deploy notification. |
## Ruby deployment tracking
[Section titled “Ruby deployment tracking”](#ruby-deployment-tracking)
You can also track a deployment from the *honeybadger* Ruby gem with `Honeybadger.track_deployment`:
```ruby
Honeybadger.track_deployment(
environment: Rails.env,
revision: `git rev-parse HEAD`.strip,
local_username: `whoami`.strip,
repository: "git@github.com:user/example.git"
)
```
# Tracking Ruby errors on AWS Lambda
> Honeybadger monitors your Ruby AWS Lambda functions for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 1 minute
Hi there! You’ve found Honeybadger’s guide to **Ruby Exception and error tracking on AWS Lambda and Serverless**. Once installed, Honeybadger will report exceptions wherever they may happen.
If you’re new to Honeybadger, read our [Getting Started guide](/lib/ruby/) to become familiar with our Ruby gem. For a refresher on working with exceptions in Ruby, check out the [Honeybadger guide to Ruby exceptions](https://www.exceptionalcreatures.com/guides/what-are-ruby-exceptions/).
## Installation
[Section titled “Installation”](#installation)
The first step is to add the honeybadger gem to your Gemfile:
```ruby
gem 'honeybadger'
```
Tell bundler to install:
```bash
bundle install --deployment --without development,test
```
Depending on your deployment method, vendoring might be required to ensure your dependencies are included. We think the [serverless framework](https://serverless.com/framework/docs/providers/aws/examples/hello-world/ruby/) is a cool way to manage your lambda functions.
It may help to use a Ruby version manager (something like [asdf](https://github.com/asdf-vm/asdf-ruby) or [rvm](https://rvm.io/)) to ensure you are building against your selected lambda Ruby runtime. You can view a list of lambda runtime versions [here](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html).
You can configure Honeybadger in your Lambda by adding your API key via the `HONEYBADGER_API_KEY` environment variable.
## Capturing exceptions
[Section titled “Capturing exceptions”](#capturing-exceptions)
To automatically capture exceptions from your Lambda handler, register your handlers with the `hb_wrap_handler` method. Any unhandled exceptions raised within the specified methods will be automatically reported to Honeybadger.
```ruby
require 'honeybadger'
hb_wrap_handler :my_handler1, :my_handler2
def my_handler1(event:, context:)
# ...
end
def my_handler2(event:, context:)
# ...
end
```
For class methods, you’ll need to first extend our `LambdaExtensions` module:
```ruby
class MyLambdaApp
extend ::Honeybadger::Plugins::LambdaExtension
hb_wrap_handler :my_handler
def self.my_handler(event:, context:)
# ...
end
end
```
# Hanami integration guide
> Honeybadger monitors your Hanami applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 4 minutes
Hi there! You’ve found Honeybadger’s guide to **Hanami exception and error tracking**. Once installed, Honeybadger will automatically report exceptions wherever they may happen:
* During a web request
* In a background job
* In a Rake task
* When a process crashes (`at_exit`)
If you’re new to Honeybadger, read our [Getting Started guide](/lib/ruby/index.html) to become familiar with our Ruby gem. For a refresher on working with exceptions in Ruby, check out the [Honeybadger guide to Ruby exceptions](https://www.exceptionalcreatures.com/guides/what-are-ruby-exceptions.html).
## Installation
[Section titled “Installation”](#installation)
The first step is to add the honeybadger gem to your Gemfile:
```ruby
gem 'honeybadger'
```
Tell bundler to install:
```bash
bundle install
```
Next, you'll set the API key for this project.
```bash
bundle exec honeybadger install [Your project API key]
```
This will do three things:
1. Generate a `honeybadger.yml` file. If you don't like config files, you can place your API key in the `$HONEYBADGER_API_KEY` environment variable.
2. If Capistrano is installed, we'll add a require statement to *Capfile*.
3. Send a test exception to your Honeybadger project.
Finally, require the honeybadger gem in your `config.ru`, before you run your Hanami app.
config.ru
```ruby
require "hanami/boot"
require "honeybadger"
run Hanami.app
```
If you’re on a Hanami **v1** app, you’ll need to add the Rack middleware manually:
config.ru
```ruby
require './config/environment'
require 'honeybadger'
# These two are optional (explained below), but for them
# to work, they must be placed *before* the ErrorNotifier.
use Honeybadger::Rack::UserInformer
use Honeybadger::Rack::UserFeedback
use Honeybadger::Rack::ErrorNotifier
run Hanami.app
```
That’s it. Honeybadger will now automatically catch exceptions in your app.
## Identifying users
[Section titled “Identifying users”](#identifying-users)
If you’re using the *devise* or the *warden* gems for user authentication, then we already associate errors with the current user.
For other authentication systems (or to customize the user values), use `Honeybadger.context` to associate the current user:
```ruby
Honeybadger.context({
user_id: current_user.id,
user_email: current_user.email
})
```
## Collecting user feedback
[Section titled “Collecting user feedback”](#collecting-user-feedback)
The Honeybadger gem has a few special tags that it looks for whenever you render an error page in a Rack-based application. These can be used to display extra information about the error, or to ask the user for information about how they triggered the error. Honeybadger automatically installs the middleware for these in your Hanami project.
### Displaying the error ID
[Section titled “Displaying the error ID”](#displaying-the-error-id)
When an error is sent to Honeybadger, our API returns a unique UUID for the occurrence within your project. This UUID can be automatically displayed for reference on error pages.
To include the error id, simply place this magic HTML comment on your error page (normally `public/500.html` in Rails):
```html
```
By default, we will replace this tag with:
```plaintext
Honeybadger Error {{error_id}}
```
Where `{{error_id}}` is the UUID. You can customize this output by overriding the `user_informer.info` option in your honeybadger.yml file (you can also enabled/disable the middleware):
config/honeybadger.yml
```yaml
user_informer:
enabled: true
info: "Error ID: {{error_id}}"
```
You can use that UUID to load the error at the site by going to [https://app.honeybadger.io/notice/some-uuid-goes-here](https://app.honeybadger.io/notice/).
### Displaying a feedback form
[Section titled “Displaying a feedback form”](#displaying-a-feedback-form)
When an error is sent to Honeybadger, an HTML form can be generated so users can fill out relevant information that led up to that error. Feedback responses are displayed inline in the comments section on the fault detail page.
To include a user feedback form on your error page, simply add this magic HTML comment (normally `public/500.html` in Rails):
```html
```
You can change the text displayed in the form via the Rails internationalization system. Here’s an example:
config/locales/en.yml
```yaml
en:
honeybadger:
feedback:
heading: "Care to help us fix this?"
explanation:
"Any information you can provide will help us fix the problem."
submit: "Send"
thanks: "Thanks for the feedback!"
labels:
name: "Your name"
email: "Your email address"
comment: "Comment (required)"
```
The feedback form can be enabled and disabled using the `feedback.enabled` config option (defaults to `true`):
config/honeybadger.yml
```yaml
feedback:
enabled: true
```
# Heroku integration guide
> Honeybadger monitors your Heroku Ruby applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 1 minute
Hi there! You’ve found Honeybadger’s guide to **Ruby exception and error tracking on Heroku**. Once installed, Honeybadger will automatically report exceptions wherever they may happen:
* During a web request
* In a background job
* In a rake task
* When a process crashes (`at_exit`)
If you’re new to Honeybadger, read our [Getting Started guide](/lib/ruby/) to become familiar with our Ruby gem. For a refresher on working with exceptions in Ruby, check out the [Honeybadger guide to Ruby exceptions](https://www.exceptionalcreatures.com/guides/what-are-ruby-exceptions/).
## Installation
[Section titled “Installation”](#installation)
The first step is to add the honeybadger gem to your Gemfile:
```ruby
gem 'honeybadger'
```
Tell bundler to install:
```bash
bundle install
```
You can configure Honeybadger on your dynos like so:
*Note: This last step isn’t necessary if you’re using our [Heroku add-on](https://elements.heroku.com/addons/honeybadger), as it adds our API key to your Heroku config automatically.*
```bash
bundle exec honeybadger heroku install [YOUR API KEY HERE]
```
This will automatically add a `HONEYBADGER_API_KEY` environment variable to your remote Heroku config and configure deploy notifications.
### Tracking deployments
[Section titled “Tracking deployments”](#tracking-deployments)
To learn more about tracking deployments, see the [Tracking deployments](/lib/ruby/getting-started/tracking-deployments/) section of the [Getting Started guide](/lib/ruby/).
Deploy tracking via Heroku is implemented using Heroku’s [app webhooks](https://devcenter.heroku.com/articles/app-webhooks). If you ran the [Installation](#installation) command already, then you should already have deployment tracking installed. Otherwise, to install the addon and configure it for Honeybadger, run the following CLI command from your project root:
```sh
bundle exec honeybadger heroku install_deploy_notification
```
If the honeybadger CLI command fails for whatever reason, you can add the deploy hook manually by running:
```sh
heroku webhooks:add -i api:release -l notify -u "https://api.honeybadger.io/v1/deploys/heroku?repository=git@github.com/username/projectname&environment=production&api_key=asdf" --app app-name
```
You should replace the `repository`, `api_key`, and `app` options with your own values. You may also want to change the environment (set to production by default).
For more about manual use of Heroku deploy tracking, see the [Heroku Deployments](/guides/heroku/#heroku-deployment-tracking) guide.
# Rack integration guide
> Honeybadger monitors your Ruby/Rack applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 4 minutes
Hi there! You’ve found Honeybadger’s guide to **Rack exception and error tracking**. Once installed, Honeybadger will automatically report exceptions wherever they may happen:
* During a web request
* In a background job
* In a rake task
* When a process crashes (`at_exit`)
If you’re new to Honeybadger, read our [Getting Started guide](/lib/ruby/index.html) to become familiar with our Ruby gem. For a refresher on working with exceptions in Ruby, check out the [Honeybadger guide to Ruby exceptions](https://www.exceptionalcreatures.com/guides/what-are-ruby-exceptions.html).
## Installation
[Section titled “Installation”](#installation)
The first step is to add the honeybadger gem to your Gemfile:
```ruby
gem 'honeybadger'
```
Tell bundler to install:
```bash
bundle install
```
Next, you'll set the API key for this project.
```bash
bundle exec honeybadger install [Your project API key]
```
This will do three things:
1. Generate a `honeybadger.yml` file. If you don't like config files, you can place your API key in the `$HONEYBADGER_API_KEY` environment variable.
2. If Capistrano is installed, we'll add a require statement to *Capfile*.
3. Send a test exception to your Honeybadger project.
Now it’s time to set up your Rack app. Start by requiring the *honeybadger* gem **after** any other gems you’re using:
```ruby
require 'rack'
# ...
require 'honeybadger'
```
Then add the middleware to your app. Make sure Honeybadger’s middleware is the first middleware you define so that it can catch exceptions in your other middleware:
```ruby
use Honeybadger::Rack::ErrorNotifier
# ...
```
### Example app
[Section titled “Example app”](#example-app)
```ruby
require 'rack'
# Load the gem
require 'honeybadger'
# Write your app
app = Rack::Builder.app do
run lambda { |env| raise "Rack down" }
end
# These middleware are optional, but for them to work,
# they must be placed *before* the ErrorNotifier middleware
use Honeybadger::Rack::UserFeedback
use Honeybadger::Rack::UserInformer
# Use Honeybadger's Rack middleware
use Honeybadger::Rack::ErrorNotifier
# Use your other middleware here
run app
```
## Identifying users
[Section titled “Identifying users”](#identifying-users)
If you’re using the *devise* or the *warden* gems for user authentication, then we already associate errors with the current user.
For other authentication systems (or to customize the user values), use `Honeybadger.context` to associate the current user:
```ruby
Honeybadger.context({
user_id: current_user.id,
user_email: current_user.email
})
```
## Collecting user feedback
[Section titled “Collecting user feedback”](#collecting-user-feedback)
The Honeybadger gem has a few special tags that it looks for whenever you render an error page in a Rack-based application. These can be used to display extra information about the error, or to ask the user for information about how they triggered the error. You can enable them by adding the middleware to your application:
```ruby
use Honeybadger::Rack::UserInformer
use Honeybadger::Rack::UserFeedback
# ^^^ These middleware must be placed *before* the ErrorNotifier
use Honeybadger::Rack::ErrorNotifier
```
### Displaying the error ID
[Section titled “Displaying the error ID”](#displaying-the-error-id)
When an error is sent to Honeybadger, our API returns a unique UUID for the occurrence within your project. This UUID can be automatically displayed for reference on error pages.
To include the error id, simply place this magic HTML comment on your error page (normally `public/500.html` in Rails):
```html
```
By default, we will replace this tag with:
```plaintext
Honeybadger Error {{error_id}}
```
Where `{{error_id}}` is the UUID. You can customize this output by overriding the `user_informer.info` option in your honeybadger.yml file (you can also enabled/disable the middleware):
config/honeybadger.yml
```yaml
user_informer:
enabled: true
info: "Error ID: {{error_id}}"
```
You can use that UUID to load the error at the site by going to [https://app.honeybadger.io/notice/some-uuid-goes-here](https://app.honeybadger.io/notice/).
### Displaying a feedback form
[Section titled “Displaying a feedback form”](#displaying-a-feedback-form)
When an error is sent to Honeybadger, an HTML form can be generated so users can fill out relevant information that led up to that error. Feedback responses are displayed inline in the comments section on the fault detail page.
To include a user feedback form on your error page, simply add this magic HTML comment (normally `public/500.html` in Rails):
```html
```
You can change the text displayed in the form via the Rails internationalization system. Here’s an example:
config/locales/en.yml
```yaml
en:
honeybadger:
feedback:
heading: "Care to help us fix this?"
explanation:
"Any information you can provide will help us fix the problem."
submit: "Send"
thanks: "Thanks for the feedback!"
labels:
name: "Your name"
email: "Your email address"
comment: "Comment (required)"
```
The feedback form can be enabled and disabled using the `feedback.enabled` config option (defaults to `true`):
config/honeybadger.yml
```yaml
feedback:
enabled: true
```
# Rails integration guide
> Honeybadger monitors your Ruby on Rails 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 **Ruby on Rails exception and error tracking**. Once installed, Honeybadger will automatically report exceptions wherever they may happen:
* During a web request
* In a background job
* In a rake task
* When a process crashes (`at_exit`)
If you’re new to Honeybadger, read our [Getting Started guide](/lib/ruby/index.html) to become familiar with our Ruby gem. For a refresher on working with exceptions in Ruby, check out the [Honeybadger guide to Ruby exceptions](https://www.exceptionalcreatures.com/guides/what-are-ruby-exceptions.html).
## Installation
[Section titled “Installation”](#installation)
[](https://honeybadger.wistia.com/medias/l3cmyucx8f)
The first step is to add the honeybadger gem to your Gemfile:
```ruby
gem 'honeybadger'
```
Tell bundler to install:
```bash
bundle install
```
Next, you'll set the API key for this project.
```bash
bundle exec honeybadger install [Your project API key]
```
This will do three things:
1. Generate a `config/honeybadger.yml` file. If you don't like config files, you can place your API key in the `$HONEYBADGER_API_KEY` environment variable.
2. If Capistrano is installed, we'll add a require statement to *Capfile*.
3. Send a test exception to your Honeybadger project.
Assuming the test completed successfully: **you’re done!**
## Identifying users
[Section titled “Identifying users”](#identifying-users)
If you’re using the *devise* or the *warden* gems for user authentication, then we already associate errors with the current user.
For other authentication systems (or to customize the user values), add the following `before_action` to your `ApplicationController`:
```ruby
before_action do
Honeybadger.context({
user_id: current_user.id,
user_email: current_user.email
})
end
```
## Collecting user feedback
[Section titled “Collecting user feedback”](#collecting-user-feedback)
The Honeybadger gem has a few special tags that it looks for whenever you render an error page. These can be used to display extra information about the error, or to ask the user for information about how they triggered the error.
### Displaying the error ID
[Section titled “Displaying the error ID”](#displaying-the-error-id)
When an error is sent to Honeybadger, our API returns a unique UUID for the occurrence within your project. This UUID can be automatically displayed for reference on error pages.
To include the error id, simply place this magic HTML comment on your error page (normally `public/500.html` in Rails):
```html
```
By default, we will replace this tag with:
```plaintext
Honeybadger Error {{error_id}}
```
Where `{{error_id}}` is the UUID. You can customize this output by overriding the `user_informer.info` option in your honeybadger.yml file (you can also enabled/disable the middleware):
config/honeybadger.yml
```yaml
user_informer:
enabled: true
info: "Error ID: {{error_id}}"
```
You can use that UUID to load the error at the site by going to [https://app.honeybadger.io/notice/some-uuid-goes-here](https://app.honeybadger.io/notice/).
### Displaying a feedback form
[Section titled “Displaying a feedback form”](#displaying-a-feedback-form)
When an error is sent to Honeybadger, an HTML form can be generated so users can fill out relevant information that led up to that error. Feedback responses are displayed inline in the comments section on the fault detail page.
To include a user feedback form on your error page, simply add this magic HTML comment (normally `public/500.html` in Rails):
```html
```
You can change the text displayed in the form via the Rails internationalization system. Here’s an example:
config/locales/en.yml
```yaml
en:
honeybadger:
feedback:
heading: "Care to help us fix this?"
explanation:
"Any information you can provide will help us fix the problem."
submit: "Send"
thanks: "Thanks for the feedback!"
labels:
name: "Your name"
email: "Your email address"
comment: "Comment (required)"
```
The feedback form can be enabled and disabled using the `feedback.enabled` config option (defaults to `true`):
config/honeybadger.yml
```yaml
feedback:
enabled: true
```
## The Rails error reporter
[Section titled “The Rails error reporter”](#the-rails-error-reporter)
On Rails 7 and above, Honeybadger supports the new [error reporter](https://guides.rubyonrails.org/error_reporting.html) included in Rails. This means you can use `Rails.error.handle` as described in the Rails docs, and errors will be reported as normal, in line with your Honeybadger configuration. `Rails.error.record` is, however, not supported, since the Honeybadger native error handlers for each integration provide much richer context for your errors than Rails’ default.
On Rails 7.1 and above, each error report can include a `source` parameter. You can use the Honeybadger config option `rails.subscriber_ignore_sources` to automatically ignore errors from certain sources:
```ruby
Honeybadger.configure do |config|
config.rails.subscriber_ignore_sources += [/some_source/]
end
```
## Content Security Policy reports
[Section titled “Content Security Policy reports”](#content-security-policy-reports)
You can use [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers to help mitigate XSS attacks, and Rails has a [DSL](https://guides.rubyonrails.org/security.html#content-security-policy) that you can use to configure those headers in your application. When a policy includes a `report-uri` or `report-to` directive, reports about blocked resources can be sent to a URL:
```ruby
Rails.application.config.content_security_policy do |policy|
policy.default_src :self, :https
...
policy.report_uri -> { "https://api.honeybadger.io/v1/browser/csp?api_key=HB_API_KEY_GOES_HERE&report_only=true&env=#{Rails.env}&context[user_id]=#{respond_to?(:current_user) ? current_user&.id : nil}" }
end
```
Every parameter in the URL is optional, aside from the `api_key` parameter. If you don’t need the value to be generated at request time (as in this example, to report the current user’s id), then you can provide a simple string as the argument to `report_uri`. If you set the `report_only` parameter to true, then our UI will label reports as “CSP Report”; otherwise, they will be labeled as “CSP Error”.
CSP Reports and Errors show up with the rest of your app’s errors in the Honeybadger UI. For this reason, and since CSP reports can be very numerous, we recommend you create a separate Honeybadger project specifically for CSP reports.
## If you use `config.exceptions_app`
[Section titled “If you use config.exceptions\_app”](#if-you-use-configexceptions_app)
If you use [the `config.exceptions_app` Rails setting](https://guides.rubyonrails.org/configuring.html#rails-general-configuration) to display a custom error page, you may need some extra config for the correct controller and action name to be displayed in Honeybadger. The following snippet assumes that the name of your custom controller is “errors” (e.g. `ErrorsController`):
```ruby
Honeybadger.configure do |config|
config.before_notify do |notice|
# Change "errors" to match your custom controller name.
break if notice.component != "errors"
# Look up original route path and override controller/action
# in Honeybadger.
params = Rails.application.routes.recognize_path(notice.url)
notice.component = params[:controller]
notice.action = params[:action]
end
end
```
## JavaScript source maps with esbuild and Sprockets
[Section titled “JavaScript source maps with esbuild and Sprockets”](#javascript-source-maps-with-esbuild-and-sprockets)
If you’re using esbuild with Sprockets, you can generate source maps for your JavaScript assets and upload them to Honeybadger. This will allow Honeybadger to display the original source code for your minified JavaScript files. Here’s a [Rake Task](https://railsinspire.com/samples/18) that uploads source maps to Honeybadger via the `assets:precompile` step.
# Ruby integration guide
> Honeybadger monitors your Ruby applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 3 minutes
Hi there! You’ve found Honeybadger’s guide to **Ruby exception and error tracking**. Once installed, Honeybadger will automatically report exceptions wherever they may happen:
* During a web request
* In a background job
* In a rake task
* When a process crashes (`at_exit`)
If you’re new to Honeybadger, read our [Getting Started guide](/lib/ruby/) to become familiar with our Ruby gem. For a refresher on working with exceptions in Ruby, check out the [Honeybadger guide to Ruby exceptions](https://www.exceptionalcreatures.com/guides/what-are-ruby-exceptions.html).
## Installation
[Section titled “Installation”](#installation)
The first step is to add the honeybadger gem to your Gemfile:
```ruby
gem 'honeybadger'
```
Tell bundler to install:
```bash
bundle install
```
Next, you'll set the API key for this project.
```bash
bundle exec honeybadger install [Your project API key]
```
This will do three things:
1. Generate a `honeybadger.yml` file. If you don't like config files, you can place your API key in the `$HONEYBADGER_API_KEY` environment variable.
2. If Capistrano is installed, we'll add a require statement to *Capfile*.
3. Send a test exception to your Honeybadger project.
Next, require the *honeybadger* gem **after** any other gems you’re using:
```ruby
# ...
require 'honeybadger'
```
Honeybadger will detect any supported 3rd-party gems you’re using such as Sidekiq, Rake, etc. and integrate with them automatically.
To notify Honeybadger of an exception you’ve rescued, use `Honeybadger.notify`:
```ruby
begin
fail 'oops'
rescue => exception
Honeybadger.notify(exception)
end
```
For additional ways to use `Honeybadger.notify`, check out the [Reporting errors](/lib/ruby/getting-started/reporting-errors/) chapter of our [Getting started guide](/lib/ruby/).
For Rack-based web applications, see the [Rack integration guide](/lib/ruby/integration-guides/rack-exception-tracking/) for instructions on how to automatically report exceptions in web requests.
# Sinatra integration guide
> Honeybadger monitors your Sinatra applications for errors and exceptions so that you can fix them wicked fast.
**Typical installation time:** 3 minutes
Hi there! You’ve found Honeybadger’s guide to **Sinatra exception and error tracking**. Once installed, Honeybadger will automatically report exceptions wherever they may happen:
* During a web request
* In a background job
* In a Rake task
* When a process crashes (`at_exit`)
If you’re new to Honeybadger, read our [Getting Started guide](/lib/ruby/index.html) to become familiar with our Ruby gem. For a refresher on working with exceptions in Ruby, check out the [Honeybadger guide to Ruby exceptions](https://www.exceptionalcreatures.com/guides/what-are-ruby-exceptions.html).
## Installation
[Section titled “Installation”](#installation)
[](https://honeybadger.wistia.com/medias/b2wr5n9fcv)
The first step is to add the honeybadger gem to your Gemfile:
```ruby
gem 'honeybadger'
```
Tell bundler to install:
```bash
bundle install
```
Next, you'll set the API key for this project.
```bash
bundle exec honeybadger install [Your project API key]
```
This will do three things:
1. Generate a `honeybadger.yml` file. If you don't like config files, you can place your API key in the `$HONEYBADGER_API_KEY` environment variable.
2. If Capistrano is installed, we'll add a require statement to *Capfile*.
3. Send a test exception to your Honeybadger project.
Finally, require the honeybadger gem in your app *after* requiring the sinatra gem:
```ruby
# Always require Sinatra first.
require 'sinatra'
# Then require honeybadger.
require 'honeybadger'
# Define your application code *after* Sinatra *and* honeybadger:
get '/' do
raise "Sinatra has left the building"
end
```
## Identifying users
[Section titled “Identifying users”](#identifying-users)
If you’re using the *devise* or the *warden* gems for user authentication, then we already associate errors with the current user.
For other authentication systems (or to customize the user values), use `Honeybadger.context` to associate the current user:
```ruby
Honeybadger.context({
user_id: current_user.id,
user_email: current_user.email
})
```
## Collecting user feedback
[Section titled “Collecting user feedback”](#collecting-user-feedback)
The Honeybadger gem has a few special tags that it looks for whenever you render an error page in a Rack-based application. These can be used to display extra information about the error, or to ask the user for information about how they triggered the error. Honeybadger automatically installs the middleware for these in your Sinatra project.
### Displaying the error ID
[Section titled “Displaying the error ID”](#displaying-the-error-id)
When an error is sent to Honeybadger, our API returns a unique UUID for the occurrence within your project. This UUID can be automatically displayed for reference on error pages.
To include the error id, simply place this magic HTML comment on your error page (normally `public/500.html` in Rails):
```html
```
By default, we will replace this tag with:
```plaintext
Honeybadger Error {{error_id}}
```
Where `{{error_id}}` is the UUID. You can customize this output by overriding the `user_informer.info` option in your honeybadger.yml file (you can also enabled/disable the middleware):
config/honeybadger.yml
```yaml
user_informer:
enabled: true
info: "Error ID: {{error_id}}"
```
You can use that UUID to load the error at the site by going to [https://app.honeybadger.io/notice/some-uuid-goes-here](https://app.honeybadger.io/notice/).
### Displaying a feedback form
[Section titled “Displaying a feedback form”](#displaying-a-feedback-form)
When an error is sent to Honeybadger, an HTML form can be generated so users can fill out relevant information that led up to that error. Feedback responses are displayed inline in the comments section on the fault detail page.
To include a user feedback form on your error page, simply add this magic HTML comment (normally `public/500.html` in Rails):
```html
```
You can change the text displayed in the form via the Rails internationalization system. Here’s an example:
config/locales/en.yml
```yaml
en:
honeybadger:
feedback:
heading: "Care to help us fix this?"
explanation:
"Any information you can provide will help us fix the problem."
submit: "Send"
thanks: "Thanks for the feedback!"
labels:
name: "Your name"
email: "Your email address"
comment: "Comment (required)"
```
The feedback form can be enabled and disabled using the `feedback.enabled` config option (defaults to `true`):
config/honeybadger.yml
```yaml
feedback:
enabled: true
```
## Content Security Policy reports
[Section titled “Content Security Policy reports”](#content-security-policy-reports)
You can use [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers to help mitigate XSS attacks, and the [SecureHeaders](https://rubygems.org/gems/secure_headers) gem makes it easy to emit those headers from your Sinatra application. When a policy includes a `report-uri` or `report-to` directive, reports about blocked resources can be sent to a URL:
```ruby
require 'rubygems'
require 'sinatra'
require 'secure_headers'
use SecureHeaders::Middleware
SecureHeaders::Configuration.default do |config|
...
report_uri: "https://api.honeybadger.io/v1/browser/csp?api_key=HB_API_KEY_GOES_HERE&report_only=true&env=#{ENV['RACK_ENV']}"
end
```
Every parameter in the URL is optional, aside from the `api_key` parameter. If you don’t need the value to be generated at request time (as in this example, to report the current user’s id), then you can provide a simple string as the argument to `report_uri`. If you set the `report_only` parameter to true, then our UI will label reports as “CSP Report”; otherwise, they will be labeled as “CSP Error”.
CSP Reports and Errors show up with the rest of your app’s errors in the Honeybadger UI. For this reason, and since CSP reports can be very numerous, we recommend you create a separate Honeybadger project specifically for CSP reports.
# Architecture deep-dive
> Learn about Honeybadger's Ruby gem architecture, threading model, and how error reporting works internally.
This guide explains the architecture of the [*honeybadger* Ruby gem](https://github.com/honeybadger-io/honeybadger-ruby), and how it interacts with your application.
## Who is this guide for?
[Section titled “Who is this guide for?”](#who-is-this-guide-for)
This guide is for anyone interested in learning about how our gem works internally or is attempting to debug/rule out a gem-related issue.
## The major components of the gem
[Section titled “The major components of the gem”](#the-major-components-of-the-gem)
The `honeybadger` gem has the following components:
* `Notice` — Represents a single exception/error report
* `Backend` — Responsible for reporting a `Notice` to the honeybadger.io API
* `Queue` — A first-in-first-out (FIFO) queue which drops items after reaching a maximum size
* `Worker` — A single-threaded worker that is responsible for processing `Notice` items in the `Queue` and notifying the `Backend`
* `Initializer` — An integration with a detected framework (such as Rails)
* `Plugin` — An isolated integration with a Ruby or 3rd party gem feature
* `Config` — The user [configuration](/lib/ruby/gem-reference/configuration/) for the gem
* `Agent` — An instance of the gem composed of a `Config` and a `Worker` (multiple `Agents` are supported, but are uncommon)
* `Honeybadger` — The global singleton `Agent`
## What happens when your app boots
[Section titled “What happens when your app boots”](#what-happens-when-your-app-boots)
The gem has two modes of booting:
1. **Normal mode**: loads `Initializers`, `Config`, and `Plugins` automatically (this is what we’ll be discussing here)
2. [Plain Ruby Mode](/lib/ruby/getting-started/plain-ruby-mode/): Skips automatically loading `Initializers`, `Config`, and `Plugins`
If your app is configured to `require 'honeybadger'` (the default when you install our gem), then it boots in **Normal Mode**. Here is the order of events in a Rails app:
1. When `'honeybadger'` is required, we immediately:
2. Detect your framework (Rails, Sinatra, etc.) and load the respective `Initializer`
3. Load our Rake `Initializer` if Rake is present in your application
4. Install our global `at_exit` handler
5. As Rails initializes, our Rack middleware are inserted in the Rails middleware stack via the `honeybadger.install_middleware` initializer (see our [Railtie](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/lib/honeybadger/init/rails.rb))
6. Rails finishes initializing
7. Honeybadger reads `Config` from supported sources
8. Honeybadger loads `Plugins`
9. Rails finishes booting
## The life cycle of an exception
[Section titled “The life cycle of an exception”](#the-life-cycle-of-an-exception)
The *honeybadger* gem integrates with popular frameworks and libraries to automatically report exceptions when they occur. Examples of where this can happen:
* Rails and Sinatra requests
* Background jobs (ActiveJob, Sidekiq, Resque, etc.)
* Rake tasks
* Ruby crashes (via our global `at_exit` handler)
Here is the order of events when an unhandled exception occurs in one of these scenarios:
1. The exception is reported to the global singleton `Agent` using [`Honeybadger.notify`](https://www.rubydoc.info/gems/honeybadger/Honeybadger/Agent#notify-instance_method)
2. A `Notice` is built from the exception and any other data passed to `Honeybadger.notify`, `Honeybadger.context`, `Honeybadger.add_breadcrumb`, etc.
3. Configured [`before_notify` callbacks](/lib/ruby/gem-reference/configuration/#changing-notice-data) are executed, passing the `Notice` to each callback (which may modify it)
4. If the `Notice` is ignored via `Config`, `before_notify` callbacks, etc., then it’s immediately dropped. Otherwise, it’s pushed to the `Worker`.
5. The `Worker` processes each `Notice` in the order that it was added to its `Queue`. The `Queue` holds up to 100 `Notices` by default (this number is configurable via the [`max_queue_size` option](/lib/ruby/gem-reference/configuration/#configuration-options)). If the number of `Notices` in the `Queue` equals the `max_queue_size`, new `Notices` are dropped until the number is reduced.
6. When the `Worker` processes a notice, it removes it from the `Queue`, passes it to the `Backend`, and waits for a response from the honeybadger.io API:
1. `429`, `503` (throttled): Applies an exponential throttle of `1.05`. When a throttle is added, the `Worker` will briefly pause between processing each `Notice` in the `Queue`. Additional throttles are added until the server stops throttling the client. Each new throttle multiplies the previous throttle by `1.05`; for example, three `429` responses would result in a \~0.158-second pause (`((1.05*1.05*1.05)-1)`—we subtract 1 to account for the initial throttle).
2. `402`, `403` (payment required/invalid API key): Suspends the `Worker` for 1 hour. During this time, all `Notices` are dropped.
3. `201` (success): if throttled, one throttle per `201` response is removed until the `Worker` is back to processing the `Queue` in real-time.
## What happens when your app shuts down
[Section titled “What happens when your app shuts down”](#what-happens-when-your-app-shuts-down)
Honeybadger performs the following via our global `at_exit` handler:
1. If there is an exception that is crashing the Ruby process, it’s reported to `Honeybadger.notify`, which calls the backend synchronously (it skips the `Worker`)
2. The `Worker` shuts down. By default, it will wait to process remaining exceptions in the `Queue`. [See `send_data_at_exit` and `max_queue_size`](/lib/ruby/gem-reference/configuration/#configuration-options)
# Frequently asked questions
> Find answers to frequently asked questions about Honeybadger's Ruby gem for error tracking and application monitoring.
## Why aren’t my errors being reported?
[Section titled “Why aren’t my errors being reported?”](#why-arent-my-errors-being-reported)
The most common reason for errors not being reported is that the gem is in a development environment. See the [Environments](/lib/ruby/getting-started/environments/#development-environments) chapter in the **Getting Started** guide for more information.
The second most common reason is that the error being reported is on the [default ignored exceptions list](/lib/ruby/getting-started/ignoring-errors/#ignore-by-class).
We also don’t capture errors in a Ruby console (IRB, pry, etc..) by default, even in production.
If neither of these is the issue, check out the [Troubleshooting guide](/lib/ruby/support/troubleshooting/#my-errors-arent-being-reported).
## Why aren’t I getting notifications?
[Section titled “Why aren’t I getting notifications?”](#why-arent-i-getting-notifications)
By default we only send notifications the first time an exception happens, and when it re-occurs after being marked resolved. If an exception happens 100 times, but was never resolved you’ll only get 1 email about it.
## Can I use Honeybadger outside of Rails, such as in my gem?
[Section titled “Can I use Honeybadger outside of Rails, such as in my gem?”](#can-i-use-honeybadger-outside-of-rails-such-as-in-my-gem)
Yes! All our gem needs to report errors is a supported Ruby version; there are no other hard dependencies. We detect and integrate with optional dependencies such as Rails by default, but if you want complete control of the initialization process you can use [Plain Ruby Mode](/lib/ruby/getting-started/plain-ruby-mode/).
See the [API Reference](https://www.rubydoc.info/gems/honeybadger/Honeybadger/Agent) for all the methods you can use to report errors from anywhere in Ruby.
## After enabling Insights, I see a lot of extra console output during my builds. How can I silence this?
[Section titled “After enabling Insights, I see a lot of extra console output during my builds. How can I silence this?”](#after-enabling-insights-i-see-a-lot-of-extra-console-output-during-my-builds-how-can-i-silence-this)
If you enabled Insights via your `config/honeybadger.yml` file, you may see extra output in your console during builds (such as asset compile in Docker). This is because the Honeybadger Insights agent is running as configured. You can temporarily disable Insights during your builds by setting the `HONEYBADGER_INSIGHTS_ENABLED` environment variable to `false`.
```bash
HONEYBADGER_INSIGHTS_ENABLED=false bundle exec rake assets:precompile
```
Alternatively, instead of configuring Insights in your `config/honeybadger.yml` file, you can enable it via the `HONEYBADGER_INSIGHTS_ENABLED` environment variable in your proudction environment. This way, Insights will only be enabled in production.
# Troubleshooting
> Troubleshoot common issues with Honeybadger's Ruby gem and resolve integration problems.
Common issues/workarounds are documented here. If you don’t find a solution to your problem here or in our [support documentation](../../#getting-support), email and we’ll assist you!
## Upgrade the gem
[Section titled “Upgrade the gem”](#upgrade-the-gem)
Before digging deeper into this guide, **make sure you are on the latest minor release of the honeybadger gem** (i.e. 3.x.x). There’s a chance you’ve found a bug which has already been fixed!
## Send a test exception
[Section titled “Send a test exception”](#send-a-test-exception)
You can send a test exception using the `honeybadger` command line utility:
```bash
honeybadger test
```
## How to enable verbose logging
[Section titled “How to enable verbose logging”](#how-to-enable-verbose-logging)
Troubleshooting any of these issues will be much easier if you can see what’s going on with Honeybadger when your app starts. To enable verbose debug logging, run your app with the `HONEYBADGER_DEBUG=true` environment variable or add the following to your *honeybadger.yml* file:
```yaml
debug: true
```
By default Honeybadger will log to the default Rails logger or STDOUT outside of Rails. When debugging it can be helpful to have a dedicated log file for Honeybadger. To enable one, set the `HONEYBADGER_LOGGING_PATH=log/honeybadger.log` environment variable or add the following to your *honeybadger.yml* file:
```yaml
logging:
path: "log/honeybadger.log"
```
## Common issues
[Section titled “Common issues”](#common-issues)
### My errors aren’t being reported
[Section titled “My errors aren’t being reported”](#my-errors-arent-being-reported)
Error reporting may be disabled for several reasons:
#### Honeybadger is not configured
[Section titled “Honeybadger is not configured”](#honeybadger-is-not-configured)
Honeybadger requires at minimum the `api_key` option to be set. If Honeybadger is unable to start due to invalid configuration, you should see something like the following in your logs:
```plaintext
** [Honeybadger] Unable to start Honeybadger -- api_key is missing or invalid. level=2 pid=18195
```
#### Honeybadger is in a development environment
[Section titled “Honeybadger is in a development environment”](#honeybadger-is-in-a-development-environment)
Errors are ignored by default in the “test”, “development”, and “cucumber” environments. To explicitly enable Honeybadger in a development environment, set the `HONEYBADGER_REPORT_DATA=true` environment variable or add the following configuration to *honeybadger.yml* file (change “development” to the name of the environment you want to enable):
```yaml
development:
report_data: true
```
#### The error is ignored by default
[Section titled “The error is ignored by default”](#the-error-is-ignored-by-default)
Honeybadger ignores [this list of exceptions](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/lib/honeybadger/config/defaults.rb#L7) by default.
#### The error was rescued without re-raising
[Section titled “The error was rescued without re-raising”](#the-error-was-rescued-without-re-raising)
Honeybadger will automatically report exceptions in many frameworks including Rails, Sinatra, Sidekiq, Rake, etc. For exceptions to reported automatically they must be raised; check for any `rescue` statements in your app where exceptions may be potentially silenced. In Rails, this includes any use of `rescue_from` which does not re-raise the exception.
Errors which are handled in a `rescue` block without re-raising must be reported to Honeybadger manually:
```ruby
begin
fail 'This error will be handled internally.'
rescue => e
Honeybadger.notify(e)
end
```
#### The configuration is being overridden
[Section titled “The configuration is being overridden”](#the-configuration-is-being-overridden)
Check to make sure that you aren’t overriding the *honeybadger.yml* configuration file via Ruby configuration using `Honeybadger.configure`, or using an environment variable (`HONEYBADGER_API_KEY`, for instance).
For example, the Honeybadger Heroku addon sets the `HONEYBADGER_API_KEY` config option automatically, so you must remove the addon (or the config option) if you switch to a Honeybadger project with a different API key.
#### A rake task is running in a local terminal
[Section titled “A rake task is running in a local terminal”](#a-rake-task-is-running-in-a-local-terminal)
By default, the Honeybadger rake integration reports errors that happen when running *outside* of a terminal, such as in a cron job or scheduled task. The integration does *not* report errors which happen when running rake manually from a terminal (i.e., if you SSH into a production server to run the task).
[To report exceptions all the time, set the `exceptions.rescue_rake` config option to `true`](/lib/ruby/gem-reference/configuration/#configuration-options).
#### The `better_errors` gem is installed
[Section titled “The better\_errors gem is installed”](#the-better_errors-gem-is-installed)
The [`better_errors` gem](https://github.com/charliesome/better_errors) conflicts with the Honeybadger gem when in development mode. To be able to report errors from development you must first temporarily disable/remove the `better_errors` gem. Better Errors should not affect production because it should never be enabled in production.
### I’m not receiving notifications
[Section titled “I’m not receiving notifications”](#im-not-receiving-notifications)
Likewise, if the error is reported but your aren’t being notified:
#### The error was reported already and is unresolved
[Section titled “The error was reported already and is unresolved”](#the-error-was-reported-already-and-is-unresolved)
By default we only send notifications the first time an exception happens, and when it re-occurs after being marked resolved. If an exception happens 100 times, but was never resolved you’ll only get 1 email about it.
### `SignalException` or `SystemExit` is reported when a process or rake task exits
[Section titled “SignalException or SystemExit is reported when a process or rake task exits”](#signalexception-or-systemexit-is-reported-when-a-process-or-rake-task-exits)
The Honeybadger gem currently [ignores signal exceptions](https://github.com/honeybadger-io/honeybadger-ruby/blob/v4.2.1/lib/honeybadger/singleton.rb#L91) in our `at_exit` callback, which is installed by default whenever Honeybadger is loaded. We do not ignore these exceptions anywhere else, such as in Rake tasks. If you would like to ignore them globally, you can add the following configuration to `honeybadger.yml`:
```yaml
exceptions:
ignore:
- !ruby/class "SystemExit"
- !ruby/class "SignalException"
```
* Related: [#306](https://github.com/honeybadger-io/honeybadger-ruby/issues/306)
## Sidekiq/Resque/ActiveJob/etc.
[Section titled “Sidekiq/Resque/ActiveJob/etc.”](#sidekiqresqueactivejobetc)
* See [Common Issues](#common-issues)
### If the error is ignored by default
[Section titled “If the error is ignored by default”](#if-the-error-is-ignored-by-default)
Honeybadger ignores [this list of exceptions](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/lib/honeybadger/config/defaults.rb#L7) by default. It may be surprising that `ActiveRecord::RecordNotFound` is on that list; that’s because in a Rails controller that error class is treated as a 404 not-found and handled internally (and thus we shouldn’t report it). Support for Sidekiq and friends was added later and inherited the default. We would like to provide alternate defaults for job processors in the future, but for now you can provide your own list of ignored class names if you want to change this behavior:
```plaintext
HONEYBADGER_EXCEPTIONS_IGNORE_ONLY=Error,ClassNames,Here bundle exec sidekiq
```
## Command line utility
[Section titled “Command line utility”](#command-line-utility)
If you get an error while running the `honeybadger` command line utility:
1. Try prefixing the command with `bundle exec`…even if you normally rely on bin-stubs to do this for you
2. Check `honeybadger help` if you’re having trouble with the syntax for a specific command.
3. Try enabling [verbose logging](#how-to-enable-verbose-logging) to get more info
4. Ask Us! We’re always here to help. Just copy the terminal output and email it to us at
## Wrong controller/action name is reported in Rails
[Section titled “Wrong controller/action name is reported in Rails”](#wrong-controlleraction-name-is-reported-in-rails)
If you’re using `config.exceptions_app`, you may need some extra config to report the correct controller and action to Honeybadger. See the [Rails integration guide](/lib/ruby/integration-guides/rails-exception-tracking/#if-you-use-configexceptions_app).
* Related: [#250](https://github.com/honeybadger-io/honeybadger-ruby/issues/250#issuecomment-379780492)
## My issue isn’t here
[Section titled “My issue isn’t here”](#my-issue-isnt-here)
For a deep-dive into how the [*honeybadger* gem](https://github.com/honeybadger-io/honeybadger-ruby/) works, check out the [Architecture Guide](/lib/ruby/support/architecture/). If you’re stuck, shoot us an:
# Data residency
> Control where your application data is stored with Honeybadger's data residency options for EU and US regions.
Data residency refers to the physical location where your organization’s data is stored and processed. It’s a way to ensure that data like customer information, application logs, and business data remain within the geographical borders of a specific country or region.
Honeybadger offers two regions (US and EU) so that your organization can choose where your data is stored and processed.
## United States
[Section titled “United States”](#united-states)
Honeybadger stores your data in the US by default (Amazon’s us-east-1 region). Unless you specifically signed up for our [EU region](#european-union), this is where your data is located.
If you access Honeybadger via one of the following subdomains, you’re in our US region:
* app.honeybadger.io
* api.honeybadger.io
## European Union
[Section titled “European Union”](#european-union)
You can optionally [sign up for an account in our EU region](https://eu-app.honeybadger.io/users/sign_up?plan=team), which we operate on dedicated infrastructure in Amazon’s eu-central-1 region in Frankfurt, Germany.
Honeybadger EU accounts are purchased separately, allowing you to choose different tiers depending on your needs. The pricing and features we offer are otherwise the same across both regions.
If you access Honeybadger via one of the following subdomains, you’re in our EU region:
* eu-app.honeybadger.io
* eu-api.honeybadger.io
# Working with LLMs
> Learn how to integrate large language models (LLMs) with Honeybadger's error tracking and monitoring tools for faster debugging and troubleshooting.
Large language models (LLMs) can help you troubleshoot your applications and fix issues faster. When integrated with Honeybadger’s error tracking and application monitoring tools, they become even more effective at helping you squash bugs and keep your systems running smoothly.
## Honeybadger Model Context Protocol (MCP) server
[Section titled “Honeybadger Model Context Protocol (MCP) server”](#honeybadger-model-context-protocol-mcp-server)
The [Honeybadger MCP server](https://github.com/honeybadger-io/honeybadger-mcp-server) provides structured access to Honeybadger’s API through the Model Context Protocol, allowing AI assistants to interact with your Honeybadger projects and monitoring data.
Instead of manually copying error details or switching between tools, your AI assistant can automatically fetch error data, analyze patterns, and provide contextual debugging suggestions—all within your existing workflow.
### What is the Model Context Protocol?
[Section titled “What is the Model Context Protocol?”](#what-is-the-model-context-protocol)
The Model Context Protocol (MCP) is a standard that enables LLMs to interact with external services in a structured and safe manner. Think of it as giving your AI assistant the ability to use tools - in this case, tools to manage your Honeybadger data and investigate errors and production issues.
### Quick start
[Section titled “Quick start”](#quick-start)
Tip
For detailed development instructions, check out the [full documentation on GitHub](https://github.com/honeybadger-io/honeybadger-mcp-server#installation).
The easiest way to get started is with Docker:
```bash
docker pull ghcr.io/honeybadger-io/honeybadger-mcp-server:latest
```
You’ll need your Honeybadger personal authentication token to configure the server, which you can find under the “Authentication” tab in your [Honeybadger user settings](https://app.honeybadger.io/users/edit#authentication).
#### Claude Code
[Section titled “Claude Code”](#claude-code)
Run this command to configure [Claude Code](https://www.anthropic.com/claude-code):
```bash
claude mcp add honeybadger -- docker run -i --rm -e HONEYBADGER_PERSONAL_AUTH_TOKEN="HONEYBADGER_PERSONAL_AUTH_TOKEN" ghcr.io/honeybadger-io/honeybadger-mcp-server:latest
```
#### Cursor, Windsurf, and Claude Desktop
[Section titled “Cursor, Windsurf, and Claude Desktop”](#cursor-windsurf-and-claude-desktop)
Put this config in `~/.cursor/mcp.json` for [Cursor](https://docs.cursor.com/context/model-context-protocol), or `~/.codeium/windsurf/mcp_config.json` for [Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp). See Anthropic’s [MCP quickstart guide](https://modelcontextprotocol.io/quickstart/user) for how to locate your `claude_desktop_config.json` for Claude Desktop:
```json
{
"mcpServers": {
"honeybadger": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"HONEYBADGER_PERSONAL_AUTH_TOKEN",
"ghcr.io/honeybadger-io/honeybadger-mcp-server"
],
"env": {
"HONEYBADGER_PERSONAL_AUTH_TOKEN": "your personal auth token"
}
}
}
}
```
#### VS Code
[Section titled “VS Code”](#vs-code)
Add the following to your [user settings](https://code.visualstudio.com/docs/configure/settings#_settings-json-file) or `.vscode/mcp.json` in your workspace:
```json
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "honeybadger_auth_token",
"description": "Honeybadger Personal Auth Token",
"password": true
}
],
"servers": {
"honeybadger": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"HONEYBADGER_PERSONAL_AUTH_TOKEN",
"ghcr.io/honeybadger-io/honeybadger-mcp-server"
],
"env": {
"HONEYBADGER_PERSONAL_AUTH_TOKEN": "${input:honeybadger_auth_token}"
}
}
}
}
}
```
See [Use MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.
#### Zed
[Section titled “Zed”](#zed)
Add the following to your Zed settings file in `~/.config/zed/settings.json`:
```json
{
"context_servers": {
"honeybadger": {
"command": {
"path": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"HONEYBADGER_PERSONAL_AUTH_TOKEN",
"ghcr.io/honeybadger-io/honeybadger-mcp-server"
],
"env": {
"HONEYBADGER_PERSONAL_AUTH_TOKEN": "your personal auth token"
}
},
"settings": {}
}
}
}
```
#### Running without Docker
[Section titled “Running without Docker”](#running-without-docker)
If you don’t have Docker, you can build the server from source:
```bash
git clone git@github.com:honeybadger-io/honeybadger-mcp-server.git
cd honeybadger-mcp-server
go build -o honeybadger-mcp-server ./cmd/honeybadger-mcp-server
```
And then configure your MCP client to run the server directly:
```json
{
"mcpServers": {
"honeybadger": {
"command": "/path/to/honeybadger-mcp-server",
"args": ["stdio"],
"env": {
"HONEYBADGER_PERSONAL_AUTH_TOKEN": "your personal auth token"
}
}
}
}
```
For detailed development instructions, check out the [full documentation on GitHub](https://github.com/honeybadger-io/honeybadger-mcp-server#installation).
### What can you do with the MCP server?
[Section titled “What can you do with the MCP server?”](#what-can-you-do-with-the-mcp-server)
Caution
The server runs in **read-only mode by default** for security. This means only read operations (like `list_projects`, `get_project`, `list_faults`) are available. Write operations such as `create_project`, `update_project`, and `delete_project` are excluded to prevent accidental modifications.
To enable write operations, explicitly set `HONEYBADGER_READ_ONLY=false`. Use with caution as this allows destructive operations like deleting projects.
Once you have Honeybadger’s MCP server running, your AI assistant gains the following capabilities:
* **Project management**: List, create, update, and delete projects, and get detailed project reports.
* **Error investigation**: Search and filter errors, view occurrences and stack traces, see affected users, and analyze error patterns.
* We’re actively developing additional tools for working with Honeybadger Insights data, account and team management, uptime monitoring, and other platform features. More to come!
For a complete list of available tools and their parameters, see the [tools documentation](https://github.com/honeybadger-io/honeybadger-mcp-server?tab=readme-ov-file#tools) in the GitHub README.
### Example workflows
[Section titled “Example workflows”](#example-workflows)
Here are some things you might ask your AI assistant to help with. Always review closely; LLMs can make mistakes.
**“Fix this error \[link to error]”**
Your assistant can look up the project and error details, open the source file from the stack trace, and fix the bug. You could also try phrases like “Tell me more about this error,” “Help me troubleshoot this error,” etc.
**“What’s happening with my Honeybadger projects?”**
Your assistant can list your projects, show recent error activity, and filter faults by time and environment to provide a quick overview or help you triage.
**“Create an interactive chart that shows error occurrences for my ‘\[project name]’ Honeybadger project over time. Use your excellent front end skills to make it look very professional and well polished.”**
Your assistant can fetch time-series data from your project and generate an interactive chart showing error trends.
## Documentation for LLMs (llms.txt)
[Section titled “Documentation for LLMs (llms.txt)”](#documentation-for-llms-llmstxt)
We provide machine-readable versions of our documentation optimized for LLMs. These files follow the [llms.txt](https://llmstxt.org/) standard and are automatically generated from our documentation content.
### Available formats
[Section titled “Available formats”](#available-formats)
* [/llms.txt](/llms.txt) - Index page with links to full and abridged documentation, plus specialized subsets
* [/llms-full.txt](/llms-full.txt) - Complete documentation in text format
* [/llms-small.txt](/llms-small.txt) - Abridged documentation with non-essential content removed
The abridged version (`llms-small.txt`) is optimized for token efficiency while preserving essential technical information.
### Specialized documentation subsets
[Section titled “Specialized documentation subsets”](#specialized-documentation-subsets)
We also provide focused documentation subsets for specific use cases:
* The Honeybadger Data (REST) API and reporting APIs
* Honeybadger Insights and BadgerQL
* Honeybadger’s user interface and product features
* Individual documentation sets for each client library (Ruby, JavaScript, Python, PHP, Elixir, etc.)
Visit [/llms.txt](/llms.txt) for the complete list with links to download.
### Using llms.txt files
[Section titled “Using llms.txt files”](#using-llmstxt-files)
These files are designed to be consumed by LLMs either:
1. **Directly:** Some LLM tools can fetch and process llms.txt files automatically
2. **As context:** Copy and paste relevant sections into your AI assistant
3. **Via automation:** Build tools that fetch and inject documentation into LLM prompts
## Responding to alerts in Slack and GitHub
[Section titled “Responding to alerts in Slack and GitHub”](#responding-to-alerts-in-slack-and-github)
Honeybadger includes full backtraces in [Slack error notifications](/guides/integrations/slack/) to provide the context that AI coding assistants need for effective debugging.
The backtrace appears as formatted code in Slack, allowing you to copy and paste it to AI debugging assistants like Cursor, Windsurf, or Copilot. If you use Cursor’s [Background Agents](https://docs.cursor.com/background-agent), you can install their [Slack integration](https://docs.cursor.com/slack) to ask Cursor to fix the error directly from Slack:
We include similar information when [creating issues for errors in GitHub](/guides/integrations/github/) and other issue trackers, which should help you—for example—[assign bugfixes to GitHub Copilot](https://github.blog/ai-and-ml/github-copilot/assigning-and-completing-issues-with-coding-agent-in-github-copilot/).
See our [integration docs](https://docs.honeybadger.io/guides/integrations/) to learn more about our 3rd-party integrations.
## Going further
[Section titled “Going further”](#going-further)
As we continue to develop LLM integrations, we’re exploring ways to make automated monitoring and debugging more intelligent. Some ideas we’re excited about:
* Root cause analysis and bug fixes
* Natural language queries for [error search](/guides/errors/search/) and [BadgerQL](/guides/insights/badgerql/)
**Do you have ideas for how LLMs could improve your Honeybadger experience?** We’d love to hear from you! Drop us a line at [support@honeybadger.io](mailto:support@honeybadger.io?subject=HB+LLMs).
## Additional resources
[Section titled “Additional resources”](#additional-resources)
* [Honeybadger MCP Server GitHub Repository](https://github.com/honeybadger-io/honeybadger-mcp-server)
* [Model Context Protocol](https://modelcontextprotocol.io/)
* [Honeybadger API Documentation](/api/)
# Quotas
> Learn how Honeybadger quotas work and optimize your error tracking budget across monthly and annual plans.
The amount you pay for Honeybadger revolves mainly around how much error traffic your projects report to our API. Read on to find out how quotas work and how to maximize the value you get from Honeybadger.
## Error reporting
[Section titled “Error reporting”](#error-reporting)
### Understanding quotas
[Section titled “Understanding quotas”](#understanding-quotas)
Your account has a limit on the number of error notifications that it will process per month. This quota varies based on the subscription plan you have chosen for your account, and reporting occurrences of an error to our API consumes your quota. For example, suppose your app sends ten notifications to our API when a user encounters the same bug ten times. In that case, your remaining quota will be reduced by ten.
Whether you pay annually or monthly, quotas reset at the beginning of the calendar month (UTC). If your usage reaches 80% of your quota for the month, and if your projects are consuming the quota faster than the month is elapsing, we will send you notifications about your quota potentially running out. In other words, if you use up 80% of your quota by the 15th of the month, we’ll give you a heads-up about that, but if you hit 80% usage on the 27th (87% of a 31-day month), we won’t. We’ll send you another warning if/when you pass 90% (assuming you don’t upgrade first) and again at 100%.
### Exceeding your quota
[Section titled “Exceeding your quota”](#exceeding-your-quota)
If you hit 100% quota in a month, we will limit your projects to processing only one error notification per minute per project for the rest of the month. Any hits to our API after that one per minute per project will be ignored and won’t count against your quota. You can resume standard processing at any time by upgrading your plan to the next tier, and you can avoid getting limited by upgrading before reaching the 100% threshold. Should you upgrade, your bill will be prorated for the new subscription amount based on your billing anniversary. We also prorate downgrades. If you need to upgrade near the end of the month, you can downgrade after the beginning of the month (assuming your error volume won’t be as high in the coming month), and you’ll only be billed a little extra on your next invoice.
As mentioned, we allow your account to exceed 100% of quota usage. However, we have a hard shutoff at 125% of quota consumption. If you hit that amount, your projects will not process any additional error notifications until you upgrade or until the 1st of the month rolls around. You can avoid the limits altogether by enabling overage billing, which allows you to go over your quota and be billed separately for that overage on the next invoice. Overage billing can work well if your error traffic puts you just over the limit for your plan, but if you are consistently going well past your quota, it will likely be cheaper for you to upgrade to the next tier. Overage charges can get very expensive, so we recommend being careful when enabling that option.
### Quota forgiveness
[Section titled “Quota forgiveness”](#quota-forgiveness)
Quotas work well when your error traffic is somewhat consistent, but sometimes, an unexpected spike in error traffic can consume your quota quickly. Having a production database go down, deploying buggy code to a staging environment, or other rarely-experienced scenarios can leave you early in the month without any quota remaining. If this happens to you, please feel free to [contact us](mailto:support@honeybadger.io) to get back in action once you’ve conquered the black swan event. Assuming this kind of thing isn’t happening to you regularly 😉, we’ll be happy to remove your account limits for the rest of the month.
### Limiting your quota usage
[Section titled “Limiting your quota usage”](#limiting-your-quota-usage)
An ounce of prevention is worth a pound of cure, right? You can help keep your Honeybadger costs down and avoid prematurely consuming your quota by using one or more of the following tips:
* Use the Throttle field on the Advanced tab of the project settings page to limit how much error traffic is processed. Setting the throttle to 1 will limit that project to accepting only 1 API request per minute.
* Use a hook in your code to prevent errors you don’t care about from being sent to our API. Examples of how to do this can be found in our client documentation — e.g., for [Ruby](/lib/ruby/getting-started/ignoring-errors/#ignore-programmatically) and [JavaScript](/lib/javascript/guides/reducing-noise/#ignoring-errors). This method is handy for ignoring errors raised by browser extensions.
* Mark an error as ignored in our UI. Any future notifications will be discarded entirely, and won’t count against your quota.
## Insights
[Section titled “Insights”](#insights)
### Daily data limit
[Section titled “Daily data limit”](#daily-data-limit)
Insights usage is measured by the amount of data you send to the [API endpoint](/api/reporting-events) each day (starting at midnight UTC). Since event and log data can be bursty, we do not immediately limit your traffic once you have reached your quota for the day. Instead, if you consistently go over your quota, you will be prompted to upgrade your subscription. If you do not upgrade or reduce the amount of data you send, then a hard limit will be applied to your account to enforce the Insights quota.
## Viewing your quota usage
[Section titled “Viewing your quota usage”](#viewing-your-quota-usage)
For a high level overview, visit the [Errors Stats page](https://app.honeybadger.io/projects/stats) and the [Insights Stats Page](https://app.honeybadger.io/projects/stats/insights) in the application to see your quota usage.
For a more detailed view, you can use BadgerQL to query your Insights data usage. Here’s an example query that will show you the amount of data you’ve sent to the Insights for a project (be sure to deselect the [Internal Stream](/guides/insights/#streams) so you only see the data you are sending):
```plaintext
stats sum(@size) as size by event_type::str
| sort size
| only toHumanString(size, "bytes"), event_type
```
You can then drill down and see the specific events that are consuming the most data.
```plaintext
filter event_type::str == "sql.active_record"
| stats count() as count by query::str
| sort count
```
With this information, you may also want to set up an [Insights Alarm](/guides/insights/alarms/) to notify you when you’re generating more events than expected. For more information on how to use BadgerQL, check out our [BadgerQL documentation](/guides/insights/badgerql/).
# Referral program
> Earn monitoring credits by referring new customers to Honeybadger.
Our customer referral program rewards you for spreading the word about Honeybadger. When someone you refer becomes a Honeybadger customer, you receive up to 20% of their payments as credit towards your bill.
## How to join
[Section titled “How to join”](#how-to-join)
Getting started with the referral program is simple:
1. Navigate to **Settings & billing** → **Referrals** in your [Honeybadger account](/guides/accounts/)
2. Accept the referral program terms
3. Share your unique referral link with colleagues, clients, or anyone who needs application monitoring
## How it works
[Section titled “How it works”](#how-it-works)
When you refer a new customer:
* You earn 20% of their payments as monthly/annual invoice credits, up to your total invoice amount
* Credits are automatically applied to your next bill
* Credits don’t roll over—use them each period or lose them
* Credits continue as long as both accounts remain active
See the [referral program terms](https://www.honeybadger.io/terms/referral-agreement/) for full details.
## Earning potential
[Section titled “Earning potential”](#earning-potential)
The more you refer, the more you can save. Here are some examples:
* **Small team ($90/month)**: Earn up to $18/month in credits
* **Growing company ($200/month)**: Earn up to $40/month in credits
* **Enterprise account ($900/month)**: Earn up to $180/month in credits
Since Honeybadger team accounts [start at $26/month](https://www.honeybadger.io/plans/), one workplace referral could cover your personal account indefinitely.
## Tax information
[Section titled “Tax information”](#tax-information)
U.S. customers expecting to earn $600 or more in annual referral credits will need to provide tax information as required by law. You can provide this information by \[sending us a W-9 form]\(mailto:support\@honeybadger.io?subject=W-9 tax info for referral program\&body=Hi, please send me a secure link to provide my tax info.%0D%0A%0D%0AAccount ID:). We will issue a 1099 form at the end of the year for tax reporting purposes. If you reach the annual threshold before providing your tax information, referral credits will be paused until we receive it.
# Security
> Keep your error data safe.
Please see [this page](https://www.honeybadger.io/security/) for more info about our policies and procedures related to security, as well our compliance information.
## Authenticating requests from Honeybadger
[Section titled “Authenticating requests from Honeybadger”](#authenticating-requests-from-honeybadger)
Requests sent from Honeybadger servers for *source maps*, *web hooks*, and *uptime checks* include the header `Honeybadger-Token` which is a secret token derived from your api key. The Honeybadger token may be used to authenticate the request (note that this token will change if you reset your project API key):
```plaintext
Honeybadger-Token: your-token
```
You can find your token on the API Key tab in project settings.
## Firewalls
[Section titled “Firewalls”](#firewalls)
To use Honeybadger behind a firewall, you’ll need to configure your firewall to allow connections to our servers. Here’s the list:
### For exception monitoring
[Section titled “For exception monitoring”](#for-exception-monitoring)
Whitelist the following IPs for outgoing traffic:
* 34.196.34.99
* 34.195.239.200
* 34.193.240.253
* 34.225.218.213
* 52.5.3.101
### For webhooks, sourcemaps, and uptime monitoring
[Section titled “For webhooks, sourcemaps, and uptime monitoring”](#for-webhooks-sourcemaps-and-uptime-monitoring)
We use a dynamic range of IPs for outbound requests to your servers. Please use the Honeybadger-Token header, described above, to authenticate requests coming from our servers.
## Reporting issues
[Section titled “Reporting issues”](#reporting-issues)
If you’ve noticed a possible security issue, please let us know at . Please note that we do not pay bounties for vulnerability reports.
## Hall of fame
[Section titled “Hall of fame”](#hall-of-fame)
We’d like to thank the following people for helping us keep Honeybadger secure:
* Manish Bhattacharya
* Jayson Zabate
* Aditya Agrawal
* Evan Ricafort
* Osanda Malith Jayathissa
* Madhu Akula
* Abdul Wasay
* Shivam Kumar Agarwal
* Sumit Sahoo
* Adam Enger
* Sajibe Kanti
* Md. Nur A Alam Dipu
* Pethuraj M
* Tinu Tomy
* Hariharan.S
* Anil Tom
* Pranshu Tiwari
* Ranjeet Kumar Singh
* Vikas Srivastava
* Pankaj Kumar Thakur
* Pratik Vinod Yadav
* Mrunal Chawda
* Bharat
* Gaurav Solanki
* Mahendra Purbia
* Aditya Soni
* Kunal Mhaske
* Suresh Kumar
* Agrah Jain
* Ome Mishra
* Dhanu Maalaian
* Bilal Abdul Muqeet
* Shaikh Sameer