Documentation

Documentation

    ›SDK Setup

    General

    • Getting Started
    • Use Cases

    SDK Setup

    • Introduction
    • JVM
    • .NET
    • Python
    • Ruby
    • Node.js
    • Deployment Examples

    Debug Session

    • Debug session setup
    • Source Repositories
    • Labels

    Breakpoints

    • Breakpoints
    • Breakpoint Status
    • Conditional breakpoints
    • Breakpoint Tasks

    Organizations

    • Organizations

    Advanced

    • Integrations
    • Collaborations
    • Controller Setup
    • Scripting Reference
    • OpenTracing
    • Keyboard Shortcuts

    More

    • Software Versions
    • Controller License
    Edit

    Node.js SDK Instrumentation

    This page will dive into the nitty gritty details on installing Rookout under various configurations.
    If you are encountering any difficulties with deploying Rookout, this is the place to look.

    Node.js

    The NodeJS SDK provides the ability to fetch debug data from a running application in real time.
    It can easily be installed by running the following command:

    npm install --save rookout
    

    Setup

    Start the SDK within your application:

    const rookout = require('rookout');
    
    
    rookout.start({
        token: '[Your Rookout Token]',
        labels:
            {
                "env":"dev" // Optional,see Labels page below Projects
            }
    });
    

    SDK API

    start

    start(options={});
    

    The start method is used to initialize the SDK. Receives configuration using an options object and returns a promise that will resolve when the initial connection attempt to the debug controller succeeds or fails. Either way, connection will be maintained and retried in the background. If you set throw_errors to true, the promise will be rejected on failure.

    Argument                             Environment Variable                                  Default ValueDescription
    tokenROOKOUT_TOKENNoneThe Rookout token for your organization. Should be left empty if you are using a Rookout ETL Controller
    labelsROOKOUT_LABELS{}A 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 or a branch name
    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_errorsNoneFalseSet to True to reject the promsise or throw an exception if start fails (error message will not be printed in console)
    sourcesROOKOUT_SOURCESNoneSource information (see below)

    stop

    stop();
    

    The stop method is used to shutdown the SDK.

    flush

    flush(cb);
    

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

    Test connectivity

    To make sure the SDK was properly installed and test your configuration (environment variables only), run the following command:

    ./node_modules/.bin/rookout-check
    

    Source information

    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 or a branch name.

    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
    

    Transpiling and Source Maps

    Transpiling your JavaScript/TypeScript on the fly (using babel-node or a similar tool), Rookout debugging will work out of the box.

    When transpiling your JavaScript/TypeScript before execution (for instance in your CI/CD), include the source maps inline within the source files or as separate files (usually app.map.js) within your deployment.

    To make sure you can validate the source file matches the file you are trying to debug, please include the original source files side-by-side with the transpiled ones or build your source map with the full source code.

    To test if you are transpiling with source maps, search for this comment in the transpiled files:

    //# sourceMappingURL=/path/to/file.js.map
    

    If you face cases where some variables are not collected, or where some breakpoints fail to be hit, try using a minimal transpile level, or set it to a recent version of Node.js.

    Configurations for Common Tools

    • Webpack - use the inline-source-map or source-map values for devtool.
    • Babel - use the --source-maps inline or --source-maps flags.
    • Typescript - use the --inlineSources flag. For ts-node add source maps using the tsconfig.json file.
    • CoffeeScript - use the -M or -m flags.

    TypeScript & Webpack

    Because of the way Webpack handles TypeScript inputs, an additional step is needed:

    1. Install source-map-loader: npm install -D source-map-loader
    2. Add the following rule to webpack.config.json (under rules):
     {
        test: /\.js$/,
        use: ["source-map-loader"],
        enforce: "pre"
     }
    

    Source Commit Detection

    The NodeJS SDK supports detecting the existing source code commit in the following methods, in descending order of priority:

    1. If the environment variable “ROOKOUT_COMMIT” exists, use it.
    2. If the environment variable “ROOKOUT_GIT” exists, search for the configuration of the “.git” folder and use its head.
    3. If the main application is running from within a Git repository, use its head.

    Supported Versions

    Rookout supports the latest NodeJS and all releases that are under maintenance (LTS). Support for older versions is limited.

    ImplementationVersions
    Node8, 10, 11, 12

    Note: The Rookout NodeJS SDK does not support running side-by-side with debugger such as WebStorm or Stackdriver Debugger.

    Serverless and PaaS deployments

    Integrating with Serverless

    When integrating Rookout into a Serverless application, you should explicitly flush the collected information.
    For most common Serverless runtimes, Rookout provides easy to use wrappers such as rookout.wrap(handler, options={}):

    const rookout = require('rookout/lambda');
    
    function handler(event, context, callback) {
            callback(null, "Hello World");
    }
    
    exports.handler = rookout.wrap(handler, {labels={"env":"dev"})};
    

    Note: Adding the Rookout SDK will slow down your Serverless cold-start times. Please make sure your timeout is no less then 10 seconds.

    For more information, please check out our deployment-examples.

    ← RubyDeployment Examples →
    • Node.js
    • Setup
    • SDK API
      • start
      • stop
      • flush
    • Test connectivity
    • Source information
    • Transpiling and Source Maps
      • Configurations for Common Tools
    • Source Commit Detection
    • Supported Versions
    • Serverless and PaaS deployments
      • Integrating with Serverless
    Documentation
    General

    WelcomeUse Cases
    SDK Setup

    Setup IntroJvm SetupDotnet SetupPython SetupRuby SetupNode SetupDeployment Examples
    Debug Session

    Debug Session SetupSource ReposProjects Labels
    Breakpoints

    BreakpointsBreakpoints StatusBreakpoints ConditionalBreakpoints Tasks
    Organizations

    Organizations
    Advanced

    IntegrationsCollaborationsController SetupBreakpoints ReferenceOpen TracingKeyboard Shortcuts
    More

    Sdk DigestsLicense
    Other

    Status
    GitHub - RookoutFacebook - RookoutTwitter - RookoutLinkedIn - Rookout