Node.js

This guide provides instructions to set up Application Performance Monitoring (APM) in a Node.js application. You can also find these instructions on the installation page in your Middleware account. For example code, view here.

Prerequisites

1. Node.js 18.17.1+: Verify with node --version
2. Python Version 3.8+ Verify with python3 --version

Installation

1 Install Node.js APM Package

Run the following command in your terminal:

shell

Shell

npm install @middleware.io/node-apm --save

2 Setup Options

With Host

Serverless

Host based APM requires the Middleware Agent which can be installed using the relevant OS based instructions. here.

Method 1: Direct Code Initialization

Add the following lines to the beginning of your application code base. The access token is your account key, which can be found on the Installation page.

index.js

Javascript

Your API Keys

const tracker = require('@middleware.io/node-apm');
tracker.track({
    serviceName: "your-service-name",
    accessToken: "<MW_API_KEY>",
});
// must come before importing any other module.
// At the very top of the entrypoint
const express = require('express'); // other dependencies

If you want to track APM data across different deployments of your application. You can pass along the app.version,

For Example, If your deployment version is 1.2.0 the config should look something like this.

index.js

Javascript

Your API Keys

const tracker = require('@middleware.io/node-apm');
tracker.track({
    serviceName: "your-service-name",
    accessToken: "<MW_API_KEY>",
    customResourceAttributes: {
      "app.version": "1.2.0",
    }
});

Method 2: Add the tracker with command line arguments

Create a file named instrument.js or instrument.ts in your project root:

instrument.js

Javascript

Your API Keys

// instrument.js
const tracker = require('@middleware.io/node-apm');
tracker.track({
    serviceName: "your-service-name",
    accessToken: "<MW_API_KEY>",
    customResourceAttributes: {
      "app.version": "1.2.0",
    }
});

To ensure the tracker is initialized before any other code runs, use the --require flag when starting your Node.js application:

Shell

Javascript

node --require ./instrument.js your-main-app.js

Method 1: Direct Code Initialization

Add the following lines to the beginning of your application code base. The access token is your account key, which can be found on the Installation page.

index.js

Javascript

Your API Keys

const tracker = require('@middleware.io/node-apm');
tracker.track({
    serviceName: "your-service-name",
    accessToken: "<MW_API_KEY>",
    target: "https://<MW_UID>.middleware.io:443",
});
// must come before importing any other module.
// At the very top of the entrypoint
const express = require('express'); // other dependencies

If you want to track APM data across different deployments of your application. You can pass along the app.version,

For Example, If your deployment version is 1.2.0 the config should look something like this.

index.js

Javascript

Your API Keys

const tracker = require('@middleware.io/node-apm');
tracker.track({
    serviceName: "your-service-name",
    accessToken: "<MW_API_KEY>",
    target: "https://<MW_UID>.middleware.io:443",
    customResourceAttributes: {
      "app.version": "1.2.0",
    }
});

Method 2: Add the tracker with command line arguments

Create a file named instrument.js or instrument.ts in your project root:

instrument.js

Javascript

Your API Keys

// instrument.js
const tracker = require('@middleware.io/node-apm');
tracker.track({
    serviceName: "your-service-name",
    accessToken: "<MW_API_KEY>",
    target: "https://<MW_UID>.middleware.io:443",
    customResourceAttributes: {
      "app.version": "1.2.0",
    }
});

To ensure the tracker is initialized before any other code runs, use the --require flag when starting your Node.js application:

Shell

Javascript

node --require ./instrument.js your-main-app.js

3 Container Variables

No Container Variables Required in case of serverless mode

Docker

Applications running in a container require an additional environment variable. If your application is not running in a container, move to Step 4.

For Docker containers, add the following environment variable to your application.

Bash

bash

MW_AGENT_SERVICE=<DOCKER_BRIDGE_GATEWAY_ADDRESS>

The DOCKER_BRIDGE_GATEWAY_ADDRESS is the IP address of the gateway between the Docker host and bridge network. This is 172.17.0.1 by default. Learn more about Docker bridge networking here

Kubernetes

Bash

bash

kubectl get service --all-namespaces | grep mw-service

Then add the following environment variable to your application deployment YAML file.

Bash

bash

MW_AGENT_SERVICE=mw-service.mw-agent-ns.svc.cluster.local

4 Capture Application Data

Traces

Distributed tracing is automatically enabled upon completion of Step 2.

Span Attributes

For any automatically instrumented endpoints, add the following code snippet:

router.post("/email/send", async (req, res) => {
  const email  = req.body.email;
  tracker.setAttribute("email", email);
  res.json({ status: "email sent" });
});

Custom Logs

To ingest custom logs into Middleware, utilize the following functions inside your logging method based on desired log severity levels.

index.js

Javascript

tracker.info('Info sample');
tracker.warn('Warning sample');
tracker.debug('Debugging Sample');
tracker.error('Error Sample');

To add stack traces along with the error log, use the following error tracking function.

index.js

Javascript

tracker.error(new Error('Error sample with stack trace'));

Custom Metrics and Spans

Create custom instruments and spans by exposing the meter and tracer with the following pattern:

index.js

Javascript

Your API Keys

const tracker = require("@middleware.io/node-apm");
// Initialize the tracker
tracker.track({
  // Service name differentiates your applications in the APM section of the Middleware platform.
  serviceName: "<your_service_name_here>",
  // You can find your access token in the Middleware platform by going to the installation page.
  accessToken: "<MW_API_KEY>",
  // The target is your Middleware platform URL.
  // When you login to the Middleware platform, you can find your target URL in the URL bar.
  target: "<your_mw_url_here>",

View more

Profiling

Application Profiling is auto-configured upon completing Step 2.

Stack Traces

Use the errorRecord method to record a stack trace when an error occurs. See an example of this method below.

index.js

Javascript

app.get('/error', function (req, res) {
    try{
        throw new Error('oh error!');
    }catch (e) {
    track.errorRecord(e)
    }
    res.status(500).send("wrong");
});

Continuous Profiling

Continuous profiling captures real-time performance insights. Access this feature under the APM > Continuous Profiling section in the Middleware platform.

Environment Variables

The following environment variables can be used to configure the Middleware APM tracker:

Customizing Resource Detection with OTEL_NODE_RESOURCE_DETECTORS

Specifies which resource detectors to use. Each detector provides specific information about the application's environment.

Default: env, process, host, os, container, serviceinstance

Possible values: env, process, serviceinstance, os, host, container, aws, azure, gcp, none, all

Example: OTEL_NODE_RESOURCE_DETECTORS=env,process,host,aws

Disabling Specific Instrumentations with MW_NODE_DISABLED_INSTRUMENTATIONS

Disables specific instrumentations to exclude certain types of data collection.

Note: File System (fs) instrumentation is permanently disabled due to performance issues.

Possible values: dns, net

Example: MW_NODE_DISABLED_INSTRUMENTATIONS=dns,net

Configuration Options

In addition to using environment variables, you can configure the Middleware APM tracker directly through the tracker.track() call. Here are the configuration options you can use: (env variables have higher priority)

Usage Example

index.js

Javascript

Your API Keys

const tracker = require('@middleware.io/node-apm');

tracker.track({
  serviceName: "my-service",
  accessToken: "your-access-token",
  projectName: "my-project",
  pauseTraces: false,
  pauseMetrics: false,
  consoleExporter: true,
  customResourceAttributes: {

View more

Graceful Shutdown (Optional)

The Middleware APM tracker provides a sdkShutdown function for graceful shutdown. This ensures all pending telemetry data is sent before your application exits. Call tracker.sdkShutdown() when your application is about to exit to ensure all data is properly flushed.

Usage

const tracker = require('@middleware.io/node-apm');

// Initialize the tracker
tracker.track({
  // Your configuration options
});

// Handle application shutdown
process.on('SIGINT', async () => {
  console.log('SIGINT signal received. Shutting down gracefully');

Legacy Node.js Support (Node.js 10+)

For applications running on legacy Node.js versions (10.x and above), Middleware provides a separate package with limited feature support and uses older OpenTelemetry libraries.

Installation

Install the legacy package using npm:

npm install @middleware.io/node-apm-legacy

Basic Setup

Add the following code at the entry point of your application:

const tracker = require('@middleware.io/node-apm-legacy');
tracker.track({
    serviceName: "your-service-name",
    accessToken: "<MW_API_KEY>",
    target: "https://<MW_UID>.middleware.io:443",
});
// must come before importing any other module.
// At the very top of the entrypoint
const express = require('express'); // other dependencies

const tracker = require('@middleware.io/node-apm-legacy');
tracker.track({
    serviceName: "your-service-name",
    accessToken: "<MW_API_KEY>",
});
// must come before importing any other module.
// At the very top of the entrypoint
const express = require('express'); // other dependencies

Basic Troubleshooting Guidelines

If you're experiencing issues with the Middleware APM tracker or not seeing the expected data, try the following steps:

1. Enable Debug Logging: Set the DEBUG flag to true in your configuration or use the environment variable to get more detailed logs:

   tracker.track({
     // other options...
     DEBUG: true
   });

   

2. Check Configuration: Ensure all required fields (like serviceName , accessToken , target and accessToken) are correctly set.

3. Initialize Tracking Function: Make sure your tracker.track() is initialized at the very top of the main server file.

4. Instrumentation Issues: If specific instrumentations aren't working, check if they're accidentally disabled in your configuration.

5. Resource Detection: If you're not seeing expected resource attributes, verify your OTEL_NODE_RESOURCE_DETECTORS setting.

6. Restart Your Application: Sometimes, a simple restart after configuration changes can resolve issues.

7. Agent Health Check: If you're using the Middleware Agent, the SDK performs a health check at startup. If you see a warning message about the health check failing, it could be due to:

   • Incorrect value of MW_AGENT_SERVICE

   If the problem persists, verify your agent configuration and ensure it's running correctly.

8. OpenTelemetry Dependency Conflicts: If you're using OpenTelemetry in your application code alongside the Middleware Node SDK, ensure that the versions are compatible. Conflicting versions can lead to unexpected behavior. Check the OpenTelemetry version used by the Middleware SDK (you can find this in the SDK's package.json) and make sure your application's OpenTelemetry dependencies match or are compatible with this version.

If problems persist after trying these steps, please contact Middleware support with your debug logs and configuration details (with sensitive information redacted).

Frequently Asked Questions (FAQ)

sudo apt-get build-dep build-essential
sudo apt-get install gcc g++ make

npm i @opentelemetry/[email protected] --save

RUN apk --no-cache add build-base
RUN apk add --update --no-cache python3 && ln -sf python3 /usr/bin/python

npm i @opentelemetry/[email protected] // or any other new version

node --experimental-loader=@opentelemetry/instrumentation/hook.mjs --import instrument.js app.js

sudo apt-get build-dep build-essential python3
sudo apt-get install gcc g++ make

RUN apk --no-cache add build-base
RUN apk add --update --no-cache python3 && ln -sf python3 /usr/bin/python