TracesMetricsApp LogsCustom LogsProfiling

This guide walks you through setting up Application Performance Monitoring (APM) on a Node.js application. These instructions can also be found on the Installation page in your Middleware Account. View example code here.



Infra Agent

Infrastructure Agent (Infra Agent). To install the Infra Agent, see our Installation Guide.


Node.js Version

Node.js version 18.17.1 or above. Check your Node.js version with the following command:

node --version

Python Version

Python version 3.8 or above. Check your Python version with the following command:

python3 --version


Step 1: Install Node.js APM Package

Run the following command in your terminal:

npm install --save

Step 2: Initialize Tracker

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.

const tracker = require('');
    serviceName: "your-service-name",
    accessToken: "<xxxxxxxxxx>"

Step 3: Container Variables


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.

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


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

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


Step 4: Capture Application Data


Distributed tracing is automatically enabled upon completion of Step 2.

Span Attributes

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

Node.js"/email/send", async (req, res) => {
  const 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.

Node.js'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.

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:

const express = require("express");
const app = express();
const tracker = require("");

// Initialize the tracker
  // 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: "<your_key_here>",
  // 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>",

// Create a tracer, used to create spans.
const tracer = tracker.getTracer();

// Create a meter, used to create custom metrics.
const meter = tracker.getMeter();

// Create a counter metric.
// For a list of other metric types, see the opentelemetry metrics API
// documentation. (
let counter = meter.createCounter("health-check-counter");

 * Generate a random integer between 0 and the range provided.
 * @param {Number} range
 * @returns {Number}
function randInt(range) {
  // Create a span. A span must be closed.
  return tracer.startActiveSpan("randInt", (span) => {
    const randomInt = Math.floor(Math.random() * range);
    // Be sure to end the span
    return randomInt;

app.get("/randInt", (req, res) => {
  // Calling the randInt function will generate a span.
  const randomInt = randInt(100);
  res.json({ number: randomInt });

app.get("/health", (req, res) => {
  // Increment the health-check-counter by 1.
  res.json({ status: "ok" });

app.listen(5051, () => {
  console.log("Server is running on port 5051");


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.

app.get('/error', function (req, res) {
        throw new Error('oh error!');
    }catch (e) {

NestJS Framework [Optional]

Step 1: Install Node Typescript APM

npm install mw-node-apm-ts

Step 2: Import Package in main.ts

Import the following package in your main.ts file:

import { track } from 'mw-node-apm-ts';

async function bootstrap() {
      serviceName: 'NestJS Test',
      accessToken: 'your-api-token',

    const app = await NestFactory.create(AppModule, { bufferLogs: true });

    await app.listen(PORT || 3000);


Step 3: Capture Application Data

The following is a sample function that fetches a user’s email address and throws an error if the user is not found, while also logging the error using a third-party logging function.

Use the below pattern for any other available methods that are mentioned in Step 4.

import { error } from 'mw-node-apm-ts';

async sampleCode(data: userDto): Promise<IResponse> {
    const user = await this.userService.getUserByEmail(;

    if (!user) {
      error('User not found');

      throw new UnprocessableEntityException({
        status: HttpStatus.UNPROCESSABLE_ENTITY,
        errors: {
          email: 'User not found!',

Continuous Profiling

Continuous profiling captures real-time performance insights from your application to enable rapid identification of resource allocation, bottlenecks, and more. Navigate to the Continuous Profiling section to learn more about using Continuous Profiling with the Node.js APM.


node-gyp Failing/Missing Dependencies

If node-gyp fails to build or your infrastructure is missing dependencies, run the following command:

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

Running Apps on Docker

If you are unable to run your Node.js app on Docker, open port 9319 locally to enable proper firewall configurations.

Need assistance or want to learn more about Middleware? Contact us at support[at]