NodeJS

Code Execution Monitoring for NodeJS applications.

Install

Install the latest version using the npm command below:

npm install @inspector-apm/inspector-nodejs --save

Configure the Ingestion Key

You need an Ingestion Key to create an Inspector instance. Get a new one by creating a project in your Inspector dashboard.

If you use dotenv you can configure the Inspector Ingestion Key in your environment file:

INSPECTOR_INGESTION_KEY=[ingestion key]

Initialization

It's important that Inspector is required in the first line of the script, before you require any other modules - i.e. before, http, mysql, etc.

This means that you should probably require Inspector in your application's main file (usually index.js, server.js or app.js).

Here's a code example of how Inspector is normally initialized in a NodeJS script:

/* 
 * -------------------------------------------
 * Initialize Inspector with the Ingestion Key.
 * -------------------------------------------
 */
const inspector = require('@inspector-apm/inspector-nodejs')({
  ingestionKey: 'xxxxxxxxxxxxx'
});

// Continue with the rest of the script...

Some of the most used modules will be autowired by default. Learn more about autowiring.

HTTP Request Monitoring

Inspector wrap incoming http requests in an entity called "Transaction". To create a real picture of what happen in your application during an http request you should start the transaction as soon as possible in the web server.

Take a look on the example below where a custom web server use patterns to route requests to handlers.

/* 
 * -------------------------------------------
 * Initialize Inspector with the Ingestion Key.
 * -------------------------------------------
 */
const inspector = require('@inspector-apm/inspector-nodejs')({
  ingestionKey: 'xxxxxxxxxxxxx682eedcce097b64b'
});

var http = require('http');
var patterns = require('patterns')();

// Setup routes and their respective route handlers
patterns.add('GET /posts/{id}', require('./routes/posts').show);

// Start web server
http.createServer(function (req, res) {
  // Check if we have a route matching the incoming request
  var match = patterns.match(req.method + ' ' + req.url);

  // If no match is found, respond with a 404. Elastic APM will in
  // this case use the default transaction name "unknown route"
  if (!match) {
    res.writeHead(404);
    res.end();
    return;
  }

  // The patterns module exposes the pattern used to match the
  // request on the `pattern` property, e.g. `GET /posts/{id}`
  inspector.startTransaction(match.pattern);

  req.params = match.params;
  match.value(req, res);
}).listen(3000);

If the transaction is sterted correctly, Inspector will automatically monitor all other task based on supported modules like mysql2, pg, mongodb, etc.

If you are using Express framework, transactions are automatically labeled based on the names of your routes. You should follow the specific express documentation.

Instrument a CLI script

A NodeJS application that run by the command line can start the transaction immediately after initialization:

/* 
 * -------------------------------------------
 * Initialize Inspector with the Ingestion Key.
 * -------------------------------------------
 */
const inspector = require('@inspector-apm/inspector-nodejs')({
  ingestionKey: 'xxxxxxxxxxxxx682eedcce097b64b'
});

/*
 * Immediately start the transaction.
 */
inspector.startTransaction(__filename);

// Continue with rest of the script...

Custom Segments

By default Inspector will report many different tasks based on the application's dependencies, but you are free to "wrap" some parts of your code that you consider relevant to create a more complete picture of what statements are executed during an execution cycle and its performance.

pageCustom Segments