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:
- In your project root, grab the module by running
npm install raygun
- 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
});
Sending errors
Automatically
When the reportUncaughtExceptions
option is enabled, uncaught exceptions will automatically be captured and sent to Raygun.
Manually
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);
}
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:
const raygunClient = new raygun.Client().init({apiKey: '{{yourApiKey}}'});
// ...
app.use(express.static(path.join(__dirname, 'public')));
app.use(raygunClient.expressHandler);
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:
const raygun = require('raygun');
const 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:
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.
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.
Custom error grouping
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";
}
});
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).
The provider is open source and available at the Raygun4node repository.