Installing the Node.js collector

Install the Instana host agent

You need to install the Instana host agent before you install the Node.js collector. For more information about installing a host agent, see Installing host agents.

Check the installed Node.js version

Ensure that the Node.js collector supports the installed Node.js version. For the supported Node.js versions, see Monitoring Node.js.

Review common installation considerations

To avoid potential problems from installing and using the Node.js collector, review the following considerations:

Bundlers (Webpack or Rollup)

When you pre-process your Node.js server application with a bundler like Webpack or Rollup, you can use either of the following installation methods:

• Installing the Node.js collector without modifying your application.
• Installing @instana/collector as a normal dependency.

The preferred installation method is Installing the Node.js collector without modifying your application.

In both cases, you need to make sure to bundle only your own code, not the code of your dependencies from the node_modules folder.

You must exclude the dependencies due to the following reasons:

• The module @instana/collector does not support being pre-processed with Webpack. Among other problems, dynamic require statements that are used in your code are not resolved correctly.
• To instrument third-party libraries, the npm package @instana/collector intercepts the require process of Node.js. But if those libraries are not loaded at run time and instead are bundled with your own code at build time, no require process is run, and the instrumentation is not applied. Therefore, Instana tracing doesn't work or works partially, that is, tracing works only for Node.js core modules like http because those modules are excluded from bundling by default.

Thus, you must configure your bundler by using the module webpack-node-externals so that everything in node_modules is excluded from all code transformations:

// your webpack.config.js:

const nodeExternals = require('webpack-node-externals');

module.exports = {
  ...
  // externals: nodeModules,
  externals: [nodeExternals()],
  ...
};

If you use Angular CLI, in particular with Angular Universal or SSR, you need to add "externalDependencies": ["@instana/collector"] (and possibly other libraries that @instana/collector instruments) to your angular.json file to exclude them from bundling.

Transpilers (Babel or Traceur)

When you use a transpiler (like Babel, Traceur, or the TypeScript compiler tsc), you can use either of the following installation methods:

• Installing the Node.js collector without modifying your application.
• Installing @instana/collector as a normal dependency.

The preferred method is Installing the Node.js collector without modifying your application.

If you choose to install @instana/collector as a normal dependency, you need to pay close attention to how import and require statements are treated by your transpiler. If your transpiler processes ES6 import statements, adding import instana from '@instana/collector'; at the beginning of your main file doesn't install the collector:

import instana from '@instana/collector';

// THIS WILL NOT WORK because transpilers change the order of imports and statements.
instana();

import express from 'express';

The installation doesn't work because, according to the ES6 spec, all imports are evaluated before the body of the module is run. Babel and other transpilers comply with this rule and move all imports to the beginning when they transpile source files. All actual statements are put after the imports. As a consequence, the import for express in the following example is placed before the instana(); call in your transpiled file:

var _instana = _interopRequireDefault(require("@instana/collector"));

var _express = _interopRequireDefault(require("express"));

var _morgan = _interopRequireDefault(require("morgan"));

function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

(0, _instana.default)(); // <- This is too late, since all other modules will already have been required.

...

The actual call to the init function of @instana/collector comes after all require statements in the transpiled file.

Instead, you can put import './instanaInit'; at the beginning of your main file and then put all other imports as follows:

// Put this import at the top of your main file. Only the import here,
// don't change this to "import instana from './instanaInit'"!
import './instanaInit';

// Now all the other imports can follow:
import express from 'express';
import morgan from 'morgan';

// The following statement is optional; it is only required if you want to use
// Instana's Node.js API (https://www.ibm.com/docs/en/instana-observability/current?topic=nodejs-instana-api):
// @ts-ignore (in case you are using TypeScript, to avoid 'Could not find a declaration file for '@instana/collector')
import instana from '@instana/collector';

The file instanaInit.js (or instanaInit.ts if you use TypeScript) must contain this one statement:

require('@instana/collector')();

By using this statement, the init function is called right away when the process starts.

In general, when any transpiler is used, you must inspect the transpiler's output files when you integrate @instana/collector.

Kubernetes and Red Hat OpenShift

If your Node.js application runs in a Kubernetes and Red Hat OpenShift environment, you can use the Instana AutoTrace WebHook or install the Node.js collector to monitor your application.

Cloud Foundry

You can monitor Cloud Foundry applications only when the Instana agent is actively running on the Diego cells of the Cloud Foundry foundation. Without the agent that is running on the underpinning Diego cell, monitoring is not supported.

For more information about how to set up Instana agents and the related Cloud Foundry or Pivotal Platform functionality, see our Cloud Foundry and Pivotal Platform documentation.

On Cloud Foundry, a configuration is not required at the level of cf push and the application manifest. The only necessary step is to add the @instana/collector package to the Cloud Foundry Node.js application as described in the Installing the Node.js collector section.

Apigee Microgateway

For more information about how to use the Instana Node.js collector package with Apigee Microgateway (also known as edgemicro), see Monitoring Apigee Microgateway.

Next.js

For Next.js applications, use the approach that is described in the Installing the Node.js collector without modifying your application section.

Installing the collector as a local dependency

To install the collector as a local dependency, complete the following steps:

1. Add the package @instana/collector to your project's dependencies:

   • If you use npm, run the following command:

     npm install --save @instana/collector`
     

   • If you use yarn, run the following command:

     yarn add @instana/collector
     

   Do not add the statement require('@instana/collector')(); to your code. None of your JavaScript or TypeScript files need to mention any @instana package.

   Ensure that the @instana/collector package is installed on the target system by using a package manager so that all its dependencies are also correctly installed. Do not run the npm install or yarn or yarn install elsewhere (like on a build system), and then copy the resulting node_modules folder to the target system. The npm install step includes compilation of the native add-ons, which needs to happen on the target architecture and for the correct Node.js version.

2. Activate the Node.js collector:

   • CommonJS: If the application uses CommonJS, complete either of the following steps when you start the node executable. Setting either NODE_OPTIONS or adding --require loads and initializes the Node.js collector before the application code.

     Make sure that you do not accidentally omit the src/immediate part when you set NODE_OPTIONS or add the --require parameter. The path needs to start with ./ so that Node.js identifies it as a relative path and not a module identifier. The path is evaluated based on the current working directory.

     • Set the NODE_OPTIONS variable before you start the Node.js activation process:

       NODE_OPTIONS="--require ./node_modules/@instana/collector/src/immediate"
       

       If you build the application with Docker, you need to set NODE_OPTIONS by adding the following line to your Dockerfile (after the last FROM statement and before the final CMD or ENTRYPOINT that starts the node process):

       ENV NODE_OPTIONS="--require ./node_modules/@instana/collector/src/immediate"
       

     • Alternately, add the --require parameter to the command that starts Node.js. If you normally start the application by using the node app/index.js command, add an extra --require command line argument. See the following example:

       node --require ./node_modules/@instana/collector/src/immediate app/index.js
       

       If this application is built and run by using Docker, you need to modify the final CMD or the ENTRYPOINT in your Dockerfile.

       For more information about the --require parameter, see -r, --require module in the Node.js documentation.

   • ECMAScript modules: If the application uses ECMAScript modules, follow the preceding steps in CommonJS. But, instead of using --require, select either the --import or --experimental-loader argument based on your Node.js version. For more information on ECMAScript modules, see the Node.js official documentation.

     • For Node.js 18.19.0 and later, use the following command to import the Instana collector:

        --import /path/to/instana/node_modules/@instana/collector/esm-register.mjs
       

     • For Node.js versions earlier to 18.19.0, use the following command to import the Instana collector:

        --experimental-loader /path/to/instana/node_modules/@instana/collector/esm-loader.mjs
       

     The loader automatically initializes the Instana Node.js collector.

Installing the collector globally

Experimental loaders are incompatible with Node.js versions before 18.19.

To install the collector globally, complete the following steps:

1. Install the package @instana/collector on the target system:

   • If you use npm, run the following command:

     npm install -g @instana/collector
     

   • If you use yarn, run the following command:

     yarn global add
     

   If you are installing the collector into a containerized application, you can add the preceding statement to Dockerfile.

2. Determine the location where the npm install -g command installs the package. The location depends on the operating system. For more information about where npm puts installed packages, see the Node.js documentation about folders.

3. Ensure that the package @instana/collector with all its dependencies is available on the target system in a well-known location, such as /path/to/instana/node_modules/@instana/collector.

   Ensure that @instana/collector is installed on the target system by a package manager so that all its dependencies are also correctly installed. Do not install @instana/collector elsewhere (like on a build system) and then copy the package to the target system. The npm install step includes compilation of the native add-ons, which needs to happen on the target architecture and for the correct Node.js version.

4. Activate the Node.js collector:

   • CommonJS: If the application uses CommonJS, complete either of the following steps when you start node. Setting either NODE_OPTIONS or adding --require loads and initializes the Node.js collector before the application code.

     Make sure you do not accidentally omit the src/immediate when you set NODE_OPTIONS or add the --require parameter. The path needs to start either with / or ./ so that Node.js identifies it as an absolute or relative path and not a module identifier.

     • Set the NODE_OPTIONS variable before you start the Node.js process:

       NODE_OPTIONS="--require /path/to/instana/node_modules/@instana/collector/src/immediate"
       

       You need to replace /path/to/instana with the actual path. If you build the application with Docker, you need to set the NODE_OPTIONS by adding the following line to your Dockerfile (somewhere after the last FROM statement and before the final CMD or ENTRYPOINT that starts the node process):

       ENV NODE_OPTIONS="--require /path/to/instana/node_modules/@instana/collector/src/immediate"
       

     • Alternately, add the --require parameter to the command that starts Node.js. If you normally start the application by using the node /path/to/app/ command, add an extra --require command line argument. See the following example:

       node --require /path/to/instana/node_modules/@instana/collector/src/immediate /path/to/app`.
       

       If this application is built and run by using Docker, you need to modify the final CMD or the ENTRYPOINT in your Dockerfile.

       For more information about the --require parameter, see -r, --require module in the Node.js documentation.

   • ECMAScript modules: If the application uses ECMAScript modules, follow the preceding steps in CommonJS. But, instead of using --require, select either the --import or --experimental-loader argument based on your Node.js version:

     • For Node.js 18.19.0 and later, use the following command to import the Instana collector:

        --import /path/to/instana/node_modules/@instana/collector/esm-register.mjs
       

     • For Node.js versions earlier to 18.19.0, add the following command to import the Instana collector:

        --experimental-loader /path/to/instana/node_modules/@instana/collector/esm-loader.mjs
       

Installing dependencies without a no optional flag

If you install dependencies with the npm install --no-optional or yarn --ignore-optional command, npm or yarn doesn't try to install optional dependencies.

To fix that, either remove the flags from the installation step, or add the following installation steps for the dependencies after the npm install --no-optional or yarn --ignore-optional step:

• npm install @instana/autoprofile or yarn add @instana/autoprofile
• npm install event-loop-stats or yarn add event-loop-stats
• npm install gcstats.js or yarn add gcstats.js

Compiling native add-ons in Node.js

Native add-ons are compiled automatically for your system and Node.js version when the Instana Node.js collector dependency is installed (as part of the npm install or yarn step). For successful compilation, complete the following steps:

1. Ensure that your system has tools like make, g++, and python installed. These tools can often be installed by using a bundle that is called build-essential or similar (depending on your operating system's package manager and registry).

   Use the following commands to install these tools for popular Linux distributions:

   • For Debian-based distributions (including Ubuntu):

     apt-get install build-essential
     

   • For Fedora-based distributions (CentOS or Red Hat)

     yum groupinstall "Development Tools"
     

   • For Alpine Linux

     apk add build-base python
     

2. Install the dependencies on the machine that runs the application. Otherwise, native add-ons might be incompatible with the target machine's system architecture or the Node.js version in use. Therefore, do not install the dependencies by running the command npm install or yarn on a build server, and then copy the application (including the dependencies) to the target machine.

3. If you run your Node.js application in a container, check the output of your Docker build for node-gyp errors (look for gyp ERR! and node-pre-gyp ERR!). If these errors are present, you must inspect and evaluate them. Some of them can be safely ignored. For example, some packages might try to download precompiled binary files. If this fails, they fall back to compilation through node-gyp. That is, the download error can be ignored, if the compilation step worked. Other packages emit many notes and warnings during compilation, which can also be ignored.

4. If the installation of an optional dependency ends with gyp ERR! not ok, you must investigate the issue. Instana cannot support fixing your particular Dockerfile, but can provide some example Docker files.

5. If the native add-on dependencies like gcstats.js and event-loop-stats are not installed successfully when npm install is run, the package @instana/collector automatically tries to use prebuilt binaries that match the operating system, Node.js version, and the libc variant. This feature is only available on x64 Linux. It can be disabled by setting INSTANA_COPY_PRECOMPILED_NATIVE_ADDONS=false.