Troubleshooting

You might encounter the following monitoring issues while you configure and monitor Node.js applications. 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:

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

Verify that the process is instrumented

If the @instana/collector package is added to your application and correctly activated, you can see 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. For more information about the steps to install the Instana Node.js collector depending on your application, see Installing the Node.js collector. For more information about the pitfalls that you can encounter over time, see the Common installation considerations section.

If your Node.js application runs in Kubernetes, try out the Instana AutoTrace webhook, which automatically and transparently adds the Node.js instrumentation to your pods.

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.

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, network visibility issues occur between the container with the application to be traced and the container of the Instana host agent. Another related issue is when the application container to be traced cannot connect to the Instana agent container on the same host due to some overlay network setup.

Often the problem is that the Node.js collector uses the wrong IP address or DNS name to communicate to the Instana agent. You can instruct the Node.js collector to use a specific network address by using the INSTANA_AGENT_HOST environment variable.

In rare cases, customers set up their networking so that the problem is not the network address, but the port the collector uses.

If you need a port remapping because the host agent does not listen on port 42699 but something else, you can instruct 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.

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

One common reason for the installation failure of @instana/autoprofile (in particular for containerized applications) is 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.

Another possible root cause is how 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.

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

For more information, see Native add-ons.

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.