Setting up agent-based Node.js monitoring

Kubernetes and Red Hat OpenShift

If your Node.js application runs in a Kubernetes and Red Hat OpenShift environment, the Instana AutoTrace webhook automatically installs the Instana Node.js collector in your cluster, follow the instructions in Installing the Instana AutoTrace webhook.

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

If your Node.js application and the Instana agent run in a Kubernetes cluster, you need to configure network access for monitored applications. For more information, see Kubernetes network access.

Native add-ons on read-only systems: Native add-ons that are compiled against a predefined Node.js version (currently v21) can cause compatibility issues with other Node.js versions (for example, v20). On read-only systems, the collector cannot unpack precompiled binary files, preventing certain native modules from loading. As a result, certain metrics, such as garbage collection data and specific event loop statistics, are not available in such environments. However, general tracing function remains unaffected. For more information, see the troubleshooting section.

Alternatively, you can manually 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 Tile 1.177.0 and later versions, install the Node.js collector by using the Instana buildpack to automate the setup of Node.js applications on Cloud Foundry.

Alternatively, you can install the Node.js collector manually.

Apigee Microgateway

To use the Instana Node.js collector package with Apigee Microgateway (also known as edgemicro), follow the instructions in Monitoring Apigee Microgateway with the Instana Node.js collector.

Next.js

For Next.js applications, install the Instana Node.js collector globally or locally and use the load flags to activate the collector.

Installing globally

As an alternative approach, you can install the Node.js collector globally by completing 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 @instana/collector
     

   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.

CommonJS

If the application uses CommonJS, activate the Node.js collector by using one of the following methods:

• Use the --require load flag for activation.
• Require and initialize the Node.js collector as the first statement in your application.

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');

ECMAScript

If your application uses ECMAScript and the @instana/collector collector that is installed as a dependency, you can activate the collector by loading the Instana Node.js collector by using the Node.js load flags.

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:

    ENV NODE_OPTIONS="--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 start your application with node app/index.js, append the appropriate --import or --experimental-loader command based on your Node.js version. 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.

--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

Bundlers

When you pre-process your Node.js server application with a bundler, such as Webpack or Rollup, make sure that you bundle only your code and 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

If you are using a transpiler, such as TypeScript or Babel, make sure that your transpiler produces CommonJS or ECMAScript dist code.

Initialize the tracer via the load flags for CommonJS and ECMAScript.

For more information about accessing the SDK within your code, see ECMAScript modules.

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