ARMS 应用监控支持的 Node.js 组件和框架-云监控(CMS)-阿里云帮助中心

为 Node.js 应用安装 ARMS 应用监控探针后，探针会在应用启动阶段启用自动采集功能。当应用加载已适配的框架或组件时，ARMS 可以自动采集请求链路、调用耗时、错误信息、数据库访问、消息调用、日志 Trace 关联、运行时指标以及 AI 调用链路等可观测数据。本文列出 ARMS 应用监控 Node.js 探针当前支持的组件和框架。

前提条件

建议使用 Node.js 14.x 及以上版本。AI 应用相关组件和 ESM Loader 场景建议使用 Node.js 16 及以上版本，生产环境推荐使用 Node.js 18 或 Node.js 20 LTS。
已安装 ARMS Node.js 探针。
```
npm install @loongsuite/cms_node_sdk
```
探针需要先于业务框架和组件加载。如果应用先加载了 express、mysql2、openai 等模块再启动探针，可能无法完整采集对应组件。CommonJS 应用建议使用 -r 方式预加载，ESM 应用建议使用 Loader 方式启动。
```
# CommonJS 应用
node -r @loongsuite/cms_node_sdk/register app.js

# ESM 应用
node --experimental-loader=@loongsuite/cms_node_sdk/import-hooks app.mjs
```

版本说明

对于 Node.js 内置模块、运行时指标或基于 diagnostics channel 的采集能力，探针不会按 npm 包版本做固定过滤，实际生效情况取决于 Node.js 运行时和对应模块是否提供可采集入口。

如果某个框架未在下表中以独立组件列出，但底层基于 Node.js http、https、undici、net 等模块发起调用，ARMS 仍可采集基础的入口或出口链路；路由、middleware、Agent、Tool 等框架语义能力以独立适配组件为准。

Web 框架

组件或框架	npm 包	支持版本	采集内容
Express	express	>=4.0.0 <6.0.0	HTTP 入口链路、路由信息、middleware/handler 执行、异常信息
Koa	koa	>=2.0.0 <4.0.0	HTTP 入口链路、middleware 执行、路由信息、异常信息
Socket.IO	socket.io	2.x、>=3.0.0 <5.0.0	事件收发、命名空间、房间广播、消息耗时、错误信息

HTTP、RPC 与网络通信

组件或模块	npm 包	支持版本	采集内容
Node.js HTTP	http、https	Node.js 内置模块	HTTP 服务端入口、HTTP 客户端出口、状态码、请求耗时、请求/响应大小、错误信息
Undici	undici	不设固定 semver 范围	基于 diagnostics channel 采集 HTTP 客户端请求、状态码、耗时、错误信息
gRPC	@grpc/grpc-js	>=1.0.0 <2.0.0	gRPC Client/Server 调用、service/method、状态码、耗时、错误信息
DNS	dns、dns/promises	Node.js 内置模块	DNS lookup 调用、解析耗时、错误信息
TCP/Unix Socket	net	Node.js 内置模块	TCP/Unix Socket 连接、目标地址、端口、连接错误

数据库与 ORM

组件或框架	npm 包	支持版本	采集内容
MySQL	mysql	>=2.0.0 <3.0.0	SQL 调用链路、SQL 语句、连接信息、慢查询、错误信息
MySQL2	mysql2	>=1.4.2 <4.0.0	SQL 调用链路、query/execute、SQL 语句、连接信息、慢查询、错误信息
PostgreSQL	pg	>=8.0.3 <9.0.0	SQL 调用链路、SQL 语句、连接信息、慢查询、错误信息
PostgreSQL Pool	pg-pool	>=2.0.0 <4.0.0	连接池 connect 调用、数据库访问链路补充信息
MongoDB	mongodb	>=3.3.0 <4.0.0、>=4.0.0 <7.0.0	MongoDB 命令、集合、数据库名、连接信息、耗时、错误信息
Mongoose	mongoose	>=5.9.7 <9.0.0	Model/Query/Aggregate 调用、集合信息、数据库操作、耗时、错误信息

缓存与消息队列

组件或框架	npm 包	支持版本	采集内容
Redis	redis	>=2.6.0 <4.0.0	Redis 命令、连接信息、调用耗时、错误信息
Node Redis Client	@redis/client、@node-redis/client	>=1.0.0 <2.0.0、>=5.0.0 <6.0.0	Redis v4/v5 客户端命令、多命令、连接信息、调用耗时、错误信息
ioredis	ioredis	>=2.0.0 <6.0.0	Redis 命令、连接信息、调用耗时、错误信息
KafkaJS	kafkajs	>=0.3.0 <3.0.0	Kafka Producer/Consumer 调用、Topic、消息收发耗时、错误信息

日志框架

组件或框架	npm 包	支持版本	采集内容
Pino	pino	>=7.0.0 <11.0.0	日志 Trace 关联字段注入
Winston	winston	>=3.0.0 <4.0.0	日志 Trace 关联字段注入
Bunyan	bunyan	>=1.8.0 <3.0.0	日志 Trace 关联字段注入
Console	console	Node.js 全局对象	console.log、console.info、console.warn、console.error Trace 关联字段注入

AI 应用组件

组件或框架	npm 包	支持版本	采集内容
OpenAI Node SDK	openai	>=4.0.0 <6.0.0	Chat/Completion/Image 调用、模型信息、Token 用量、流式调用、错误信息
LangChain JS	@langchain/core、langchain	不设固定 semver 范围，以 @langchain/core/callbacks/manager 等模块入口可加载为准	Chain、LLM、Tool、Retriever、Embedding 等运行链路、Token 用量、错误信息
LangGraph	@langchain/langgraph	不设固定 semver 范围，以 @langchain/langgraph/prebuilt 和 @langchain/langgraph/pregel 等模块入口可加载为准	ReAct Agent、Pregel stream、Agent/Step 元数据，并与 LangChain 采集协同形成完整 Agent 链路
Vercel AI SDK	ai	>=4.0.0 <7.0.0	generateText、streamText、generateObject、streamObject、Tool、Embedding、Rerank、Agent 调用链路
Anthropic Claude Agent SDK	@anthropic-ai/claude-agent-sdk	>=0.3.0 <1.0.0	query、startup 调用、Agent 运行、模型请求、工具调用、会话信息、Token 用量、错误信息

Node.js 运行时指标

指标类别	采集对象	采集内容
Event Loop	Node.js 事件循环	事件循环延迟、事件循环利用率等指标
V8	V8 引擎	堆内存、GC 次数、GC 耗时、堆空间使用等指标
Process	Node.js 进程	CPU、内存、线程相关指标、上下文切换等进程指标

配置项说明

Node.js 探针内置的自动采集组件默认开启。可在 ARMS 控制台中按应用调整探针开关，也可在初始化 SDK 时通过 instrumentations 字段显式配置。

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

const sdk = new NodeSDK({
  serviceName: 'your-app-name',
  licenseKey: 'your-license-key',
  regionId: 'cn-hangzhou',
  instrumentations: {
    mysql2: {
      enabled: true
    },
    openai: {
      enabled: true
    },
    vercel_ai: {
      enabled: true
    },
  },
});

sdk.start();

常用配置 key 如下：

类别	配置 key
HTTP 与网络	http、undici、grpc、dns、net
Web 框架	express、koa、socketio
数据库	mysql、mysql2、pg、mongodb、moogoose
缓存与消息	redis、ioredis、kafka
日志	pino、winston、bunyan、console
AI	openai、langchain、langgraph、vercel_ai、claude_agent
运行时	runtime

说明

Mongoose 组件面向用户展示为 mongoose，当前代码配置 key 为 moogoose。如果需要通过代码显式配置 Mongoose 采集开关，请使用 moogoose。

注意事项

AI 组件可能涉及 prompt、response、tool input/output 等正文内容。生产环境中建议根据合规要求配置正文采集策略和最大长度等规则。
对于未在本文列出的组件，ARMS 可能仍能通过底层 HTTP、RPC 或数据库客户端采集基础链路，但不会保证具备该组件专属的语义字段和视图能力。
组件版本范围会随探针版本演进而更新。升级探针后，以对应版本文档和发布说明为准。