@loongsuite/cms_node_sdk

v1.0.4

Published

4 days ago

0High
0Medium
0Low

fangxiu.wf

guangli.fj

yunjin4

@loongsuite/cms_node_sdk

简介

本页提供三个可直接运行的集成方式：

AMD（ESM Loader 自动注入）
CMD（CommonJS 预加载注入）
手动埋点（完全手动创建与结束 Span）

安装

npm i @loongsuite/cms_node_sdk @loongsuite/cms_trace @loongsuite/cms_exporters @loongsuite/cms_core

说明

SDK 默认启用 http 自动埋点；AMD/CMD 两种自动注入方式下无需额外配置。
下述示例仅使用 Console 导出，复制即可运行并在控制台看到导出日志。

环境变量配置

使用 -r @loongsuite/cms_node_sdk/register 预加载时,可通过环境变量配置 SDK 行为。

核心配置

| 环境变量 | 说明 | 默认值 | 优先级 | |---------|------|--------|--------| | ARMS_APP_NAME | 应用名称 (推荐) | - | 高 | | CMS_SERVICE_NAME | 应用名称 (向后兼容) | cms-auto | 低 | | ARMS_LICENSE_KEY | ARMS License (推荐) | - | 高 | | ARMS_LICENSE | ARMS License (向后兼容) | - | 低 | | ARMS_REGION_ID | ARMS 区域 ID | - | - | | ARMS_WORKSPACE | ARMS 工作空间 | - | - | | ARMS_APP_ID | 应用 ID (可选) | - | - |

集群/容器元数据 (K8s 环境)

| 环境变量 | 说明 | 默认值 | |---------|------|--------| | ARMS_CLUSTER_ID | 集群 ID | - | | ARMS_CLUSTER_NAME | 集群名称 | - | | ARMS_WORKLOAD_KIND | 工作负载类型 (Deployment/StatefulSet 等) | - | | ARMS_WORKLOAD_NAME | 工作负载名称 | - | | ARMS_NAMESPACE | 命名空间 | - | | ARMS_AGENT_ENV | 代理环境标识 | DEFAULT | | ARMS_HOST_TAGS | 主机标签 | - |

导出器配置

| 环境变量 | 说明 | 默认值 | |---------|------|--------| | OTLP_TRACES_URL | OTLP Trace 端点 | - | | CMS_OTLP_ENDPOINT | OTLP Trace 端点 (兼容) | - | | CMS_OTLP_URL | OTLP Trace 端点 (兼容) | - | | ARMS_ENABLE_CONSOLE_EXPORTER | 启用 Console 导出器 (true/false) | false | | CMS_ENABLE_CONSOLE_EXPORTER | 启用 Console 导出器 (兼容) | false |

批处理配置

| 环境变量 | 说明 | 默认值 | 单位 | |---------|------|--------|------| | ARMS_EXPORT_BATCH_DELAY_MS | 批处理延迟 (推荐) | 300 | 毫秒 | | CMS_EXPORT_BATCH_DELAY_MS | 批处理延迟 (兼容) | 300 | 毫秒 | | ARMS_MAX_EXPORT_BATCH_SIZE | 批处理大小 (推荐) | 1 | 条 | | CMS_EXPORT_BATCH_MAX | 批处理大小 (兼容) | 1 | 条 |

注意: 批处理参数在使用 -r @loongsuite/cms_node_sdk/register 预加载时生效。如果手动创建 NodeSDK,请在 BatchSpanProcessor 中配置这些参数。

其他配置

| 环境变量 | 说明 | 默认值 | |---------|------|--------| | APSARA_APM_OXS_ENABLED | 启用 OXS 区域 | false | | OTEL_RESOURCE_ATTRIBUTES | 资源属性 (OTel 标准) | - |

使用示例

# 推荐: 使用新的 ARMS_ 前缀环境变量
ARMS_APP_NAME=my-service \
ARMS_LICENSE_KEY=your_license_key \
ARMS_REGION_ID=cn-hangzhou \
node -r @loongsuite/cms_node_sdk/register ./app.js

# 兼容: 使用旧版环境变量(仍然有效)
CMS_SERVICE_NAME=my-service \
ARMS_LICENSE=your_license_key \
ARMS_REGION_ID=cn-hangzhou \
node -r @loongsuite/cms_node_sdk/register ./app.js

# K8s 环境: 包含集群元数据
ARMS_APP_NAME=my-service \
ARMS_LICENSE_KEY=your_license_key \
ARMS_REGION_ID=cn-hangzhou \
ARMS_CLUSTER_ID=cluster-123 \
ARMS_NAMESPACE=production \
ARMS_WORKLOAD_KIND=Deployment \
ARMS_WORKLOAD_NAME=my-deployment \
node -r @loongsuite/cms_node_sdk/register ./app.js

# 混合配置: 新变量优先级更高
ARMS_APP_NAME=new-name CMS_SERVICE_NAME=old-name node -r @loongsuite/cms_node_sdk/register ./app.js
# 实际使用: new-name

迁移指南

如果您之前使用旧版环境变量,建议迁移到新的标准命名:

| 旧变量名 | 新变量名 | 状态 | |---------|---------|------| | CMS_SERVICE_NAME | ARMS_APP_NAME | ✅ 推荐迁移 | | ARMS_LICENSE | ARMS_LICENSE_KEY | ✅ 推荐迁移 | | CMS_EXPORT_BATCH_DELAY_MS | ARMS_EXPORT_BATCH_DELAY_MS | ✅ 推荐迁移 | | CMS_EXPORT_BATCH_MAX | ARMS_MAX_EXPORT_BATCH_SIZE | ✅ 推荐迁移 | | CMS_ENABLE_CONSOLE_EXPORTER | ARMS_ENABLE_CONSOLE_EXPORTER | ✅ 推荐迁移 |

注意:

所有旧版环境变量在当前版本中仍然完全兼容,您可以按需逐步迁移
新变量名与 Python 探针和 Java 探针保持一致,便于多语言统一管理

一、AMD 集成（ESM Loader）

适用：ESM 项目。通过 Node.js Loader 在模块加载阶段完成自动注入。

新建文件 server-auto.mjs

import { NodeSDK } from '@loongsuite/cms_node_sdk';
import { BatchSpanProcessor } from '@loongsuite/cms_trace';
import { ConsoleSpanExporter } from '@loongsuite/cms_exporters';

const sdk = new NodeSDK({
  serviceName: 'amd-demo',
  spanProcessors: [
    new BatchSpanProcessor(new ConsoleSpanExporter(), {
      scheduledDelayMillis: 300,
      maxExportBatchSize: 1,
    }),
  ],
});
sdk.start();

const httpMod = await import('http');
const http = httpMod.default ?? httpMod;

const server = http.createServer((_req, res) => {
  res.statusCode = 200;
  res.setHeader('content-type', 'text/plain');
  res.end('ok');
});

server.listen(8888, () => {
  console.log('AMD/ESM loader demo: http://localhost:8888');
});

启动命令

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

二、CMD 集成（CommonJS 预加载）

适用：CommonJS 项目。通过 -r 预加载在用户代码前启用自动埋点。

新建文件 app.js

const http = require('http');

const server = http.createServer((_req, res) => {
  res.statusCode = 200;
  res.setHeader('content-type', 'text/plain');
  res.end('ok');
});

server.listen(8890, () => {
  console.log('CMD/preload demo: http://localhost:8890');
});

启动命令

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

三、手动埋点

无需自动注入，完全由业务代码创建与关闭 Span。

新建文件 server-manual.mjs

import { NodeSDK } from '@loongsuite/cms_node_sdk';
import { BatchSpanProcessor } from '@loongsuite/cms_trace';
import { ConsoleSpanExporter } from '@loongsuite/cms_exporters';
import * as http from 'http';

const sdk = new NodeSDK({
  serviceName: 'manual-demo',
  spanProcessors: [
    new BatchSpanProcessor(new ConsoleSpanExporter(), {
      scheduledDelayMillis: 300,
      maxExportBatchSize: 1,
    }),
  ],
});
sdk.start();

const tracer = sdk.getTracerManager().getTracer('manual-demo');

const server = http.createServer((req, res) => {
  const span = tracer.startSpan(`${req.method} ${req.url}`, { kind: 1 /* SERVER */ });
  try {
    const tm = sdk.getTracerManager();
    const cm = sdk.getContextManager();
    cm.with(tm.setSpan(cm.active(), span), () => {
      const child = tracer.startSpan('work:handle_request');
      child.end();
      res.statusCode = 200;
      res.setHeader('content-type', 'text/plain');
      res.end('ok');
    });
  } finally {
    span.end();
  }
});

server.listen(8889, () => {
  console.log('Manual demo: http://localhost:8889');
});

启动命令

node ./server-manual.mjs

四、可选：切换导出器到 OTLP/ARMS

如需接入 OTLP/ARMS，可将示例中的 ConsoleSpanExporter 替换或并列为其他导出器。

五、Node 18 以下版本注意事项

为保证在 Node < 18 环境下稳定运行，请注意：

ESM/Loader 标志

使用 AMD/ESM Loader 方式时，Node 14/12 需要实验标志：

# Node 14/12 示例
node --experimental-modules --experimental-loader=@loongsuite/cms_node_sdk/import-hooks ./server-auto.mjs

顶层 await 的替代

Node 12 对 ESM 支持较弱，若顶层 await 不可用，可改为 IIFE：

// server-auto.mjs (替代写法)
import { NodeSDK } from '@loongsuite/cms_node_sdk';
import { BatchSpanProcessor } from '@loongsuite/cms_trace';
import { ConsoleSpanExporter } from '@loongsuite/cms_exporters';

const sdk = new NodeSDK({
  serviceName: 'amd-demo',
  spanProcessors: [new BatchSpanProcessor(new ConsoleSpanExporter(), { scheduledDelayMillis: 300, maxExportBatchSize: 1 })],
});
sdk.start();

(async () => {
  const httpMod = await import('http');
  const http = httpMod.default ?? httpMod;
  const server = http.createServer((_req, res) => {
    res.statusCode = 200;
    res.setHeader('content-type', 'text/plain');
    res.end('ok');
  });
  server.listen(8888, () => console.log('AMD/ESM loader demo: http://localhost:8888'));
})();

上下文管理器选择

Node 12 全版本可用：AsyncHooksContextManager（推荐）。
Node ≥ 12.17 且环境允许：可使用 AsyncLocalStorageContextManager。

// 手动埋点/CMD 场景可显式指定：
const { AsyncHooksContextManager, AsyncLocalStorageContextManager } = require('@loongsuite/cms_context');

const sdk = new NodeSDK({
  contextManager: new AsyncHooksContextManager(), // Node 12 稳妥选择
});

ESM 项目与 CommonJS 的选择

Node 12/14 下，若非必须，优先使用 CommonJS 预加载（CMD）方式；更简单、更稳定。
仅在需要拦截 ESM 静态导入时，再考虑 AMD/ESM Loader 方式并开启实验标志。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

环境变量配置

核心配置

集群/容器元数据 (K8s 环境)

导出器配置

批处理配置

其他配置

使用示例

迁移指南