search close

NodeJS Module Install

access_time Updated Jun 20, 2021

Compatibility

This is compatible with Node 0.10 to 12.X. All dependencies are explicitly specified in the npm-shrinkwrap.json file.

Installation

One may install the latest version from npmjs.com using:

npm install sigsci-module-nodejs

For specific releases prior to 1.5.3, installation can be performed from the release archive:

npm install https://dl.signalsciences.net/sigsci-module-nodejs/<VERSION>/sigsci-module-nodejs-<VERSION>.tgz

See the package archive for a list of versions.

Usage For Native Applications

Use the native API if your application invokes http.createServer directly. Adding Signal Sciences involves:

  1. Importing the sigsci module
  2. Creating a SigSci object, adding or overriding any parameters.
  3. Wrapping your native dispatcher
    // Import sigsci module
    var Sigsci = require('sigsci-module-nodejs')
    
    // your code
    
    // 2. Create a SigSci object
    var sigsci = new Sigsci({
     path: '/var/run/sigsci.sock'
     // other parameters here
    })
    
    // 3. Wrap dispatcher with sigsci.wrap
    
    // WAS http.createServer(dispatcher).listen(8085, '127.0.0.1')
    
    http.createServer(sigsci.wrap(dispatcher)).listen(8085, '127.0.0.1')
    

Usage For Node.js Express

The nodejs express module is exposed as a express middleware and is typically inserted as the first middleware, right after the var app = express() statement . See the express Using Middleware documentation for more details.

In particular, adding Signal Sciences involves:

  1. Importing the sigsci module
  2. Creating a SigSci object, adding or overriding any parameters.
  3. Inserting the SigSci module
    // Import sigsci module
    var Sigsci = require('sigsci-module-nodejs')
    
    // your code
    
    // 2. Create a SigSci object
    var sigsci = new Sigsci({
    path: '/var/run/sigsci.sock'
    // other parameters here
    })
    
    // 3. Insert the SigSci module middleware right after the express app is created.
    
    // WAS
    // var app = express()
    //
    // Other routes and middleware
    // app.use(...)
    // app.get('/route', ...)
    
    
    // NEW
    var app = express()
    app.use(sigsci.express())   // NEW
    
    // continue with existing routes and middleware
    app.use(...)
    app.get('/route', ...)
    

Usage For Node.js Restify

Installing the Signal Sciences module for Restify is similar to NodeJs, except that 404 errors are handled differently in Restify. For best results, Signal Sciences should hook into the NotFound event. See the Restify node server api for more details.

Usage for Node.js Hapi

Tested with Hapi 14.X. Add at the top of your file:

var Sigsci = require('sigsci-module-nodejs')

var sigsci = new Sigsci({
path: '/var/run/sigsci.sock'
// see other options below
})

Then before the server stanza add the following two lines:

server.ext('onRequest', sigsci.hapi())
server.on('response',   sigsci.hapiEnding())

// existing code vvvvv
server.start((err) => {
if (err) {
  throw err
}
  console.log('Server running at:', server.info.uri)
})

Usage for Node.js Hapi v18

var Sigsci = require('sigsci-module-nodejs')

var sigsci = new Sigsci({
path: '/var/run/sigsci.sock'
// see other options below
})
// Creating a Server
const server = Hapi.Server({
    port: 8085
});
// Add SigSci request lifecycle methods
server.ext('onRequest', sigsci.hapi18())
server.events.on('response', sigsci.hapi18Ending())
// existing code vvvvv
await server.start()
console.log('Server running at:', server.info.uri)

Parameters

One can pass various parameters to SigSci object:

var sigsci = new Sigsci({
path: '/var/run/sigsci.sock'
// other parameters here
})

The most important ones are listed here. See the file SigSci.js for more details and default values.

Name Description
port Specifies the port to connect to the agent via TCP.
host Specifies the IP address to connect to the agent via TCP (optional). Default: localhost
path Specifies the Unix Domain Socket to connect to the agent via UDS.
socketTimeout Number of milliseconds to wait for a response from the agent. After this time the module allows the original request to pass (i.e. fail open).
maxPostSize Controls the maximum size in bytes of a POST body that is sent to the agent. If the body is larger than this value, the post body is not sent to the agent. This allows control over performance (larger POST bodies take longer to process) and to prevent DoS attacks.
log The function to use to log error messages. By default it will be something to the effect of: function (msg) { console.log(util.format('SIGSCI %s', msg))

Next Steps

Explore other installation options: