Manually install the Node.js probe - Cloud Monitor - Alibaba Cloud Documentation Center

Prerequisites

Your build environment can connect to the public internet or the Alibaba Cloud internal network, and its security group allows outbound TCP traffic on ports 80 and 443.
Your Node.js version is 14.x or later.
Your project uses npm, yarn, or pnpm as the package manager.

Usage notes

If your application uses a supported framework such as Express, Koa, or Fastify, the probe automatically performs non-intrusive instrumentation.
For applications with custom startup scripts, make sure the probe loads before the application starts.
If your application uses cluster mode, make sure the probe is loaded in each worker process.

Step 1: Install the probe SDK

Choose an installation method:

Install from the npm repository: npm install @loongsuite/cms_node_sdk.
Install with yarn: yarn add @loongsuite/cms_node_sdk.
Install with pnpm: pnpm add @loongsuite/cms_node_sdk.

Step 2: Configure environment variables

Add the following environment variables to your Node.js application:

# Method 1: Add environment variables for all processes in the current shell
export ARMS_APP_NAME=your-app-name   # Your application name.
export ARMS_REGION_ID=your-region-id   # The region ID for your Alibaba Cloud account.
export ARMS_LICENSE_KEY=your-license-key   # Your Alibaba Cloud license key.

# Method 2: Add environment variables for a specific process
ARMS_APP_NAME=your-app-name ARMS_REGION_ID=your-region-id ARMS_LICENSE_KEY=your-license-key node -r @loongsuite/cms_node_sdk/register app.js

You can obtain the license key through OpenAPI or from the Integration Center in the CMS 2.0 console.

Install in a Docker environment (optional)

For Docker environments, modify your Dockerfile as shown in the following example.

# Add environment variables
ENV ARMS_APP_NAME={AppName}
ENV ARMS_REGION_ID={regionId}
ENV ARMS_LICENSE_KEY={licenseKey}

## Your existing environment

Step 3: Initialize the probe

The Node.js SDK supports two initialization modes. Choose one based on your requirements:

Programmatic approach

Initialize the SDK in your application's entry point file with the following parameters:

serviceName: Your application name (required).
licenseKey: Your Alibaba Cloud license key (required).
regionId: Your Alibaba Cloud region ID (required), such as cn-hangzhou or cn-shanghai.

CommonJS approach:

// Must be the first line of app.js or index.js
const { NodeSDK } = require('@loongsuite/cms_node_sdk');

// Initialize the SDK (licenseKey, serviceName, and regionId are required)
const sdk = new NodeSDK({
  serviceName: 'your-app-name',        // Application name
  licenseKey: 'your-license-key',      // Get this from the ARMS console
  regionId: 'cn-hangzhou',             // Your Alibaba Cloud region
  // workspace: 'your-workspace',      // Optional: workspace
});

// Start the SDK
sdk.start();

// Your application code starts here
const express = require('express');
const app = express();
// ... other code

ES Module approach:

// Must be the first line of app.mjs or index.mjs
import { NodeSDK } from '@loongsuite/cms_node_sdk';

// Initialize the SDK (licenseKey, serviceName, and regionId are required)
const sdk = new NodeSDK({
  serviceName: 'your-app-name',        // Application name
  licenseKey: 'your-license-key',      // Get this from the ARMS console
  regionId: 'cn-hangzhou',             // Your Alibaba Cloud region
  // workspace: 'your-workspace',      // Optional: workspace
});

// Start the SDK
sdk.start();

// Your application code starts here
import express from 'express';
const app = express();
// ... other code

Important:

The serviceName, licenseKey, and regionId parameters are required.
You must call sdk.start() before importing any other application modules (such as express or mysql) to ensure automatic instrumentation works correctly.

Automatic injection

For codeless instrumentation, configure the SDK with environment variables and preload it at startup with the -r flag.

This mode uses the environment variables configured in Step 2, so no code changes are required.

Step 4: Start the application

Start the application in programmatic mode

If you use the programmatic approach (Mode 1), start your application with the standard command:

node app.js

Start the application using automatic injection (register mode)

If you use automatic injection (Mode 2 in Step 3), preload the probe with the Node.js -r flag:

node -r @loongsuite/cms_node_sdk/register app.js

The -r flag initializes the ARMS Node.js probe and enables non-intrusive instrumentation.

Start the application with an ESM loader (ESM projects)

If your project uses ES modules, use the Node.js loader to automatically inject the SDK during module loading:

node --experimental-loader=@loongsuite/cms_node_sdk/import-hooks app.mjs

This method is suitable for pure ESM projects and requires the --experimental-loader flag in the startup command.

Verify the installation

About one minute after installation, check whether your application appears in the ARMS console under Application Monitoring > Application List. The application is successfully connected when it appears in the list and reports data.

Advanced configuration

Custom configuration

You can customize the probe behavior programmatically:

const { NodeSDK } = require('@loongsuite/cms_node_sdk');

const sdk = new NodeSDK({
  serviceName: 'my-custom-service',
  licenseKey: 'your-license-key',
  regionId: 'cn-hangzhou',
  workspace: 'your-workspace',
  // Other custom configurations, such as sampling policies or custom exporters
});

sdk.start();

Configure with environment variables (register mode)

When using register mode, the following environment variables are supported:

Parameter	Description	Required
`ARMS_APP_NAME`	Application name	Yes
`ARMS_LICENSE_KEY`	ARMS license key	Yes
`ARMS_REGION_ID`	ARMS region ID (for example, cn-hangzhou)	Yes
`ARMS_WORKSPACE`	ARMS workspace	No
`CMS_ENABLE_CONSOLE_EXPORTER`	Enables the console exporter. Valid values: `true`, `false`.	No
`CMS_OTLP_ENDPOINT`	The URL of the OTLP export endpoint.	No
`OTEL_LOG_LEVEL`	Sets the probe's log level. Valid values: `debug`, `info`, `warn`, `error`.	No. Default: `info`.

FAQ

Does the probe affect application performance?

The probe is designed for minimal overhead, typically less than 5%.

Which Node.js frameworks are supported?

The probe supports major Node.js web frameworks including Express, Koa, Fastify, Hapi, and Restify, as well as database clients for MySQL, PostgreSQL, Redis, and MongoDB.

Must the SDK be imported first?

Yes. You must call sdk.start() or use the -r preload flag before importing any other application modules (such as express or mysql). Otherwise, automatic instrumentation will fail for these modules.

How do I disable the probe?

Call the sdk.shutdown() method to gracefully shut down the probe. In register mode, the probe shuts down automatically when the process exits.

Is TypeScript supported?

Yes. The SDK is written in TypeScript and includes complete type definitions.

Can I pin the probe version?

Yes. Install a specific version by running the following command:

npm install @loongsuite/cms_node_sdk@<version>

Replace <version> with the actual version number.