raygun

Raygun.io plugin for Node

Raygun4Node

Raygun.io plugin for Node

Install the module with: npm install raygun

var raygun = require('raygun');
var raygunClient = new raygun.Client().init({ apiKey: 'your API key' });
raygunClient.send(theError);
 
// For express, at the end of the middleware definitions, just above app.listen: 
app.use(raygunClient.expressHandler);

The Express documentation says Though not strictly required, by convention you define error-handling middleware last, after other app.use() calls, but that is incorrect. If the app.use(raygunClient.expressHandler); call is not immediately before the app.listen call, then errors will not be handled by Raygun.

You can pass custom data in on the Send() function, as the second parameter. For instance (based off the call in test/raygun_test.js):

client.send(new Error(), { 'mykey': 'beta' }, function (response){ });

You can send the request data in the Send() function, as the fourth parameter. For example:

client.send(new Error(), {}, function () {}, request);

If you want to filter any of the request data then you can pass in an array of keys to filter when you init the client. For example:

var raygun = require('raygun');
var raygunClient = new raygun.Client().init({ apiKey: 'your API key', filters: ['password', 'creditcard'] });

You can add tags to your error in the Send() function, as the fifth parameter. For example:

client.send(new Error(), {}, function () {}, {}, ['custom tag 1', 'important error']);

New in 0.4: You can set raygunClient.user to a function that returns the user name or email address of the currently logged in user.

An example, using the Passport.js middleware:

var raygunClient = new raygun.Client().init({apiKey: "yourkey"});
 
raygunClient.user = function (req) {
  if (req.user) {
    return req.user.username;
  }
}

####raygunClient.user(req)

Param: req: the current request. Returns: The current user's identifier, or an object that describes the user.

This will be transmitted with each message sent, and a count of affected users will appear on the dashboard in the error group view. If you return an email address, and the user has associated a Gravatar with it, their picture will be also displayed.

If you return an object, it may have any of the following properties (only identifier is required):

identifier is the user identifier. This will be used to uniquely identify the user within Raygun. This is the only required parameter, but is only required if you are using user tracking.

isAnonymous is a bool indicating whether the user is anonymous or actually has a user account. Even if this is set to true, you should still give the user a unique identifier of some kind.

email is the user's email address.

fullName is the user's full name.

firstName is the user's first or preferred name.

uuid is the identifier of the device the app is running on. This could be used to correlate user accounts over multiple machines.

Any other properties will be discarded.

Note: setUser deprecated in 0.4

Release 0.3 previously had a setUser function that accepted a string or function to specify the user, however it did not accept arguments. This method is considered deprecated and will be removed in the 1.0 release, thus it is advised to update your code to set it with the new user function.

Call setVersion(string) on a RaygunClient to set the version of the calling application. This is expected to be of the format x.x.x.x, where x is a positive integer. The version will be visible in the dashboard.

You can change the endpoint that error messages are sent to by specifying the host, port, and useSSL properties in the raygunClient.init() options hash. By default, host is api.raygun.io, port is 443, and useSSL is true.

Call Raygun.onBeforeSend(), passing in a function which takes up to 5 parameters (see the example below). This callback function will be called immediately before the payload is sent. The first parameter it gets will be the payload that is about to be sent. Thus from your function you can inspect the payload and decide whether or not to send it.

You can also pass this in as an option to init() like this: raygunClient.init({ onBeforeSend: function(payload) { return payload; } });

From the supplied function, you should return either the payload (intact or mutated as per your needs), or false.

If your function returns a truthy object, Raygun4Node will attempt to send it as supplied. Thus, you can mutate it as per your needs - preferably only the values if you wish to filter out data that is not taken care of by the filters. You can also of course return it as supplied.

If, after inspecting the payload, you wish to discard it and abort the send to Raygun, simply return false.

By example:

var myBeforeSend = function (payload, exception, customData, request, tags) {
  console.log(payload); // Modify the payload here if necessary
  return payload; // Return false here to abort the send
}

Raygun.onBeforeSend(myBeforeSend);

View a screencast on creating an app with Node.js and Express.js, then hooking up the error handling and sending them at http://raygun.io/blog/2013/07/video-nodejs-error-handling-with-raygun/

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using "npm test".

  • 0.7.1 - Default useSSL to true.
  • 0.7.0 - Add onBeforeSend hook, api endpoint options, and bug fixes
  • 0.6.2 - Fix utf8 chars causing 400s, log when errors occur when posting
  • 0.6.1 - Replace deprecated request.host with request.hostname if it exists.
  • 0.6.0 - Added ability to send tags with exception reports.
  • 0.5.0 - Added filters for sensitive request data, and better affected user tracking
  • 0.4.2 - Minor test refactor
  • 0.4.1 - Fixed issue where getting cpu information returned undefined
  • 0.4.0 - Added user function, deprecated setUser
  • 0.3.0 - Added version and user tracking functionality; bump jshint version, update test
  • 0.2.0 - Added Express handler, bug fixes
  • 0.1.2 - Include more error information
  • 0.1.1 - Point at the correct API endpoint, include correct dependencies for NPM
  • 0.1.0 - Initial release

Copyright (c) 2015 MindscapeHQ Licensed under the MIT license.