Installing the Node.js collector

You can install the Node.js collector to monitor Node.js applications in your environment.

Before you begin

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:

Incorrect collector integration

Incorrectly integrating the collector with your Node.js application can result in reduced observability for your application in Instana. While your application is displayed in Instana, tracing works only partially. Some calls are traced, while others are missed.

  • CommonJS: When you use CommonJS, putting the require statement as the first statement in your application and calling the function that is exported by require('@instana/collector') later is not sufficient.

    The following examples show incorrect collector integration:

    // WRONG!
require('@instana/collector'); // @instana/collector is not initialized

require('something');
require('another-thing');

...

    // WRONG!
const instana = require('@instana/collector');

require('something');
require('another-thing');

instana(); // TOO LATE!
...

    Instead, you need to call the function that is exported by require('@instana/collector') immediately before any other require or import statements. You can either call the function in one statement as shown in Step 2 in Installing the Node.js collector (note the second pair of parentheses in require('@instana/collector')()) or in two consecutive statements as follows:

    // Correct:
const instana = require('@instana/collector');
instana(); // this is fine

// Now all other modules can be required:
require('something');
require('another-thing');
...

  • ECMAScript modules: When you use ECMAScript modules (ESM), do not import or require the collector in the code as follows:

    import instana from '@instana/collector'
instana()
import { something, else } from 'some-module';

    Instead, load the collector by using the experimental loaders flag.

Tracing with multiple tracers

Do not trace a single Node.js application with Instana and a third-party tracer (for example, New Relic, Dynatrace, or Datadog) at the same time.

Using OpenTelemetry

Do not use both the OpenTelemetry SDK and the Instana collector in the same Node.js application. If you use both, the following problems might occur:

  • Missing call in Instana
  • Duplicated data in Instana
  • Broken instrumentations

However, if you want to use the OpenTelemetry SDK, see Node.js OpenTelemetry integration.

Start here

Use the installation method that is most suitable for your application's platform and build scenario. Start with the following sections, which lead you to the steps to install the Node.js collector.

Installing the Node.js collector for different build scenarios

If you use a bundler (like Webpack or Rollup) or a transpiler (like Babel, Traceur, or the TypeScript compiler tsc), use the section that is provided to guide you to the steps for installing the Node.js collector and any other considerations for your build scenario.

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:

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:

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.

Deploying the Node.js collector on different platforms

Use the section provided to guide you to the steps for installing the Node.js collector and any other considerations for the platform that your Node.js application runs on.

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.

Instana AutoTrace webhook

The Instana AutoTrace webhook is an implementation of a Kubernetes Mutating webhook Admission Controller that automatically configures all the requirements to run Node.js applications across an entire Kubernetes cluster.

If you install the Instana AutoTrace webhook on your Kubernetes clusters, you needn't manually trace any of your Node.js applications that are running in those clusters.

If you use the Instana AutoTrace webhook and you want to use the Instana Node.js SDK, review the using the API together with the AutoTrace webhook section.

Installing the Node.js collector manually

If your Node.js application and the Instana agent that is run in a Kubernetes cluster, you need to install the Node.js collector package and configure network access for monitored applications. For more information about the required configuration, see Kubernetes network access.

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

Ensure that you read through the Start here section.

Important:
  • ECMAScript support was added in Node.js collector 2.14.0.
  • Some ECMAScript modules features are in the experimental phase. For more information, see official documentation.

To install the Instana Node.js collector, complete the following steps:

  1. Install the npm package @instana/collector in your application:

    npm install --save @instana/collector

  2. Activate the collector from within the Node.js application:

    To activate the collector in your Node.js application, see the CommonJS and ECMAScript sections.

CommonJS

If the application uses CommonJS, activate the collector within the application by requiring and initializing it as the first statement in your application.

Ensure that this line is the first statement otherwise the collector cannot access certain information. For more information about correctly adding this line, see Incorrect collector integration.

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

// All other require statements must be done after the collector is initialized.
// Note the () after the require statement of the collector which initializes it.


// const express = require('express');

The preceding code initializes the collector with default configuration options. You can also pass in a configuration object when you initialize the Instana Node.js collector. For a list of valid configuration options, see Node.js Collector Configuration. For more information about configuring connectivity between your monitored application and the Instana agent, see Agent communication.

ECMAScript

If your application uses ECMAScript and the @instana/collector collector is installed as a dependency, activate the collector for the application by loading the Instana Node.js collector through the Node.js command line flags. Follow the instructions in the ECMAScript section.

Installing the Node.js collector without modifying your application

In situations where you cannot (or do not want to) modify the source code of the monitored application, you can install the collector without modifying the source code. This approach is preferred for applications that are built with Webpack, Babel, or any other bundler or transpiler. Also, you can use this approach for Next.js applications.

By using this approach, you can install the collector in either of the following ways:

  • Install @instana/collector as a local dependency of your project
  • Install @instana/collector globally on the target system.

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 require('@instana/collector')(); function to your code. None of your JavaScript or TypeScript files need to mention @instana package.

  2. Activate the Node.js collector:

    To activate the collector in your Node.js application, see the CommonJS and ECMAScript sections.

CommonJs

For applications that use CommonJS, complete one of the following steps when you start the Node.js executable. Using either NODE_OPTIONS or the --require flag loads and initializes the Node.js collector before your 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

If the application uses ECMAScript modules, complete either of the following steps when you start the node executable. Setting NODE_OPTIONS or selecting either the --import or --experimental-loader argument based on your Node.js version loads and initializes the Node.js collector before the application code. For more information on ECMAScript modules, see the Node.js official documentation.

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

    If you build the application with Docker, 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):

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

      ENV NODE_OPTIONS="--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"

  • Alternately, include the --import or --experimental-loader parameter when you start Node.js. If you launch your application with node app/index.js, append the appropriate --import or --experimental-loader command based on your Node.js version to the command line argument. See the following example:

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

      node --import /path/to/instana/node_modules/@instana/collector/esm-register.mjs app/index.js

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

      node --experimental-loader /path/to/instana/node_modules/@instana/collector/esm-loader.mjs app/index.js

    The loader automatically initializes the Instana Node.js collector.

Enable the collector on Windows

If the application uses ECMAScript modules and your operating system is Windows, prepend file:/// to the path for the ECMAScript loader:

--import file:///path/to/instana/node_modules/@instana/collector/esm-register.mjs
or
--experimental-loader file:///path/to/instana/node_modules/@instana/collector/esm-loader.mjs

Installing the collector globally

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.

  4. Activate the Node.js collector:

    • CommonJS: If the application uses CommonJS, follow the steps in the CommonJS section.

    • ECMAScript modules: If the application uses ECMAScript modules, follow the steps in the ECMAscript section.

Native add-ons

The tracer installs the following native add-ons:

  • gcstats.js: Retrieves information about garbage collection.
  • event-loop-stats: Retrieves information about event loop activity.
  • autoprofile: Investigates performance issues or bottlenecks. The AutoProfile™ is disabled by default. To enable AutoProfile™, see Node.js collector configuration.

These add-ons are "optional npm dependencies". If they can't be installed on your system, the collector still works as expected. If you are experiencing a problem with the add-ons, see the troubleshooting section. For more information about C++ add-ons requirements, see the official Node.js docs or node-gyp.

Installing dependencies without optional dependencies

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

To fix the issue of not installing the native add-ons by npm or yarn, either remove the flags from the installation step, or add the following installation steps:

  • 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

Disabling the Node.js collector during development

You can use environment variables to disable the Node.js collector for (local) development. The Express framework popularized the environment variable NODE_ENV for this purpose.

To disable the Node.js collector, complete the following steps:

  1. Load the Node.js collector in the following way:

    if (process.env.NODE_ENV !== 'development') {
  require('@instana/collector')();
}

  2. Start your application locally with the NODE_ENV variable set to development. See the following examples:

    export NODE_ENV=development

    NODE_ENV=development node myApp.js

Troubleshooting

Could not load @instana/autoprofile

The following error occurs if the client or customer needs to enable the AutoProfile™:

Could not load @instana/autoprofile. You will not get profiling information for this Node.js app in Instana, although autoprofiling has been enabled.

To fix this error, check whether your Node.js version is supported and run the npm rebuild command.

Copying the precompiled build

The following error usually happens when the Node.js Tracer tries to unpack the precompiled binaries and the tmp folder is not writeable (for example, in Kubernetes pod’s):

Copying the precompiled build for event-loop-stats (linux/x64/musl/ABI 108) failed. [Error: ENOENT: no such file or directory, lstat '/tmp/event-loop-stats'] {
  errno: -2,
  code: 'ENOENT',
  syscall: 'lstat',
  path: '/tmp/event-loop-stats'
}

To fix the copying of the precompiled build error, check whether the system is in not readonly mode.

Fixing Ecmascript URL Scheme Error on Windows

The following error often occurs when you enable the Instana collector in a Windows ECMAScript application:

Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only file and data URLs are supported by the default ESM loader.

This error arises when you specify an absolute path in the loader commands. To resolve this issue, prepend file:/// to the path. For more information, see the Enable collector on Windows section.

runtime-version-switch module not found error message

The following error is displayed if the AutoTrace webhook instrumentation version is outdated but the Node.js collector is updated to the latest version. This error occurs due the removal of the runtime-version-switch script from the AutoTrace webhook.

Error: Cannot find module '/opt/instana/instrumentation/nodejs/runtime-version-switch'
Require stack:
- internal/preload
  at Module._resolveFilename (node:internal/modules/cjs/loader:1144:15)
  at Module._load (node:internal/modules/cjs/loader:985:27)
  at Function.patchedModuleLoad [as _load] (/opt/instana/instrumentation/nodejs/node_modules/@instana/core/src/util/requireHook.js:93:34)

Although you are on the latest AutoTrace webhook, the already deployed Kubernetes artifacts might reference an outdated instrumentation image.

To resolve the runtime-version-switch module not found error message, complete the following steps: 1. Uninstall the AutoTrace webhook. 2. Redeploy the AutoTrace webhook to apply the changes.