Monitoring Node.js

You can monitor your Node.js applications by using the Instana Node.js collector to identify bottlenecks and optimize application performance. After you install the Instana host agent, install and activate the Node.js collector (also known as Node.js Tracer) in your application. You can then view metrics and traces that are related to Node.js in the Instana UI.

Instana Node.js collector

The Instana Node.js collector is an npm package that you add to the dependencies of your Node.js apps. It enables metrics collection and automatic tracing and reports metrics and traces to Instana.

This collector requires an agent to be installed. For more information, see Installing host agents.

Instana agentless Node.js collector

If you want to avoid installing a host agent on a server, use the Instana serverless collector. For more information about monitoring Node.js application by using the Instana serverless collector, see Agentless monitoring of Node.js (public preview).

Limitations of Node.js collector

The Instana Node.js collector package is exclusively for monitoring Node.js server applications with Instana.

For monitoring Node.js applications that run on the following platforms, see their corresponding pages:

If your serverless environment is not on the preceding list, try out the Instana serverless collector. For more information, see Agentless monitoring of Node.js (public preview).

Prerequisites for monitoring Node.js

Before you set up monitoring for Node.js applications, complete the following prerequisites:

  • Install the Instana host agent. For more information, see Installing host agents.
  • Check the Support information section to make sure that the Instana Node.js collector is compatible with your current setup.
  • Check whether the collector supports the specific libraries and frameworks that you are using. For more information, see Supported libraries for tracing.

Setting up monitoring

To set up monitoring for Node.js applications, complete the following steps:

  1. Install and activate the Node.js collector.

  2. Configure the Node.js collector.

    If you use Kubernetes, Red Hat OpenShift, or Cloud Foundry, additional configuration is required. For more information, see Configure additional settings

After you set up monitoring, tracing is enabled by default. For more information about the available tracing support for Node.js applications, see Tracing support.

You can then view the gathered metrics and traces in the Instana UI. For more information, see Viewing metrics.

Installing the Instana Node.js collector

To install the Instana Node.js collector and enable Instana to monitor your Node.js applications, install the npm package @instana/collector by running the following command:

npm install --save @instana/collector

After the collector is installed, you need to activate it within the application. To activate the collector correctly, load and initialize it before any other files are loaded. To achieve that, add the following line as the first statement to your application code:

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

For more information, see Installing Node.js collector.

Kubernetes

If your Node.js applications are run exclusively on Kubernetes, you can use the Instana AutoTrace webhook method instead, which require no modifications to your applications.

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

Apigee Microgateway

For more information about how to use the Instana Node.js collector package with Apigee Microgateway (also known as edgemicro), see the Apigee Microgateway page.

Configuring the Node.js collector

For more information on how to configure the Instana Node.js collector, see Node.js collector configuration.

Configuring additional settings

If your setup includes Kubernetes, Red Hat OpenShift, or Cloud Foundry, you need to configure additional settings.

Kubernetes and Red Hat OpenShift

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.

Cloud Foundry

Notes:

  • The Instana agent can run on the Diego cells of the Cloud Foundry foundation. Diego's cells are the fundamental units of execution within the Cloud Foundry Diego runtime. They provide the necessary infrastructure for running applications on Cloud Foundry. Each Diego cell is a virtual or physical machine that is responsible for managing and running application instances, including tasks such as scheduling, scaling, and health monitoring. Without an agent that is running on the underpinning Diego cell, monitoring Cloud Foundry applications is not supported.

  • For Tile 1.177.0 and later versions, the instana_buildpack automates the setup of Node.js applications on Cloud Foundry. For more information, see Instana buildpack.

For more information about how to set up Instana host agents and the related Cloud Foundry or Pivotal Platform functions, see Cloud Foundry and Pivotal Platform.

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.

API

The Instana Node.js collector package provides an API for custom tracing. For more information, see API page.

Viewing metrics

To view the metrics, complete the following steps:

  1. From the sidebar of the Instana UI, select Infrastructure.
  2. Click a specific monitored host.

You can see a host dashboard with all the collected metrics and monitored processes.

Tracked configuration Metrics
Runtime versions GC activity
Deployed apps Memory usage
Name Heap Spaces
Version Event Loop
Description HTTP Servers - Request/Response Times
Arguments Health check status and time of last status change
Dependencies
HTTP Servers Config
Health checks (through admin-plugin-healthcheck)

The dependencies of a Node.js process can also be retrieved from the software versions API endpoint.

Health Signatures

Health check support

The Instana Node.js collector conducts custom health checks and runs them every ten seconds. If the checks fail for at least 30 seconds, an issue is raised to inform the user.

Health checks are gathered from installed admin-plugin-healthcheck modules.

Health check

Health checks are listed in the Node.js dashboard. Then, an issue about failing health checks is raised.

Issue

Node.js EOL version warning

Starting from 1.136.0, the collector sends an issue event when applications are running under an EOL (end of life) version of Node.js.

EOL Node.js versions no longer receive updates, which leaves applications vulnerable to security issues and miss important runtime improvements, like CPU and memory consumption optimization.

Customers relying on these versions are encouraged to update to active versions of Node.js.

Important: Despite the recommendation to use actively maintained runtimes, Instana supports older versions of Node.js.

Tracing support

Instana supports the following tracing:

OpenCensus Instana Trace Exporter

Instana provides an OpenCensus Trace Exporter for applications that are written in Node.js. By using the Instana agent processes as a proxy, Instana forwards traces that are exported by applications that are instrumented with Census to the Instana backend.

For more information, see the OpenCensus Exporters website.

AutoProfile™

This feature is in public preview.

AutoProfile™ generates and reports process profiles to Instana automatically and continuously. For more information about profiles, see Analyze profiles.

To enable AutoProfile™, see Node.js collector configuration.

Troubleshooting

You might encounter some monitoring issues while you configure and monitor Node.js applications. For more information, see Troubleshooting.