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:
const raygun = require('raygun');
const raygunClient = new raygun.Client().init({
  apiKey: 'YOUR_API_KEY_HERE',
  batch: true,
  reportUncaughtExceptions: true
});

When the reportUncaughtExceptions option is enabled, uncaught exceptions will automatically be captured and sent to Raygun.

You can also report errors manually by calling raygunClient.send(error).

For example:

try {
  // some code that may throw an error
} catch (error) {
  raygunClient.send(error);
}

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:

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

// ...
app.use(express.static(path.join(__dirname, 'public')));
app.use(raygunClient.expressHandler);

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:

const raygun = require('raygun');
const 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:

const 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: