手动安装 Node.js 探针 - 云监控

为Node.js应用安装探针后，ARMS即可开始监控Node.js应用，您可以查看应用拓扑、调用链路、SQL分析等一系列监控数据。本文介绍如何为Node.js应用手动安装探针。

前提条件

确保您的编译环境和公网或阿里云内网连通，且编译环境所在安全组已开放80、443的TCP出方向权限。
检查您的Node.js版本。建议使用Node.js 14.x及以上版本。
确保您的项目使用npm、yarn或pnpm等包管理工具。

注意事项

如果您的应用使用了特定的框架（如Express、Koa、Fastify等），探针会自动识别并进行无侵入式埋点。
对于使用自定义启动脚本的应用，需要确保探针在应用启动前正确加载。
如果应用使用了cluster模式，请确保每个worker进程都能正确加载探针。

步骤一：安装探针SDk

选择一种下载方式：

npm仓库下载：npm install @loongsuite/cms-node-sdk。
yarn下载：yarn add @loongsuite/cms-node-sdk。
pnpm下载：pnpm add @loongsuite/cms-node-sdk。

步骤二：配置环境变量

您需要手动为Node.js应用添加以下环境变量：

# 方式一：为本SHELL中所有进程添加环境变量
export ARMS_APP_NAME=xxx   # 应用名称。
export ARMS_REGION_ID=xxx   # 对应的阿里云账号的RegionID。
export ARMS_LICENSE_KEY=xxx   # 阿里云 LicenseKey。

# 方式二：为某个进程单独添加环境变量
ARMS_APP_NAME=xxx ARMS_REGION_ID=xxx ARMS_LICENSE_KEY=xxx node -r @loongsuite/cms-node-sdk/register app.js

其中LicenseKey可以通过OpenAPI获取，或从CMS2.0 控制台接入中心获取。

（可选）Docker环境安装参考

对于Docker环境，可以参考以下Dockerfile示例修改您的Dockerfile文件。

# 添加环境变量
ENV ARMS_APP_NAME={AppName}
ENV ARMS_REGION_ID={regionId}
ENV ARMS_LICENSE_KEY={licenseKey}

## 原有环境

步骤三：初始化探针

Node.js SDK 支持两种使用模式，您可以根据需求选择其中一种：

模式一：编程方式（推荐）

在代码中直接初始化SDK，需要在应用入口文件中提供以下信息：

serviceName：应用名称（必填）。
licenseKey：阿里云 LicenseKey（必填）。
regionId：阿里云区域ID（必填），如 cn-hangzhou、cn-shanghai 等。

CommonJS 方式：

// app.js 或 index.js 的第一行
const { NodeSDK } = require('@loongsuite/cms-node-sdk');

// 初始化SDK（必须提供 licenseKey、serviceName、regionId）
const sdk = new NodeSDK({
  serviceName: 'your-app-name',        // 应用名称
  licenseKey: 'your-license-key',      // 从ARMS控制台获取
  regionId: 'cn-hangzhou',             // 您的阿里云区域
  // workspace: 'your-workspace',      // 可选：工作空间
});

// 启动SDK
sdk.start();

// 您的应用代码
const express = require('express');
const app = express();
// ... 其他代码

ES Module 方式：

// app.mjs 或 index.mjs 的第一行
import { NodeSDK } from '@loongsuite/cms-node-sdk';

// 初始化SDK（必须提供 licenseKey、serviceName、regionId）
const sdk = new NodeSDK({
  serviceName: 'your-app-name',        // 应用名称
  licenseKey: 'your-license-key',      // 从ARMS控制台获取
  regionId: 'cn-hangzhou',             // 您的阿里云区域
  // workspace: 'your-workspace',      // 可选：工作空间
});

// 启动SDK
sdk.start();

// 您的应用代码
import express from 'express';
const app = express();
// ... 其他代码

重要提示：

serviceName、licenseKey、regionId 是必填参数。
必须在导入其他业务模块（如 express、mysql 等）之前调用 sdk.start()，以确保自动埋点生效。

模式二：使用 register 自动注入（零代码侵入）

如果您希望零代码侵入，可以通过环境变量配置，然后在启动时使用 -r 参数预加载 SDK。

此模式已在步骤二中配置环境变量，无需修改代码。

步骤四：启动应用

通过编程方式启动应用

如果您使用编程模式（步骤三的模式一），直接启动应用即可：

node app.js

通过 register 自动注入启动应用

如果您使用 register 模式（步骤三的模式二），使用 Node.js 的 -r 参数预加载探针：

node -r @loongsuite/cms-node-sdk/register app.js

-r 参数负责ARMS Node.js探针初始化配置及无侵入埋点。

通过 ESM Loader 启动应用（ESM 项目）

如果您的项目使用 ESM 模块，可以使用 Node.js Loader 在模块加载阶段完成自动注入：

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

此方式适用于纯 ESM 项目，需要在启动命令中添加 --experimental-loader 参数。

结果验证

约一分钟后，若Node.js应用出现在ARMS控制台的应用监控 > 应用列表页面中且有数据上报，则说明接入成功。

高级配置

自定义配置

您也可以通过编程方式自定义探针的行为：

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',
  // 其他自定义配置，如采样策略、自定义导出器等
});

sdk.start();

环境变量配置（register 模式）

使用 register 模式时，支持以下环境变量：

环境变量	说明	是否必填
`ARMS_APP_NAME`	应用名称	是
`ARMS_LICENSE_KEY`	ARMS 授权 key	是
`ARMS_REGION_ID`	ARMS 区域 ID（如 cn-hangzhou）	是
`ARMS_WORKSPACE`	ARMS 工作空间	否
`CMS_ENABLE_CONSOLE_EXPORTER`	启用控制台导出器（true/false）	否
`CMS_OTLP_ENDPOINT`	OTLP 导出端点 URL	否
`OTEL_LOG_LEVEL`	日志级别（debug/info/warn/error）	否，默认 info

常见问题

探针会影响应用性能吗？

探针设计时已充分考虑性能影响，通常对应用性能的影响在 5% 以内。

支持哪些 Node.js 框架？

支持 Express、Koa、Fastify、Hapi、Restify 等主流 Node.js Web 框架，以及 MySQL、PostgreSQL、Redis、MongoDB 等数据库客户端。

必须在第一行引入 SDK 吗？

是的，必须在导入任何业务模块（如 express、mysql 等）之前调用 sdk.start() 或使用 -r 参数预加载，否则这些模块将无法被自动埋点。

如何关闭探针？

可以在程序中调用 sdk.shutdown() 方法优雅关闭探针。如果使用 register 模式，探针会在进程退出时自动关闭。

支持 TypeScript 吗？

完全支持。SDK 使用 TypeScript 编写，提供完整的类型定义。

支持指定探针版本吗？

支持。您可以通过以下命令安装指定版本的探针：

npm install @loongsuite/cms-node-sdk@<version>

请将 <version> 替换为实际的版本号。