Skip to main content

Node.js SDK

This page will dive into the nitty gritty details on installing Rookout under various configurations.

Installation

Install the Rookout Node SDK using one of the following methods:


npm install --save rookout

Setup

To add the SDK to your application, add:


const rookout = require('rookout');

Start

To start the SDK, add the following to your app’s entry point:


rookout.start({
token: '[Your Rookout Token]',
labels:
{
env: "dev" // Optional, see the Labels page for more info.
}
});

Note that the rookout.start method returns a promise that resolves (fulfills) when the connection attempt either succeeds or fails. You can change this behavior by setting the throw_errors parameter to true (to reject on fail). Either way, you can choose to utilize this Promise or ignore it.

Flush

The flush method allows explicitly flushing the Rookout logs and messages. The callback is executed when the method finishes.


rookout.flush(cb);

Connectivity test

To make sure the SDK is properly configured and test your connection (using environment variables only), run the following command:


./node_modules/.bin/rookout-check

Configuration

The following table includes all configuration options. Pass them to the rookout.start method or using environment variables.

ParameterEnvironment VariableDefault ValueDescription
tokenROOKOUT_TOKENNoneThe Rookout token for your organization.
labelsROOKOUT_LABELSA dictionary of key:value labels for your application instances. Use k:v,k:v format for environment variables
git_commitROOKOUT_COMMITNoneString that indicates your git commit
git_originROOKOUT_REMOTE_ORIGINNoneString that indicates your git remote origin
hostROOKOUT_CONTROLLER_HOSTNoneIf you are using a Rookout ETL Controller, this is the hostname for it
portROOKOUT_CONTROLLER_PORTNoneIf you are using a Rookout ETL Controller, this is the port for it
proxyROOKOUT_PROXYNoneURL to proxy server
debugROOKOUT_DEBUGFalseSet to True to increase log level to debug
throw_errors---FalseSet to True to reject the promsie when start fails
sourcesROOKOUT_SOURCESNoneSources information (see info below). Replaces ROOKOUT_COMMIT and ROOKOUT_REMOTE_ORIGIN
live_loggerROOKOUT_LIVE_LOGGERFalseSet to True to enable Rookout Live Logger
quietROOKOUT_QUIETFalseSet to True to stop informative log messages from being written to the standard output and error

Code manipulation

Source maps

If your application's code is being transpiled or bundled, you must include the source maps, either in-line or as separate files.

  • Webpack - use either the inline-source-map or source-map values for the devtool option in the Webpack config file (reference).
  • Babel - use either the "inline", "both" or true values for the sourceMaps option in the Babel config file (reference).
  • TypeScript - add either "inlineSourceMap": true or "sourceMap": true as well as "inlineSources": true in the TypeScript config file (reference).
  • CoffeeScript - pass either the -M (inline) or -m flags to the coffee CLI tool (reference).

Note: When using both Webpack and TypeScript together, please do as follows:

  • Webpack + TypeScript - add "sourceMap": true as well as "inlineSources": true in the TypeScript config file and use either the inline-source-map or source-map values for the devtool option in the Webpack config file.

Bundling tools

By default, Webpack packs Rookout with all other modules, which can get tricky and may not work. We recommend excluding it from the bundle by following these instructions:

  • Webpack - There are two options, both require editing the webpack.config.js file:

    1. Exclude all modules - Import webpack-node-externals like so: const nodeExternals = require('webpack-node-externals');, then add externals: [nodeExternals()] to module.exports.
    2. Exclude Rookout only - Add externals: {'rookout': 'commonjs rookout'} to module.exports, or externals: {'rookout/lambda': 'commonjs rookout/lambda'} if running on AWS Lambda with our wrapper.
  • Angular Universal - Add "externalDependencies": ["rookout"], under "options" inside angular.json.

Note: In this case, the node_modules directory must be available where your application is running, as the modules will no longer get packed into the bundle. If you only excluded the Rookout module, only it needs to be available.

Uglification/minification

Rookout works with uglified/minified code if it's provided with source maps, however, mangling (changing of variable names) should not be applied.

Webpack may automatically mangle variable names when used in production. To disable mangling in webpack, add the following to webpack.config.js:


const TerserPlugin = require("terser-webpack-plugin");

module.exports = {

// ...

optimization: {
minimizer: [new TerserPlugin({
terserOptions: {
mangle: false,
},
})],
},
};

Source information

To enable automatic source fetching, information about the source control must be specified.

Environment Variables or Start Parameters

Use the environment variables or start parameters as described above in the API section.

Git Folder

Rookout gets the source information from the .git folder if both of the following apply:

  1. The .git folder is present at any of the parent directories of where the application is running (searching up the tree).
  2. No environment variables or start parameters are set for source information.

Multiple Sources

Use the environment variable ROOKOUT_SOURCES to initialize the SDK with information about the sources used in your application.

ROOKOUT_SOURCES is a semicolon-separated list with a source control repository and revision information. This will allow Rookout to automatically fetch your application's source code from the right revision, and also additional dependencies' sources. When using Git the repository is a URL (remote origin) and the revision is a full commit hash.

For example let's say I use https://github.com/Rookout/tutorial-nodejs with the commit 2f79053d7bc7c9c9561a30dda202b3dcd2b72b90 and I use the Lodash package (https://github.com/lodash/lodash) from its master branch:


ROOKOUT_SOURCES=https://github.com/Rookout/tutorial-nodejs#cf85c4e0365d8082ca2e1af63ca8b5b436a13909;https://github.com/lodash/lodash#master

Supported Versions

Rookout offers full support for all recent LTS versions (currently supported 12, 14, 16, 18, 20).

To use Rookout with other versions set the environment variable ROOKOUT_SKIP_NODE_WHITELIST=true.

Note: The Rookout NodeJS SDK does not support running side-by-side with another debugger.

Serverless and PaaS Deployments

Integrating with serverless

For most serverless types, you can install Rookout normally, as described above.

For AWS Lambda, it is recommended to use the provided wrapper like so:


const rookout = require('rookout/lambda');

function handler(event, context, callback) {
callback(null, "Hello World");
}

exports.handler = rookout.wrap(handler, {token: '[Your Rookout Token]', labels: {env: "dev"}});

Serverless cold-start times

Cold start time may increase by up to 500ms when using Rookout. If cold-start times are critical, the initialization time can be further reduced by adding `` to the options object of the Lambda wrapper, or setting "ROOKOUT_LAMBDA_QUICK_START=True" as an environment variable.

Debugging Node Modules

By default, Rookout ignores your project's dependencies in the node_modules folder.

If the project you wish to debug is installed as a node module, create a file in the project's repository root folder, called .rookout, with the following content:


#package

Note: Rookout does not map the most common NPM packages for performance reasons and does not allow setting breakpoints inside such packages.