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.

What can I send from my node.js application?

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.

Getting started

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

Sending errors

Using domains

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;
});

Express.js

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;

Other NodeJS frameworks

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

Manual sending

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.

Error tracking examples

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.

Sending custom data

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

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

Callback

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.

Sending request data

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

Tags

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

Unique user tracking

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
    };
  }
}

Version tracking

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.

Source maps

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.

Using Private Source Maps with Node.js apps

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.

Node.js source maps

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).