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
```

版本说明

下表中的支持版本范围来自 @loongsuite/cms_node_sdk@1.0.10 及其依赖包中的自动采集组件定义。对于 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 执行、路由信息、异常信息
Next.js	next	>=12.0.0 <17.0.0	服务端请求、SSR、RSC、API、错误页、静态页、路由信息、状态码、耗时和异常信息
Nuxt 2	@nuxt/server、@nuxt/vue-renderer、@nuxt/core	>=2.3.0 <3.0.0	SSR/SPA/API/server middleware、`asyncData`、`fetch`、`validate`、Vue renderer 等阶段
Nuxt 3/Nitro/h3	h3、hookable、Node.js `http`/`https`	h3 >=1.0.0 <2.0.0；hookable >=5.0.0 <6.0.0	服务端请求、h3 handler、Nitro Hook、Node.js request listener
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 调用、解析耗时、错误信息；自 1.0.9 起默认关闭，需要时通过 `dns: { enabled: true }` 显式启用
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 用量、错误信息
Mastra	@mastra/core、@mastra/observability	@mastra/core >=1.50.0 <2.0.0	Agent、Step、LLM、Tool、Workflow Span，以及输入输出、Token、错误和 RED 指标；需要安装 `@mastra/observability`
Genkit	@genkit-ai/core	>=1.0.4 <2.0.0	Flow、Agent、Model、Tool、Retriever、Embedding 等调用链路、Token 用量和错误信息
MCP SDK v1	@modelcontextprotocol/sdk	>=1.0.0 <2.0.0	MCP Server request、notification 和 tool handler Span，采集参数、结果、资源 URI、JSON-RPC 错误和耗时
MCP Server v2	@modelcontextprotocol/server	>=2.0.0 <3.0.0	MCP v2 Server request、notification 和 tool handler 自动采集
Chrome DevTools MCP	chrome-devtools-mcp	>=1.8.0 <1.9.0	Chrome DevTools 工具调用链路；`tools/call` 以 TOOL 语义接入 GenAI Trace 和指标
Pi Agent SDK	@earendil-works/pi-agent-core、@earendil-works/pi-ai、@earendil-works/pi-coding-agent、@earendil-works/pi-durable	>=0.74.0 <2；pi-durable >=1.2.0 <1.3.0	Agent、Step、LLM、Tool、压缩、树导航、流式响应、重试和队列事件；记录模型、Provider、Token、缓存 Token、Cost、TTFT、状态和耗时
OpenClaw	openclaw、@loongsuite/cms_instrumentations/openclaw	1.0.11 新增；本次验证 2026.10.5；未定义完整支持范围	模型、工具、子 Agent、错误、取消链路采集。RUM 场景下默认不采集正文，普通 NodeSDK 不适用该默认。验证环境为独立 Node agent/gateway 及 Electron 44.9.1 的 main/worker/utility/spawn/fork 进程；ASAR 仅验证 runtime 提取注入，不构成完整 OpenClaw ASAR 业务验收

Node.js 运行时指标

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

接入能力补充

接入能力	说明
RUM Electron	1.0.11 新增 Node.js Trace runtime，支持接收回调或经过鉴权的本地 HTTP 通道交接，并与 RUM Electron 配合使用。
开源 OpenTelemetry Instrumentation	通过 OpenTelemetry API 兼容桥接接入 NodeSDK 的链路、指标及上下文；与 NodeSDK 原生采集重叠时支持自动去重。第三方 Instrumentation 需自行安装并启用，具体组件以实际验证为准。
`genai_utils` 兼容接入	支持通过 OpenTelemetry API 兼容桥接，将 `genai_utils` 生成的 GenAI Span 接入 NodeSDK 的 Trace 采集与上报链路，并与 NodeSDK 自动采集的调用链共享上下文，关联 Agent、模型和工具调用。需由业务侧安装并初始化 `genai_utils`。

配置项说明

Node.js 探针内置的大部分自动采集组件默认开启。自 1.0.9 起，DNS 插桩默认关闭，需要时可通过 dns: { enabled: true } 显式启用。可以在 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: {
    next: {
      enabled: true,
    },
    nuxt: {
      enabled: true,
    },
    mysql2: {
      enabled: true,
    },
    openai: {
      enabled: true,
    },
    vercel_ai: {
      enabled: true,
    },
    mastra: { enabled: true },
    genkit: { enabled: true },
    mcp: { enabled: true },
  },
});

sdk.start();

常用配置 key 如下：

类别	配置 key
HTTP 与网络	http、undici、grpc、dns、net
Web 框架	express、koa、next、nuxt、socketio
数据库	mysql、mysql2、pg、mongodb、moogoose
缓存与消息	redis、ioredis、kafka
日志	pino、winston、bunyan、console
AI	openai、langchain、langgraph、vercel_ai、claude_agent、mastra、genkit、mcp、openclaw、pi_agent
运行时	runtime
SDK 顶层	`processIsolation`（可选身份隔离，默认关闭；开启后每个业务进程或 worker 分别初始化 SDK，Trace、Metric、Log 身份对齐；显式 `service.instance.id` 保留；`host.ip`、`net.host.ip` 和 `net.host.ipv4` 固定为实际网卡 IP 并覆盖自定义逻辑 IP）

说明

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

注意事项

自动采集要求探针先于目标模块加载。如果应用先加载了 express、next、nuxt、mysql2、openai、@mastra/core、@genkit-ai/core 或 MCP Server 模块，再启动探针，可能无法完整采集对应组件。
Next.js 自动采集能力从 @loongsuite/cms_node_sdk@1.0.5 起支持；Nuxt 2 自动采集能力从 @loongsuite/cms_node_sdk@1.0.7 起支持；Mastra、Genkit 和 MCP Server 自动采集能力从 1.0.9 起支持。
Nuxt 2 场景基于 @nuxt/server、@nuxt/vue-renderer、@nuxt/core 关键模块采集。Nuxt 2.3.0 以下版本不在当前支持范围内。
AI 组件可能涉及 prompt、response、tool input/output 等正文内容。MCP 会采集工具参数、参数摘要和结果，并通过固定长度的安全 JSON 投影限制属性大小；截图、音频和 blob 等二进制正文会被省略。当前尚未单独开放 MCP 脱敏配置，生产环境启用前需确认相关内容允许进入 Trace。
MCP 插桩在 1.0.9 中默认开启，首版仅提供 mcp: { enabled: boolean } 开关并仅支持 Server 端。MCP SDK v1 需要 Node.js 18 及以上，MCP Server v2 需要 Node.js 20 及以上；chrome-devtools-mcp 1.8.x 需要 Node.js 20.19+/22.12+/23+。ESM 应用继续使用现有 import-hooks Loader，无需新增注册入口。
MCP 的 tools/call 会标记为 gen_ai.span.kind=TOOL；resource、prompt 等协议操作保持普通 MCP Server Span，不会按名称推断为 Retriever 或 Reranker。Tool 内部真实的检索或重排调用应由相应框架或模型 SDK 插桩产生嵌套 Span。
自 1.0.9 起，探针内部 INFO、DEBUG、WARN、ERROR 诊断输出统一进入 stderr 并受日志级别控制；业务代码自己的 console.log 仍进入 stdout。stdio MCP Server 仍需由应用保证不向 stdout 写入业务日志。
对于未在本文列出的组件，ARMS 可能仍能通过底层 HTTP、RPC 或数据库客户端采集基础链路，但不会保证具备该组件专属的语义字段和视图能力。
组件版本范围会随探针版本演进而更新。升级探针后，请以对应版本文档和发布说明为准。