honeybadger-js
Advanced tools
A JavaScript library for integrating apps with the Honeybadger Rails Error Notifier.
A client-side JavaScript library for integrating apps with the :zap: Honeybadger Error Notifier. For server-side javascript, check out our NodeJS library.
Place the following code between the <head></head> tags of your page:
<script src="//js.honeybadger.io/v0.5/honeybadger.min.js" type="text/javascript" data-apiKey="project api key" data-environment="production" data-revision="git SHA/project version"></script>
Honeybadger may also be configured via JavaScript:
<script type="text/javascript">
Honeybadger.configure({
apiKey: 'project api key',
environment: 'production',
revision: 'git SHA/project version'
});
</script>
Here's a video walkthrough of a basic, global installation:
npm install honeybadger-js --save
bower install honeybadger --save
var Honeybadger = require("path/to/honeybadger");
Honeybadger.configure({
apiKey: 'project api key',
environment: 'production',
revision: 'git SHA/project version'
});
requirejs(["path/to/honeybadger"], function(Honeybadger) {
Honeybadger.configure({
apiKey: 'project api key',
environment: 'production',
revision: 'git SHA/project version'
});
});
Note: First, make sure you use bundler >= 1.8.4.
Add the following to your Gemfile:
source 'https://rails-assets.org' do
gem 'rails-assets-honeybadger'
end
Add the following to application.js:
//= require honeybadger
Honeybadger.configure({
apiKey: 'project api key',
environment: 'production',
revision: 'git SHA/project version'
});
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:
try {
// ...error producing code...
} catch(error) {
Honeybadger.notify(error);
}
See the full documentation for the notify method for more examples.
You can set configuration options by using the Honeybadger.configure function. All of the available options are shown below:
Honeybadger.configure({
// Output Honeybadger debug messages to the console
debug: false,
// Honeybadger API key (required)
apiKey: '',
// The revision of the current deploy
revision: '',
// Collector Host
host: 'api.honeybadger.io',
// Use SSL?
ssl: true,
// Project root
projectRoot: 'http://my-app.com',
// Environment
environment: 'production',
// Component (optional)
component: '',
// Action (optional)
action: '',
// Ignore Patterns (optional)
// Array of error messages as regexes that should be ignored
ignorePatterns: [/known\ error/i],
// Should unhandled (window.onerror) notifications be sent?
onerror: true,
// Disable notifications?
disabled: false,
// Send notifications asynchronously
async: true
});
You can call Honeybadger.configure as many times as you like. The existing configuration data will be merged with any new data you provide. This is especially useful for changing the action and component values inside of single-page apps.
The global Honeybadger instance may also be configured via data attributes on the script tag which loads honeybadger.js:
<script src="honeybadger.js" type="text/javascript" data-component="pages" data-action="index" ...></script>
Honeybadger.notify(): Send an exception to HoneybadgerIf you've caught an exception and want to send it to Honeybadger, this is the method for you.
try {
// ...error producing code...
} catch(error) {
Honeybadger.notify(error);
}
JavaScript often uses generic class names -- such as Error -- which are uninformative and also cause unrelated errors to be grouped together. To get around this issue it's a good practice to send a custom error class when notifying Honeybadger:
Honeybadger.notify(error, 'DescriptiveClass');
You can also set or override other optional data which is reported with the error:
Honeybadger.notify(error, {
message: 'My custom message',
name: 'DescriptiveClass',
component: 'badgers',
action: 'show',
context: { badgerId: 1 },
fingerprint: 'This unique string will group similar errors together',
environment: 'production',
projectRoot: 'https://www.example.com/',
params: { key: 'value' },
cookies: { key: 'value' } // May also be sent as a string in the document.cookie "foo=bar;bar=baz" format.
});
Finally, you can notify Honeybadger of anything, even if you don't have an error object:
Honeybadger.notify('Badgers!');
Honeybadger.notify('Badgers!', { ... });
Honeybadger.notify('Badgers!', 'CustomClass');
Honeybadger.notify('Badgers!', 'CustomClass', { ... });
Honeybadger.notify({
message: 'Badgers!',
name: 'CustomClass',
...
});
A stacktrace will be generated for you (when possible) if you do not provide an error object.
Honeybadger.wrap(): Wrap the given function in try/catch and report any exceptionsIt can be a pain to include try/catch blocks everywhere in your app. A slightly nicer option is to use Honeybadger.wrap. You pass it a function. It returns a new function which wraps your existing function in a try/catch block.
Honeybadger.wrap(function(){
throw "oops";
})();
Note that wrap returns a function. This makes it easy to use with event handlers, as in the example below:
$(document).on("click", "#myElement", Honeybadger.wrap(function(){ throw "oops"; }));
Honeybadger.setContext(): Set metadata to be sent if an exception occursJavascript exceptions are pretty bare-bones. You probably have some additional data that could make them a lot easier to understand - perhaps the name of the current Angular view, or the id of the current user. This function lets you set context data that will be sent if an error should occur.
You can call setContext as many times as you like. New context data will be merged with the existing data.
// On load
Honeybadger.setContext({
user_id: 123
});
// Later
Honeybadger.setContext({
backbone_view: 'tracks'
});
// The context now contains { user_id: 123, backbone_view: 'tracks' }
Honeybadger.resetContext(): Clear context metadataIf you've used Honeybadger.setContext to store context data, you can clear it with Honeybadger.resetContext.
// Set the context to {}
Honeybadger.resetContext();
// Clear the context, then set it to `{ user_id: 123 }`
Honeybadger.resetContext({
user_id: 123
});
Honeybadger.beforeNotify(): Add a callback to be run before an exception is reportedPassing a function to Honeybadger.beforeNotify will add the function
to a list of before notify handlers. If the function includes a
parameter, the Notice object will be passed as an argument. Multiple
handlers may be added in this fashion:
Honeybadger.beforeNotify(function(notice) {
notice.message = 'My custom message';
});
// To halt notification, return false from any `beforeNotify` handler:
Honeybadger.beforeNotify(function(notice) {
if (notice.class == 'MyCustomError') return false;
});
The following notice attributes may be modified by your notification handlers:
Honeybadger.configure(): Set configuration valuesThe configure method takes an object containing config values. Its return value is unspecified.
Honeybadger.configure({apiKey: "adlkjfljk"});
Honeybadger.factory(): create a new client instance.The factory method returns a new instance of Honeybadger which can be configured differently than the global/singleton instance.
var other_hb = Honeybadger.factory({apiKey: "zxcvbnm"});
other_hb.notify("This will go to an alternate project.");
Honeybadger can automatically un-minify your code if you provide a sourcemap along with your minified JavaScript files.
For source maps to work properly, first make sure you're configuring the revision option in honeybadger.js. The value should be a unique version number for your current code deployment (a git SHA works well for this). The revision is used to tell Honeybadger that your code has changed and that it should update your source translations for future errors:
Honeybadger.configure({
apiKey: 'project api key',
environment: 'production',
revision: 'dcc69529edf375c72df39b0e9195d60d59db18ff'
});
We recommend uploading your source map files to our servers every time you deploy your code. It's also possible for you to host your source map files yourself along with your production assets, in which case we'll try to download your source maps when an error is reported to us.
See our guide to learn how to generate source maps and providing them to Honeybadger.
To automatically send cookies with all error reports, use the following ::beforeNotify handler:
Honeybadger.beforeNotify(function(err){
err.cookies = document.cookie;
return true;
})
Honeybadger.js automatically reports uncaught exceptions from window.onerror. To
disable notifications for uncaught exceptions, set the onerror option to
false.
Honeybadger.configure({
apiKey: 'project api key',
onerror: false
});
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 https://developer.mozilla.org/en/docs/Web/API/GlobalEventHandlers/onerror#Notes for more info.
git checkout -b my_branchgit commit -am "Boom"git push origin my_branchFirst, install the required npm packages with npm install. After that you can run the dev server with grunt dev; this will launch a development server at http://127.0.0.1:9999. It will also run the test suite automatically when files change.
To run the test suite by itself, use grunt jasmine.
The Honeybadger gem is MIT licensed. See the MIT-LICENSE file in this repository for details.
FAQs
A JavaScript library for integrating apps with the Honeybadger Rails Error Notifier.
The npm package honeybadger-js receives a total of 15,262 weekly downloads. As such, honeybadger-js popularity was classified as popular.
We found that honeybadger-js demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.