Troubleshooting

You might encounter the following monitoring issues while you configure and monitor Node.js applications with Instana. For more information about monitoring Node.js applications, see Monitoring Node.js.

Node.js collector not installed

Monitoring issue type: nodejs_collector_not_installed

The Node.js process is unable to connect with the agent to send traces and metrics.

Cause:

This issue can occur due to one of the following reasons:

  • Incorrect installation of the @instana/collector package: If the @instana/collector package is added to your application and correctly activated, you can see the following entries in your application logs:

    Attempting agent communication via <hostname>:<port>

    If you do not see any such message in your application log, the package @instana/collector is probably not installed and initialized correctly.

    Incorrect integration of the collector with your Node.js application can reduce the observability for your application in Instana. Although your application is displayed in Instana, tracing works only partially. Some calls are traced, while others are missed.

  • Network connectivity issues: If the Node.js collector is installed, and you see the following message in your application logs, the @instana/collector package cannot communicate with the host agent due to a networking issue:

    Announce attempt failed: <error>. Will retry in <seconds>s.

Solution:

To resolve this issue, troubleshoot as follows:

Verifying collector integration

To verify the collector integration, see the following sections:

CommonJS

If you use CommonJS, call the function that is exported by require('@instana/collector') immediately before any other require or import statements. You can call the function in one of the following ways:

  • Call the function in a single statement:

    require('@instana/collector')()

  • Call the function 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');
...

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

ECMAScript modules

If you use ECMAScript modules (ESM), load and initialize the collector by using the load flags. Do not initialize the collector in the code as follows:

import instana from '@instana/collector'
// Wrong!
instana()

import { something, else } from 'some-module';

Fixing networking issues

To resolve networking issues, troubleshoot as follows:

  • Verify that the Node.js process can connect to the host agent on the same host on port 42699. For more information about the required network visibility, see Network requirements for the Instana host agent.

  • In containerized platforms, check network visibility between the container with the application to be traced and the container of the Instana host agent. Ensure that no overlay network setup issue exists when the application container to be traced tries to connect to the Instana agent container on the same host.

  • Ensure that the Node.js collector uses the correct IP address or DNS name to communicate to the Instana agent. If you need to change the network address, you can instruct the Node.js collector to use the INSTANA_AGENT_HOST environment variable.

  • Ensure that the host agent is listening on port 42699. If you need a port remapping because the host agent does not listen on port 42699 but something else, you can configure the collector to use a different port by using the INSTANA_AGENT_PORT environment variable.

If none of the preceding solutions help you troubleshoot the issue, open a Support ticket.

Collector initialized too late

Monitoring issue type: nodejs_collector_initialized_too_late

When the @instana/collector package is initialized after other Node.js packages are loaded, you can view the nodejs_collector_initialized_too_late warning displayed on your Node.js dashboard.

Cause:

This error occurs due to loading other Node.js packages before requiring and initializing the @instana/collector package. For more information, see Installing the Node.js collector and Verifying collector integration.

Solution

To resolve this issue, update your code to require and initialize the @instana/collector package before any other initializations. For more information, see Activating the collector.

AutoProfile package missing or loading issue

Monitoring issue type: nodejs_collector_native_addon_autoprofile_missing

You configured the Node.js process to use Instana's AutoProfile feature, but the package @instana/autoprofile might not be loaded. As a result, you do not get profiling information for this Node.js application in Instana.

Error message:

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

Cause:

The package @instana/autoprofile is an optional dependency of @instana/collector, and it is automatically installed when possible. But because it is a native add-on, its installation can fail. For more information, see Native add-ons.

The installation failure of @instana/autoprofile (in particular for containerized applications) can be due to any of the following reasons:

  • The absence of necessary operating system packages for building C++ code. This issue occurs when these packages are missing on the target machine or within the target container image.

  • The way the container image is built. Node.js packages need to be installed on in the target image. Running npm install or yarn on a build system and then copying the entire node_modules folder to a container image with a potentially different architecture or operating system does not work. This step needs to happen inside the target image.

  • If the commands npm install --no-optional or yarn --ignore-optional are used to install dependencies, the package can also be missing.

  • The @instana/autoprofile module is not compatible with the current Node.js version.

Solution:

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

Missing or duplicated calls

Error:

Sometimes Instana might miss capturing some calls or display duplicated calls, resulting in incomplete or inaccurate tracing data.

Cause:

Missing or duplicated calls can occur due to the following reasons:

  • Unsupported triggers: Usually, Instana tracers capture only outgoing calls when an active entry span exists. In some edge cases, this rule can lead to calls that you expect to be captured are not captured. For example, when work is triggered by a mechanism that is not supported by Instana automatic instrumentation.
  • Tracing with multiple tracers: Using Instana along with a third-party tracer (such as New Relic, Dynatrace, or Datadog) in the same Node.js application can cause missing or duplicated calls and Node.js instrumentation failures.

Solution:

To resolve or prevent this issue, follow these steps:

  • Use Custom Tracing for Unsupported Triggers: Create an entry span through custom tracing by using the Instana Node.js SDK. For more information about the Node.js SDK, see Tracing is inactive when no active entry span exists.

  • Avoid Tracing with Multiple Tracers: Refrain from tracing a single Node.js application with multiple tracers at the same time.

Precompiled build copy failure

Error message:

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

Cause:

This 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 pods).

Solution:

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

Unsupported ECMAScript URL Scheme on Windows

Error message:

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

Cause:

This error arises when you specify an absolute path in the loader commands.

Solution:

To resolve this issue, prepend file:/// to the path. For more information, see Enable collector on Windows.

Runtime version switch module missing

Error message:

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)

Cause:

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

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

Solution:

To resolve this issue, complete the following steps:

  1. Uninstall the AutoTrace webhook.
  2. Redeploy the AutoTrace webhook to apply the changes.