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 does not connect with the agent to send traces and metrics due to one of the following reasons:

  • The @instana/collector package is not installed correctly in the Node.js application.
  • The Node.js process cannot report to the host agent on the same host due to network connectivity issues.

To resolve this issue, complete the following steps:

Verify that the Node.js process is instrumented

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.

To ensure that the Node.js process is correctly instrumented, troubleshoot as follows:

Fix networking 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.

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

To ensure that tracing works correctly, require and initialize the @instana/collector package before any other Node.js packages. However, the @instana/collector package can detect that it is initialized too late. If other packages were loaded before its initialization, the nodejs_collector_initialized_too_late warning is displayed on your Node.js dashboard. For more information, see Installing the Node.js collector and Common installation considerations.

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

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.

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.

Missing calls due to 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. The solution for these use cases is to 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.