1. Home
  2. Language Guides
  3. Node.js
  4. Crash Reporting
  5. Installation

Installation

The official Raygun provider for Node.js allows you to easily access crash reporting and error monitoring for your node.js network application.

This provider is flexible and supports many configuration scenarios - you can have it running and sending errors quickly, by manually placing send() calls when you detect an error. If you are using the Express.js web application framework, you can add the included middleware at the end of your middleware definitions. Or, you can use node.js domains.

The provider can send Error objects, with error details (time, message etc) a stack trace, request data, environment data, custom user data and more. If you wish to manually send other information, the transport object has a Send function which will pass data to Raygun with the required fields.

To add Raygun to your node.js app, follow these steps:

  1. In your project root, grab the module by running
npm install raygun
  1. Create a RaygunClient using your application API key:
var raygun = require('raygun');
var raygunClient = new raygun.Client().init({ apiKey: '{{yourApiKey}}' });

A good way to trap and send exceptions, as it works with both synchronous and asynchronous code, is by using domains. In the code sample below, a test error is being thrown in the run function.

var d = require('domain').create();

setTimeout(function () {
  process.exit(1);
}, 3000).unref();

raygunClient.send(err, null, function () {
  process.exit(1);
});

d.run(function(){
  var err = new Error('phasers offline');
  throw err;
});

If you are using express.js to develop a web application, you can use the provided middleware as an error handler, at the bottom of your middleware definitions:

var raygunClient = new raygun.Client().init({apiKey: '{{yourApiKey}}'});

// ...
app.use(express.static(path.join(__dirname, 'public')));
app.use(raygunClient.expressHandler);
var err = new Error('help!');
throw err;

We have written a quick start blog post that covers Hapi, Restify, Koa and pure Node HTTP.

If you don't want to use domains, such as with in an older version of node.js, you can also wrap your code in a try block, then call raygunClient.send(err) in the catch block.

We've created a blog post showing ways to send errors in node.js to Raygun - check it out for idiomatic examples of how to set up the provider. Often the most appropriate way is to use Domains, or the included Express middleware handler if you use express.js.

You can pass custom data in on the Send() function, as the second parameter. For instance:

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

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

The value passed to the 3rd argument callback is the response from the Raygun API - there's nothing in the body, it's just a status code response. If everything went ok, you'll get a 202 response code. Otherwise we throw 401 for incorrect API keys, 403 if you're over your plan limits, or anything in the 500+ range for internal errors. We use the nodejs http/https library to make the POST to Raygun, you can see more documentation about that callback here.

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']);

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: "{{yourApiKey}}"});

raygunClient.user = function (req) {
  if (req.user) {
    return {
      identifier: req.user.username,
      email: req.user.email,
      fullName: req.user.fullName,
      firstName: req.user.firstName,
      uuid: req.user.deviceID
    };
  }
}

The string properties on a User have a maximum length of 255 characters. Users who have fields that exceed this amount will not be processed.

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 provide your own grouping key if you wish. NOTE: We only recommend doing this if you are having issues with errors not being grouped properly.

When initializing Raygun, pass through a groupingKey function.

const raygunClient = new raygun.Client().init({
  apiKey: 'INSERT_API_KEY_HERE',
  groupingKey: function(message, exception, customData, request, tags) {
    return "BUILD_CUSTOM_KEY_HERE";
  }
});

Raygun supports source mapping for Node.js stacktraces which include column numbers. To enable this feature you will need to upload your map files to the JavaScript Source Map Center and enable the processing of Node.js error stacktraces.

Raygun supports source mapping for Node.js stacktraces which include column numbers. To enable this feature simply upload your map files as per the instructions on this page and enable the processing of Node.js errors with this setting in Raygun.

Managing files in the JavaScript Source Map Center Files in the JavaScript Source Map Center can be managed via a few API calls.

A GET request to https://app.raygun.com/jssymbols/[applicationIdentifier] will return a JSON object listing all files within the center. eg.

curl
  -X GET
  -u my@email.com:mypassword
  https://app.raygun.com/jssymbols/[applicationIdentifier]

Returns:

{
  "Count": totalNumberOfItems,
  "Items": [
    {  
       "Url": "https://urlOfItem",
       "FileName": "fileName.js",
       "UploadedOn": "2016-01-01..."
    },
    ...
  ]
}

A DELETE request to https://app.raygun.com/jssymbols/[applicationIdentifier]/all will remove all files within the center. eg.

curl
  -X DELETE
  -u my@email.com:mypassword
  https://app.raygun.com/jssymbols/[applicationIdentifier]/all

A DELETE request to https://app.raygun.com/jssymbols/[applicationIdentifier] will remove files with the specified URLS from the center. eg.

curl
  -X DELETE
  -u my@email.com:mypassword
  -F "url=https://example.com/js/myjs.min.map"
  https://app.raygun.com/jssymbols/[applicationIdentifier]

All requests use the same authentication methods as the upload call (Basic Authentication and Token Authentication).

The provider is open source and available at the Raygun4node repository.

On this page: