Node-offline-debug NPM

Node-offline-debug

Install

To install the node-offline-debug package, follow npm guidelines: add it to your package.json or install it manually with 'npm install':

npm install node-offline-debug

Example

To instrument your code, 'require' the package as a first step in your app. All the packages that are subsequently loaded will be instrumented.

NOTE: in order to have your packages instrumented you must load them using 'require(<package_name>)'. You cannot instrumrent packages that are "required" during runtime in a general fashion, such as loading all *.js files from a folder.

The following code samples are instrumenting the word-finder application. The application's main file is 'server.js'. However in order to instrument it as well, we added a new 'init.js' file which require 'node-offline-debug' and then 'server.js':

// Load the instrumentation
// All 'required' modules afterwards are analyzed
require('node-offline-debug');

// This module is now analyzed and instrumented
var server = require('./server.js');

The interesting function in word-finder is 'search(word)' in the words.js file. In order to track it we define in the configuration a debug_service of type 'file', which loads functions to track from the package's 'config/debug_configuration_word_finder.json' file:

{
    "functionList": [{
        "functionName": "search(word)",
        "sourceFile": "words.js",
        "line": 3,
        "selected": true
    }, {
        "functionName": "function(req, res)",
        "sourceFile": "server.js",
        "line": 17,
        "selected": false
    }]
}

This configuration will track 'search(word)'. Note that the second entry for tracking the 'express' handler for '/' is disabled ('selected' is set to false). The output is dependent on the definition of the debug_service (see the configuration section). If, however, you are using a debug_service of type 'file', you can direct the output to the console. After the function invocation is completed, debug data is printed out as a structured json.

How it works

Configuration options

"exclude": "express", "elasticsearch", "node_modules", "monitor"
List of instrumentation exclusions. Files which have any of these strings in their path will not be instrumented.
"url": "server.com" (for the 'debug_service' of type 'service')
The base URL for the AppDebug service.
"username": "admin", "password": "pwd" (for the 'debug_service' of type 'service')
Username and password to access the AppDebug service.
"path": "../config/debug_configuration.json", "outputLog": "debug" (for the 'debug_service' of type 'file')
Set the file which stores function debug configuration, and the log level/type which tracking data will be sent to.
"autoCheckConfiguration" : { "once": false, "every": 10000 }
Applies to all debug services (including 'file'). Determines how function tracking settings are retrieved from the debug service. If 'once' is set to 'true', function tracking settings will only be checked once when node-offline-debug is loaded. If set to ‘false’, it will be retrieved at time intervals, indicated by the 'every' milliseconds setting.

Contributing

We will be happy to improve this library, and we encourage you to submit fixes for defects, new features and performance improvements. To contribute to node-offline-debug, please use GitHub pull requests:

You MUST write a clear title and description of your change.
You SHOULD have descriptive commit comments, and you are encouraged to rebase and squash commits.
As with most instrumentation, performance overhead on the instrumented application should be minimized at all costs. Please test and make sure that your changes did not increase the overhead, by running a few simple scenarios of the instrumented application and comparing their single user performance: without 'requiring' node-offline-debug, with 'require' but with no function tracking, with a single function tracked and with many functions tracked.